codex-workflow-v2 2.0.0-alpha.7 → 2.0.0-alpha.7.2

package/docs/alpha7.2-corrective-context-refresh-brief.md

@@ -0,0 +1,484 @@
+# codex-workflow-v2 2.0.0-alpha.7.2 corrective context-refresh brief
+
+## Status and authority
+
+This document is the single source of truth for the narrow
+`codex-workflow-v2@2.0.0-alpha.7.2` lifecycle patch. The candidate is based on
+published tag `v2.0.0-alpha.7.1` at commit
+`90e40108a593e0b908862c9326ceae8bfe8f6d67` and is developed only in the
+detached worktree
+`/Users/home-pc/Documents/Codex/2026-08-15/codex-workflow-v2-alpha7-2/work/codex-workflow-v2-alpha7-2`.
+
+Workflow V2 is not used to plan, authorize, implement, test, or audit this
+patch. The source repository's main checkout is read-only. No tag, push, or npm
+publication is authorized.
+
+The `signal_v4` repository and its external Workflow state are read-only
+evidence. Exact replay must use a disposable byte copy of state and must never
+point a mutating command at the original state root.
+
+## Scoped feasibility decision
+
+Alpha.7.2 guarantees command-local complete prevalidation before the first
+durable recovery write, recovery-local serialization against duplicate recovery
+callers, immediate under-lock evidence revalidation, and run-time revalidation
+before a recovery is consumed. It does not claim global serializability against
+unrelated Task, Knowledge Map, delegation, sidecar, or lease writers and does
+not add a cross-file journal or global mutation protocol.
+
+The inherited cross-store TOCTOU/crash window between final revalidation and
+append is the same architectural risk class already present in alpha.7.1
+multi-file transitions. A later evidence change makes the recovery event stale
+and `task run` must fail closed. This residual risk is documented rather than
+silently promoted into a new alpha.7.2 guarantee.
+
+## Exact defect and baseline evidence
+
+The production-shaped state is:
+
+- Task `TASK-01M00W190K3V3HM68Q3QVSH1AY`, revision `25`, status `ready`;
+- guarded Step `STEP-002-FORMALIZATION-CONTRACTS`, status `planned`;
+- two failed ordinary remediation attempts, making ordinal `3` the next
+  attempt;
+- corrective event `CRD-01M011B4MM5R1FZG2DSDRHVXJ4`, decision
+  `continue-fix`, triggering ordinal `3`;
+- decision Plan hash
+  `21a17679b219f33822beaf519903c1adf497c318facf1a954550a54cef840e19`;
+- current Plan hash
+  `9cb6b0c9f9400335877316c8163f35f5cf25c5fa3a4cd4775cf591e5293f3264`;
+- one recorded Knowledge rebind from revision `163` to `165`, linking those
+  exact Plan hashes, followed by an approved delegated execution authorization
+  whose reason is the canonical content-only context-refresh reason.
+
+The historical and current Plan artifacts differ in exactly one line: Knowledge
+Map revision/hash. Objective, requirements, acceptance, risks, knowledge
+impact, knowledge targets, graph use, Steps, allowed writes, expected outputs,
+checks, and forbidden scope are byte-identical after normalizing that one
+binding line.
+
+An alpha.7.1 replay against a disposable copy of the untouched state produced:
+
+1. `next -> action: task run`, Task revision `25`, Step
+   `STEP-002-FORMALIZATION-CONTRACTS`;
+2. the exact advertised `task run` failed with `TRANSITION_BLOCKED` because the
+   corrective decision Plan hash differs from the current Plan hash;
+3. the disposable state content digest remained unchanged;
+4. the copied writer lease was stale before both calls and its heartbeat and
+   expiry remained unchanged, proving that the mismatch guard runs before lease
+   heartbeat and that lease staleness is not this navigation defect.
+
+The primary defect is therefore `next`/transition disagreement. Because a
+post-refresh Step may be `planned`, alpha.7.1 omits it from corrective-posture
+discovery and advertises a run that the exact transition will reject. A sibling
+constructed `failed` Step can instead advertise another corrective decision,
+but that decision is also impossible because the existing Step/ordinal binding
+must remain unique. That sibling is a separate regression variant, not a
+replacement for the exact production replay.
+
+## Required outcome
+
+An existing `continue-fix` remains usable after an authorized context refresh
+that changes only the Plan's Knowledge Map binding. Any other Plan difference
+continues to block. Alpha.7.1 state gains a normal, verifiable, append-only
+recovery transition; historical state and the original corrective event are
+never edited.
+
+## Design
+
+### D1 — explicit recovery event, not decision rewriting
+
+Add an append-only Task sidecar,
+`corrective-decision-recoveries.jsonl`. A recovery event binds:
+
+- the original corrective event ID/hash and its exact Step/ordinal;
+- the decision Plan hash and current rebound Plan hash;
+- a semantic Plan digest computed after replacing the one Knowledge Map
+  binding line with a fixed sentinel;
+- the one exact direct Knowledge-rebind record from the decision Plan to the
+  current Plan;
+- the matching current delegated Knowledge Map approval, current delegated
+  Task execution authorization, and mechanically rebound Plan Risk Audit;
+- the historically valid grant identity shared by those delegated approvals;
+- the recovering actor and timestamp.
+
+The event does not create a new corrective decision and does not change the
+original event. Sidecar hash chaining makes ordering and tampering explicit.
+At most one recovery may exist for the same corrective event and target Plan.
+An identical retry returns the existing event without writing; a conflicting
+duplicate is rejected as corrupt or conflicting state.
+
+### D2 — strict semantic equivalence
+
+Recovery reads the current `plan.md` and the immutable historical
+`.versions/plan.md.<decision-plan-hash>` artifact. Both hashes must match their
+bindings. Each artifact must contain exactly one canonical Knowledge Map line:
+
+`- Knowledge map: revision <positive integer>, hash <sha256>`
+
+After replacing only that complete line with the same fixed sentinel, the full
+UTF-8 artifacts must be byte-identical and their semantic digest must match.
+This intentionally rejects formatting drift outside the binding as well as
+semantic drift. In particular, any change to Objective, requirements,
+acceptance, risks, knowledge impact/reason/targets, graph use, Step identity,
+Step objective, dependencies, expected outputs, allowed writes, forbidden
+scope, or checks blocks recovery.
+
+### D3 — confirmed authorized context-refresh evidence
+
+Alpha.7.2 accepts exactly one unique direct `TaskState.knowledgeRebinds` record
+whose `previousPlanHash` is the decision Plan and whose `reboundPlanHash` is the
+current Plan. Multi-hop recovery is forbidden: alpha.7.1 does not retain enough
+historical Knowledge Map approval evidence to prove every intermediate hop, and
+endpoint comparison could conceal an intermediate semantic Plan change that was
+later reverted.
+
+Ordering must be proved from persisted array order and timestamps, not endpoint
+uniqueness alone. Rebind timestamps must be strictly increasing. The selected
+record must be the first rebind after both the corrective decision and source
+Plan Risk Audit and also the final rebind in the array. No other rebind may have
+a timestamp between the decision/source-audit binding and selected record, or
+between the selected record and current Task binding. An intermediate rebind is
+fatal even if a later record returns to the same endpoint Plan semantics.
+
+The direct rebind's from/to Knowledge Map revision and hash must match the
+bindings extracted from the two verified Plan artifacts. The current Project
+Knowledge Map must be active, its revision/hash and approval map hash must match
+the direct rebind target, and its approval must contain delegated evidence for
+`project_memory.approve`.
+
+The current Task Plan must have exactly one corresponding approved execution
+authorization with:
+
+- the same rebound Plan hash and unchanged Brief hash;
+- `authorizationMode: delegated` and non-null delegation evidence;
+- delegation transition `task.execution_authorize`;
+- one of the two exact canonical reasons emitted only by alpha.7.1
+  `task context-refresh`: delegated content-only or delegated Plan-bounded
+  supporting-source context refresh;
+- decision `approved`.
+
+The current Knowledge Map approval and Task execution authorization must have
+the same actor, authorization mode, grant ID, policy hash, principal, and
+delegate; only their delegated transition names may differ. The persisted grant
+record must match that shared immutable delegation identity and contain both
+transitions. Its scope must be project-wide or the exact Task Milestone backed
+by one valid alpha.7 milestone-autonomy contract whose grant ID, policy hash,
+principal, delegate, and expiry all match; that contract is part of the recovery
+evidence fingerprint. Task-scoped or unproven Milestone-scoped grants fail
+closed. Both approval
+timestamps must fall between grant creation and expiry and, if the grant was
+later revoked, before `revokedAt`. Recovery recognizes historical authorization;
+it does not require an unexpired grant at recovery time and does not create a
+new delegated approval.
+
+Recovery must also find exactly one source Plan Risk Audit for the decision Plan
+and the unique current Plan Risk Audit for the rebound Plan. Both sidecar events
+must have valid chain/hash integrity and the same Brief hash, planner, auditor,
+decision, split rationale, and Step classifications. The current audit summary
+must equal the source summary plus exactly one canonical
+` Rebound automatically after content-only Task context refresh.` suffix; its
+Knowledge binding must match the direct rebind target. The current audit must be
+the immediate next Plan Risk Audit event
+(`current.previousEventHash === source.eventHash`), so no intermediate audit may
+exist, and the direct rebind must be the Task's last Knowledge rebind. The
+rebound audit records the post-rebind Task revision, and the current Task must be
+exactly one revision later because the final composite action is execution
+authorization (`currentAudit.taskRevision + 1 === task.revision`). Chronology
+must be map approval <= direct rebind <= rebound audit <= Task authorization.
+Together these are the exact mechanical relationships emitted by
+`appendReboundPlanRiskAudit` and `refreshTaskContext`, not a newly supplied
+audit. In the exact legacy state this invariant is explicit: rebound audit Task
+revision `24`, current authorized Task revision `25`.
+
+For alpha.7.1 this is the strongest recoverable evidence already persisted by
+the composite transition. It cannot prove atomic call provenance
+cryptographically because alpha.7.1 did not persist a dedicated context-refresh
+event; this limitation is recorded under Remaining risks. The conjunction of
+immutable Plan versions, one direct rebind, current delegated Knowledge Map
+approval, matching current delegated Task authorization, the same historically
+valid grant,
+Brief continuity, and mechanical Plan Risk Audit rebound is required. A
+standalone rebind, arbitrary `task authorize --reason`, human authorization,
+missing or mismatched map approval, independently replaced risk audit, wrong
+delegation transition, or broken chain fails closed.
+
+### D4 — recovery transition and validation order
+
+Expose `task corrective-decision-recover` with Task ID, Step ID, expected Task
+revision, actor, and optional writer token.
+The transition performs all read-only validation before its first write:
+
+1. adoption/state/event-chain integrity and expected Task revision;
+2. exact Step, two-failure/ordinal-3 posture, and no hard stop;
+3. unique original corrective event and `decision=continue-fix`;
+4. explicit revalidation of corrective-auditor independence against the exact
+   covered remediation/review/attestation history (a `checks-failed` event may
+   legitimately have no reviewer attestation);
+5. current Plan/Brief/execution authorization freshness;
+6. historical/current Plan artifact hashes and strict semantic equivalence;
+7. one unique direct Knowledge rebind, current delegated Knowledge Map approval,
+   the same historically valid delegation identity, and current delegated Task
+   authorization;
+8. unique mechanically rebound source/current Plan Risk Audit pair;
+9. existing recovery uniqueness/idempotence;
+10. current recovery authority as defined in D4a, including C1 actor and exact
+    writer-token ownership when a claimed handoff exists.
+
+After the complete read-only preflight, recovery acquires a Task-local atomic
+recovery lock created with exclusive-create semantics. This lock is deliberately
+shared only by recovery callers; it is not represented as a store-wide
+transaction. Under the lock the command re-reads and re-fingerprints every
+evidence item used by preflight, rechecks Task revision and recovery head, and
+then either returns an already identical recovery idempotently, rejects drift or
+a conflicting recovery without an append, or appends one hash-chained recovery
+event. Parallel recovery commands therefore cannot append two events.
+
+Expected validation failures before append must leave Task JSON, all durable
+sidecars, `.versions`, writer lease, repository files, and Git history unchanged.
+Creating and removing the transient recovery lock is coordination, not a domain
+write. Recovery does not change Task revision, Step state, authorization,
+Knowledge Map, writer lease, repository files, or Git history. Because unrelated
+alpha.7.1 writers do not share this lock, `task run` must re-read the recovery
+and its complete evidence before consuming it and fail closed on any later
+drift.
+
+### D4a — historical refresh proof versus current recovery authority
+
+Two time questions are deliberately separate:
+
+1. Historical context-refresh authorization is proved by the original shared
+   grant being unexpired and unrevoked at the recorded delegated Knowledge Map
+   approval and Task authorization timestamps, plus the direct mechanical
+   rebound evidence in D3. Later wall-clock expiry does not rewrite history.
+2. Current authority to append recovery and then run requires the exact
+   Task execution authorization for the current Brief/Plan, no remediation hard
+   stop, valid C1 claimant/actor/lease-token identity, and no revocation that
+   invalidates the authority being exercised. Lease expiry alone does not
+   invalidate token identity. Natural expiry without revocation does not
+   invalidate an already-recorded exact Task execution authorization, matching
+   alpha.7.1 runtime semantics. A later grant revocation, changed authorization,
+   actor mismatch, changed C1 claim, or lease-owner/token mismatch blocks both
+   recovery and run. Alpha.7.2 does not add a renewed-grant bridge or rewrite
+   historical delegated evidence.
+
+If legacy fields cannot prove the historical timestamps/policy or current
+authority under these rules, recovery is `NO-GO`; it must not infer authority
+from a reason string, renew a grant implicitly, or weaken an existing gate.
+
+### D5 — runtime resolution and navigation
+
+The guarded remediation gate may treat a stale-Plan `continue-fix` as applying
+to the current Plan only when one unique, fully validated recovery event targets
+that Plan. Without it, `task run` remains blocked.
+
+Corrective-posture discovery must include a guarded `planned` Step when it has
+at least two remediation events. Therefore exact alpha.7.1 state must no longer
+advertise `task run`. If strict recovery assessment succeeds, `next` advertises
+`task corrective-decision-recover` with the exact decision event, Step,
+ordinal, from/to Plan hashes, required actor/lease posture, and then-run intent.
+For claimed C1 posture, `next` must additionally verify that the lease file
+exists, lease owner equals the claimant, and hash(lease token) equals the claim's
+writer-token binding. Lease expiry alone is reported but is not a recovery
+blocker because exact token proof can renew it at the later run. If assessment
+fails, `next` returns a non-running blocked/doctor action with the concrete
+failed predicates. It must never advertise another independent corrective
+decision for the occupied Step/ordinal.
+
+After recovery, `next` may advertise `task run`, and the exact run must pass the
+corrective Plan-binding gate. The alpha.7.2 `next`/run consistency claim is
+strictly scoped to that corrective recovery/binding gate. Existing branch,
+cleanliness, allowedWrites, dependencies, active Knowledge Map, authorization,
+C1, and writer-lease guards still execute normally and may independently block;
+expanding navigation into a complete run preflight is outside this narrow patch.
+
+### D6 — preserved safety properties
+
+- `STATE_SCHEMA_VERSION` remains `2`; canonical Task/Milestone schemas are not
+  broadened.
+- Attempt 3 remains corrective and a third failure remains a hard stop. Recovery
+  is prohibited at or beyond hard stop.
+- Non-`continue-fix` decisions are never recoverable.
+- Reviewer/corrective-auditor independence remains attached to the original
+  decision and is explicitly revalidated through the exact covered
+  decision/remediation/review/attestation history before recovery.
+- Recovery requires current exact execution authorization and does not grant a
+  new authorization.
+- C1 actor and writer-token ownership are checked without refreshing the lease
+  before semantic validation. The later run retains the existing heartbeat
+  behavior.
+- Existing corrective decision uniqueness by Task/Step/ordinal remains intact.
+- Broken corrective, remediation, review, authorization, rebind, or recovery
+  evidence fails closed.
+- Recovery serialization is not authorization: it only prevents duplicate
+  append races after all safety predicates pass.
+
+## Inherited residual risk and broader follow-up
+
+There remains a pre-existing cross-store TOCTOU/crash window after final
+under-lock revalidation because ordinary alpha.7.1 Task, Knowledge Map,
+delegation, sidecar, and lease writers do not participate in the recovery lock.
+This patch neither widens that window nor claims to eliminate it. A later drift
+is detected by mandatory run-time evidence revalidation and blocks execution.
+
+The smallest broader follow-up is a separately authorized shared mutation or
+transaction protocol for all normal `FileStateStore` entity/artifact/sidecar
+writers and `WriterLockManager` lease writers, with crash recovery, stale-lock,
+reentrant composition, and schema-2 compatibility tests. That architectural
+change is explicitly outside alpha.7.2.
+
+## Regression and negative test matrix
+
+The release-blocking deterministic regression is:
+
+`two failures -> continue-fix -> authorized content-only context refresh ->`
+`Plan binding hash changes while normalized Plan is identical -> next offers`
+`recovery -> recovery append succeeds -> next/run reaches the ordinary branch,`
+`authorization, Knowledge, C1 and lease guards with corrective mode permitted`.
+
+It must assert exact attempt ordinal, event IDs/hashes, old/new Plan hashes,
+semantic digest, rebind/authorization evidence, sidecar chain, Task revision,
+and single append. A production-state replay must use the exact `signal_v4`
+Task/Step/decision/hashes in a disposable copy and prove the before/after
+alpha.7.1 and alpha.7.2 navigation results.
+
+Negative tests must separately reject, without writes:
+
+- Step definition, Objective, checks, or allowedWrites changes (with at least
+  requirements/acceptance/risks/expectedOutputs/forbiddenScope covered by the
+  exact normalized-artifact comparator or table-driven siblings);
+- a decision other than `continue-fix`;
+- absent confirmed context-refresh evidence;
+- human, malformed, stale, wrong-transition, or otherwise unauthorized refresh
+  evidence;
+- missing/mismatched/human current Knowledge Map approval, a different grant
+  identity between map and Task authorization, or a non-mechanical Plan Risk
+  Audit rebound;
+- Step or triggering ordinal mismatch;
+- a third failure/hard-stop posture;
+- corrective auditor equal to the latest strict reviewer for a covered
+  review-backed failure;
+- damaged corrective/remediation/recovery event chain or event hash;
+- missing, hash-mismatched, ambiguous, multi-hop, or non-direct historical
+  Plan/rebind evidence;
+- a second independent corrective decision for the occupied Step/ordinal;
+- repeated recovery, which must return the original recovery event byte-for-byte
+  or deterministically reject without any write.
+
+A concurrency regression must launch two recovery attempts from the same Task
+revision and assert that the durable recovery log contains exactly one valid
+event, its chain is intact, one caller succeeds, and the other either receives
+that exact event idempotently or a deterministic serialization/CAS rejection
+without a second append.
+
+A targeted command-local TOCTOU regression must pause after semantic preflight, mutate one
+fingerprinted input before serialization/CAS (at minimum the grant/revocation
+record and one remediation/PRA evidence sidecar in separate cases), then prove
+deterministic `STATE_CONFLICT`, zero recovery events, unchanged Task/lease, and
+no durable sidecar or `.versions` mutation from the rejected recovery.
+
+The sibling constructed state where alpha.7.1 returned
+`task corrective-decision` after refresh must prove that alpha.7.2 routes to
+explicit recovery instead of suggesting an impossible second decision.
+
+## Verification disposition and evidence
+
+Focused deterministic recovery/navigation tests and the exact disposable
+`signal_v4` replay are release-blocking. The full package checks run on Node
+`24.17.0`: validation, release check, pack check, downstream smoke, plugin check,
+and diff hygiene. A final independent audit must review requirements, full diff,
+test/replay evidence, and the inherited residual risk.
+
+Read-only before/after snapshots record `signal_v4` HEAD/branch/index, worktree
+and cached diff digests, stash identities, plus external project-state
+content/metadata digests. Any unexplained difference is a release blocker.
+
+## Executed verification evidence
+
+All commands below ran on Node `24.17.0` in the detached candidate worktree:
+
+- focused recovery suite: `14/14` passed, covering deterministic recovery,
+  exact semantic comparator negatives, non-continue/missing/unauthorized/wrong
+  Step/wrong ordinal/intermediate rebind/hard-stop/reviewer-independence/
+  broken-chain failures, forged actor/scope rejection, idempotence,
+  revocation/C1/autonomy-contract revalidation, injected grant and PRA drift,
+  and two concurrent recovery writers producing one event;
+- `npm run validate`: `106/106` tests passed with typecheck;
+- `npm run release:check`, `npm run pack:check`, `npm run smoke:downstream`,
+  and `npm run plugin:check`: passed;
+- gateway handshake: package `2.0.0-alpha.7.2`, protocol `1`, state schema `2`,
+  capability `corrective-decision-context-recovery-v1`;
+- `git diff --check`: passed, and dry-run/smoke left no tarball in the worktree.
+
+A fresh byte-copy of the original Workflow state produced the exact replay:
+
+1. `next -> task corrective-decision-recover`, Task revision `25`, guarded
+   `STEP-002-FORMALIZATION-CONTRACTS`, CRD
+   `CRD-01M011B4MM5R1FZG2DSDRHVXJ4`, ordinal `3`, exact `21a176... -> 9cb6b0...`
+   Plan hashes;
+2. recovery appended `CDR-01M01C354BRJBDZ0BXZX7A3ARJ`, event hash
+   `18a17a4d9f2b6f7fafb13eb38e2c12122a4e93265c2e96edeb62852fa9dfae68`,
+   evidence fingerprint
+   `6d41590ea49b16183eda20645660f43a383c9cc17210edda2de96d790f5b32ec`,
+   semantic Plan hash
+   `be92aa797218cda1767bb92ced023dd5d7d38f024593b063357f46557f3164ff`;
+3. an identical retry returned that same event and the log remained one event;
+4. `next -> task run`; the exact run passed the corrective gate and changed only
+   disposable state to Task revision `26`, Task/Step `in_progress`, Worker role.
+
+Final read-only snapshots still show `signal_v4` at commit
+`5e26f6c9b4dd0caf57c6a66812121a5b658d4363`, the same branch, clean index and
+worktree digests `e3b0...`, tracked-index digest `a7164020...`, and stash object
+`69c2e5828fa5e31360afe1dbf89154396cc73300`. Two comparable before/after
+snapshot scopes remain unchanged: the signal_v4 project subtree, using
+path-qualified per-file SHA-256 plus mode/size/mtime/ctime metadata, is
+`a24caf122745ae9ed84f64c2484bf7f7750816996559eba9c996ead7a626aa12` /
+`fb77439261056342b6e4b81cad83c4f4ebf7a3807619ba43621783818ab348b4`;
+the entire external schema-v2 root, using relative-path per-file SHA-256 plus
+type/mode/size/mtime metadata, matched its fresh-copy pre-replay composites
+`17f28588d92f9d4386438c5a182618466920a8602361252faaace73727d94a70` and
+`625afd9d281cc5a00af23d4c1ac17efaf7c050d0ebd1a199dee89f090f212bf9`.
+The source main checkout remains clean at `90e4010`; no new tag, push, or publish
+was performed.
+
+## Safe `signal_v4` update/resume path
+
+The release recommendation must preserve:
+
+- Step 1 commit `5e26f6c9b4dd0caf57c6a66812121a5b658d4363` on the existing Task branch;
+- stash `stash@{0}` / object
+  `69c2e5828fa5e31360afe1dbf89154396cc73300`, containing the Step 2 recovery
+  work;
+- Task state revision `25` and all historical sidecars;
+- the current C1 claim and its exact writer-token binding.
+
+After alpha.7.2 is published through a separately authorized release process,
+the safe sequence is: snapshot branch/HEAD/stash/state; update only the
+project-local workflow package with a no-save/no-lock mechanism; verify exact
+package/protocol/schema/project identity; run read-only diagnostics; execute the
+advertised recovery with the existing C1 actor and exact token; verify
+`next -> task run`; launch Step 2 and receive an active Worker envelope; only
+then restore `stash@{0}` while that Worker is ready to continue Step 2 within
+its `allowedWrites`, before Step completion. Never edit external state manually,
+repair/remove the stale lease to bypass evidence checks, restore the stash after
+completion, or pop/drop it before the Worker boundary. Natural historical grant
+expiry follows existing alpha.7.1 authorization semantics; revocation or any
+changed evidence blocks recovery/run. Any missing commit/stash, changed project
+ID, failed evidence predicate, or schema change is `NO-GO`.
+
+## Remaining risks and release gate
+
+Alpha.7.1 did not persist an explicit atomic context-refresh event. Legacy
+recovery therefore proves the strongest available direct conjunction of
+Plan-version, rebind, current map approval, matching historically valid
+delegation, Task authorization, mechanical Plan Risk Audit rebound, reason, and
+Brief evidence,
+but cannot prove the originating method call cryptographically. Confidence is
+high for genuine alpha.7.1 state and deliberately low for manually forged state;
+forged, multi-hop, or ambiguous evidence must fail closed wherever detectable.
+
+Release recommendation is conditional: alpha.7.2 may be released only if the
+narrow implementation satisfies every regression and package check, the exact
+disposable replay proves truthful navigation and permitted run, final audit
+finds no safety regression, and read-only after-snapshots match the signal_v4
+baselines. The inherited global transaction/crash limitation remains an
+explicit residual risk and candidate for a separate architectural release.

