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

package/docs/stable-release-defect-register.md

@@ -0,0 +1,268 @@
+# Stable Release Defect Register
+
+This register captures defects and operational gaps found while running the
+alpha.7 line against the `signal_v4` Milestone 3 lifecycle. It is intentionally
+separate from implementation briefs: an item stays here until it is either
+verified fixed by a regression test or explicitly classified as downstream-only.
+
+Last reviewed: 2026-08-15.
+
+## Severity and status
+
+- **Confirmed** means the behavior was reproduced from package or downstream evidence.
+- **Investigation** means the risk is concrete, but the package defect boundary is not yet proven.
+- **Closed-regression** means a patch exists; the stable release must retain its regression coverage.
+- **Downstream** means the finding belongs to `signal_v4`, not to the workflow package.
+
+## Workflow findings closed for beta.1
+
+### WF-STABLE-001 — `locks repair` exposes a full writer token
+
+- Status: Closed-regression in beta.1
+- Severity: High
+- Area: lock recovery, CLI output, secret handling
+- Evidence: the `locks repair` result includes the complete credential-bearing writer token rather
+  than a redacted value or one-time bounded handoff.
+- Risk: a transcript, log, screenshot, or delegated agent output can disclose authority that permits
+  state mutation.
+- Stable-release requirement:
+  - never print the full token in ordinary JSON or human-readable output;
+  - return only a redacted fingerprint unless an explicit secure handoff channel is used;
+  - add CLI, JSON-envelope, logging, snapshot, and error-path tests proving no token leakage;
+  - preserve deterministic recovery and avoid making the token unrecoverable before ownership is
+    safely transferred.
+
+### WF-STABLE-002 — standalone Project Knowledge `next` is misleadingly attributed to a failed Task
+
+- Status: Closed-regression in beta.1
+- Severity: Medium
+- Area: `next`, Project Knowledge Map, remediation terminality
+- Signal replay evidence:
+  - Task `TASK-01M00W190K3V3HM68Q3QVSH1AY` is `needs_fix` with
+    `STEP-002-FORMALIZATION-CONTRACTS` failed and a `split-required` decision;
+  - after a top-level reconcile, `next` correctly returns scope `project-memory`, action
+    `project-memory approve`, revision `168`, but also returns that failed Task as `taskId`.
+- Risk: an agent or operator can interpret a standalone project approval as permission to refresh or
+  resume the terminal remediation path.
+- Stable-release requirement:
+  - standalone Project Knowledge actions must not look like Task execution actions;
+  - either omit `taskId` or expose it under an explicit non-authorizing field such as
+    `triggerTaskId`/`stalenessOriginTaskId`;
+  - state clearly that approval cannot authorize, refresh, or resume the referenced Task;
+  - add a replay for `split-required -> main branch reconcile -> standalone approval next`.
+
+### WF-STABLE-003 — terminal `split-required` is routed into unsafe Knowledge rebind
+
+- Status: Closed-regression in beta.1
+- Severity: Critical
+- Area: corrective terminal decisions, Milestone membership evolution, `next`
+- Signal replay evidence:
+  - after human approval of Project Knowledge Map revision `169`, exact `next` returns
+    `task knowledge-rebind` for `TASK-01M00W190K3V3HM68Q3QVSH1AY` at revision `28`;
+  - the Task is `needs_fix`, its guarded Step is failed, and its current corrective decision is
+    `split-required`;
+  - `taskCanRebindKnowledge` accepts every `needs_fix` Task without checking a hard-blocking
+    corrective decision;
+  - repository `next` lets Knowledge Map rebind override the Task-level `doctor` result for the
+    `split-required` posture;
+  - `rebindTaskKnowledge` changes the Plan hash, sets status to
+    `awaiting_execution_authorization`, clears review/block state, and supersedes execution
+    authorization without preserving the terminal decision on the rebound Plan;
+  - no Task cancellation transition exists, and a started Task remains repository-actionable while
+    its Milestone is active even if membership disposition is changed.
+- Risk: following exact `next` can detach the new Plan hash from the recorded `split-required`
+  decision and make the failed Task appear authorizable again. Ignoring `next` to create or
+  reclassify a replacement Task cannot remove the started failed Task from repository routing.
+- Stable-release requirement:
+  - reject `knowledge-rebind` and `context-refresh` before the first write when the current
+    corrective posture is `split-required` or `stop-escalate`;
+  - keep terminal corrective decisions effective across Project Knowledge changes without
+    rebinding or rewriting the historical Task Plan;
+  - provide one unambiguous replacement route with explicit old/new Task relationship;
+  - require atomic or journal-recoverable membership evolution;
+  - prevent both orphan replacement Tasks and a still-required terminal Task;
+  - make repository `next` return that replacement route rather than `knowledge-rebind`;
+  - add deterministic and real-agent E2E coverage for
+    `split-required -> Project Knowledge approval -> replacement -> Milestone continuation`.
+
+### WF-STABLE-004 — workflow package upgrades can remain stranded on a Task branch
+
+- Status: Closed-regression in beta.1
+- Severity: Medium
+- Area: update instructions, branch ownership, Milestone base verification
+- Evidence: dependency commit `3f45abc88f7b85091c484d0b84f4c96d1dfeb045` pinned
+  `codex-workflow-v2@2.0.0-alpha.7.2.1` only on the failed Task branch while local `main`, the
+  Milestone base, remained on alpha.7.1. Recovery required a manually scoped cherry-pick producing
+  `fabd1c868a9baa74c7ef273bf0272753c7927812` on local `main`.
+- Risk: diagnostics run with one package version while Milestone creation or replacement work starts
+  from another, invalidating assumptions and repeating already-fixed lifecycle failures.
+- Stable-release requirement:
+  - update preflight and documentation must distinguish current worktree version from Milestone base
+    branch version;
+  - provide an explicit dependency-only landing check before lifecycle work continues;
+  - fail closed when declared, locked, installed, current-branch, and base-branch versions diverge;
+  - never suggest merging unrelated product commits to transport a workflow dependency update.
+
+### WF-STABLE-005 — agent guidance did not make replacement membership evolution explicit
+
+- Status: Closed-regression in beta.1
+- Severity: Medium
+- Area: recovery prompts, operator guidance
+- Evidence: the generated post-approval prompt said to create a thin required replacement Task but
+  did not explicitly require reclassification of the old failed membership and Milestone
+  reauthorization through exact Core transitions.
+- Risk: correct package primitives can still be used in the wrong order, recreating an apparently
+  active but non-completable Milestone.
+- Stable-release requirement:
+  - ship a canonical `split-required` operator/delegate recovery prompt;
+  - require `status`/`next` after every state boundary;
+  - distinguish Task creation, replacement linkage, membership evolution, and execution
+  reauthorization;
+- prohibit manual state editing and resumption of the failed Step.
+
+### WF-STABLE-006 — composite context refresh has no multi-file crash-recovery journal
+
+- Status: Closed-regression in beta.1
+- Severity: High
+- Area: Project Knowledge refresh, Task rebind, delegated reauthorization, durability
+- Evidence: alpha.7.1 validates the complete transition before its first canonical write and uses
+  atomic replacement for each individual file, but the composite transition performs multiple file
+  writes without a transaction journal. A process or machine failure between those writes can leave
+  a partially applied cross-file transition.
+- Risk: the repository can be clean while Project Knowledge, Task binding, authorization, and audit
+  sidecars disagree after a crash. Prevalidation prevents logical rejection after the first write but
+  cannot recover an interrupted physical write sequence.
+- Stable-release requirement:
+  - introduce a project-local transaction journal or an equivalent recoverable commit protocol;
+  - define deterministic roll-forward/rollback semantics for every write boundary;
+  - make recovery idempotent and preserve append-only audit history;
+  - add crash-injection tests before and after each canonical and sidecar write;
+  - prove `doctor`, `status`, and `next` detect and route every interrupted legacy/candidate shape;
+  - never silently treat a partial refresh as authorized.
+
+### WF-STABLE-007 — full validation commands may race through shared build/clean outputs
+
+- Status: Closed-regression in beta.1
+- Severity: Medium if confirmed
+- Area: maintainer validation, reproducibility
+- Evidence: concurrent `npm test` and `npm run validate` runs stopped producing reliable completion
+  evidence after both reached shared test/build phases. A later sequential run continued normally.
+  The observed behavior is consistent with shared `build`/`clean` output contention, but the exact
+  cause has not been isolated.
+- Risk: maintainers can mistake a hung or corrupted concurrent run for passing release evidence, or
+  waste hours waiting on a validation process that cannot complete deterministically.
+- Verification required:
+  - reproduce with process-level tracing and isolated logs;
+  - identify shared directories, cleanup commands, ports, caches, and child processes;
+  - distinguish a package-script race from a test-runner or environment defect.
+- Stable-release requirement if confirmed:
+  - isolate run outputs/resources or enforce an explicit single-run lock with a clear diagnostic;
+  - ensure interruption cleans up child processes and resources;
+  - document whether concurrent full validation is supported;
+  - add a deterministic concurrency regression where practical.
+
+### WF-STABLE-008 — replacement Task local start required a manual base-branch switch
+
+- Status: Closed-regression in beta.1
+- Severity: Low
+- Area: local Task start, replacement autonomy, Git preconditions
+- Evidence: the final disposable E2E correctly materialized and reauthorized the replacement, but
+  its first `task start` was safely rejected because the clean checkout still pointed at the
+  cancelled Task branch instead of `main`; the Delegate recovered by switching branches and retrying.
+- Stable guard: local Task start resolves the exact declared base ref and creates the new Task branch
+  from that ref even when another clean Task branch is checked out. Dirty worktrees and external
+  ownership rules remain fail-closed.
+
+## Beta.1 closure evidence
+
+- `WF-STABLE-001`: CLI integration proves both inspection and stale repair return only a token
+  fingerprint and never the writer token.
+- `WF-STABLE-002`: repository navigation returns diagnostic provenance as
+  `stalenessOriginTaskId` with `authorizesTask: false`; eligible atomic refresh is a Task-scoped
+  top-level action.
+- `WF-STABLE-003`: deterministic terminal replay and the disposable real-agent Milestone prove
+  `split-required -> replacement -> reauthorization -> merge -> final acceptance`, with the old
+  Task cancelled, linked, immutable in history, and without a retained writer lease.
+- `WF-STABLE-004`: update-preflight regressions cover declared, locked, installed, current-branch,
+  and active Milestone base versions plus dependency-only transport guidance.
+- `WF-STABLE-005`: `docs/split-required-recovery.md` and the packaged gateway protocol define one
+  exact replacement ordering and prohibit manual membership/state mutation.
+- `WF-STABLE-006`: beta transaction regressions inject ordinary failure and dead-process exit at
+  every target-write boundary, then prove rollback or idempotent roll-forward, including file
+  deletion. Context refresh and replacement both use the project journal.
+- `WF-STABLE-007`: a deterministic second full-validation owner fails immediately with
+  `VALIDATION_ALREADY_RUNNING`; the sequential release suite completed normally.
+- `WF-STABLE-008`: the local branch-start regression begins on a clean historical Task branch and
+  proves the new Task branch is created from the exact `main` commit.
+
+## Downstream findings to retain as E2E fixtures
+
+### SIGNAL-M3-001 — stable identifier validation misses real U+0000 after line terminators
+
+- Status: Downstream confirmed defect
+- Owner: `signal_v4`
+- Workflow relevance: use as the thin replacement-Task fixture for validating `split-required`
+  recovery; do not implement the product fix in this repository.
+- Required downstream acceptance: reject real U+0000 in every position, including immediately after
+  line terminators, without weakening other stable-identifier rules.
+
+### SIGNAL-M3-002 — Project Knowledge has an unresolved `ownership` gap
+
+- Status: Downstream gap, currently non-blocking
+- Owner: `signal_v4`
+- Evidence: candidate Knowledge Map revision `168`, hash
+  `8d775d82fb1aec85322a923ecf62053453160376033f45bd3c7e2a8c2588d51d`, reports no conflicts
+  and one missing `ownership` category source.
+- Rule: do not expand the NUL replacement Task to fix this gap. Track it as separate project
+  documentation work.
+
+### SIGNAL-M3-003 — local `main` has no configured `origin`
+
+- Status: Downstream operational risk
+- Owner: `signal_v4`
+- Evidence: local `main` is at `fabd1c868a9baa74c7ef273bf0272753c7927812`, but `git ls-remote
+  --heads origin main` fails because `origin` is not configured.
+- Risk: a local dependency correction may be mistaken for a shared or durable project update.
+- Rule: resolve repository remote/backup policy separately; do not let workflow lifecycle commands
+  infer permission to publish.
+
+## Closed alpha.7 regressions that must not recur
+
+### WF-REG-001 — context-only Knowledge Map rebinding invalidated `continue-fix`
+
+- Status: Closed-regression in alpha.7.2
+- Stable guard: semantic Plan equality must preserve an authorized `continue-fix`; semantic changes
+  must invalidate it; recovery remains append-only and non-mutating on failure.
+
+### WF-REG-002 — recovered corrective decision still produced `TOKEN_RECOVERY_NO_GO`
+
+- Status: Closed-regression in alpha.7.2.1
+- Stable guard: an append-only remediation-mode recovery must restore the exact allowed transition
+  without a fourth remediation run, duplicate decision, manual state edit, or writer-lease bypass.
+
+### WF-REG-003 — delegated creation of exact Plan-declared supporting Knowledge sources was blocked
+
+- Status: Closed-regression in alpha.7.1
+- Stable guard: only exact normalized Plan-declared supporting sources with
+  `knowledgeImpact=create` may be added; wildcard, directory, canonical, unauthorized, removal,
+  category/authority changes, gaps, and conflicts remain blocked before the first write.
+
+### WF-REG-004 — E2E history contained a spurious review failure from the harness
+
+- Status: Closed-regression in alpha.7.1 E2E evidence
+- Stable guard: fresh real-agent E2E evidence must separate harness/setup failures from lifecycle
+  review attempts and must not pollute the Task remediation history.
+
+### WF-REG-005 — `next` offered work that the exact transition would reject
+
+- Status: Closed-regression in alpha.7.2
+- Stable guard: `next` must use the same binding, recovery, terminal-decision, and corruption
+  predicates as the exact mutating transition. If the transition is guaranteed to reject, `next`
+  must return the recovery/blocking action instead of a Task run.
+
+## Stable-release exit rule
+
+The stable release is not ready while any Confirmed workflow finding above is open. Investigation
+items must be either reproduced and fixed or closed with recorded evidence that Core already provides
+the required safe semantics. Downstream findings do not block the package by themselves, but the NUL
+fixture must complete the real-agent replacement path through final Milestone acceptance.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "codex-workflow-v2",
-  "version": "2.0.0-alpha.7.2",
+  "version": "2.0.0-beta.1",
   "description": "Requirements-first Codex development workflow with local state and explicit Git ownership.",
   "repository": {
     "type": "git",
@@ -40,7 +40,7 @@
     "clean": "node --eval \"import('node:fs').then(({rmSync}) => { rmSync('dist', {recursive:true, force:true}); rmSync('.test-dist', {recursive:true, force:true}); })\"",
     "build": "npm run clean && tsc -p tsconfig.build.json && node scripts/mark-cli-executable.mjs",
     "typecheck": "tsc -p tsconfig.json --noEmit",
-    "test": "npm run build && tsc -p tsconfig.test.json && node --test .test-dist/tests/*.test.js",
+    "test": "node scripts/with-validation-lock.mjs test",
     "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",

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`
@@ -127,8 +129,10 @@ 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
+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

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

@@ -51,12 +51,19 @@ 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` 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.
+
 ## Product Or Workflow Graph Refresh
 
 1. Run `graph refresh-request --kind product|workflow --mode moderate`.

package/schemas/remediation-mode-recovery-event.schema.json

@@ -0,0 +1,42 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://codex-workflow.local/schemas/remediation-mode-recovery-event.schema.json",
+  "title": "Codex Workflow V2 Remediation Mode Recovery Event",
+  "type": "object",
+  "additionalProperties": false,
+  "required": [
+    "eventId", "taskId", "stepId", "taskRevision", "remediationEventId",
+    "remediationEventHash", "correctiveDecisionEventId", "correctiveDecisionEventHash",
+    "correctiveDecisionRecoveryEventId", "correctiveDecisionRecoveryEventHash",
+    "attemptOrdinal", "planHash", "actor", "c1ClaimEventHash",
+    "writerLeaseTokenHash", "fromMode", "toMode", "reason",
+    "previousEventHash", "recordedAt", "eventHash"
+  ],
+  "properties": {
+    "eventId": { "type": "string", "pattern": "^RMR-[0-9A-HJKMNP-TV-Z]{26}$" },
+    "taskId": { "type": "string", "pattern": "^TASK-[0-9A-HJKMNP-TV-Z]{26}$" },
+    "stepId": { "type": "string", "pattern": "^STEP-[0-9]{3}(?:-[A-Z0-9-]+)?$" },
+    "taskRevision": { "type": "integer", "minimum": 1 },
+    "remediationEventId": { "type": "string", "pattern": "^RME-[0-9A-HJKMNP-TV-Z]{26}$" },
+    "remediationEventHash": { "$ref": "#/$defs/hash64" },
+    "correctiveDecisionEventId": { "type": "string", "pattern": "^CRD-[0-9A-HJKMNP-TV-Z]{26}$" },
+    "correctiveDecisionEventHash": { "$ref": "#/$defs/hash64" },
+    "correctiveDecisionRecoveryEventId": { "type": "string", "pattern": "^CDR-[0-9A-HJKMNP-TV-Z]{26}$" },
+    "correctiveDecisionRecoveryEventHash": { "$ref": "#/$defs/hash64" },
+    "attemptOrdinal": { "const": 3 },
+    "planHash": { "$ref": "#/$defs/hash64" },
+    "actor": { "type": "string", "minLength": 1 },
+    "c1ClaimEventHash": { "$ref": "#/$defs/nullableHash64" },
+    "writerLeaseTokenHash": { "$ref": "#/$defs/nullableHash64" },
+    "fromMode": { "const": "ordinary" },
+    "toMode": { "const": "corrective" },
+    "reason": { "const": "alpha7.2-recovered-continue-fix-mode-omission" },
+    "previousEventHash": { "$ref": "#/$defs/nullableHash64" },
+    "recordedAt": { "type": "string", "format": "date-time" },
+    "eventHash": { "$ref": "#/$defs/hash64" }
+  },
+  "$defs": {
+    "hash64": { "type": "string", "pattern": "^[a-f0-9]{64}$" },
+    "nullableHash64": { "type": ["string", "null"], "pattern": "^[a-f0-9]{64}$" }
+  }
+}

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}$" }
   }
 }