codex-workflow-v2 2.0.0-alpha.4 → 2.0.0-alpha.6.1

package/docs/autonomy-guardrails.md

@@ -0,0 +1,143 @@
+# Autonomous Development Guardrails
+
+These rules keep delegated execution autonomous without turning approval into a rubber stamp.
+Alpha.6 adds no persistent canonical state fields and keeps `stateSchemaVersion: 2`.
+
+## Plan Risk Audit
+
+Before execution authorization, every alpha.6 Task needs a current Plan Risk Audit sidecar
+bound to the current Brief, Plan, and approved Knowledge Map. This is mandatory even when all
+Steps are unguarded and the decision is `approved`.
+
+The payload must classify every current Step exactly once and declare:
+
+- `planner` and a distinct `auditor`
+- `decision`: `approved`, `approved-with-rationale`, `split-required`, or `stop-escalate`
+- per-Step guarded categories, concrete `failureModes`, and `reviewRequired`
+- `requiredEvidence` entries that exactly match executable checks in that Step
+- `splitRationale` when migration is intentionally coupled to recovery or runtime composition
+
+The workflow rejects omitted Steps, extra Steps, duplicate classifications, stale bindings,
+and self-contradictory classifications. `split-required` and `stop-escalate` block execution
+authorization. The sidecar, not informal Plan prose, is
+the source of truth for which Steps require strict review.
+
+Guarded categories cover:
+
+- forward database or state migrations;
+- concurrent ownership, queues, cursors, compare-and-swap, or locking;
+- restart, replay, recovery, or crash windows;
+- external provider lifecycle, hidden retries, defaults, timeouts, or error mapping;
+- runtime composition boundaries, security boundaries, auth/secrets, and irreversible execution.
+
+The original Plan must contain the corresponding failure evidence. A migration needs a
+populated forward-upgrade scenario, not only a clean bootstrap. Concurrent state needs
+deterministic race tests. Recovery needs restart and crash-window evidence. Provider work
+needs failure injection and verification of provider defaults. When persistence migration,
+recovery orchestration, and executable composition form independently verifiable failure
+boundaries, they are separate Tasks rather than one oversized Task.
+
+For adopted legacy Tasks, the bootstrap audit covers only the remaining non-`completed` and
+non-`skipped` Steps recorded at the adoption boundary.
+
+## Strict Step Review
+
+If the current Plan Risk Audit marks a Step for strict review, `task step-complete` still
+creates the workflow-owned commit, but the Step stays non-terminal and `next` routes to
+`task step-review`. Canonical completion is recorded only after the strict review and the
+reviewer attestation both bind to that exact completion commit.
+
+Invalid or stale review sidecars fail closed. The workflow blocks downstream acceptance and
+normal continuation when review evidence is malformed, unverified, or commit-mismatched.
+
+## Repeated failed review and remediation breaker
+
+The first failed independent review returns the Task to `needs_fix` and requires a changed or
+new remediation Step. After two distinct failed-review attempts, `next` returns
+`task plan-set with independent corrective audit`. Another Plan requires a JSON audit:
+
+```json
+{
+  "auditor": "corrective-auditor",
+  "summary": "The corrective Step covers the latest findings without changing the Brief.",
+  "decision": "continue-fix",
+  "reviewedFindingIds": ["REV-001", "REV-002"]
+}
+```
+
+Apply it with `task plan-set --corrective-audit-file <file>` only for the `continue-fix`
+path. The Auditor must differ from the failed-review author and cover every latest finding.
+`replan-required`, `split-required`, and `stop-escalate` are stop decisions: Core does not
+start another implementation loop.
+
+For alpha.6 guarded Steps, remediation attempts are also tracked in
+`remediation-events.jsonl`. Two ordinary remediation attempts are allowed. A third ordinary
+retry is blocked until `task corrective-decision` records a current corrective decision in
+`corrective-decisions.jsonl`. `continue-fix` allows bounded continuation; the other decisions
+stop or redirect ordinary execution. If that third, corrective remediation review also fails,
+Core enters a hard stop: a fourth run and another `continue-fix`/`replan-required` decision are
+rejected. Only `split-required` or `stop-escalate` may be recorded.
+
+## Content-only context refresh
+
+When `next.contextRefresh` offers an exact option, a project-scoped delegate may run one
+composite transition:
+
+```text
+task context-refresh
+  = project-memory reconcile
+  + delegated project-memory approve
+  + task knowledge-rebind
+  + delegated task execution authorize
+```
+
+The command requires the exact Task and Knowledge Map revisions, delegate actor, and grant.
+Core validates both grant transitions before the first write. It is allowed only when an
+already approved source set has content-hash drift and its category, scope, authority, gaps,
+and conflicts are unchanged. New or removed sources and any classification/authority change
+stop on the ordinary visible Knowledge Map flow.
+
+## Chat ownership
+
+One Milestone coordinator chat owns Discovery, Task order, exact delegated approvals, merge
+observation, Milestone validation, and final acceptance. Every required Task runs in a
+dedicated user-visible Task chat. A Task chat may use internal Worker and Reviewer contexts,
+but only its delegate coordinator uses the grant. This prevents one long Milestone context
+from accumulating every implementation and review loop.
+
+## Update boundary
+
+Before changing the exact npm version, run `update preflight`. A compatible update is safe
+only when the repository is clean, no Step is `in_progress`, and no writer lease is active.
+An expired lease is also a blocker until the ordinary explicit stale-lock repair is completed.
+The command is read-only and reports every blocker. It does not install a package or migrate
+state. When `stateSchemaVersion` remains `2`, the external project state is reused unchanged.
+Existing schema 2 projects then use `state adoption-prepare` and `state adoption-apply`; they
+do not use `state migrate` for alpha.6 adoption.
+
+## Milestone closure
+
+After every current `required` Task is `merged`, run `milestone validate` on the clean base
+HEAD. `next` exposes a completion policy and the state-bound final gate. The coordinator must
+compare Result, evidence, Plan hash, and validated HEAD. A delegate may accept only through an
+exact `milestone.final_accept` option, must remain the recorded actor, and must pass the
+current `MSA-*` code. Without that option the ordinary later-message human gate applies.
+
+## Human-only Milestone scope change and C1 handoff
+
+Milestone scope change beyond the initial empty planning posture is explicit and human-only:
+use `milestone scope-change-prepare` and `milestone scope-change-apply`. The change is
+journaled across `state.json`, `plan.json`, and `scope-change-events.jsonl`, and delegated
+approval never authorizes it.
+
+`C1` handoff uses `task handoff-prepare`, `task claim --claim-token ...`, and terminal
+`task handback-create`. Preparation returns a one-time token and prompt bound to a stable
+`handoffId`, revision, Brief/Plan/Knowledge hashes, Milestone and Task display numbers,
+expected next action, delegate/grant, creation time, and expiry. Only the claim-token hash is
+stored; `task handoff-show` cannot recover it. Claim fails closed on expiry, actor, token,
+revision, context, grant, or writer-owner mismatch. While pending, `next` blocks normal
+execution behind claim; while claimed, only the
+claimant may mutate with the bound writer token. Milestone-linked Tasks require this claimed
+posture before start. Terminal handback preserves status, merge/result/evidence/review and
+Knowledge bindings, limitations, and recommended next action. This is machine-bound actor and
+lease evidence only; it is not proof of a separate thread.