package/docs/autonomy-guardrails.md

@@ -75,14 +75,18 @@ start another implementation loop.
 For guarded Steps, remediation attempts are also tracked in
 `remediation-events.jsonl`. Two ordinary remediation attempts are allowed. A third ordinary
 retry is blocked until `task corrective-decision` records a current corrective decision in
-`corrective-decisions.jsonl`. `continue-fix` allows bounded continuation; the other decisions
-stop or redirect ordinary execution. If that third, corrective remediation review also fails,
-Core enters a hard stop: a fourth run and another `continue-fix`/`replan-required` decision are
-rejected. Only `split-required` or `stop-escalate` may be recorded. At the corrective boundary,
-`next` derives a distinct `agent:corrective-auditor:<task-id>` actor; selecting that actor is not
-a human approval, while auditor independence remains mandatory.
-
-## Content-only context refresh
+`corrective-decisions.jsonl`. The corrective gate is derived from the guarded Step, current
+Plan Risk Audit, remediation history, and corrective-decision history, so it remains visible
+after content-only context refresh, Task Knowledge rebind, and reauthorization. `continue-fix`
+allows bounded continuation; `replan-required` requires an actual new Plan posture before
+execution; the other decisions stop or redirect ordinary execution. If that third, corrective
+remediation review also fails, Core enters a hard stop: `next` must report the stop without
+throwing, a fourth run and another `continue-fix`/`replan-required` decision are rejected,
+and only `split-required` or `stop-escalate` may be recorded. At the corrective boundary,
+`next` derives a distinct `agent:corrective-auditor:<task-id>` actor; selecting that actor is
+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:
@@ -96,10 +100,20 @@ task context-refresh
 ```
 
 The command requires the exact Task and Knowledge Map revisions, delegate actor, and grant.
-Core validates both grant transitions before the first write. It is allowed only when an
-already approved source set has content-hash drift and its category, scope, authority, gaps,
-and conflicts are unchanged. New or removed sources and any classification/authority change
-stop on the ordinary visible Knowledge Map flow.
+Core validates both grant transitions and the complete Knowledge diff before the first write.
+The existing content-only path remains limited to an already approved source set whose category,
+scope, authority, gaps, and conflicts are unchanged.
+
+A Milestone Autonomy Grant may additionally admit a new supporting source when the current,
+already execution-authorized Task Plan declares `knowledgeImpact: create` and the source's exact
+normalized file path and scanner category in `knowledgeTargets`. Every added source must match;
+wildcards and directory-like targets are not authority. The Task must belong to that exact
+Milestone and the delegate and grant must still satisfy the immutable autonomy contract. Removed
+sources, canonical additions, unplanned additions, changes to existing category/scope/authority
+or classification identity, changed gaps, and changed or non-empty conflicts fail closed before
+state is written. `next.contextRefresh.addedSources` exposes the exact eligible additions, while
+`next.contextRefreshBlocked.unsafeDifferences` reports the concrete mismatches.
+Standalone Project Memory approval is never enabled by this path.
 
 ## Chat ownership
 
@@ -142,8 +156,9 @@ scope change remains explicit and human-only through `milestone scope-change-pre
 
 After the initial Plan, one human may approve a time-bound (maximum 72 hours) Milestone
 Autonomy Contract. It creates a milestone-scoped grant for Task/Milestone execution and final
