diff --git a/dev/ACTIVE_TASK.json b/dev/ACTIVE_TASK.json index 9d40435..30dace5 100644 --- a/dev/ACTIVE_TASK.json +++ b/dev/ACTIVE_TASK.json @@ -1,5 +1,5 @@ { - "task_file": "dev/tasks/DEV-000103-epistemics-truth-v1-proposal.json", - "task_id": "DEV-000103", + "task_file": "dev/tasks/DEV-000104-agent-execution-plane-proposal.json", + "task_id": "DEV-000104", "task_revision": 1 } diff --git a/dev/tasks/DEV-000104-agent-execution-plane-proposal.json b/dev/tasks/DEV-000104-agent-execution-plane-proposal.json new file mode 100644 index 0000000..a577868 --- /dev/null +++ b/dev/tasks/DEV-000104-agent-execution-plane-proposal.json @@ -0,0 +1,23 @@ +{ + "task_id": "DEV-000104", + "task_revision": 1, + "architecture_revision": "ADR-0018", + "base_repo_revision": "339f6a6", + "risk_tier": "E", + "intent": "Prepare the proposed ADR-0020 Agent Execution Plane boundary for review without implementing dispatcher, worker, schema, callback or deployment changes.", + "requirement_ids": ["WP-300", "Durable dispatch lease heartbeat", "Independent verification and truthful UNKNOWN outcome"], + "allowed_change_scope": {"modules": ["work-execution-governance"], "paths": ["docs/proposals/ADR-0020-agent-execution-plane-v1.md", "dev/ACTIVE_TASK.json", "dev/tasks/DEV-000104-agent-execution-plane-proposal.json"]}, + "forbidden_change_scope": {"paths": ["architecture/**", "contracts/**", "database/**", "migrations/**", "modules/**", "cmd/**", "runtime/**", "adapters/**", "deploy/**", ".gitea/**"]}, + "allowed_architecture_delta": {"new_cross_module_dependencies": 0, "new_canonical_owners": 0, "new_privileges": 0, "new_third_party_dependencies": 0, "new_database_owner_roles": 0}, + "contracts": {"consume": ["ADR-0017 General Agent Delegation and Codex Bridge V1", "Proposed ADR-0019 Epistemics Truth V1", "Core semantic model Work/Capability/Artifact/Continuity boundaries"], "may_change": ["Proposed ADR-0020 only; no accepted contract changes"]}, + "semantic_owner": "work-execution-plane-proposal-only", + "canonical_state": [], + "state_transitions": ["dispatch -> leased -> running -> result -> independently verified", "lease expiry/callback uncertainty -> UNKNOWN or RECOVERING", "cancel request -> acknowledged cancellation or typed unknown"], + "side_effects_and_privileges": ["No runtime side effects, external mutation, connector access, credential access or authority expansion"], + "persistence_and_migrations": ["No schema, migration, queue, worker or lease implementation changes"], + "failure_retry_restart": ["Retry creates a new run and preserves history; late or duplicate callbacks cannot become authoritative"], + "assumptions": ["Work remains canonical owner of durable delegation execution", "Artifact remains canonical owner of attestation metadata", "Production deployment remains outside this proposal"], + "acceptance_scenarios": ["Worker identity and dispatch idempotency are explicit", "Lease fencing and heartbeat expiry are explicit", "Callback authentication/replay handling is explicit", "Cancellation/retry/UNKNOWN semantics preserve history", "Independent verification gates Work completion", "No implementation or registry delta is introduced"], + "required_tests": ["go test ./...", "go vet ./...", "go run ./cmd/devctl preflight -active dev/ACTIVE_TASK.json", "go run ./cmd/devctl check-diff -active dev/ACTIVE_TASK.json", "go run ./cmd/devctl check-architecture", "go run ./cmd/devctl/independent", "git diff --check", "proposal scope and required-section review"], + "terminal_gap_states": ["BLOCKED_BY_ARCHITECTURE_GAP", "BLOCKED_BY_SPEC_GAP", "BLOCKED_BY_CONFLICT"] +} diff --git a/docs/proposals/ADR-0020-agent-execution-plane-v1.md b/docs/proposals/ADR-0020-agent-execution-plane-v1.md new file mode 100644 index 0000000..ece5306 --- /dev/null +++ b/docs/proposals/ADR-0020-agent-execution-plane-v1.md @@ -0,0 +1,97 @@ +# Proposal ADR-0020 — Agent Execution Plane V1 + +Status: Proposed +Task: DEV-000104 + +## Problem and evidence + +ADR-0017 defines durable delegation semantics, but the audit found no +automatic dispatcher/worker plane, lease/heartbeat lifecycle, callback +authentication or independent verification boundary. A worker must be able +to stop, restart and resume without turning a missing callback into success or +silently duplicating external work. + +## Decision proposed + +1. Keep `work` as the canonical owner of `Delegation`, `AgentRun`, + `AgentCheckpoint`, `AgentResult` and verification gating. `capability` + owns executor-neutral agent implementations; adapters own transport and + process details. +2. Every dispatch has a stable `dispatch_id`, delegation id, run id, + implementation id, exact source/worktree identity, bounded instruction + artifact reference, requested capability set, authority/credential refs, + deadline and idempotency key. The derived instruction must preserve + OriginalHumanIntent, inferred goal, added context and verification plan as + separate provenance fields. +3. A worker must acquire a durable lease before execution. Lease ownership is + a fencing token, not an in-memory mutex. Heartbeats extend the lease only + for the same run and fencing token; an expired lease makes late callbacks + non-authoritative. +4. Dispatch and callback endpoints authenticate the worker identity and bind + every message to delegation, run, dispatch, implementation and fencing + token. Forged, replayed, out-of-order or duplicate callbacks are rejected + or recorded as non-authoritative evidence. Idempotent acknowledgement is + allowed only for the exact previously accepted event. +5. Checkpoints and artifacts are content-addressed metadata owned by + `artifact`, with typed refs from Work. Artifact attestation records source + revision/worktree, producer, digest, test command/result and capture time; + an un-attested path or log is not completion evidence. +6. Cancellation is a durable Work decision. The dispatcher sends cancellation + to the leased worker, records acknowledgement or timeout, and never erases + history. A worker that cannot prove cancellation remains `UNKNOWN` or + `RECOVERING` until reconciled. +7. Retry is policy-driven and distinguishes retryable transport/worker loss, + execution-window exhaustion, human blocker, invalid result and unknown + external outcome. Retry creates a new run under the same delegation and + preserves prior checkpoints/results; it never reuses an idempotency key for + an unproven external mutation. +8. A run result cannot complete Work directly. Independent verification must + consume the declared artifacts and tests through a separate verifier + identity and produce a typed verification result. Verification failure, + missing evidence and verifier unavailability remain distinct states. +9. Secrets are resolved only through approved `CredentialRef` boundaries and + are not copied into instructions, callbacks, artifacts, logs or task + packets. Worker startup has no ambient credential inheritance. +10. The plane is durable and restartable: dispatch intent, lease, heartbeat, + cancellation, checkpoint, result, verification and reconciliation events + are persisted before their projections claim progress. + +## Lifecycle proposal + +Delegation remains the higher-level human/work intent. A run progresses through +`DISPATCHED`, `LEASED`, `RUNNING`, `CHECKPOINTED`, `SUCCEEDED`, `FAILED`, +`CANCEL_REQUESTED`, `CANCELLED`, `EXHAUSTED`, `WAITING_HUMAN`, `UNKNOWN` or +`RECOVERING`, subject to explicit transition guards. `SUCCEEDED` means only +that the worker returned an accepted result; Work completion additionally +requires independent verification. Lease expiry and missing heartbeat never +become success. + +## Alternatives and rationale + +- An in-memory queue or goroutine was rejected because it loses dispatch state + on restart and violates durable timer/lease requirements. +- A single generic `AgentManager` was rejected because it collapses Work, + Capability, Artifact and Continuity ownership. +- Trusting worker-reported success was rejected because the worker and + verifier must remain separate authorities. +- Reusing the same run on retry was rejected because it makes duplicate + external effects and late callbacks indistinguishable. + +## Boundaries, consequences and non-goals + +No new canonical owner, provider, deployment authority, database migration, +Codex-specific domain contract or automatic self-modification is proposed. +The design enables restartable external work and truthful failure handling, +but requires durable event ordering, fencing, artifact storage and verifier +capacity before WP-301 can claim production readiness. + +## Migration, rollback and revisit triggers + +Implementation must begin behind an opt-in dispatch path with a dry-run +verifier and deterministic fake worker. Existing delegation records remain +readable; unknown legacy RUNNING records are classified by WP-302 rather than +silently resumed. Rollback disables new dispatch and drains/recovers leases; +history and artifacts remain. Revisit if a worker needs authority beyond its +declared capability, if a second transport changes callback guarantees, or if +artifact attestation cannot be made independent of the worker. +