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

package/docs/autonomy-guardrails.md

@@ -48,6 +48,9 @@ If the current Plan Risk Audit marks a Step for strict review, `task step-comple
 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.
+When `next` advertises `task step-review`, pass the exact claimant or required actor as
+`--actor`; the isolated reviewer identity is created inside Core and must not be substituted
+into the mutation actor slot.
 
 Invalid or stale review sidecars fail closed. The workflow blocks downstream acceptance and
 normal continuation when review evidence is malformed, unverified, or commit-mismatched.
@@ -88,8 +91,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
@@ -150,7 +154,11 @@ current `MSA-*` code. Without that option the ordinary later-message human gate
 ## Bounded Milestone autonomy and C1 handoff
 
 Initial assembly may materialize every linked Task before one complete `milestone plan-set`;
-the Milestone cannot execute until all reverse memberships are classified. Ordinary semantic
+the Milestone cannot execute until all reverse memberships are classified. During that exact
+window `next` returns non-executable `milestone initial-assembly` navigation with explicit
+linked-Task Discovery/materialization options; the closing Plan option appears after the first
+linked Task exists. A failed navigation call must not
+be bypassed with a direct Plan command. Ordinary semantic
 scope change remains explicit and human-only through `milestone scope-change-prepare` and
 `milestone scope-change-apply`.
 

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.