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

package/docs/alpha7.1-implementation-brief.md

@@ -0,0 +1,268 @@
+# codex-workflow-v2 2.0.0-alpha.7.1 implementation brief
+
+## Status and authority
+
+This document is the single source of truth for the local `2.0.0-alpha.7.1`
+release candidate. It was authorized in the current Codex task on 2026-08-14.
+Workflow V2 must not be used to organize or authorize this development work.
+
+The candidate is based on the published tag `v2.0.0-alpha.7` at commit
+`b7ce0b5e14791e8177c104a2344dfb46f459696f` and is developed in the standalone
+repository `/Users/home-pc/htdocs/codex-workflow-v2` on the isolated branch
+`codex/workflow-v2-alpha7-1`.
+
+No tag, push, or npm publication is authorized. The `signal_v4` repository,
+its external Workflow state, and its Milestone 3 state are read-only evidence
+and must not be changed.
+
+## Problem statement
+
+Alpha.7 adds a bounded Milestone autonomy contract, but its guarded remediation
+state machine is not internally consistent after a strict Step review failure
+causes Project Knowledge refresh, Task Knowledge rebind, and delegated
+reauthorization.
+
+The production-shaped failure is:
+
+1. A guarded Step fails two strict reviews and records two ordinary remediation
+   events.
+2. The Step's commits make Project Knowledge stale.
+3. Project Knowledge is reconciled and approved, then the Task Plan is rebound
+   and reauthorized under a new Plan hash.
+4. The Task remains runnable and the failed Step remains the remediation target,
+   but `next` no longer advertises `task corrective-decision` because the gate is
+   derived only for `needs_fix`.
+5. `recordStepCorrectiveDecision` also accepts only `needs_fix` or a narrowly
+   defined `blocked` unverified-review posture, so the advertised and executable
+   transitions can diverge.
+
+This creates a lifecycle deadlock and previously encouraged signal-specific
+rescue patches. Alpha.7.1 must fix the generic transition semantics. It must not
+hard-code repository names, Task IDs, Step IDs, revisions, commits, Plan hashes,
+or package-upgrade rescue identities.
+
+The real-agent E2E exposed a second autonomy deadlock. A normal Task that adds a
+new test can cause the repository scanner to add that file as a supporting
+Knowledge source. The Milestone autonomy contract currently permits only
+content-hash-only atomic refresh, so the new source forces another human approval
+even when its exact path, category, authority, and reason were declared in the
+authorized Task Plan. Alpha.7.1 must distinguish such Plan-bounded supporting
+source additions from unplanned source-set or authority changes.
+
+## User outcomes
+
+1. A Milestone coordinator can execute a bounded Milestone autonomously without
+   asking for repeated human approvals covered by the Milestone autonomy
+   contract.
+2. A guarded Step gets at most two ordinary remediation attempts, then exactly
+   one independently audited corrective attempt when `continue-fix` is chosen.
+3. Project Knowledge refresh, Task Knowledge rebind, and delegated
+   reauthorization preserve the remediation posture rather than losing or
+   bypassing it.
+4. `next` always recommends a transition that the corresponding command can
+   execute from the same immutable state, subject only to the evidence explicitly
+   named by that recommendation.
+5. A third failed guarded remediation reaches a hard stop. Only split or stop
+   escalation is permitted; a fourth run is impossible.
+6. Discovery quality is checked, but ordinary human incompleteness and
+   non-blocking unknowns do not require the user to pre-plan agent behavior.
+7. A Task may add a supporting Knowledge source declared by its already
+   authorized Plan without creating another human gate; undeclared additions,
+   canonical-source additions, removals, authority/category changes, gaps, and
+   conflicts still fail closed.
+
+## Required state-machine semantics
+
+### R1 — generic corrective posture
+
+Derive the corrective posture from the current guarded Step, current Plan Risk
+Audit, remediation history, and corrective-decision history. Do not infer it
+solely from `Task.status`.
+
+The derivation must work when the same failed guarded Step is represented in any
+legitimate post-failure/post-refresh status produced by the Workflow, including
+`needs_fix`, post-rebind `ready`, post-authorization `ready`, and the existing
+blocked/unverified strict-review retry posture.
+
+### R2 — `next`/command consistency
+
+If a guarded Step has two failed remediation events and no decision for attempt
+3, `next` must advertise `task corrective-decision` before `task run` regardless
+of a content-only Knowledge refresh, Plan rebind, or delegated reauthorization.
+
+When `next` advertises `task corrective-decision`,
+`recordStepCorrectiveDecision` must accept the same Task/Step state with the
+recommended revision, Plan Risk Audit, actor/lease posture, and independent
+auditor evidence.
+
+### R3 — Plan rebind continuity
+
+Knowledge rebind may create a new Plan hash. Historical remediation events remain
+immutable. A corrective decision is bound to the current Plan hash and the exact
+covered remediation event IDs. Rebind must not reset attempt counts or permit a
+third ordinary attempt.
+
+### R4 — bounded recovery
+
+- Attempts 1 and 2 are ordinary.
+- Attempt 3 requires an independent corrective decision.
+- `continue-fix` enables exactly the third corrective attempt.
+- `replan-required` requires an actual new Plan posture before execution.
+- `split-required` and `stop-escalate` block execution.
+- After a third failed remediation event, `next` must expose a stable hard-stop
+  action and must not throw while merely reporting status.
+- A fourth `task run` and a fourth `continue-fix` decision are prohibited.
+
+### R5 — priority ordering
+
+Pending strict review for an already recorded completion commit outranks
+Knowledge refresh. After that review is terminal, required Project Knowledge
+refresh and Task Knowledge rebind remain mandatory. Once current knowledge and
+authorization are restored, an outstanding corrective decision outranks another
+run. C1 claim/handoff constraints remain authoritative and must not be bypassed.
+
+### R6 — Milestone autonomy
+
+The alpha.7 Milestone autonomy contract remains bounded by its immutable semantic
+scope, delegate, expiry, policy hash, and allowed transitions. It may cover
+Milestone execution/final acceptance, Task execution/final acceptance, and
+content-only Project Knowledge approval. Semantic scope changes still require
+new human authority. Alpha.7.1 must not broaden these permissions.
+
+### R7 — Plan-bounded supporting-source refresh
+
+The user explicitly authorized this bounded delegated-approval expansion in the
+current Codex task after the real-agent E2E exposed the supporting-source
+deadlock. The authorization is limited to the complete fail-closed predicate
+below.
+
+The atomic delegated `task context-refresh` transition may accept a newly
+discovered Knowledge source only when all of the following are true:
+
+- the active Task belongs to the Milestone named by the autonomy grant;
+- the current authorized Task Plan declares `knowledgeImpact: create` and an
+  exact `knowledgeTargets` entry for the new path and category;
+- the scanner classifies that exact path and category as `supporting`;
+- no previously approved source is removed;
+- no existing source changes category or authority;
+- no unplanned source is added;
+- gaps and conflicts are unchanged and no new conflict exists.
+
+The transition remains atomic: reconcile, approve the exact safe candidate,
+rebind Task Knowledge, and supersede execution authorization together. It must
+not permit standalone Project Memory approval, canonical-source creation,
+wildcard/directory targets, or mutation beyond the Task's current Plan and the
+existing Milestone autonomy policy. `next` must expose this delegated refresh
+only when the complete predicate is satisfied and otherwise report the concrete
+unsafe differences.
+
+## Required tests
+
+### Deterministic replay (release-blocking)
+
+Add a production-shaped regression using opaque, non-hard-coded Step IDs. It must
+replay the complete sequence:
+
+1. Milestone autonomy and delegated Task authorization.
+2. Guarded Step completion and strict-review failure 1.
+3. Ordinary remediation, completion, and strict-review failure 2.
+4. Project Knowledge staleness, content-only reconcile/approval, Task Knowledge
+   rebind, refreshed Plan Risk Audit, and delegated reauthorization.
+5. `next -> task corrective-decision` and successful recording by an auditor
+   distinct from the latest strict reviewer.
+6. Corrective attempt 3 and successful strict review, followed by Task completion.
+7. A sibling replay where attempt 3 fails and proves stable hard-stop reporting,
+   rejection of a fourth run, and rejection of `continue-fix` for attempt 4.
+
+The replay must assert state, sidecar bindings, attempt ordinals, Plan hashes,
+returned actions, and absence of repository-specific rescue logic.
+
+Add a sibling deterministic replay for R7. It must prove that one exact
+Plan-declared supporting test source can be accepted through atomic delegated
+context refresh, while an undeclared source, a canonical addition, a removal,
+and an authority/category change remain ineligible and cannot mutate state.
+
+### Existing suites (release-blocking)
+
+`npm run validate`, `npm run release:check`, `npm run pack:check`,
+`npm run smoke:downstream`, and `npm run plugin:check` must pass sequentially
+under the repository's supported Node version. Parallel build/clean scripts are
+not valid evidence because they race on shared output directories.
+
+### Real-agent isolated E2E (release-blocking)
+
+Create `test-runs/2.0.0-alpha.7.1/project` as a disposable repository inside the
+standalone project. Use the sibling `codex-home`, `workflow-state`, `plugin-root`,
+`npm-cache`, and `evidence` directories for complete isolation. Install the
+candidate from a local `npm pack` tarball, not the public registry. The globally
+installed Codex Workflow plugin remains disabled; the real agent loads only the
+candidate gateway from the isolated plugin root.
+
+Run a real Delegate agent through:
+
+`initial Discovery -> Milestone -> bounded Milestone autonomy -> Tasks -> strict
+review/remediation and Knowledge refresh -> merge/handback -> Milestone validate
+-> delegated final accept`.
+
+The Milestone must be small enough to finish but contain at least three Tasks:
+
+1. A bounded safe-contract implementation Task that adds a Plan-declared
+   supporting test source and exercises the R7 atomic refresh path.
+2. A guarded persistence/documentation Task that causes content drift and two
+   deterministic strict-review failures before a bounded corrective success,
+   exercising reconcile, rebind, and reauthorization.
+3. A composition/acceptance Task that closes the Milestone.
+
+The initial Discovery prompt should imitate a real product-owner request: desired
+outcome, examples and constraints are present, while implementation details,
+exact Step decomposition, retry mechanics, and some non-blocking design choices
+are deliberately omitted. The agent must discover and resolve what it can,
+record non-blocking unknowns honestly, and proceed without asking the user to
+predict its implementation behavior. The signal_v4 M3 Discovery may be used as
+read-only style evidence, but its domain and identifiers must not be copied into
+the candidate logic.
+
+E2E acceptance requires the Milestone to reach final acceptance, all Tasks to be
+terminal, repository state clean, no active or stale writer leases, no action
+requiring human approval inside the granted semantic scope, and an evidence log
+that identifies every command/action and final entity status without secrets.
+The run must include at least one new supporting test source admitted through the
+R7 atomic delegated context-refresh path; manually approving that source is not
+acceptable passing evidence.
+
+## Ownership and integration
+
+- Main coordinator: owns this Brief, integration, local tarball, isolated E2E,
+  final evidence, and all decisions that cross file ownership.
+- State-machine implementer: owns production changes in `src/` and directly
+  related contracts/reference documentation. Must not edit E2E evidence.
+- E2E/test owner: owns deterministic regression tests, fixtures, and isolated E2E
+  harness documentation/scripts. Must not change production semantics without a
+  written finding to the coordinator.
+- Independent auditor: starts only after implementation and E2E evidence are
+  complete; reviews Brief-to-diff traceability, test validity, release artifacts,
+  and residual risks without editing implementation files.
+
+All contributors share the worktree, must preserve concurrent edits, and must not
+revert changes they did not create.
+
+## Stop-loss and release gate
+
+All local iterations retain version `2.0.0-alpha.7.1`; individual failures do not
+create alpha.7.2/alpha.7.3 versions. No publication occurs until deterministic
+replay, the real-agent Milestone, and independent audit all pass.
+
+If real-agent execution cannot be completed because Codex cannot be launched with
+the required isolation or cannot exercise a deterministic failure seam, that is
+a release blocker, not permission to substitute a mocked test.
+
+## Deliverables
+
+1. This Brief.
+2. Generic source diff and reference documentation.
+3. Deterministic replay and all package validation evidence.
+4. Local alpha.7.1 tarball identity and downstream installation evidence.
+5. Real-agent E2E evidence through Milestone final acceptance.
+6. Independent audit with every finding resolved or explicitly accepted by the
+   user.
+7. Remaining risks and a release recommendation. No tag, push, or publish.

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.1",
   "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.