-acceptance plus Project Memory approval only inside an atomic content-only Task context refresh
-for the same Milestone. Standalone Project Memory approval remains forbidden. The contract binds
+acceptance plus Project Memory approval only inside an atomic Task context refresh for the same
+Milestone. That refresh covers content-only drift and the exact Plan-bounded supporting-source
+addition described above. Standalone Project Memory approval remains forbidden. The contract binds
 the immutable outcome, success signal, acceptance, checks, discovery, and base branch.
 `milestone autonomy-evolve` may only alter Task memberships; it records the
 agent actor plus the autonomy-contract event hash in the journaled scope-change sidecar and

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "codex-workflow-v2",
-  "version": "2.0.0-alpha.7",
+  "version": "2.0.0-alpha.7.2",
   "description": "Requirements-first Codex development workflow with local state and explicit Git ownership.",
   "repository": {
     "type": "git",

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

@@ -121,10 +121,18 @@ fourth run is prohibited; only split or stop may be recorded.
 
 ## Context refresh
 
+Before `task plan-set`, compare exact Step `allowedWrites` and expected output paths with scanner
+classifications. A planned new scanner-visible Knowledge file must be declared with
+`knowledgeImpact: create` and an exact path/category `knowledgeTargets` entry. Wildcards,
+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
-operation is restricted to content-hash-only drift and records the ordinary delegated map and
-Task authorization evidence. Any semantic map change remains on the normal visible path.
+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
+`contextRefreshBlocked.unsafeDifferences`, keep the change on the normal visible Knowledge path.
 
 Before updating the installed package, run `update preflight`. Continue only for `safe=true`.
 For an alpha.6 project trapped between a pending strict review and forbidden Knowledge rebind,
@@ -171,8 +179,9 @@ codex-workflow milestone autonomy-grant --repo <git-root> --id <MS-ID> \
 ```
 
 The contract issues a milestone-scoped grant for the existing Task/Milestone approval transitions
-and Project Memory approval only inside an atomic content-only Task context refresh for the same
-Milestone. It cannot approve Project Memory independently. `milestone autonomy-evolve --file
+and Project Memory approval only inside an atomic Task context refresh for the same Milestone.
+That composite path covers content-only drift plus exact Plan-bounded supporting-source additions;
+it cannot approve Project Memory independently. `milestone autonomy-evolve --file
 <plan.json>` is permitted only when outcome, success signal, acceptance, checks, discovery, and
 base branch still match the contract. It journals agent actor plus contract evidence and requires
 reauthorization afterward.

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

@@ -43,9 +43,19 @@ classifications, hashes, gaps, conflicts, and approval evidence.
 
 Do not create a memory directory or write project files during scan.
 
+Before `task plan-set`, the Technical Planner compares every exact `allowedWrites` and expected
+output path with the package scanner classifications. If the Plan will create a file that the
+scanner will treat as Project Knowledge (for example a test or documentation source), declare
+`knowledgeImpact: create` and one `knowledgeTargets` entry with that exact normalized path and
+scanner category. Do not replace the path with a wildcard or directory, do not infer or assign
+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. Never use it when the source set,
-classification, authority, gaps, or conflicts changed.
+the returned Task/map revisions, actor, and grant. 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.
 
 ## Product Or Workflow Graph Refresh
 
@@ -112,8 +122,10 @@ For an entire Milestone, prefer one bounded `milestone autonomy-prepare` gate af
 initial membership Plan exists. Show principal, delegate, expiry, semantic-scope hash, policy
 hash, and `MAC-*` code, then stop. A later exact approval permits `milestone autonomy-grant`.
 The resulting grant covers the existing Task/Milestone approval transitions and the Project
-Memory approval portion of an atomic content-only Task context refresh for the same Milestone;
-it never permits standalone Project Memory approval. It also permits `milestone autonomy-evolve`
+Memory approval portion of an atomic Task context refresh for the same Milestone. Besides
+content-only drift, Core may accept exact supporting-source additions predeclared by the current
+execution-authorized Task Plan; unsafe differences remain blocked. The contract never permits
+standalone Project Memory approval. It also permits `milestone autonomy-evolve`
 only for membership changes; any change to outcome, success signal, acceptance, checks,
 discovery, or base branch requires the ordinary human scope-change gate. Never self-renew or
 replace the contract.