codex-workflow-v2 2.0.0-alpha.7.2 → 2.0.0-beta.1

package/docs/alpha7.2.1-remediation-recovery-brief.md

@@ -0,0 +1,86 @@
+# Codex Workflow V2 2.0.0-alpha.7.2.1 — remediation recovery brief
+
+## Source and scope
+
+Source release: `v2.0.0-alpha.7.2` at
+`1d5b09f0116ea241b9b5f71c0fa3320ac4318891`.
+
+This is a narrow lifecycle patch. It does not change product scope, Milestone
+semantics, the three-attempt guarded-review limit, or historical events in
+place. `signal_v4` is read-only evidence and must be replayed only from a copy
+of its workflow state.
+
+## Reproduced defects
+
+### D1 — recovered third attempt is recorded as ordinary
+
+After two ordinary failures, an authorized `continue-fix`, a Knowledge-only
+Plan rebind, and alpha.7.2 corrective recovery, `task run` correctly permits
+attempt ordinal 3. If that run later fails checks or strict review, the failure
+writer loses the recovery binding and appends remediation ordinal 3 with
+`mode=ordinary`. The same Core then rejects its own event as `STATE_CORRUPT`.
+
+Exact production evidence:
+
+- Task `TASK-01M00W190K3V3HM68Q3QVSH1AY`;
+- Step `STEP-002-FORMALIZATION-CONTRACTS`;
+- corrective decision `CRD-01M011B4MM5R1FZG2DSDRHVXJ4`;
+- recovery `CDR-01M01ST9ENGH4F3W5TRJ9EC53C`;
+- malformed remediation `RME-01M01TBQ4P5KR24J51WTMT79DY`;
+- ordinal `3`, stored mode `ordinary`, required effective mode `corrective`.
+
+### D2 — `next` advertises an impossible context refresh
+
+With an active Step and Knowledge drift from its uncommitted allowed writes,
+`next` may advertise delegated `task context-refresh`, while the transition
+correctly rejects any refresh during `Step=in_progress`. The truthful action is
+the active Step action (`task step-complete`, then strict review). Knowledge
+refresh follows only after the Step becomes terminal.
+
+## Required behavior
+
+1. Every guarded failure writer (`checks-failed`, `review-failed`, and
+   `review-unverified`, including retry/idempotence paths) must preserve the
+   exact validated corrective-recovery binding and record ordinal 3 as
+   `corrective`.
+2. Alpha.7.2 legacy state with exactly the D1 shape must have one explicit,
+   append-only recovery transition. The original remediation event and its
+   hash chain remain byte-for-byte unchanged.
+3. The recovery event binds the exact Task, Step, Task revision, malformed
+   remediation ID/hash, corrective decision ID/hash, corrective recovery
+   ID/hash, ordinal, Plan hash, actor, and mode correction
+   `ordinary -> corrective`.
+4. Recovery validation and authority checks occur before the first write.
+   Failure is non-mutating; identical retry is idempotent; conflicting or
+   duplicate recovery fails closed.
+5. After recovery, `next` must expose the existing guarded hard stop with only
+   `split-required` and `stop-escalate`. A fourth remediation run remains
+   prohibited.
+6. Any other ordinal, mode, decision, Plan, event-chain, review evidence,
+   recovery evidence, actor/token, Task/Step status, or duplicate shape is not
+   recoverable.
+7. While a Step is active, `next` must return its executable Step action and
+   must not advertise `task context-refresh` or standalone Project Knowledge
+   work that the exact transition ordering rejects.
+
+## Deterministic evidence
+
+- Future path: two failures → recovered continue-fix → run → failed checks and
+  failed/unverified strict-review variants → ordinal 3 is corrective. Failed
+  checks/review reach hard stop; unverified isolation permits only strict-review
+  retry for the same completion commit and never another run.
+- Legacy path: copy exact malformed alpha.7.2 state → `next` advertises the
+  explicit recovery → recovery append → identical retry is idempotent →
+  original files unchanged except the new recovery sidecar → `next` advertises
+  hard stop, never `task run`.
+- Negative cases cover mismatched IDs/hashes/revision/actor/token, missing or
+  ambiguous recovery, broken event chains, non-ordinal-3 events, and repeated
+  conflicting recovery.
+- Navigation parity: active Step plus eligible Knowledge drift returns
+  `task step-complete`; after completion it returns strict review before any
+  context refresh.
+
+## Release boundary
+
+Stop after full deterministic validation, exact disposable `signal_v4` replay,
+and self-review. Do not tag, push, publish, or mutate `signal_v4`.

package/docs/autonomy-guardrails.md

@@ -88,8 +88,9 @@ not a human approval, while auditor independence remains mandatory.
 
 ## Atomic context refresh
 