package/docs/decisions.md

@@ -57,3 +57,30 @@ This document closes the requirement gaps identified during the V2 design review
     both actors and the policy hash; revocation blocks future uses. This is an additive schema
     2 entity and optional authorization metadata, so existing schema 2 projects require no
     migration. It is local policy evidence, not a cryptographic identity signature.
+11. **Core-owned Step commit.** `task run` dispatches a Worker that leaves changes
+    uncommitted. For an active Step, `next` returns the exact `task step-complete` transition
+    and Step ID. That transition validates history and allowed paths, runs checks, creates
+    the atomic commit, and records evidence. A manual Worker commit is unrecorded history and
+    fails closed without changing persisted Task state. This changes navigation and
+    diagnostics only; state schema 2 and protocol 1 remain unchanged.
+12. **Autonomous correction guardrail.** The initial Plan must make migration,
+    concurrency, restart/replay, crash-window, and provider risks visible. After two failed
+    independent reviews, another corrective Plan requires a distinct Auditor covering every
+    latest finding. The audit is append-only artifact evidence; no Task state field or schema
+    change is required.
+13. **Content-only context refresh.** A delegate may compose reconcile, approval, knowledge
+    rebind, and execution reauthorization only when the approved source classification is
+    identical and only content hashes changed. Core validates both delegated transitions
+    before writing. Source-set, category, scope, authority, gap, or conflict changes stay on
+    the ordinary visible approval path. State schema 2 and protocol 1 remain unchanged.
+14. **Autonomous chat and closure boundary.** A Milestone coordinator owns orchestration and
+    final acceptance while each required Task uses a dedicated user-visible Task chat.
+    `next` exposes the Milestone completion contract, and delegated acceptance retains the
+    delegate actor and exact state-bound MSA code.
+15. **Safe update preflight.** Dependency updates begin with a read-only preflight requiring
+    a clean checkout, no running Step, and no active writer lease. It does not install,
+    migrate, or mutate project state.
+16. **Claimed-C1 rescue is one guarded transition.** The alpha.6.1 backport may bypass only
+    the stale Knowledge binding that blocks one exact pending strict review. It requires the
+    original claimant actor and writer token, preserves the lease, rechecks clean completion
+    HEAD and C1 bindings, and never composes stale-lock repair with review.

