lifecycle-protocol

Lifecycle Protocol

This is the single human-readable lifecycle protocol. AGENTIC_LOOP.md is the small acting-methodology index; role files describe role boundaries; skills own procedures; adapters route to those sources. The CLI modules below are the machine authority. This protocol explains their shared lifecycle without making prose a mutation input.

Facts, Verdicts, And Refusals

Protected evaluators return a shared fact/verdict shape: ordered facts identify the canonical fact, observed state, fact owner, policy code when applicable, and evidence; a verdict is legal, illegal, or unknown; reasons identify failed or unavailable material facts; prerequisites name required protected inputs. src/result-envelope.js renders public validation results from that shape.

Every refusal has a stable code from src/refusal-classes.js, a material fact, a fact owner, and a safe deterministic nextAction when repair is mechanical. src/repair-policy.js owns routing. A diagnostic does not grant authority. It cannot move a task, consume a packet, accept review, certify audit, or cross a human gate. Mechanical recomputation is performed atomically by the protected CLI command, not delegated to a role.

task explain is the read-only consumer of those evaluator projections. It returns { derived: true, persisted: false, authority: "none", task, actions }; each action preserves the evaluator's facts, verdict, applicability, reasons, and prerequisites. It does not create evidence and no receipt or required check may invoke it as mutation evidence.

Canonical Lifecycle

1. Contract and readiness. The Maintainer owns durable task scope and required checks. The CLI validates the trusted task-contract baseline and readiness against current facts. A broad activation scope does not authorize a task and readiness does not create activation.
2. Authorization and dispatch. task prepare-dispatch derives a packet from current task, activation, readiness, repository, backend, role capability, and task-specific evidence. It is a read-only prediction. The packet is stale whenever a protected input changes.
3. Atomic role start. For files, task role-start <id> --packet <path> revalidates and consumes the exact packet, records the in-progress carrier transition, and initializes the scratch check aggregate in one transaction. No post-start packet recomputation authorizes work. GitHub uses its guarded backend-equivalent transition.
4. Implementation evidence. The Engineer modifies only accepted scope, runs the required checks, and uses CLI-produced execution evidence. On files, guarded task evidence mutations append allowed implementation evidence without changing protected task-contract fields.
5. Return and review. task prepare-return derives a raw role return from the consumed packet, current carrier, exact artifact, and check evidence. task verify-return is the protected receiving boundary. Only a current verified return may enter review preparation; a raw return is not review evidence or completion.
6. Review, audit, closeout. The Maintainer independently reviews the exact artifact. A fresh Auditor assesses the exact frozen candidate when enabled. Human-controlled closeout consumes the current evidence; no prior green, diagnostic, comment, label, or status auto-crosses the gate.