codex-workflow-v2 2.0.0-beta.1 → 2.0.0-beta.11

package/docs/development-flow.md

@@ -28,6 +28,16 @@ uses a bootstrap audit over the preserved non-`completed`, non-`skipped` Steps o
 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`.
 
+P01-A adds a second, bounded admission check without adding a lifecycle stage. Before
+`task authorize`, Core reads the selected committed source and recognizes only three versioned
+mechanical forms: an exact root `npm run <literal-script>`, an exact structured
+`path:<repository-relative POSIX path>` output, and that same path supplied by an exact transitive
+Step predecessor with write authority. A proved contradiction returns to `task plan-set` without
+writing an approval. Unsupported commands, prose, or ambiguous future creation remain
+`unverified`, not pass or failure. A clear payload is stored inside the execution authorization,
+bound to the Brief, Plan, analyzer inputs/set, selected HEAD, and phase-aware base/Task branch.
+Freshness is checked before claim lease acquisition, Task start, and direct execution entry.
+
 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
@@ -40,6 +50,11 @@ 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.
+Use the exact claimant or required actor from `next` as `--actor`; the independent reviewer
+runs inside Core and is not supplied as the CLI actor.
+When `next` includes `gitMutationPolicy`, obtain bounded permission for that exact Git-writing
+transition before the first call instead of probing and retrying after a `.git/index.lock`
+failure. For `task start`, this applies only when invoking `--workspace-owner local`.
 
 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
@@ -58,7 +73,9 @@ additions under Milestone autonomy; every unsafe source-set, category, scope, au
 conflict change is rejected.
 
 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
+Task head. `task review-launch` starts a separate read-only reviewer and atomically records its
+result. If C1 handoff is active, keep `--actor` equal to the current claimant or required actor
+from `next`; the reviewer identity remains internal to the compound route. 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.
@@ -73,6 +90,14 @@ For guarded 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.
 
+One bounded exception avoids a deliberately repeated failure for an older authorization without
+P01-A evidence or a contradiction that becomes observable only after execution starts. If the first guarded check failure
+is caused by an absent root npm script that the Step cannot add because `package.json` is outside
+its `allowedWrites`, fresh `next` advertises `task plan-integrity-recover`. The command records only
+the exact evidence-bound early `replan-required` posture; it never edits source, Plan, or Git.
+Continue through the advertised corrective yield and corrective replan rather than calling
+`task run` again.
+
 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
@@ -88,7 +113,10 @@ Discovery -> Milestone planning -> execution authorization -> active
   -> final acceptance -> accepted
 ```
 
-A Milestone Plan records outcome, success signal, acceptance, checks, and Task membership.
+A Milestone Plan records outcome, success signal, acceptance, checks, Task membership, and the
+canonical Task dependency DAG. Every membership explicitly supplies `dependsOnTaskIds`, including
+`[]`. A required consumer may depend only on required members of the same Milestone; duplicate,
+self, dangling, external, non-required-provider, and cyclic edges are rejected before commit.
 Membership is `required`, `waived`, or `cancelled`; non-required entries require a reason.
 Changing the Plan increments the membership revision, supersedes execution authorization,
 and prevents new linked Tasks from starting. A Task that has started cannot be removed;
@@ -97,24 +125,33 @@ may finish while an amendment awaits authorization.
 
 During initial planning, all linked Tasks may be materialized before one complete
 `milestone plan-set`; no execution is available until the Plan classifies every reverse
-membership. After that boundary, semantic changes use human-only
+membership. Repository `next` returns `milestone initial-assembly` both before Task 1 and between
+linked Tasks. Its `linked-task-assembly` option explicitly permits `discovery start` and
+`discovery materialize`; after the first linked Task exists, its closing option permits one
+complete `milestone plan-set`. A failed
+`status` or `next` is not permission to call the closing command directly. After that boundary,
+semantic changes use human-only
 `milestone scope-change-prepare` and `milestone scope-change-apply`. A previously issued
 Milestone Autonomy Contract may instead use `milestone autonomy-evolve` for membership-only
 changes while the outcome, success signal, acceptance, checks, discovery, and base branch
 remain unchanged. The same contract may complete an atomic content-only Task context refresh
 without a new human gate, but cannot approve Project Memory independently. Both paths retain
-journaled recovery across `state.json`, `plan.json`, and `scope-change-events.jsonl`.
+journaled recovery across `state.json`, `plan.json`, and `scope-change-events.jsonl`. The initial
+Plan uses the same recovery machinery for its exact two-file `state.json` + `plan.json` commit and
+does not manufacture a scope-change event.
 
 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
 and never changes Task state or reverts merged commits.
 
-Repository-level `next` considers Milestone membership before it dispatches a Task. An
-unstarted linked Task is actionable only while its Milestone is `active` and its current
-membership is `required`. Unstarted `waived`/`cancelled` memberships and Tasks belonging to
+Repository-level `next` considers Milestone membership and dependencies before it dispatches a
+Task. A linked Task is actionable only while its Milestone is `active`, its current membership is
+`required`, and every declared required predecessor is `merged`. Handoff prepare, claim before
+lease acquisition, and Task start use the same predicate. Unstarted `waived`/`cancelled`
+memberships and Tasks belonging to
 an accepted/cancelled Milestone are historical records, not work. A Task that already owns
-a workspace remains actionable while its non-terminal Milestone permits it to finish.
+a workspace does not bypass an unsatisfied Milestone predecessor.
 
 After successful Milestone validation, `next` emits `requiredHumanGate` containing the
 Milestone revision, Plan/Result/evidence hashes, validated base HEAD, and a deterministic
@@ -128,11 +165,29 @@ With an eligible `milestone.final_accept` grant, `next` additionally returns
 `delegatedApprovalOptions`. The delegate may then use the current `MSA-*` code in the same
 turn because the earlier grant-issuance turn is the controlling user decision. Without such
 an option, the ordinary later-message human gate remains mandatory.
+Pass `--delegation-grant` only when the same `next` response exposes an exact eligible
+`delegatedApprovalOptions` entry for that transition. Ordinary C1 handoff, claim, run,
+step-complete, step-review, merge, and sync-base do not consume a Milestone approval grant.
 
 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.
 
+The coordinator creates that chat as a new standalone Codex task, never as a fork/handoff of its
+own thread, and sends only a fresh TaskContextPacket for the exact Task. It creates or reuses the
+chat just before dispatch, not as an empty membership placeholder. The project registry allocates
+one monotonic `#NNN` and builds `#NNN · M<NN> · Coord · <Milestone title> · <MS-ID>` or
+`#NNN · M<NN>/T<NN> · Task · <Task title> · <TASK-ID>`; the Task ordinal still comes from approved
+membership order. Exact readback and registry-owned fallback are mandatory.
+
+Dispatch is followed by an explicit coordinator supervision loop. The Milestone chat waits on the
+one currently routed Task chat with bounded `wait_threads` calls, reads it when it completes or
+needs attention, and then verifies repository `status -> next`. A recoverable non-human boundary is
+returned to the same chat with `send_message_to_thread`; only a genuine user/semantic gate or
+unrecoverable blocker ends the coordinator turn. The next Task chat is created only after Core
+confirms that the prior required Task is terminal and merged. Task completion does not implicitly
+wake a coordinator that has already ended its turn.
+
 ## Responsibility boundaries
 
 | Participant | Responsible for | Cannot decide |