package/references/state-machine.md

@@ -37,11 +37,16 @@ bindings, supersedes execution authorization, and returns the Task to
 `awaiting_execution_authorization`. It cannot run while a Step is `in_progress` or while the
 Task is `blocked`; unrelated blocks must be resolved through their owning transition.
 
-For guarded remediation, two ordinary remediation attempts are allowed. A third
+For guarded remediation, two ordinary remediation attempts are allowed. Corrective posture is
+derived from the guarded Step, current Plan Risk Audit, remediation history, and
+corrective-decision history rather than from `Task.status` alone, so the same gate survives
+content-only Knowledge refresh, Task Knowledge rebind, and later reauthorization. A third
 ordinary retry is blocked until a current corrective decision exists for the same Step and
-Plan binding. `continue-fix` allows bounded continuation; `replan-required`,
-`split-required`, and `stop-escalate` stop ordinary execution. A failed third corrective
-attempt is a hard stop: no fourth run or new continue/replan decision is accepted.
+Plan binding. `continue-fix` allows exactly the third corrective attempt; `replan-required`
+requires an actual new Plan posture before execution; `split-required` and `stop-escalate`
+stop ordinary execution. A failed third corrective attempt is a hard stop: `next` must
+report the stop without throwing, no fourth run is allowed, and no new `continue-fix` or
+`replan-required` decision is accepted.
 
 Milestone authorization is bound to its Plan and membership revision. Plan amendments
 supersede authorization. Milestone validation and acceptance are bound to the current base
