codex-workflow-v2 2.0.0-alpha.7.2.1 → 2.0.0-beta.2

package/plugins/codex-workflow-gateway/references/protocol.md

@@ -25,6 +25,8 @@ Current capability set:
 - `delegated-approval-v1`
 - `task-knowledge-rebind-v1`
 - `task-context-refresh-v1`
+- `terminal-task-replacement-transaction-v1`
+- `project-composite-transaction-journal-v1`
 - `corrective-plan-audit-v1`
 - `safe-update-preflight-v1`
 - `strict-reviewer-v1`
@@ -42,6 +44,7 @@ Current capability set:
 - `alpha6-adoption-posture-v1`
 - `alpha6-strict-review-rescue-v1`
 - `milestone-initial-assembly-v1`
+- `milestone-initial-assembly-navigation-v2`
 - `milestone-autonomy-contract-v1`
 - `milestone-autonomous-membership-evolution-v1`
 - `task-c1-derived-worker-actor-v1`
@@ -73,7 +76,9 @@ version, canonical entity summaries, and the current sidecar baseline hash. Adop
 
 ## Worker Step completion and strict Step Review
 
-`task run` dispatches one Step and returns its writer token and Worker envelope. The Worker
+`task run` dispatches one Step and returns a first-field `writerLeaseReceipt`, followed by the
+credential-free lease metadata, Task state, and Worker envelope. Consume the receipt before the
+remaining payload and retain its token only in working memory. The Worker
 must leave all changes uncommitted and must not stage, commit, amend, reset, rebase, or
 modify Git history.
 
@@ -82,11 +87,36 @@ While that Step is `in_progress`, repository-level `next` normally returns
 `workflow-core` ownership. The coordinator invokes that transition with the current revision
 and writer token. Core then runs configured checks, validates `allowedWrites`, stages the
 changes, creates the atomic commit, and records evidence.
+When `next` also includes `gitMutationPolicy`, obtain bounded permission for that exact
+Git-writing transition before the first call; do not probe and retry after a
+`.git/index.lock` failure. For `task start`, the policy applies only when the coordinator
+chooses `--workspace-owner local`.
+
+When `next` also includes `writerTokenContract`, the coordinator must retain the active writer
+lease from `writerLeaseReceipt` and pass it with the advertised option on the first transition call.
+The contract never contains the token value. Do not print, persist, reconstruct, or replace the
+token with a redacted fingerprint; stop before mutation when the active lease is unavailable.
+Satisfy this contract separately from any `gitMutationPolicy` on the same response.
+
+`codex-workflow <noun> [action] --help` is a read-only command-discovery route. It exits without
+constructing workflow state or validating lifecycle inputs. Use exact option lists only when the
+response says `exactOptionContractAvailable=true`; otherwise consult this packaged protocol. After
+help, obtain a fresh `next` before invoking the lifecycle transition.
 
 If the current Plan Risk Audit marks that Step for strict review, the commit is still
 workflow-owned, but `next` then returns `action: "task step-review"` with the same `stepId`
 and the exact `completionCommit`. Canonical Step completion remains blocked until the strict
 review and reviewer attestation sidecars verify against that exact commit.
+Invoke `task step-review` with the same lifecycle actor advertised by `next`
+(`c1Handoff.claimant` or `requiredActor` when present). The isolated reviewer is launched
+inside Core; do not substitute the reviewer identity into `--actor`. In claimed C1 posture,
+`next.writerTokenContract` is mandatory for both `task step-review` and the later
+`task review-launch`; pass the retained active lease on the first call of each exact action.
+
+After submission, a pending Task review is advertised as `action: "task review-launch"`, not
+`task review-record`. That compound route launches the read-only reviewer and atomically
+records the returned review. If claimant-bound mutation is active, pass the same lifecycle
+actor through `--actor`; reviewer identity remains internal to the route.
 
 An unrecorded commit is Git history drift. Stop instead of adding another commit or editing
 workflow state manually; recovery remains coordinator-controlled.
@@ -127,8 +157,16 @@ classifications. A planned new scanner-visible Knowledge file must be declared w
 directories, and inferred authority are not declarations; only Core may decide whether the final
 diff is eligible for delegated refresh.
 
-Use `task context-refresh` only when the same `next` response exposes `contextRefresh` for the
-exact grant. Pass Task revision, map revision, delegate actor, and grant ID. The composite
+For every `task plan-set` navigation, consume `next.taskPlanContract` before building the Plan.
+Its `requiredRequirementIds` and `requiredAcceptanceIds` are exact-membership preconditions, not
+descriptive hints. Preserve each ID verbatim in the corresponding Plan array and use the returned
+Brief hash plus Knowledge Map revision/hash as the planning binding. Missing or stale contract data
+is a stop condition.
+
+Use `task context-refresh` only when the same `next` response returns it as the top-level action and
+exposes `contextRefresh` for the exact grant. Pass Task revision, map revision, delegate actor, and
+grant ID. Never run standalone `project-memory reconcile` first; Core blocks that non-atomic route
+when the exact delegated composite is available. The composite
 operation accepts content-hash-only drift and, under a Milestone Autonomy Grant, an exact
 supporting-source addition predeclared by the current execution-authorized Task Plan. Core checks
 the full fail-closed predicate; do not reconstruct it in the gateway. When `next` instead returns