-When `next.contextRefresh` offers an exact option, a project-scoped delegate may run one
-composite transition:
+When `next` returns top-level `action: task context-refresh` with an exact option, a
+project-scoped delegate may run one composite transition and must not run standalone reconcile
+first:
 
 ```text
 task context-refresh

package/docs/beta1-stabilization-brief.md

@@ -0,0 +1,165 @@
+# Codex Workflow V2 2.0.0-beta.1 Stabilization Brief
+
+Status: implementation complete; release candidate awaiting user authorization for commit/tag/push/publish
+
+Baseline: `v2.0.0-alpha.7.2.1` (`1214b4c`)
+
+Primary evidence register: [stable-release-defect-register.md](stable-release-defect-register.md)
+
+## Objective
+
+Produce one feature-frozen beta release that closes every confirmed workflow defect found during
+the `signal_v4` Milestone 3 alpha.7 replay, resolves or evidence-closes the remaining validation
+concurrency investigation, preserves every alpha.7 regression guard, and proves that a real agent can
+recover a terminal `split-required` Task by creating a replacement Task without reviving or rewriting
+the historical Task.
+
+No intermediate npm version is published. `signal_v4` and its external workflow state are read-only
+evidence. Workflow V2 is not used to organize this repository's implementation.
+
+## Release scope
+
+### B1 — Secret-safe lock recovery (`WF-STABLE-001`)
+
+- `locks repair` must never expose a plaintext writer token in ordinary CLI JSON, logs, errors, or
+  snapshots.
+- A repaired lease may expose only non-authorizing metadata and a token fingerprint.
+- If ownership recovery needs a new credential, it must use an explicit one-time handoff boundary
+  rather than a reusable token in general diagnostics.
+
+### B2 — Terminal corrective routing and replacement (`WF-STABLE-002/003`)
+
+- `split-required` and `stop-escalate` outrank Project Knowledge reconcile, approval, rebind, context
+  refresh, authorization, and Task run.
+- `task knowledge-rebind` and `task context-refresh` reject these postures before their first write.
+- A Project Knowledge change cannot detach a terminal corrective decision from its historical Plan.
+- `next` must expose an explicit replacement route for `split-required`; `stop-escalate` remains a
+  hard stop.
+- Replacement must be one journal-recoverable transition that:
+  - consumes one ready Task Discovery;
+  - materializes a new Task with a new ID and the same active Milestone;
+  - changes the old membership from `required` to `cancelled` with a reason;
+  - adds the replacement as `required` with an explicit relationship reason;
+  - marks the old Task `cancelled` without changing its Plan, Steps, review, remediation, corrective,
+    result, or evidence history;
+  - revokes the cancelled Task's writer lease in the same recoverable transaction;
+  - absorbs exact safe Plan-bound Knowledge drift through the active Milestone Autonomy Grant in
+    that transaction, so the replacement Task can be planned without a stranded standalone gate;
+  - supersedes Milestone execution authorization and increments membership revision;
+  - leaves no orphan Task or partial membership state after process interruption;
+  - is idempotently recoverable from its journal.
+- Normal standalone Project Knowledge actions must identify a triggering Task only as diagnostic
+  provenance, never as implied Task authorization.
+- When an exact delegated atomic context refresh is eligible, `next` must return it as the top-level
+  action and standalone reconcile must fail before writing; an agent cannot create an avoidable
+  human-approval gap by selecting the nested Project Knowledge sub-transition.
+
+### B3 — Update/base diagnostics and canonical recovery guidance (`WF-STABLE-004/005`)
+
+- Update diagnostics must distinguish the current checkout from an active Milestone base branch and
+  report exact declared, locked, installed, current-branch, and base-branch workflow versions.
+- Divergence must fail closed before lifecycle work continues and must recommend dependency-only
+  transport rather than merging product commits.
+- Documentation must include one canonical `split-required` recovery prompt and exact ordering for
+  replacement, membership evolution, Milestone reauthorization, new Task planning, and execution.
+
+### B4 — Composite context-refresh durability (`WF-STABLE-006`)
+
+- Project Knowledge reconcile/approval, Task Plan rebind, rebound risk-audit evidence, and execution
+  authorization must use a recoverable multi-file transaction.
+- All semantic and authority checks happen before the first target write.
+- Crash recovery is deterministic and idempotent at every write boundary.
+- `doctor`, `status`, and `next` detect an incomplete transaction and return the exact recovery action;
+  no partial refresh is treated as authorized.
+
+### B5 — Deterministic maintainer validation (`WF-STABLE-007`)
+
+- Reproduce or disprove shared-output contention between full validation commands.
+- If confirmed, serialize destructive build/test output preparation or isolate per-run artifacts.
+- Concurrent invocation must either complete independently or fail immediately with a clear,
+  non-secret diagnostic; it must not hang silently.
+- Child processes and temporary resources are cleaned up after interruption.
+
+## Required deterministic evidence
+
+1. Exact `signal_v4` replay:
+   `split-required -> Knowledge Map 169 active -> next replacement -> replacement transaction -> old
+   Task immutable/terminal -> new required Task planning`.
+2. Negative rebind/context-refresh tests for `split-required` and `stop-escalate` proving zero writes.
+3. Replacement rejection tests for wrong Task, wrong Milestone, wrong decision, non-ready Discovery,
+   semantic Milestone changes, stale revisions, expired/wrong actor autonomy, corrupt sidecars, and
+   duplicate retries.
+4. Crash injection before and after every replacement and context-refresh transaction write.
+5. CLI/output scans proving writer tokens are absent.
+6. Base-version divergence tests for clean and dirty repositories and unrelated product commits.
+7. Concurrent validation reproduction with bounded completion.
+8. All existing unit, integration, milestone, alpha.6, alpha.7, packaging, plugin, downstream smoke,
+   release, and root regression checks.
+
+## Real-agent acceptance
+
+Create a fresh disposable downstream project with isolated `CODEX_HOME`, workflow state, plugin root,
+and a locally packed beta candidate. A real Delegate must complete:
+
+1. Discovery and initial Milestone assembly.
+2. A guarded Task with three failed strict reviews, `continue-fix`, and a terminal
+   `split-required` decision.
+3. A Project Knowledge change and human-style approval boundary.
+4. The exact replacement transition without rebind of the failed Task.
+5. Replacement Task implementation, review, merge, remaining required Task completion, Milestone
+   validation, and final acceptance.
+
+The E2E is invalid if the harness injects lifecycle failures, edits external state, reuses a stale
+plugin cache, bypasses `next`, or requires a fourth remediation attempt.
+
+## Final evidence
+
+- Deterministic package suite: all beta.1 transaction, terminal-routing, Knowledge refresh,
+  diagnostics, concurrency, alpha.6, alpha.7, integration, Milestone, and workflow regressions pass.
+- Crash replay covers rollback and dead-process roll-forward at every tested write boundary,
+  including deletion of the cancelled Task writer lease.
+- Real-agent disposable run:
+  `test-runs/2.0.0-beta.1/replacement-e2e-final`.
+- Historical Task `TASK-01M02N276D6AE83VBVRH17RDQY` ended `cancelled` at revision 18 and links to
+  replacement Task `TASK-01M02NMZZBVCA4TZKK6WG724RY`.
+- Replacement Task passed its guarded Step review and independent final review, then merged as
+  `c8d45be7f3165731cf891a47e88a112f76d0119f`.
+- Milestone `MS-01M02N1M9M1CT8RHYGSZH8ETHC` reached `accepted` revision 7; final `next` returned
+  repository `idle`.
+- The run exposed one additional bounded UX defect: local replacement start initially required a
+  manual return from the cancelled Task branch to `main`. The final candidate makes local Task start
+  create its branch from the exact declared base ref even when another clean Task branch is checked
+  out, with a deterministic regression.
+
+## Non-goals
+
+- Fixing the downstream `signal_v4` NUL validator in this repository.
+- Deleting historical Milestones, Tasks, branches, chats, worktrees, or append-only evidence.
+- Broadening delegated authority or removing human final acceptance.
+- Publishing, tagging, pushing, or modifying `signal_v4` without separate user authorization.
+- Declaring `2.0.0` stable before the new real `signal_v4` Milestone completes successfully.
+
+## Release gate
+
+`2.0.0-beta.1` is recommended only when all confirmed findings are closed, every investigation is
+resolved with evidence, deterministic and crash replay pass, the real-agent disposable Milestone
+reaches final acceptance, an independent final audit has no unresolved material finding, and the
+release diff contains no downstream product implementation.
+
+## Final audit and residual risks
+
+No material requirement gap remains in the beta.1 scope. The final source audit confirmed that
+authority checks precede replacement/context-refresh target writes, cancelled Task authority is
+deleted inside the same recoverable transaction, terminal decisions outrank Knowledge navigation,
+and ordinary CLI output contains no reusable writer credential.
+
+Residual beta risks are bounded:
+
+- the project journal is a local-process/local-filesystem recovery protocol, not a distributed
+  cross-host transaction service; cross-machine synchronization remains outside the package
+  contract;
+- the final real-agent run encountered and safely recovered the clean-branch start precondition;
+  the final candidate fixes that behavior and covers it deterministically, but the entire long E2E
+  was not repeated solely for that Git convenience change;
+- `2.0.0` stable remains gated on a successful new real `signal_v4` Milestone, as stated in the
+  non-goals.

package/docs/delegated-approval.md

@@ -160,9 +160,10 @@ exact `task step-complete` из `next`, а core выполняет checks, со
 записывает 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 используй обычный видимый процесс.
+Если next возвращает top-level `action: task context-refresh` и exact `contextRefresh` для того же
+grant, выполни только `task context-refresh`; не запускай перед ним standalone reconcile. Exact
+Plan-declared supporting additions допустимы только когда их признал Core. При любом другом
+изменении source set, category/authority, gaps или conflicts используй обычный видимый процесс.
 
 После submit запусти отдельный Independent Reviewer; Reviewer не использует
 grant и не исправляет код. После второго failed review не запускай очередной

package/docs/development-flow.md

@@ -50,10 +50,12 @@ 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

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

@@ -20,14 +20,21 @@ The downstream smoke packs the actual tarball, installs it into an empty tempora
 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.1, 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.
+
+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,53 @@
+# 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` and `next`. 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` and `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
+   `status` and `next` 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.