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

package/docs/validation-report.md

@@ -1,56 +1,124 @@
-# V2 Alpha Validation Report
-
-Release candidate `2.0.0-alpha.7` was validated on 2026-08-14 with Node.js 24.17.0.
-
-- TypeScript typecheck and build passed.
-- The authoritative sequential suite passed `86/86` with `--test-concurrency=1`. An earlier
-  ordinary parallel run also passed its then-current `85/85` suite, but CLI subprocess
-  contention made one test take 165 seconds; the final sequential exit is the release evidence.
-- `npm run pack:check`, `npm run smoke:downstream`, `npm run release:check`,
-  `npm run plugin:check`, and `git diff --check` passed. Packaging and downstream smoke used
-  an isolated temporary npm cache because the user cache contains pre-existing root-owned
-  entries.
-- The repository-level `tools/tests/codex-workflow-regression.mjs` update/install regression
-  completed with `status: PASS`.
-- Dry-run packaging produced `codex-workflow-v2-2.0.0-alpha.7.tgz` with 139 files; downstream
-  installation and packaged CLI handshake passed.
-
-Alpha.7 regression coverage includes:
-
-- pending strict Step Review outranks Knowledge Map reconcile/rebind after a knowledge-changing
-  completion commit; review succeeds against the exact historical approved binding even while
-  the current map is stale, and rebind remains mandatory before the next Step;
-- read-only alpha.6 rescue-preflight rejects active leases and accepts only one exact pending
-  strict-review candidate on the clean recorded completion HEAD;
-- seven linked Tasks can be materialized during initial Milestone assembly and classified by
-  one complete initial Plan without repeated scope-change approvals;
-- one maximum-72-hour Milestone Autonomy Contract issues the existing Task/Milestone approval
-  permissions, permits Project Memory approval only inside an atomic content-only Task context
-  refresh, permits journaled membership-only evolution, requires reauthorization, and rejects
-  both standalone Project Memory approval and semantic scope drift; a later human semantic
-  change invalidates future uses of the autonomy grant;
-- C1 Worker and corrective Auditor actors are deterministically derived while claim, lease,
-  handoff, and reviewer/auditor independence checks remain fail-closed;
-- every newly recorded guarded Plan Risk Audit requires an exact proof obligation per failure
-  mode: hostile counterexample, expected safe result, and executable evidence command;
-  historical alpha.6 audits remain readable for recovery only;
-- existing Milestone journal recovery, reverse-membership integrity, delegation, adoption,
-  Knowledge Map, graph, strict reviewer, Git ownership, and remediation hard-stop tests remain
-  green.
-
-Compatibility claims verified:
-
-- `protocolVersion: 1` and `STATE_SCHEMA_VERSION: 2` remain unchanged;
-- canonical Task and Milestone schemas remain byte-identical;
-- the generic delegated transition allow-list remains unchanged;
-- new evidence is additive through `autonomy-contract-events.jsonl`, optional autonomous
-  fields on scope-change events, and optional proof obligations on Plan Risk Audit events;
-- the gateway handshake advertises alpha.7 rescue, initial assembly, autonomy, derived actor,
-  corrective routing, and proof-obligation capabilities.
-
-Not claimed here:
-
-- no npm publication, Git tag, push, or downstream project mutation was performed;
-- no manual rewrite of external Workflow state is part of the recovery design;
-- the local package cannot cryptographically prove a real human identity or a physically
-  separate Codex task beyond the existing actor, process-isolation, sidecar, and lease evidence.
+# V2 beta.11 Validation Report
+
+Release candidate `2.0.0-beta.11` was validated on 2026-08-24 with Node.js 24.17.0.
+
+## Automated release evidence
+
+- `npm ci` completed from the committed lockfile with 0 reported vulnerabilities.
+- The final `npm run validate` passed `319/319` sequential tests with no failures, skips,
+  cancellations, or todos. The focused Signal recovery suite passed independently (`5/5`).
+- `npm run pack:check` passed. The beta.11 tarball contains 269 files; package size is approximately
+  951 kB and unpacked size is 3.7 MB.
+- `npm run smoke:downstream` packed and installed the actual beta.11 tarball in an empty temporary
+  project, then passed the packaged CLI handshake. The first sandboxed attempt was network-blocked
+  while fetching `ajv`; the authorized network retry and the final post-`npm ci` run passed.
+- `npm run plugin:check`, the plugin-creator structural validator, the skill validator,
+  `npm run docs:pdf:check`, `npm run release:check`, and `git diff --check` passed. The bundled
+  gateway cachebuster is `0.1.0+codex.20260824113210`.
+
+## Bounded Plan-integrity recovery evidence
+
+- Recovery becomes applicable only after the first ordinary `checks-failed` remediation for a
+  guarded failed Step when at least one Plan check is an exact root `npm run[-script] <name>`
+  command whose named script is absent from the root `package.json`, and that manifest is outside
+  the Step's exact `allowedWrites` boundary.
+- Fresh evidence binds the Task revision, first remediation event ID/hash, current Plan and Step
+  definition, root manifest path/hash, Git HEAD, exact check commands, missing script names, and
+  current dirty-file set into one canonical conflict hash.
+- An eligible `next` advertises only `task plan-integrity-recover`. The mutation appends one
+  schema-validated `replan-required` corrective decision and does not modify the worktree or invent
+  a second failed execution attempt.
+- Existing C1 ownership remains authoritative. A claimed Worker must execute the advertised
+  recovery and then yield its claim before the existing journaled, Human-gated corrective-replan
+  transition can prepare replacement Plan authority.
+- The route fails closed when `package.json` is writable by the Step, no missing-script check
+  matches the bounded npm-script grammar, unrelated dirty files exist, bindings drift, or
+  persisted evidence is malformed or tampered.
+
+## Regression coverage
+
+- Four dedicated beta.11 regressions cover the exact happy path, the in-scope-manifest exclusion,
+  dirty-worktree rejection, and sidecar evidence tampering.
+- Existing remediation-mode recovery retains higher navigation priority than the new assessment;
+  the legacy malformed-third-attempt regression passes unchanged.
+- The corrective-replan serialized definition SHA moved to
+  `c601cc100790a19e6ece2a1d60fb46d1e1d52e6922e6104d84f4b6ffe7ba0225` because the decision event
+  schema now admits the bounded ordinal-2 recovery record. Its runtime semantic fingerprint remains
+  `bd4e7a0ddfcb6abc0c5eb107775e6aea7e08c4606dda4d945d77af8a4520710d`, and the runtime catalog hash
+  remains `fa1d11860d4f07978c3b8e85d1f91cd3d15b17284b05f41e05d462d3bb092aed`.
+- The beta.10 dependency-provenance and exact Signal T04 revision-26 regressions remain green.
+- The read-only Milestone projection still preserves `T03 cancelled → T08 replacement`, and the
+  monotonic chat registry/title fallback regressions remain green.
+
+## Trusted-harness release replay
+
+- A fresh disposable project installed the actual current beta.11 tarball, declared the exact
+  `2.0.0-beta.11` dependency, and passed package handshake plus `doctor` with protocol 2 and state
+  schema 2. Its Git checkout remained clean.
+- The automatic trusted harness invoked the real packaged CLI and append-only recorded Discovery
+  bootstrap, sequential `status → next` checkpoints, Project Knowledge scan/approval, and
+  Discovery-to-Task materialization through the resulting `task plan-set` boundary.
+- The semantic lifecycle log validated `24/24` events with no failed or unadvertised mutation and
+  no missing checkpoint. Its SHA-256 is
+  `5c1d666aa3bc27c4b6687b836a565823a1f567227e93f76b2c3285217fb9a0b7`.
+- The matched raw result log contains 12 successful CLI results, no C1 credential fields, and has
+  SHA-256 `a51bae7221fa0ff30bd571ca3800bf8ac44911d7746f68e5e86987b6c357ccf6`.
+  The exercised tarball SHA-256 is
+  `3b7ed19961ba8394625d3a481fafb196dd80be5b138635a0bd1ce084a47fc06e`.
+- This targeted real-agent replay validates release navigation discipline and package integration;
+  it does not claim a second full product Milestone. Deeper P01/P04 lifecycle behavior is covered
+  by the deterministic and integration suites listed below.
+
+## Not claimed
+
+- Validation itself performs no npm publication, Git tag, push, Signal Workflow mutation, or local
+  plugin reinstall.
+- The implementation and package gates prove the bounded route. A real blocked project must still
+  install the published beta.11 package and follow its fresh project-local `handshake → doctor →
+  status → next → advertised recovery` navigation.
+
+## Post-beta.11 combined P04-A/P01-A candidate evidence
+
+This later evidence was recorded on 2026-08-24 on branch `codex/p04-task-dependencies` and was
+incorporated into the final beta.11 candidate.
+
+- P04-A adds the canonical Milestone dependency DAG, atomic initial Plan transaction/recovery,
+  dependency-bound handoff/claim/start, legacy fail-closed policy, and unconditional pre-write
+  structural replacement shutdown.
+- P01-A adds three versioned read-only analyzers, canonical in-event evidence/hash binding,
+  exact pre-start and corrective source selection, and phase-aware freshness before claim/start/run.
+- After final source review added a pre-Git-mutation start race guard, `npm test` passed the exact
+  final sequential `319/319` suite with zero failures, skips, cancellations, or todos. The 13/13
+  focused P01-A suite, 84/84 affected P01/P04/Task lifecycle selection, and 4/4 beta.11
+  late-recovery compatibility tests also passed.
+- `npm run typecheck`, `npm run plugin:check`, `npm run release:check`, schema validation inside
+  the full suite, the focused packaged-handshake capability test, and `git diff --check` passed.
+- The changed bundled gateway uses cachebuster `0.1.0+codex.20260824113210`; it was validated but
+  not reinstalled.
+- No merge, package install, tag, publication, plugin reinstall, Signal mutation, or brief status
+  transition to `implemented` is claimed by this candidate evidence.
+
+## beta.11 PDF release documentation evidence
+
+The Russian PDF set was regenerated and revalidated on 2026-08-24 against the combined beta.11
+candidate described above.
+
+- The three tracked PDF binaries now have reviewable Markdown authorities under
+  `docs/pdf/sources/` and one deterministic ReportLab generator. `npm run docs:pdf:check`
+  regenerated all outputs and reported an empty stale set.
+- All 24 pages were rendered and visually inspected: architecture is 6 pages, the delegated
+  chat-only guide is 8 pages, and the technical reference is 10 pages. Text extraction found no
+  empty pages. The architecture orphan-page defect found during inspection was removed, and the
+  complete delegated Discovery prompt no longer splits its readiness checklist across pages.
+- The content documents beta.11 delegated Discovery, the Milestone Autonomy Contract, explicit
+  `dependsOnTaskIds`, P04-A runnable routing and structural-replacement stop, P01-A mechanical
+  feasibility, C1 credential boundaries, external-sealed review, Plan-integrity recovery, and the
+  limited derived-graph role of `codebase-memory-mcp`.
+- `npm run pack:check` passed with an isolated writable npm cache. The 269-file dry-run tarball
+  contains all three PDFs, all three Markdown sources, the PDF README and pinned requirement, and
+  both generator/check scripts.
+- On the same beta.11 code tree, `npm run validate` passed `319/319`; `npm run typecheck`,
+  `npm run plugin:check`, `npm run release:check`, and `git diff --check` also passed.
+
+This evidence makes the documentation package-ready for beta.11. The release action remains a
+separate Git/tag operation after all final gates pass on the exact candidate tree.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "codex-workflow-v2",
-  "version": "2.0.0-beta.1",
+  "version": "2.0.0-beta.11",
   "description": "Requirements-first Codex development workflow with local state and explicit Git ownership.",
   "repository": {
     "type": "git",
@@ -34,6 +34,8 @@
     "references",
     "plugins",
     "docs",
+    "scripts/generate-pdf-docs.py",
+    "scripts/run-pdf-docs.mjs",
     "README.md"
   ],
   "scripts": {
@@ -41,13 +43,19 @@
     "build": "npm run clean && tsc -p tsconfig.build.json && node scripts/mark-cli-executable.mjs",
     "typecheck": "tsc -p tsconfig.json --noEmit",
     "test": "node scripts/with-validation-lock.mjs test",
+    "test:signal-t04-recovery": "node scripts/with-validation-lock.mjs test-signal-t04",
     "validate": "npm run typecheck && npm test",
     "pack:check": "npm run build && npm pack --dry-run",
     "smoke:downstream": "npm run build && node scripts/downstream-smoke.mjs",
     "plugin:check": "node scripts/validate-plugin.mjs",
+    "docs:pdf": "node scripts/run-pdf-docs.mjs",
+    "docs:pdf:check": "node scripts/run-pdf-docs.mjs --check",
     "release:check": "node scripts/release-check.mjs",
     "publish:release": "node scripts/publish.mjs"
   },