@@ -162,11 +200,28 @@ claimed, only the claimant may mutate the Task, and lease-bound mutations must p
 bound writer token. Milestone-linked Tasks must be claimed before start, and handback is
 terminal and evidence-bound. When target actor is omitted, Core derives
 `agent:worker:<task-id>`. No thread id is required or accepted as authority.
+The successful prepare response begins with `credentialHandoff`. Consume that receipt before the
+Task/event/bundle payload, retain its token only in working memory, and pass it exactly once to the
+declared `task claim --claim-token` action for the declared target actor. The later bundle remains
+contextual and intentionally contains no second copy of the claim token.
+The successful claim response then begins with `writerLeaseReceipt`. Retain that token only in
+working memory. In claimed C1 posture, fresh `next` exposes `writerTokenContract` on `task run`;
+pass the receipt token through its declared `--writer-token` option on the first run call. The
+successful run returns the refreshed writer receipt for later lease-bound transitions.
 
 ## Milestone assembly, autonomy, and human gate
 
 During initial planning, materialize every linked Task and then call `milestone plan-set` once
 with the complete membership. Execution is blocked while reverse membership is incomplete.
+Before Task 1 and between linked Tasks, follow top-level `next.action = "milestone initial-assembly"`.
+Its `linked-task-assembly.commands` permit `discovery start` and `discovery materialize`; after the
+first linked Task exists, the separate closing option permits `milestone plan-set`. If `status` or `next` fails, stop: never label
+the gap expected and invoke `milestone plan-set` directly.
+
+Every required navigation checkpoint is strictly sequential: start `status`, wait until its
+terminal result is recorded, then start `next` and wait for its terminal result. Never issue the
+pair concurrently or through a parallel tool call. The trusted transcript validator treats a
+second invocation before the first terminal result as indeterminate release evidence.
 
 After that Plan, one human may prepare and grant a maximum-72-hour Milestone Autonomy Contract:
 
@@ -223,6 +278,10 @@ transition matches the requested command, with the named delegate as actor and t
 as `--delegation-grant`. The resulting authorization event records the grant and both actors.
 For `milestone.final_accept`, also pass the current `MSA-*` code; the existing grant replaces
 the later-message requirement, not the state binding.
+Do not pass `--delegation-grant` to ordinary C1 handoff, claim, run, step-complete,
+step-review, merge, or sync-base calls. Those transitions are not authorized by a Milestone
+approval grant unless the same `next` response explicitly advertises an eligible grant for the
+exact transition.
 
 Delegated approval does not cover adoption apply or the ordinary semantic Milestone scope-change
 path. Membership-only evolution requires the separate Milestone Autonomy Contract.

package/plugins/codex-workflow-gateway/skills/codex-workflow-gateway/SKILL.md

@@ -51,12 +51,59 @@ scanner category. Do not replace the path with a wildcard or directory, do not i
 authority, and do not claim delegated-refresh eligibility; Core decides eligibility from the
 resulting repository diff and current authorization state.
 
-When `next` exposes an exact delegated `contextRefresh`, use `task context-refresh` only for
-the returned Task/map revisions, actor, and grant. A source-set change is eligible only when
+When `next.action` is `task plan-set` (including the corrective-audit variant), treat
+`next.taskPlanContract` as the exact transition precondition. Copy every
+`requiredRequirementIds` entry into Plan `requirements` and every `requiredAcceptanceIds` entry
+into Plan `acceptance` as exact array members; semantic prose may be added but cannot replace those
+IDs. Bind the Plan to the returned `briefHash` and active `knowledgeMap` revision/hash. Stop if the
+contract is absent or conflicts with the current Task/Knowledge state.
+
+When `next` returns top-level `action: task context-refresh`, use only that atomic action for
+the returned Task/map revisions, actor, and grant. Do not run standalone `project-memory reconcile`
+first: Core rejects it because it would create a human-approval gap and strand the Task. A
+source-set change is eligible only when
 Core identifies it as a Plan-bounded supporting-source addition under the same Milestone
 Autonomy Grant. Never infer eligibility from the Plan yourself; if Core returns
 `contextRefreshBlocked.unsafeDifferences`, use the ordinary visible Knowledge Map flow.
 
