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

package/docs/development-flow.md

@@ -40,6 +40,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
@@ -50,13 +55,17 @@ 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.
+When `next` returns top-level `action: task context-refresh` with an eligible grant,
+`task context-refresh` composes reconcile, delegated map approval, rebind, and delegated
+execution reauthorization. Do not run standalone reconcile first. Core validates both approval
+transitions before writing. It permits content-only drift and exact Plan-declared supporting-source
+additions under Milestone autonomy; every unsafe source-set, category, scope, authority, gap, or
+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.
@@ -95,7 +104,12 @@ 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
@@ -126,6 +140,9 @@ 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

package/docs/project-memory.md

@@ -30,12 +30,14 @@ definition, status, and evidence record, records the old/new binding, supersedes
 authorization, and cannot run while a Step is in progress. If local state is lost, the map
 is rebuilt from repository files.
 
-For delegated autonomy, repository `next` may expose `contextRefresh` when the stored map was
-active and inspection proves content-hash-only drift. `task context-refresh` then performs
+For delegated autonomy, repository `next` returns top-level `action: task context-refresh` and an
+exact `contextRefresh` option when the stored map was active and inspection proves eligible drift.
+Do not run standalone reconcile first. `task context-refresh` then performs
 reconcile, delegated map approval, Task rebind, and delegated execution authorization while
-preserving the ordinary audit events. The command rejects new/removed sources, category,
-scope or authority changes, changed gaps, and conflicts. Those changes always remain visible
-for normal classification and approval.
+preserving the ordinary audit events. In addition to content-only drift, a Milestone Autonomy Grant
+may admit one or more exact Plan-declared supporting sources. The command rejects removed,
+undeclared, canonical, category/scope/authority-changing, gap-changing, and conflicting sources.
+Those changes remain visible for normal classification and approval.
 
 ## Codebase graph
 

package/docs/release.md

@@ -15,19 +15,33 @@ Before tagging a release:
 5. `npm run plugin:check`
 6. `npm run release:check`
 7. validate `plugins/codex-workflow-gateway` with the Codex plugin validator
+8. validate the append-only real-agent log with
+   `node scripts/validate-lifecycle-transcript.mjs --file <lifecycle-log.jsonl>`
 
 The downstream smoke packs the actual tarball, installs it into an empty temporary project,
 runs the packaged CLI handshake, and proves installation created none of `.codex`, `.tasks`,
 `.increments`, or `.memory-bank` in that project.
 
-For alpha.7, the release gate also relies on `npm run release:check` to fail if:
+For beta.2, the release gate also relies on `npm run release:check` to fail if:
 
 - canonical entity schema 2 shapes drift;
 - protocol 1 compatibility is no longer additive;
 - the delegated transition allow-list expands;
 - schema-2 adoption is presented as `state migrate` instead of posture sidecars;
 - alpha.7 rescue, Milestone autonomy (including guarded content refresh), derived actor, or
-  proof-obligation capabilities and schemas are absent from the packaged surface.
+  proof-obligation capabilities and schemas are absent from the packaged surface;
+- terminal Task replacement, project-level transaction recovery, secret-safe lock diagnostics,
+  version/base diagnostics, or serialized maintainer validation are missing.
+- truthful initial-assembly navigation capability is absent from the packaged surface.
+
+The separate lifecycle transcript validator fails if the real-agent log contains a mutation that
+bypasses failed `status`/`next`, an unadvertised or failed mutation, an unresolved syntax-only
+retry, or missing post-mutation checkpoints.
+
+Full `npm test` and `npm run validate` invocations share destructive build outputs and are therefore
+single-owner operations. A concurrent invocation fails immediately with
+`VALIDATION_ALREADY_RUNNING`; retry it after the owner exits. Stale process locks are recovered
+automatically.
 
 Tag releases as `v<package-version>`. The tag workflow verifies the tag/package match and
 uses npm trusted publishing with public access. For a public GitHub repository and public

package/docs/split-required-recovery.md

@@ -0,0 +1,54 @@
+# Canonical `split-required` recovery
+
+Use this procedure only when the exact package-local `next` response identifies a terminal
+`split-required` decision. Never rebind, refresh, replan, authorize, or resume the historical Task.
+
+## Delegate prompt
+
+```text
+Continue the active Milestone through the package-local codex-workflow-v2 Core only.
+
+1. Run `codex-workflow status --repo .` and `codex-workflow next --repo .`. Treat every returned
+   revision and action as authoritative. Stop on corruption, stop-escalate, version divergence, or
+   an unexpected action. Do not edit workflow state or sidecars.
+2. Confirm that `next` reports the historical Task as `split-required`. Do not run
+   `task knowledge-rebind`, `task context-refresh`, `task plan-set`, `task authorize`, or `task run`
+   for that Task.
+3. If `next` says `discovery start`, create one thin replacement Discovery containing only the
+   failed Step's remaining outcome, exact acceptance, constraints, and explicit out-of-scope. Make
+   it `ready_to_materialize`, then run `status` and `next` again.
+4. When `next` returns `task replacement-materialize`, run that exact command with its old Task,
+   Discovery, and Milestone revisions, a precise replacement title, and the current authorized
+   actor. This single transaction must consume the Discovery, cancel/link the historical Task,
+   create/link the replacement Task, change both memberships, supersede Milestone execution
+   authorization, and leave the Milestone awaiting reauthorization. Do not perform a separate
+   scope change for these effects.
+5. Run `status`, wait for terminal success, then run `next`; never issue the pair in parallel.
+   Verify: old Task `cancelled`; old membership `cancelled`; new Task
+   `planning` and `replacementForTaskId` points to the old Task; new membership `required`;
+   Milestone `awaiting_execution_authorization`. If any relation is missing, stop and run `doctor`.
+6. Follow the exact `next` transition to reauthorize the changed Milestone. Run `status` to
+   terminal success and then `next` again. Do not reuse the historical Task's Plan or authorization.
+7. Plan the replacement Task from its own Brief, record the required Plan Risk Audit, authorize it,
+   prepare and claim its C1 handoff, and execute only the exact Step returned by `next`. Run
+   sequential `status` then `next` checkpoints after every state boundary.
+8. Complete review, final acceptance, merge, remaining required Tasks, Milestone validation, and
+   Milestone final acceptance through exact Core transitions. Never create a fourth remediation
+   attempt for the historical Task.
+```
+
+## Exact replacement command shape
+
+```sh
+codex-workflow task replacement-materialize --repo . \
+  --id TASK-OLD \
+  --expected-revision OLD_TASK_REVISION \
+  --discovery DISC-REPLACEMENT \
+  --expected-discovery-revision DISCOVERY_REVISION \
+  --expected-milestone-revision MILESTONE_REVISION \
+  --title "Thin replacement title" \
+  --actor agent:milestone-coordinator
+```
+
+Copy revisions from the same `next` response. If multiple ready Discoveries exist, Core refuses to
+guess; choose the intended Discovery explicitly after reviewing its raw content.