package/docs/delegated-approval.md

@@ -52,6 +52,13 @@ delegation.transition
 acceptance still requires the current `MSA-*` code, preserving the revision/hash/HEAD binding;
 the pre-issued grant replaces only the later human-message requirement.
 
+Alpha.6 does not widen this allow-list. Delegated approval does not authorize:
+
+- `state adoption-apply`
+- `milestone scope-change-prepare`
+- `milestone scope-change-apply`
+- any replacement human gate for Milestone membership repair or scope decisions
+
 ## Starting a delegate chat
 
 A grant does not start an agent and is not attached to a Codex chat automatically. Open a new
@@ -74,6 +81,10 @@ scope changes are not approval transitions: the delegate stops and asks the user
 Independent Reviewer roles may implement or review work, but the coordinating delegate alone
 uses the grant and passes `--delegation-grant` to the Core transition.
 
+This matters more in alpha.6 because Milestone scope changes are explicitly journaled,
+human-only lifecycle actions. A delegate may continue ordinary Milestone execution only inside
+the already approved scope.
+
 ### Milestone delegate prompt
 
 Use project scope when the Milestone does not exist yet. An existing Milestone and its linked
@@ -99,8 +110,9 @@ project, status active, delegate, scope, transitions и expiresAt. Не созд
 вернул exact delegatedApprovalOptions для этого DGR-ID и transition; actor
 всегда agent:deputy, никогда user.
 
-Required Tasks выполняй последовательно. Для каждой Task можешь создать
-отдельный Codex-чат, передав ему Task delegate prompt, тот же actor и DGR-ID;
+Required Tasks выполняй последовательно. Для каждой Task обязательно создай
+отдельный пользовательский Codex-чат, передав ему Task delegate prompt, тот же actor и DGR-ID.
+Milestone-чат не реализует Steps и не накапливает fix-loop всех Tasks;
 не запускай два writer на одном checkout. Worker и Reviewer не используют
 grant: approval-команды выполняет только delegate-координатор после их evidence.
 
@@ -135,19 +147,32 @@ Authorization выполняй только когда текущий next со
 delegatedApprovalOptions для DGR-ID и task.execution_authorize; используй
 actor agent:deputy и --delegation-grant, не записывай actor user.
 
-Далее следуй штатному lifecycle: один Step - один writer lease - один commit,
-checks и evidence. Worker не использует grant. При изменении Knowledge Map
+Далее следуй штатному lifecycle: один Step - один writer lease. Worker меняет
+только разрешённые файлы и оставляет их uncommitted; затем координатор вызывает
+exact `task step-complete` из `next`, а core выполняет checks, создаёт commit и
+записывает evidence. Worker не использует grant. При изменении Knowledge Map
 выполни reconcile; approve разрешён только при exact project_memory.approve
 option этого project-scoped grant. Затем knowledge-rebind и новая authorization.
+Если next содержит exact `contextRefresh` для того же grant, можешь вместо четырёх
+команд выполнить `task context-refresh`; при любом изменении source set,
+category/authority, gaps или conflicts используй обычный видимый процесс.
 
 После submit запусти отдельный Independent Reviewer; Reviewer не использует