+When `next` reports terminal `split-required`, follow `docs/split-required-recovery.md` from the
+installed package. The only valid continuation is the exact `task replacement-materialize`
+transition (or creation of its one ready Discovery when requested). Never rebind, refresh, replan,
+authorize, or resume the historical Task, and never emulate the membership changes manually.
+
+When `next` returns `milestone initial-assembly`, execution is unavailable. Follow only the
+advertised `linked-task-assembly.commands` (`discovery start` and `discovery materialize`) until all
+intended linked Tasks exist. The closing `milestone plan-set` option appears only after at least one
+linked Task exists; use it once with the complete membership. After every boundary, run `status`,
+wait for its terminal success, and only then run `next`; never launch the checkpoint pair in
+parallel or in one parallel tool batch. If either fails, stop; do not
+describe the reverse-membership gap as expected and invoke a direct closing command.
+
+When `next` includes `gitMutationPolicy`, obtain bounded permission for that exact Git-writing
+transition before the first call. Do not probe and retry after a `.git/index.lock` failure.
+For `task start`, the policy applies only when choosing `--workspace-owner local`; for
+`task step-complete`, `task merge`, and `task sync-base`, the advertised transition itself
+writes Git metadata.
+
+When `next` includes `writerTokenContract`, treat it as an exact first-call precondition. Retain
+the active writer lease from the first-field `writerLeaseReceipt` returned by `task run` and pass it using the advertised `option` for that
+transition. The token is sensitive: never print, summarize, persist, or substitute a redacted
+fingerprint. Stop before mutation if the active lease is unavailable. This input contract is
+independent from `gitMutationPolicy`; satisfy both when both are present.
+
+On successful `task handoff-prepare`, consume the first-field `credentialHandoff` before reading
+the Task/event/bundle payload. Retain its one-time token only in working memory and use it exactly
+once with the declared `action` and `option` for the declared `targetActor`. Successful `task claim`
+returns a first-field `writerLeaseReceipt`; retain that lease and pass it to claimed `task run` when
+the fresh `next.writerTokenContract` requires it. Successful `task run` returns the refreshed
+`writerLeaseReceipt`; retain it only until Core releases that lease.
+Never search later payload fields for either credential and never copy credentials into evidence.
+
+Command discovery with `codex-workflow <noun> [action] --help` is read-only. Use it only when the
+exact invocation syntax is not already available from `next` and this protocol. Consume declared
+`requiredOptions` and `optionalOptions`; when `exactOptionContractAvailable=false`, consult the
+packaged protocol instead of guessing. Help never replaces a fresh `next` before mutation.
+
 ## Product Or Workflow Graph Refresh
 
 1. Run `graph refresh-request --kind product|workflow --mode moderate`.
@@ -111,6 +158,9 @@ Never create, broaden, renew, or replace a grant from an agent's own judgment. N
 the delegate as the user. When `next` exposes an eligible option, pass its grant ID through
 `--delegation-grant` and use the exact delegate string as `--actor`. The core remains the
 authority for status, expiry, scope, transition, and revocation checks.
+If the same `next` response does not expose an eligible option for that exact transition, do
+not pass `--delegation-grant`. Ordinary C1 handoff, claim, run, step-complete, step-review,
+merge, and sync-base do not inherit a Milestone approval grant.
 
 For delegated Milestone final acceptance, the current `MSA-*` code is still required, but a
 new user turn is not: the previously issued grant is the controlling decision. If no eligible
@@ -149,5 +199,6 @@ returns `safe=true` with a clean checkout, no running Step, and no active writer
 - A request changes before evidence is bound.
 - An action would make MCP or the local map authoritative project memory.
 - A requested mutation is not authorized by the package CLI state.
+- A lifecycle `status` or `next` failed; do not continue with a different lifecycle mutation.
 - A human gate was emitted but the user has not approved its exact confirmation code in a
   later message and no exact eligible delegated approval option exists.

package/references/state-machine.md

@@ -63,7 +63,10 @@ human turn boundary.
 
 During initial planning, all linked Tasks may be materialized before one complete
 `milestone plan-set`; execution remains blocked until every reverse membership is classified.
-After that boundary, semantic updates use human-only `milestone scope-change-prepare` and
+`next` returns `milestone initial-assembly` before Task 1 and after every safe linked-Task
+materialization, with explicit `discovery start` and `discovery materialize` commands. After at
+least one linked Task exists, it also exposes the closing `milestone plan-set` command. Failed navigation is fail-closed and cannot be treated as an
+expected assembly signal. After that boundary, semantic updates use human-only `milestone scope-change-prepare` and
 `milestone scope-change-apply`. A human-confirmed, expiring Milestone Autonomy Contract may
 use `milestone autonomy-evolve` only for membership changes while outcome, success signal,
 acceptance, checks, discovery, and base branch remain fixed. It may also approve Project Memory

package/schemas/task.schema.json

@@ -52,6 +52,8 @@
         },
         "additionalProperties": false
       }
-    }
+    },
+    "replacementForTaskId": { "type": ["string", "null"], "pattern": "^TASK-[0-9A-HJKMNP-TV-Z]{26}$" },
+    "replacedByTaskId": { "type": ["string", "null"], "pattern": "^TASK-[0-9A-HJKMNP-TV-Z]{26}$" }
   }
 }