+  "dependencies": {
+    "ajv": "8.20.0"
+  },
   "devDependencies": {
     "@types/node": "24.10.1",
     "typescript": "5.9.3"

package/plugins/codex-workflow-gateway/.codex-plugin/plugin.json

@@ -1,12 +1,17 @@
 {
   "name": "codex-workflow-gateway",
-  "version": "0.1.0",
+  "version": "0.1.0+codex.20260824113210",
   "description": "Thin personal Codex gateway for exact project-local Codex Workflow V2 packages and codebase-memory-mcp.",
   "author": {
     "name": "Codex Workflow Maintainers"
   },
   "license": "MIT",
-  "keywords": ["codex", "workflow", "codebase-memory", "gateway"],
+  "keywords": [
+    "codex",
+    "workflow",
+    "codebase-memory",
+    "gateway"
+  ],
   "skills": "./skills/",
   "interface": {
     "displayName": "Codex Workflow Gateway",
@@ -14,7 +19,9 @@
     "longDescription": "Resolves the exact project-local Codex Workflow V2 package, delegates workflow semantics to its CLI, and maintains derived codebase-memory graph bindings with explicit fallback evidence.",
     "developerName": "Codex Workflow Maintainers",
     "category": "Productivity",
-    "capabilities": ["Interactive"],
+    "capabilities": [
+      "Interactive"
+    ],
     "defaultPrompt": [
       "Show the next valid Codex Workflow V2 action.",
       "Refresh the project code graph for planning.",

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

@@ -1,4 +1,23 @@
-# Gateway Protocol V1
+# Gateway Protocol V2
+
+## beta.11 coordinator projections, retained review provenance, chat registry, and Plan-integrity recovery
+
+- When fresh `next` advertises `task plan-integrity-recover`, consume its exact Task revision,
+  Step, actor, and writer-token contract. This route is valid only for the Core-derived
+  first-failure missing-root-npm-script evidence and must be followed by fresh `status -> next`.
+  It records a replan posture without changing Plan or product files; corrective yield and the
+  existing state-bound corrective-replan Human gate remain mandatory.
+
+- `update dependency-provenance-preflight --id <TASK-ID>` is read-only. The matching
+  `update dependency-provenance-recover --id <TASK-ID> --expected-revision <N> --actor <ACTOR>
+  --reason <TEXT>` is valid only when preflight and fresh `next` both advertise it. Historical
+  product commits absent from the current corrective Step are recognized only through intact passed
+  strict-review plus verified reviewer-attestation chains and remain separately auditable as
+  `retainedHistoricalCommits`.
+- `milestone progress --id <MS-ID>` is a read-only projection and the sole source for Coordinator
+  progress tables. It preserves cancelled/replacement Tasks as distinct membership rows.
+- `scripts/chat-registry.mjs` atomically allocates project-monotonic `#NNN`, builds all six title
+  families, verifies exact readback, supplies deterministic fallbacks, and binds the verified chat.
 
 ## Handshake
 
@@ -11,7 +30,7 @@ codex-workflow gateway handshake --repo <git-root>
 Require:
 
 - package name `codex-workflow-v2`
-- protocol version `1`
+- protocol version `2`
 - state schema version `2`
 - the capabilities needed for the requested operation
 
@@ -25,10 +44,13 @@ Current capability set:
 - `delegated-approval-v1`
 - `task-knowledge-rebind-v1`
 - `task-context-refresh-v1`
-- `terminal-task-replacement-transaction-v1`
+- `structural-task-replacement-disabled-v1`
 - `project-composite-transaction-journal-v1`
 - `corrective-plan-audit-v1`
 - `safe-update-preflight-v1`
+- `bounded-dependency-provenance-recovery-v1`
+- `retained-reviewed-history-recovery-v1`
+- `milestone-progress-projection-v1`
 - `strict-reviewer-v1`
 - `legacy-snapshot-v1`
 - `plan-risk-audit-sidecar-v1`
@@ -36,7 +58,10 @@ Current capability set:
 - `step-remediation-circuit-breaker-sidecar-v1`
 - `milestone-scope-change-sidecar-v1`
 - `milestone-membership-integrity-v1`
+- `milestone-task-dependency-dag-v1`
+- `milestone-initial-plan-transaction-v1`
 - `task-c1-handoff-sidecar-v1`
+- `task-mechanical-feasibility-v1`
 - `semantic-plan-risk-audit-v2`
 - `guarded-remediation-hard-stop-v1`
 - `milestone-reverse-membership-integrity-v1`
@@ -44,11 +69,20 @@ 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-autonomy-content-refresh-v1`
 - `milestone-autonomous-membership-evolution-v1`
 - `task-c1-derived-worker-actor-v1`
 - `guarded-corrective-auditor-routing-v1`
+- `corrective-decision-context-recovery-v1`
+- `remediation-mode-recovery-v1`
 - `plan-proof-obligations-v1`
+- `bounded-plan-integrity-recovery-v1`
+- `corrective-yield-journal-v1`
+- `corrective-replan-journal-v1`
+- `corrective-replan-human-gate-v1`
+- `corrective-replan-protocol-v2`
 
 Protocol `1` and schema `2` remain valid only because alpha.7 is additive. The gateway must
 not claim compatibility if canonical entity shapes or non-additive command semantics change.
@@ -75,7 +109,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.
 
@@ -84,11 +120,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.
@@ -129,6 +190,12 @@ 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.
 
+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
@@ -166,11 +233,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:
 
@@ -227,6 +311,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.