@@ -62,8 +67,14 @@ After that boundary, semantic updates use human-only `milestone scope-change-pre
 `milestone scope-change-apply`. A human-confirmed, expiring Milestone Autonomy Contract may
 use `milestone autonomy-evolve` only for membership changes while outcome, success signal,
 acceptance, checks, discovery, and base branch remain fixed. It may also approve Project Memory
-only within an atomic content-only context refresh for a Task in that Milestone; standalone map
-approval remains forbidden. Both update paths journal
+only within an atomic context refresh for a Task in that Milestone; standalone map approval
+remains forbidden. In addition to content-only drift, that composite transition may accept a new
+supporting source only when its exact normalized path and scanner category were declared by the
+current execution-authorized Task Plan under `knowledgeImpact: create`. The Task must belong to
+the grant's Milestone. Every added source must match the Plan, and removals, canonical additions,
+wildcard or directory targets, existing source category/scope/authority changes, gaps, and
+conflicts fail closed before any state write. `next` exposes the composite option only when the
+full predicate passes and otherwise reports concrete unsafe differences. Both update paths journal
 `state.json`, `plan.json`, and `scope-change-events.jsonl` together. Membership integrity is validated
 before scheduling, Task start, Milestone validation, scope change, and repository `next`.
 The same guard scans in reverse and blocks every live Task whose `milestoneId` is absent from