-grant и не исправляет код. Выполни допустимый fix-loop. Final acceptance делай
+grant и не исправляет код. После второго failed review не запускай очередной
+патч: получи отдельный corrective Plan audit, охватывающий все последние findings,
+и передай его через `--corrective-audit-file`. Продолжай только при
+`decision=continue-fix`; остальные решения верни пользователю/координатору.
+Final acceptance делай
 только при exact task.final_accept option для DGR-ID, затем штатный merge.
 Если option отсутствует, grant истёк, scope не совпал или требуется смысловое
 решение пользователя - остановись. В конце покажи Task status, commits, checks,
 review и delegated authorization event.
 ```
 
+Milestone coordinator waits for the dedicated Task chat to return its terminal Task status
+and merge evidence before starting the next required Task. Internal subagents inside one
+oversized Milestone chat are not a substitute for this user-visible Task boundary.
+
 After autonomous work, inspect the recorded events and revoke a broad grant when it is no
 longer needed. Revocation does not erase completed approvals.
 

package/docs/development-flow.md

@@ -21,10 +21,25 @@ Materialization requires an observable outcome, scope, acceptance criteria, and
 blocking unknowns. No Task identifier or branch exists before this gate. Task authorization
 is hash-bound to Brief and Plan. Later Plan changes supersede it.
 
+In alpha.6, execution authorization also requires a current Plan Risk Audit bound to the same
+Brief, Plan, Knowledge Map, and exact Step set. For existing schema 2 projects upgraded into
+alpha.6, execution additionally requires adoption posture first; remaining legacy scope then
+uses a bootstrap audit over the preserved non-`completed`, non-`skipped` Steps only.
+The audit names a Plan author and independent auditor, binds each guarded failure mode to
+exact executable evidence, and blocks authorization on `split-required` or `stop-escalate`.
+
 Local execution creates `codex/task-<id>-<slug>` from a clean base only after authorization.
 An externally owned checkout must already use a dedicated non-base branch. The core never
 creates or removes external worktrees. Each Step declares allowed writes, dependencies, and
-checks; unexpected paths or failed checks block its atomic commit.
+checks. `task run` dispatches exactly one Step and returns a writer lease. The Worker changes
+only allowed files and leaves them uncommitted. Repository-level `next` then returns the exact
+`task step-complete` transition for the active Step. That core transition runs checks, stages
+the allowed changes, creates the atomic Step commit, and records evidence. Unexpected paths,
+failed checks, or any manual/unrecorded Worker commit block completion.
+
+If the current Plan Risk Audit marks the Step for strict review, the atomic commit is still
+created by core, but the Step remains non-terminal and `next` routes to `task step-review`
+until commit-bound strict review and reviewer attestation pass.
 
 After a Step changes approved project knowledge, the Delivery Coordinator reconciles and
 reapproves the Project Knowledge Map, then runs `task knowledge-rebind` between Steps. The
@@ -35,12 +50,27 @@ active Worker Step, a no-op binding, an invalid knowledge target, or a modified
 artifact. After the user authorizes the rebound Plan, execution resumes in the existing
 workspace; if all Steps are complete, the next action is submission.
 
+When `next.contextRefresh` exposes an eligible project-scoped grant and content-only mode,
+`task context-refresh` may compose reconcile, delegated map approval, rebind, and delegated
+execution reauthorization. Core validates both approval transitions before writing and
+rejects any source-set, category, scope, authority, gap, or conflict change.
+
 Submission requires a clean, auditable Task history and records evidence for the exact
 Task head. `task review-launch` starts a separate read-only reviewer. A passing fresh review
 permits Result creation. Human final acceptance binds Brief, Plan, Result, evidence, and
 the accepted head. Base advancement forces synchronization, checks, review, and acceptance
 to be repeated before merge.
 
+The Technical Planner performs a risk review before authorization. Migration work includes a
+populated forward-upgrade check; concurrent state includes deterministic races; restart,
+replay, and crash claims include restart/crash-window evidence; provider work includes
+failure injection and hidden-default verification. After two failed independent reviews,
+another Plan requires a distinct corrective Auditor and `--corrective-audit-file`. Only a
+`continue-fix` audit may continue; replan, split, and stop decisions return to coordination.
+For guarded alpha.6 remediation, a third ordinary retry is blocked until a current
+`task corrective-decision` exists for the same Step and Plan binding. If that corrective
+attempt fails review, the third failure is a hard stop and no fourth run is permitted.
+
 Execution authorization and final acceptance use the human path by default. If the user has
 previously issued an active delegation grant for the exact transition and scope, the named
 delegate may perform that transition with `--delegation-grant`. The event keeps the delegate
@@ -63,6 +93,11 @@ and prevents new linked Tasks from starting. A Task that has started cannot be r
 it can be retained as waived/cancelled with history and reason. Tasks already in progress
 may finish while an amendment awaits authorization.
 
+After the initial empty planning posture, alpha.6 does not use ordinary `milestone plan-set`
+for scope changes. It uses human-only `milestone scope-change-prepare` and
+`milestone scope-change-apply`, with journaled recovery across `state.json`, `plan.json`, and
+`scope-change-events.jsonl`.
+
 A Milestone has no integration branch. Validation requires all required Tasks to be
 `merged`, checks the current clean base branch, and writes evidence plus Result. Final
 acceptance binds those artifacts to the unchanged base HEAD. Cancellation records a reason
@@ -87,6 +122,10 @@ With an eligible `milestone.final_accept` grant, `next` additionally returns
 turn because the earlier grant-issuance turn is the controlling user decision. Without such
 an option, the ordinary later-message human gate remains mandatory.
 
+The Milestone coordinator keeps implementation out of its long-lived context: every required
+Task runs in a dedicated user-visible Task chat. The Milestone chat owns ordering, exact
+delegated transitions, merge observation, cross-Task validation, and final acceptance.
+
 ## Responsibility boundaries
 
 | Participant | Responsible for | Cannot decide |