codex-workflow-v2 2.0.0-beta.13.8 → 2.0.0-beta.14

package/docs/development-flow.md

@@ -1,264 +1,61 @@
-# Development Flow
+# Current development flow
 
-## Task lifecycle
+## Task and Milestone
 
-```text
-Project Knowledge Map scan and approval
-  -> Discovery
-  -> Task materialization
-  -> Plan with STEP-* entries and knowledge/graph declarations
-  -> execution authorization
-  -> local task branch or externally owned workspace
-  -> one writer and one commit per Step
-  -> submission evidence
-  -> strict independent review
-  -> Result
-  -> final acceptance
-  -> local merge or external merge confirmation
-```
+Project Knowledge → Discovery → Task/Brief → Plan and independent Risk Audit → execution authorization → claimed workspace → Steps → submission → independent review → Result → final acceptance → merge.
 
-Materialization requires an observable outcome, scope, acceptance criteria, and no
-blocking unknowns. No Task identifier or branch exists before this gate. Task authorization
-is hash-bound to Brief and Plan. Later Plan changes supersede it.
+A Milestone orders required Tasks through an explicit dependency DAG and validates their combined result on its clean base branch. It has no integration branch. Initial assembly creates the linked Tasks before one complete membership Plan; `next` supplies the available assembly options. Required predecessors must be merged before a consumer starts. Started Tasks and completed evidence are retained in history.
 
-In alpha.7, execution authorization also requires a current Plan Risk Audit bound to the same
-Brief, Plan, Knowledge Map, and exact Step set. For existing schema 2 projects upgraded into
-alpha.7, execution additionally requires adoption posture first; remaining legacy scope then
-uses a bootstrap audit over the preserved non-`completed`, non-`skipped` Steps only.
-The audit names a Plan author and independent auditor, binds each guarded failure mode to
-exact executable evidence, and blocks authorization on `split-required` or `stop-escalate`.
+Every mutation uses the current revision and exact Brief/Plan/HEAD bindings. Read `status`, then `next`; execute the advertised transition and refresh both after success. A failed observation or mutation does not authorize another route. `next` is navigation, not proof that arbitrary implementation work will finish.
 
-P01-A adds a second, bounded admission check without adding a lifecycle stage. Before
-`task authorize`, Core reads the selected committed source and recognizes only three versioned
-mechanical forms: an exact root `npm run <literal-script>`, an exact structured
-`path:<repository-relative POSIX path>` output, and that same path supplied by an exact transitive
-Step predecessor with write authority. A proved contradiction returns to `task plan-set` without
-writing an approval. Unsupported commands, prose, or ambiguous future creation remain
-`unverified`, not pass or failure. A clear payload is stored inside the execution authorization,
-bound to the Brief, Plan, analyzer inputs/set, selected HEAD, and phase-aware base/Task branch.
-Freshness is checked before claim lease acquisition, Task start, and direct execution entry.
+## Planning and execution
 
-Local execution creates `codex/task-<id>-<slug>` from a clean base only after authorization.
-An externally owned checkout must already use a dedicated non-base branch. The core never
-creates or removes external worktrees. Each Step declares allowed writes, dependencies, and
-checks. `task run` dispatches exactly one Step and returns a writer lease. The Worker changes
-only allowed files and leaves them uncommitted. Repository-level `next` then returns the exact
-`task step-complete` transition for the active Step. That core transition runs checks, stages
-the allowed changes, creates the atomic Step commit, and records evidence. Unexpected paths,
-failed checks, or any manual/unrecorded Worker commit block completion.
+Discovery must establish an observable outcome, scope, acceptance and resolved blocking unknowns before materialization. A Plan maps requirements to Steps, dependencies, exact allowed paths, checks, outputs and Knowledge impact. The independent Plan Risk Audit binds the same Plan and source context. A proved mechanical contradiction returns to planning; unsupported analysis is `unverified`, not a pass.
 
-If the current Plan Risk Audit marks the Step for strict review, the atomic commit is still
-created by core, but the Step remains non-terminal and `next` routes to `task step-review`
-until commit-bound strict review and reviewer attestation pass.
-Use the exact claimant or required actor from `next` as `--actor`; the independent reviewer
-runs inside Core and is not supplied as the CLI actor.
-The native reviewer uses one closed strict-output schema: every declared object property is
-required, while semantically optional finding fields are represented explicitly as nullable.
-Malformed output fails closed as an unverified review and cannot become remediation authority.
-When `next` includes `gitMutationPolicy`, obtain bounded permission for that exact Git-writing
-transition before the first call instead of probing and retrying after a `.git/index.lock`
-failure. For `task start`, this applies only when invoking `--workspace-owner local`.
+Authorization binds the Plan and its audit. Plan changes supersede it. Local execution starts on the Task branch; an externally owned workspace must already be on a dedicated non-base branch. A current claimant and local credential reference are required wherever fresh `next` specifies them.
 
-After a Step changes approved project knowledge, the Delivery Coordinator reconciles and
-reapproves the Project Knowledge Map, then runs `task knowledge-rebind` between Steps. The
-transition rebuilds `plan.md` from the stored semantic Plan and the active map binding,
-preserves Step status and evidence, records the rebind, supersedes every current execution
-authorization, and moves the Task to `awaiting_execution_authorization`. It rejects an
-active Worker Step, a no-op binding, an invalid knowledge target, or a modified Plan
-artifact. After the user authorizes the rebound Plan, execution resumes in the existing
-workspace; if all Steps are complete, the next action is submission.
+The Worker changes only the dispatched Step's effective allowed paths and leaves changes uncommitted. Core `task step-complete` runs checks, verifies history, makes the atomic Step commit and records evidence. Guarded Steps remain pending until an independent strict review and attestation bind that exact commit. Never substitute a manual commit or a self-authored review.
 
-When `next` returns top-level `action: task context-refresh` with an eligible grant,
-`task context-refresh` composes reconcile, delegated map approval, rebind, and delegated
-execution reauthorization. Do not run standalone reconcile first. Core validates both approval
-transitions before writing. It permits content-only drift and exact Plan-declared supporting-source
-additions under Milestone autonomy; every unsafe source-set, category, scope, authority, gap, or
-conflict change is rejected.
+Failed review ordinarily returns to a fix in the same Task. Attempt count does not authorize success or impose an artificial terminal stop. A replan requires recorded evidence of a Plan obstruction and preserves Task objective, requirements and acceptance. Completed Steps remain verified history. See [guardrails](autonomy-guardrails.md) for recovery and authority boundaries.
 
-Submission requires a clean, auditable Task history and records evidence for the exact
-Task head. `task review-launch` starts a separate read-only reviewer and atomically records its
-result. If C1 handoff is active, keep `--actor` equal to the current claimant or required actor
-from `next`; the reviewer identity remains internal to the compound route. A passing fresh review
-permits Result creation. Final Task acceptance binds Brief, Plan, Result, evidence, and
-the accepted head. It is human/delegated by default; a Task covered by the current audited-remediation
-Milestone authority uses the exact `correctiveDerivedApproval` actor returned by `next` without a
-new human gate. Base advancement forces synchronization, checks, review, and acceptance
-to be repeated before merge.
+After Knowledge changes between Steps, use the current rebind or atomic context-refresh route described in [project memory](project-memory.md). Pending completion/review and already-started failed-Step recovery must not be bypassed with a Knowledge refresh. A fresh execution authorization is required where Core superseded the prior one.
 
-The Technical Planner performs a risk review before authorization. Migration work includes a
-populated forward-upgrade check; concurrent state includes deterministic races; restart,
-replay, and crash claims include restart/crash-window evidence; provider work includes
-failure injection and hidden-default verification. Repeated failed reviews remain on the same
-Task. They require a new remediation Step for final Task review, or another implementation and
-fresh strict review for a failed guarded Step; they do not require a separate corrective Auditor
-based only on attempt count. Guarded attempts above two are recorded as `corrective` and remain
-executable. A reviewer routes to `replan` only with an exact Plan obstruction and minimal Plan
-change; ordinary findings default to `fix`. Remediation cannot change the Task objective,
-requirements, or acceptance.
+Submission binds a clean, auditable Task HEAD. Passing independent review permits Result creation. Result entry releases the execution lease before the human final-acceptance wait; reacquire the credential through fresh `next` before merge. Base advancement can require synchronization, validation and acceptance again.
 
-One bounded exception avoids deliberately repeating an already-proved Plan-integrity failure.
-Missing root scripts and missing mandatory selectors use the advertised evidence-bound
-`replan-required` path. For beta.12.16's exact direct check-support case, fresh `next` instead binds
-the imported SHA/catalog support module and records a machine-derived `continue-fix` scope. Continue
-with fresh `task run`; its envelope contains the original Step paths plus that one support path.
-Core still owns the commit and review packet. Do not add adjacent files or treat this as generic
-permission to change the Plan.
+After every required Task is merged, Milestone validation binds Result, checks and the clean base HEAD. Acceptance uses its exact current confirmation binding. Cancellation retains history and never reverts merged code.
 
-If a later proof Step leaves changes both in its own scope and in files owned by a completed
-transitive predecessor, fresh `next` advertises `task downstream-proof-recover` instead of
-`task step-complete`. The command preserves the dirty worktree and HEAD, append-only records the
-invalidated predecessor completion, yields its C1 lease, and returns the same Task to `task plan-set`.
-The replacement Plan must cover the unfinished remainder and pass a fresh Risk Audit and execution
-authorization. Do not stash, reset, commit, or recreate the Task around this route.
+## Roles and supervision
 
-If the repository is still on a package version that cannot advertise that route, beta.12.6 has
-one update-only bridge. After exact dependency-only commits have aligned the active Milestone base
-and Task branch, `update downstream-proof-dependency-recover` validates recorded history at the
-candidate parent, binds the active proof dirty set by content hash, and registers only the Task
-dependency commit. Product bytes and Step state remain unchanged; fresh `next` must then advertise
-the ordinary `task downstream-proof-recover`. This is not a general dirty-update permission.
+| Role | Owns | Does not grant |
+|---|---|---|
+| User / principal | Semantic scope, classifications, consent and grant policy | Fabricated evidence |
+| Scope Lead | Discovery and unresolved questions | Product edits |
+| Technical Planner | Plan and requirement/check mapping | Execution approval |
+| Coordinator | Current route, dispatch, supervision and closure | Arbitrary authority or scope expansion |
+| Worker | One dispatched Step | Plan changes, self-review or manual Core commits |
+| Independent Reviewer | Immutable review packet and evidence | Fixes or acceptance |
+| Core | State, hashes, transactions, ownership and Git mechanics | Semantic product decisions |
 
-If beta.12.6 already performed that recovery but a subsequent Knowledge approval mechanically
-rebound its rejected Plan, use only the beta.12.7 stranded-replan bridge advertised by fresh `next`.
-The source preflight runs before dependency transport and binds the exact beta.12.6 Task revision,
-HEAD, dirty paths, and content hash. After dependency-only base/Task commits and provenance recovery,
-`task downstream-proof-replan-recover` restores `needs_fix`. Reconcile/approve stale Project Knowledge,
-then replace the full unfinished Plan. The preserved dirty set may enter execution only through one
-new Step whose `allowedWrites` owns every path and whose fresh `next` reports validated carryover.
-Completing that Step still requires its checks, Core-owned commit, and any guarded strict review.
+Use one dedicated Task chat per required Task and a supervising Milestone coordinator. Dispatch uses the packaged registry's unique mapping and fresh TaskContextPacket. A completed chat is not a merged Task: inspect Core state before dispatching a successor. Recoverable continuation stays in the same Task chat. The coordinator waits on active work and stops for a real user gate, an unrecoverable blocker or terminal closure.
 
-A sandboxed Docker `EPERM`, `operation not permitted`, or `permission denied` result is not a failed
-daemon check. Re-run the exact probe/check once with sandbox escalation without consuming a retry.
-Restart Docker Desktop only with separate authorization after the escalated call reaches Docker and
-proves the daemon unavailable.
+For a tracked Worker, verify the real App checkout with `dispatch-context-check` before the first write and after a checkout/branch change. A match is not a writer credential or filesystem permission. Independent reviewers inspect only the bound immutable packet and repository evidence; a different reviewer checkout is not a reason to mutate or reconcile it.
 
-Execution authorization and final acceptance use the human path by default. The only Core-derived
-exception is a current audited-remediation Milestone authority described below. If the user has
-previously issued an active delegation grant for the exact transition and scope, the named
-delegate may perform that transition with `--delegation-grant`. The event keeps the delegate
-as actor and separately records the principal and policy hash. Expired, revoked, wrong-scope,
-wrong-transition, and wrong-actor grants are rejected before the lifecycle state changes.
+## Explaining a change
 
-## Milestone lifecycle
+Use `change explain --task <id> --file <proposal.json>` to assess additional paths, membership or semantic scope against current state. Its closed proposal binds revision, request, HEAD and dirty bytes; it grants no permission. `requiresUser: null` is unknown, not approval. An external permission denial remains separate from Workflow grants.
 
-```text
-Discovery -> Milestone planning -> execution authorization -> active
-  -> required Tasks merge independently into base
-  -> cross-Task validation on clean base HEAD
-  -> final acceptance -> accepted
-```
+Machine-proved check-support scope may use the exact advertised recovery. Unproved additional paths require Plan review. Membership changes and semantic scope changes use their own authority; never widen `allowedWrites` manually. Command input shapes come from the current local CLI `--help`, not copied historical recipes.
 
-A Milestone Plan records outcome, success signal, acceptance, checks, Task membership, and the
-canonical Task dependency DAG. Every membership explicitly supplies `dependsOnTaskIds`, including
-`[]`. A required consumer may depend only on required members of the same Milestone; duplicate,
-self, dangling, external, non-required-provider, and cyclic edges are rejected before commit.
-Membership is `required`, `waived`, or `cancelled`; non-required entries require a reason.
-Changing the Plan increments the membership revision, supersedes execution authorization,
-and prevents new linked Tasks from starting. A Task that has started cannot be removed;
-it can be retained as waived/cancelled with history and reason. Tasks already in progress
-may finish while an amendment awaits authorization.
+## Check execution failures
 
-During initial planning, all linked Tasks may be materialized before one complete
-`milestone plan-set`; no execution is available until the Plan classifies every reverse
-membership. Repository `next` returns `milestone initial-assembly` both before Task 1 and between
-linked Tasks. Its `linked-task-assembly` option explicitly permits `discovery start` and
-`discovery materialize`; after the first linked Task exists, its closing option permits one
-complete `milestone plan-set`. A failed
-`status` or `next` is not permission to call the closing command directly. After that boundary,
-semantic changes use human-only
-`milestone scope-change-prepare` and `milestone scope-change-apply`. A previously issued
-Milestone Autonomy Contract may instead use `milestone autonomy-evolve` for membership-only
-changes while the outcome, success signal, acceptance, checks, discovery, and base branch
-remain unchanged. The same contract may complete an atomic content-only Task context refresh
-without a new human gate, but cannot approve Project Memory independently. Both paths retain
-journaled recovery across `state.json`, `plan.json`, and `scope-change-events.jsonl`. The initial
-Plan uses the same recovery machinery for its exact two-file `state.json` + `plan.json` commit and
-does not manufacture a scope-change event.
+Core drains stdout and stderr while checks run and retains a bounded output tail; large output alone is not a failed check. An ordinary nonzero exit follows the existing product-check failure route. Spawn failures, shell command-unavailable exits (126/127), signals, deadlines, cancellation and unconfirmed cleanup return `CHECK_INFRASTRUCTURE_FAILED` with diagnostic results instead. They do not create a failed-Step cause or authorize fix/replan. Stop the failed invocation, diagnose its infrastructure result, then obtain fresh `status` and `next` before an explicit retry; there is no automatic retry.
 
-There is one narrower route for a confirmed pre-execution topology defect. When the current Plan
-Risk Audit for an unstarted required Task records `stop-escalate`, repository `next` routes through
-a remediation Discovery and then `milestone remediation-materialize`. Core accepts no free-form
-Milestone Plan. It atomically:
+Checks default to 120 seconds per command and 600 seconds for the command batch, plus bounded process cleanup. Configure positive millisecond limits with `CODEX_WORKFLOW_CHECK_TIMEOUT_MS` and `CODEX_WORKFLOW_CHECK_TOTAL_TIMEOUT_MS` (maximum 600000). Library callers can supply `CheckExecutionOptions` as the fourth `WorkflowService` constructor argument. These limits are independent of the repository's development-test deadlines.
 
-- consumes one ready Discovery and creates one new required remediation Task;
-- makes that Task inherit the blocked Task's exact direct predecessor frontier, all already merged;
-- adds exactly one dependency edge from the blocked Task to the remediation Task;
-- preserves Milestone outcome, success signal, acceptance, checks, prior memberships, discovery,
-  and base branch;
-- binds the scope-change sidecar to the exact rejected Task revision, Brief/Plan hashes, and
-  `stop-escalate` audit event/hash;
-- supersedes the old execution authorization and records a `corrective-derived` replacement bound
-  to the prior authorization and audit.
+The synchronous API does not promise delivery of a live JavaScript `AbortSignal` while it blocks. An absolute `CODEX_WORKFLOW_CHECK_CANCEL_FILE` path (or `cancellationFile` option) provides explicit cancellation: creating the file cancels the current check; an existing file prevents launch. The caller owns this file and must clear its cancellation request before an intentional retry. Caller termination is monitored by the separate supervisor. The command and batch deadlines include helper startup.
 
-No confirmation code or human approval is used for this route. It is idempotent per audit and
-rejects dirty checkout, active/stale leases, pending operations, a started Task, a non-current
-audit, a changed predecessor frontier, a non-merged predecessor, or any attempt to change Milestone
-semantics. Repository `next` prioritizes the remediation Task. After it merges, `next` returns the
-original Task to `task plan-set`; its replacement Plan and Risk Audit are evaluated normally.
-Current required Tasks may use the exact `correctiveDerivedApproval.actor` returned by `next` for
-Task execution authorization and final acceptance. Worker handoff, checks, commits, strict review,
-and final Milestone acceptance remain ordinary independent gates.
+On the supported POSIX host, each check has an owned process group. Timeout/cancellation sends TERM then KILL and verifies cleanup before returning success or a product failure; unconfirmed cleanup is an infrastructure failure. The result explicitly reports `cleanupScope: owned-process-group`. Check commands must remain in that owned group: arbitrary daemonization into another session is not an isolation or containment guarantee. Checks have no interactive stdin. Normal shell exit codes are preserved; Core does not invent a signal from a conventional numeric shell exit.
 
-A Milestone has no integration branch. Validation requires all required Tasks to be
-`merged`, checks the current clean base branch, and writes evidence plus Result. Final
-acceptance binds those artifacts to the unchanged base HEAD. Cancellation records a reason
-and never changes Task state or reverts merged commits.
+Infrastructure failure preserves uncommitted files and does not reset Git or manufacture new approvals. Step completion remains retryable under its existing state; Milestone validation leaves its prior result and approvals unchanged. After a Task base sync, Core records the new Git history and invalidates the old final acceptance before checks. Pending sync validation must finish through fresh `task sync-base` without another merge; review, result and acceptance cannot bypass it. A changed Task HEAD, check binding or dirty checkout requires diagnosis and blocks that continuation without deleting files.
 
-Repository-level `next` considers Milestone membership and dependencies before it dispatches a
-Task. A linked Task is actionable only while its Milestone is `active`, its current membership is
-`required`, and every declared required predecessor is `merged`. Handoff prepare, claim before
-lease acquisition, and Task start use the same predicate. Unstarted `waived`/`cancelled`
-memberships and Tasks belonging to
-an accepted/cancelled Milestone are historical records, not work. A Task that already owns
-a workspace does not bypass an unsatisfied Milestone predecessor.
-
-After successful Milestone validation, `next` emits `requiredHumanGate` containing the
-Milestone revision, Plan/Result/evidence hashes, validated base HEAD, and a deterministic
-confirmation code. The coordinator must show this complete binding and stop. Only a later,
-explicit user response containing that code permits `milestone accept --actor ...
---confirmation-code ...`. The CLI rejects a missing, stale, or mismatched code. This proves
-that the recorded confirmation matches the displayed state; identity still depends on the
-trusted Codex/user interaction boundary rather than on the local npm package alone.
-
-With an eligible `milestone.final_accept` grant, `next` additionally returns
-`delegatedApprovalOptions`. The delegate may then use the current `MSA-*` code in the same
-turn because the earlier grant-issuance turn is the controlling user decision. Without such
-an option, the ordinary later-message human gate remains mandatory.
-Pass `--delegation-grant` only when the same `next` response exposes an exact eligible
-`delegatedApprovalOptions` entry for that transition. Ordinary C1 handoff, claim, run,
-step-complete, step-review, merge, and sync-base do not consume a Milestone approval grant.
-
-The Milestone coordinator keeps implementation out of its long-lived context: every required
-Task runs in a dedicated user-visible Task chat. The Milestone chat owns ordering, exact
-delegated transitions, merge observation, cross-Task validation, and final acceptance.
-
-The coordinator creates that chat as a new standalone Codex task, never as a fork/handoff of its
-own thread, and sends only a fresh TaskContextPacket for the exact Task. It creates or reuses the
-chat just before dispatch, not as an empty membership placeholder. The project registry allocates
-one monotonic `#NNN` and builds `#NNN · M<NN> · Coord · <Milestone title> · <MS-ID>` or
-`#NNN · M<NN>/T<NN> · Task · <Task title> · <TASK-ID>`; the Task ordinal still comes from approved
-membership order. Exact readback and registry-owned fallback are mandatory.
-
-Dispatch is followed by an explicit coordinator supervision loop. The Milestone chat waits on the
-one currently routed Task chat with bounded `wait_threads` calls, reads it when it completes or
-needs attention, and then verifies repository `status -> next`. A recoverable non-human boundary is
-returned to the same chat with `send_message_to_thread`; only a genuine user/semantic gate or
-unrecoverable blocker ends the coordinator turn. The next Task chat is created only after Core
-confirms that the prior required Task is terminal and merged. Task completion does not implicitly
-wake a coordinator that has already ended its turn.
-
-## Responsibility boundaries
-
-| Participant | Responsible for | Cannot decide |
-| --- | --- | --- |
-| User / principal | map classifications, direct approvals, delegation policy and revocation, arbitrary scope changes | implementation evidence |
-| Delegate | only transitions explicitly allowed by an active grant | grant creation, expansion, impersonating the principal |
-| Scope Lead | discovery, facts, unknowns, Task/Milestone recommendation | production edits |
-| Technical Planner | requirements mapping, Steps, checks, knowledge impact | authorization |
-| Delivery Coordinator | valid transitions, dispatch, evidence collection, exact audited-remediation route | arbitrary scope expansion |
-| Worker | one dispatched Step within allowed paths | adjacent Steps or Plan changes |
-| Independent Reviewer | isolated comparison of requirements, diff, checks, and evidence | fixes or acceptance |
-| Core CLI | state, revisions, hashes, locks, Git mechanics, diagnostics | semantic product choices |
-
-All mutations use revision compare-and-swap. Dirty state, stale hashes, concurrent writers,
-scope drift, failed checks, invalid reviewer isolation, and changed base HEAD fail closed.
+A base branch that advances again while Task sync validation is pending does not block validation of the recorded Task snapshot. After renewed review and acceptance, the usual base-sync route handles the newer base. If cleanup cannot be verified, retain the reported `cleanupEvidencePath` for diagnosis; it is not permission to signal arbitrary processes or to retry blindly.

package/docs/project-memory.md

@@ -1,50 +1,31 @@
-# Project Memory
-
-## Durable source
-
-Ordinary version-controlled project files are the only durable project memory. Examples
-include `AGENTS.md`, `README.md`, architecture and decision documents, command references,
-ownership rules, testing guidance, operations runbooks, and domain documentation. V2 does
-not create a parallel repository memory bank and does not store file contents in local state.
-
-## Project Knowledge Map
-
-`project-memory scan` deterministically discovers candidate files and stores only path,
-category, scope, authority, content hash, and verification metadata in local state. The user
-approves canonical/supporting choices. Conflicts and missing categories remain explicit.
-
-- Scope Lead scans, presents gaps/conflicts, and requests classification decisions.
-- User owns canonical/supporting approval and resolves semantic conflicts.
-- Technical Planner reads approved sources and declares knowledge impact and targets in Plan.
-- Worker reads canonical sources plus approved Step targets and updates only targets allowed
-  by the Plan.
-- Independent Reviewer checks that required durable knowledge changes are present and bound
-  to the reviewed commit.
-- Delivery Coordinator re-scans after relevant changes, reconciles and reapproves the map,
-  then uses `task knowledge-rebind` before requesting fresh execution authorization.
-
-If any approved file changes, the derived map becomes stale. `project-memory reconcile`
-updates discovered metadata; changed classifications require user approval. A knowledge
-rebind is mechanical: it may change only the Plan's map revision/hash, preserves every Step
-definition, status, and evidence record, records the old/new binding, supersedes execution
-authorization, and cannot run while a Step is in progress. If local state is lost, the map
-is rebuilt from repository files.
-
-For delegated autonomy, repository `next` returns top-level `action: task context-refresh` and an
-exact `contextRefresh` option when the stored map was active and inspection proves eligible drift.
-Do not run standalone reconcile first. `task context-refresh` then performs
-reconcile, delegated map approval, Task rebind, and delegated execution authorization while
-preserving the ordinary audit events. In addition to content-only drift, a Milestone Autonomy Grant
-may admit one or more exact Plan-declared supporting sources. The command rejects removed,
-undeclared, canonical, category/scope/authority-changing, gap-changing, and conflicting sources.
-Those changes remain visible for normal classification and approval.
-
-## Codebase graph
-
-The graph is an optional derived index, never the durable memory authority. The gateway asks
-the core for a fingerprinted refresh request, invokes `codebase-memory-mcp`, and returns
-evidence. The core accepts evidence only for the current root, HEAD/package fingerprint,
-mode, and request ID. The product graph retains its current binding. The workflow graph also
-retains one previous package-version binding. A stale or unavailable provider is recorded
-as explicit fallback; agents continue from approved repository sources and must not present
-fallback as fresh graph evidence.
+# Project Knowledge and code orientation
+
+Version-controlled repository files are durable project knowledge. The local Knowledge Map stores paths, classification, scope, authority and hashes; it does not create a second memory bank or make an MCP index authoritative.
+
+Scope Lead discovers sources and unresolved conflicts; the user approves canonical/supporting classifications. Plans bind approved sources and declare Knowledge impact. Workers update only authorized targets, reviewers verify the result, and coordinators reconcile changed source bindings.
+
+A changed approved file makes its map binding stale. Rebind is mechanical: it preserves Step definitions, status and evidence, records old/new bindings and supersedes execution authorization. It cannot run over an active Worker Step or conceal a Plan obstruction. Pending strict review retains its immutable historical binding and precedes current-map rebind.
+
+When fresh `next` returns `task context-refresh`, use its exact eligible delegate/grant and Task/Knowledge revisions without standalone reconcile first. Core atomically combines reconciliation, scoped approval, rebind and, where execution is eligible, reauthorization. A planning-only refresh preserves stopped planning without execution authority. Content-only drift is eligible only with unchanged classifications, scope, authority, gaps and conflicts. A Milestone contract may additionally admit exact supporting sources already declared by the authorized Plan. Removed, canonical, undeclared or conflicting sources require ordinary classification/approval.
+
+## Workflow code discovery
+
+Use `codebase-memory-mcp` first for workflow implementation orientation. Match the exact workflow source Git root, or the exact installed package root returned by Core for consumer-side workflow diagnostics. Never select a graph by similar project name or use the consumer's product graph to explain package internals.
+
+For source work, verify graph status and refresh the exact checkout when HEAD changes. For installed packages, use the current Core graph request and bind evidence only to that exact root/package fingerprint. Use symbol search, call tracing and selected snippets; do not repeatedly scan the whole tree after a ready graph exists.
+
+Core `graph status` is read-only: it returns the current request, inspected binding and structural `observation` without registering a project, creating locks or recovering journals. A graph result does not authorize lifecycle continuation; use fresh `next` for the permissible transition. `graph refresh-request`, bind and fallback remain explicit mutation commands.
+
+If the provider is unavailable, indexing/refresh cannot complete, or the exact new/non-code artifact is absent, record the operation, source root and reason before scoped filesystem fallback. Do not label fallback as fresh graph evidence. The gateway governs workflow orientation; it does not require indexing product code. Knowledge approval is never evidence that a graph is ready.
+
+## Product graph: inactive
+
+Product graph indexing is not used by the active workflow. Do not request its refresh or binding.
+Absent or stale product bindings do not gate next, Plans, Knowledge approval or context refresh.
+Existing bindings remain readable through explicit diagnostic commands; they are not Knowledge authority.
+Project Knowledge Map continues to use deterministic repository file scanning and its existing approval contract.
+Keep the Plan schema field `graphUse`; use `not-applicable` for new product Plans. Existing `code-aware`
+values do not require an index or a new Knowledge approval. No product refresh owner or schedule is introduced.
+
+The installed-workflow graph indexes the exact installed package. The maintainer graph indexes the
+exact workflow development checkout. Neither is the product graph or a replacement for Knowledge Map.

package/docs/release-app-evidence.md

@@ -0,0 +1,190 @@
+# Supplied Codex App release evidence
+
+This is the external-artifact interface used by [release policy](release.md) and `scripts/release-app-evidence.mjs`. It describes how a release owner supplies evidence after a **real Codex App run on a disposable synthetic project**. It does not authorize a run, approve publication or create an App task. Automatic regression fixtures are never live evidence.
+
+## Candidate and collection
+
+Finish automated qualification for the committed candidate first. Retain `.release/candidate.tgz`, `.release/automated.json`, `.release/passport.json` and their referenced files. Use that retained archive for the App installation; do not repack it. Copy the exact `candidate` object from the passport. `automatedEvidenceSha256` is SHA-256 of the **file bytes** of `.release/automated.json`, including its formatting and final newline.
+
+Preserve and inspect the original Coordinator, Worker and reviewer records. A new Worker task must be created by Coordinator with `create_thread`; a new independent reviewer task can be created by Coordinator or Worker. Three distinct thread IDs are mandatory. A fork, a pending `clientThreadId`, a role description alone or an agent's assertion that another task exists is insufficient.
+
+The actual captured route must include installed `gateway handshake`, Task execution and Step completion, an external sealed review, and a later `merged` outcome for the same Workflow Task. Preserve failures and subsequent checkpoints. The generic lifecycle validator rejects failed navigation, unadvertised mutations, missing checkpoints and unfinished calls; passing that validator alone does not establish App provenance or independent review.
+
+Preserve six separate files:
+
+| Artifact key | Required contents |
+| --- | --- |
+| `dispatch` | Original Coordinator App JSON export containing its identity and Worker creation record; optionally reviewer creation. |
+| `worker` | Original Worker App JSON export containing its identity and its actual App-selected gateway resolution record; reviewer creation if Worker dispatched it. |
+| `reviewer` | Original independent reviewer App JSON export containing its identity and its own exact external review result. |
+| `packet` | Exact Core packet value returned by `task step-review-packet` or `task review-packet`. |
+| `reviewResult` | Exact external review envelope produced by that reviewer, as described below. |
+| `lifecycle` | Actual append-only capture JSONL, with original command results, timestamps and provenance. |
+
+Use the provider's JSON export rather than rewriting its records to fit a sample structure. Preserve provider redactions; never add credentials, confirmation codes or vault contents to the bundle. JSON pointers below locate fields in the available original format. A malformed or unsupported export needs an explicit supported export procedure, not invented tool results.
+
+## Capture interface
+
+The existing bootstrap accepts:
+
+```sh
+node scripts/bootstrap-disposable-release-fixture.mjs \
+  --candidate "$CANDIDATE_TARBALL_ABSOLUTE_PATH" \
+  --sha256 "$EXACT_TARBALL_SHA256" \
+  --version "$EXACT_PACKAGE_VERSION"
+```
+
+`--preflight` performs archive inspection only. Without it, bootstrap creates an isolated repository/state root and synthetic authority; its receipt explicitly records simulated approval and no production consent. Use only the returned disposable paths. Bootstrap success is not an App lifecycle result.
+
+Prepare a capture configuration with these fields. References use `{ "file": "<absolute path>", "sha256": "<actual file SHA-256>" }`:
+
+| Capture configuration field | Binding |
+| --- | --- |
+| `candidate` | Exact workflow candidate commit SHA, a string. |
+| `version` | Exact package version. |
+| `artifact` | Retained candidate tarball reference. |
+| `bootstrapReceipt` | Actual disposable-bootstrap receipt reference. |
+| `repository`, `stateRoot` | Absolute disposable paths from that receipt. |
+| `cli` | Installed `node_modules/codex-workflow-v2/dist/src/cli.js` reference. |
+| `projector` | Installed `dist/src/navigation-actions.js` reference. |
+| `validator` | Exact candidate `scripts/validate-lifecycle-transcript.mjs` reference. |
+| `captureFiles` | Exactly the candidate recorder and its helper references: `scripts/capture-lifecycle.mjs` and `scripts/lifecycle-capture-evidence.mjs`. |
+| `runId` | Unique nonempty identifier for this live capture. |
+| `workerThreadId` | Actual new Worker App thread ID. |
+| `log` | Absolute path of this run's append-only JSONL. |
+
+Run actual lifecycle commands through the recorder from the App task. For example, the initial installed-package observation is:
+
+```sh
+WORKFLOW_CAPTURE_CONFIG="$CAPTURE_CONFIG_ABSOLUTE_PATH" \
+  node scripts/capture-lifecycle.mjs gateway handshake
+```
+
+The recorder supplies the bound repository and JSON output options. Then execute the current package's advertised lifecycle actions with their exact inputs; this document is not a replacement action plan. After each mutation, complete `status`, then `next`. Run `scripts/validate-lifecycle-transcript.mjs --file "$CAPTURE_LOG_ABSOLUTE_PATH"` against the current candidate build to diagnose the collected log.
+
+The recorder emits original provenance fields `candidate`, `artifact.sha256`, `runId`, `workerThreadId`, `cliSource`, `projectorSource`, `validatorSource` and `captureSources`. Release verification compares CLI/projector hashes with bytes extracted from the retained tarball and recorder/helper/validator hashes with candidate source files. Historical absolute paths in provenance are not followed to recover missing evidence. The current native producer format is mandatory: provenance needs `configSha256`; invocation/result events need `phase: "agent"` and `invocationId`; each unique invocation BEGIN must have a matching terminal `invocationId`; terminal results need `exitStatus`, `timedOut`, `stdoutSha256`, `stderrSha256`, `expectedRevision`, `errorCode`, and coherent `ok`/`result` fields. Flattened historical logs or summaries missing these fields are rejected even if the generic lifecycle validator would accept them. Every event needs a valid nondecreasing `recordedAt`, no later than evidence collection; the whole run must remain within the release contract's freshness window.
+
+## Closed evidence envelope
+
+`evidence.json` has **exactly** `schema` and `payload`. All objects explicitly listed as closed below reject additional or missing fields. Original provider exports and the original Core packet remain their native structures.
+
+| Closed object | Exact fields and constraints |
+| --- | --- |
+| Envelope | `schema`: `codex-workflow.release-app-evidence/v1`; `payload`. |
+| `payload` | `candidate`, `automatedEvidenceSha256`, `observedAt`, `environment`, `runId`, `threads`, `taskId`, `artifacts`, `appBindings`. |
+| `candidate` | `version`: exact nonempty version; `commitSha`: 40 lowercase hex characters; `tarballSha256`: 64 lowercase hex characters. All must match the passport. |
+| `environment` | `node`: exact `.node-version` value used by the App run; `platform`: actual `darwin` or `linux`. Windows is not admitted. |
+| `threads` | `coordinator`, `worker`, `reviewer`: distinct actual nonempty App thread IDs. |
+| `artifacts` | Exactly `dispatch`, `worker`, `reviewer`, `packet`, `reviewResult`, `lifecycle`. |
+| Each artifact reference | `path`: relative to `evidence.json`'s directory; `sha256`: 64 lowercase hex characters hashing actual file bytes. |
+| `appBindings` | `dispatches`, `coordinatorThreadPointer`, `workerThreadPointer`, `reviewerThreadPointer`, `reviewerResultPointer`, `gatewayResolutionPointer`. |
+| Original gateway resolution record | `packageVersion`, `skillPath`, `skillSha256`, `pluginManifestSha256`. The record is selected inside the original Worker export, not supplied as a separate summary. |
+| Each of exactly two `dispatches` | `role`, `source`, `recordPointer`, `toolPointer`, `threadPointer`. One role is `worker`, one is `reviewer`. `source` is `dispatch` or `worker`; Worker creation must use `dispatch`. |
+
+`runId` must equal the capture run ID. `taskId` identifies the single Workflow Task whose execution, review and merged outcome are being demonstrated. `observedAt` is the actual ISO timestamp of collecting and checking this run and automated report; it must not precede automated qualification completion. Both automated and App evidence currently expire after seven days, according to the executable contract. A new timestamp cannot refresh old capture events.
+
+No owner attestation, release decision, signature or signing key is part of the evidence contract. Publication authorization is a separate explicit user decision; a complete evidence bundle does not grant that authorization.
+
+Artifact files must be nonempty regular files of at most 32 MiB each. All six paths must differ. Absolute paths, empty components, `.`/`..`, backslashes and symlink traversal are rejected. Keep the complete directory together when transferring the bundle.
+
+The following **placeholder envelope is deliberately invalid and is not live evidence or release approval**. Every angle-bracket value must come from actual records:
+
+```json
+{
+  "schema": "codex-workflow.release-app-evidence/v1",
+  "payload": {
+    "candidate": {
+      "version": "<exact candidate version>",
+      "commitSha": "<exact 40-character commit SHA>",
+      "tarballSha256": "<actual retained tarball SHA-256>"
+    },
+    "automatedEvidenceSha256": "<actual .release/automated.json SHA-256>",
+    "observedAt": "<actual evidence collection ISO timestamp>",
+    "environment": { "node": "<actual pinned Node>", "platform": "<actual darwin or linux>" },
+    "runId": "<actual capture runId>",
+    "threads": { "coordinator": "<actual ID>", "worker": "<different actual ID>", "reviewer": "<third actual ID>" },
+    "taskId": "<actual Workflow Task ID>",
+    "artifacts": {
+      "dispatch": { "path": "coordinator.json", "sha256": "<actual file hash>" },
+      "worker": { "path": "worker.json", "sha256": "<actual file hash>" },
+      "reviewer": { "path": "reviewer.json", "sha256": "<actual file hash>" },
+      "packet": { "path": "packet.json", "sha256": "<actual file hash>" },
+      "reviewResult": { "path": "review-result.json", "sha256": "<actual file hash>" },
+      "lifecycle": { "path": "lifecycle.jsonl", "sha256": "<actual file hash>" }
+    },
+    "appBindings": {
+      "coordinatorThreadPointer": "<pointer into coordinator.json>",
+      "workerThreadPointer": "<pointer into worker.json>",
+      "reviewerThreadPointer": "<pointer into reviewer.json>",
+      "reviewerResultPointer": "<pointer into reviewer.json>",
+      "gatewayResolutionPointer": "<pointer to original gateway resolution result in worker.json>",
+      "dispatches": [
+        { "role": "worker", "source": "dispatch", "recordPointer": "<pointer to original creation record>", "toolPointer": "<relative pointer to tool name>", "threadPointer": "<relative pointer to successful result ID>" },
+        { "role": "reviewer", "source": "worker", "recordPointer": "<pointer to original creation record>", "toolPointer": "<relative pointer to tool name>", "threadPointer": "<relative pointer to successful result ID>" }
+      ]
+    }
+  }
+}
+```
+
+## Original App pointers and reviewer result
+
+Pointers use JSON Pointer syntax: `""` selects the document, `/field/0/value` traverses properties and array indexes, `~0` represents `~`, and `~1` represents `/`. Identity/result pointers start at their named export. A dispatch `recordPointer` first selects one original tool record in its `source` export; `toolPointer` and `threadPointer` are evaluated **inside that record**, not globally.
+
+The tool pointer supports fully qualified exports (`mcp__codex_app__create_thread` or `mcp__codex_app.create_thread`) and native App session records. For a native record, select the original `payload.item` with `recordPointer`: it must have `type: "McpToolCall"`, `server: "codex_app"`, `tool: "create_thread"`, `status: "completed"`, no error and `result.isError: false`. Use `toolPointer: "/tool"` and `threadPointer: "/result/content/0/text/threadId"` (or the actual text block index); JSON inside the original text is traversed directly. Failed calls, forks, another server and pending client IDs are rejected. Preserve the original record; do not rewrite it into a fully qualified synthetic record. The result pointer must resolve to the returned persistent `threadId` of the expected role. If setup returned only a `clientThreadId`, retain the later resolved creation record before proceeding. Do not substitute the client ID.
+
+MCP exports sometimes store JSON inside a string. While following an explicit pointer, the validator parses such an intermediate string before traversing its next property. For example, `/result/content/0/text/threadId` can traverse a `text` string containing `{"threadId":"..."}`. It does not search arbitrary text for a matching substring. `reviewerResultPointer` may also end at a JSON string, which is parsed as the exact review envelope. Markdown prose or fenced JSON is not parsed automatically; retain an original structured result export.
+
+`gatewayResolutionPointer` selects the original Worker's recorded result of reading and hashing the gateway skill selected by its actual App skill catalog. It may end at a JSON-encoded result string, like the reviewer result pointer. The selected record is closed:
+
+```json
+{
+  "packageVersion": "<exact installed workflow package version>",
+  "skillPath": "<actual absolute catalog-selected path ending in SKILL.md>",
+  "skillSha256": "<SHA-256 of the actual selected skill bytes>",
+  "pluginManifestSha256": "<SHA-256 of that installed plugin manifest bytes>"
+}
+```
+
+Verify the original App catalog selection, corresponding skill read/hash operation and installed plugin manifest read/hash operation in that Worker export. A newly authored summary, an arbitrary repository copy or the package handshake alone does not prove which skill App loaded. Preserve the original operation and its result; the JSON pointer selects that result inside the original export. If those original records are absent, collect the missing real App evidence before attachment.
+
+Verification compares `skillSha256` with `plugins/codex-workflow-gateway/skills/codex-workflow-gateway/SKILL.md` extracted from the retained tarball, and `pluginManifestSha256` with its packed `plugins/codex-workflow-gateway/.codex-plugin/plugin.json`. These are the mandatory `gatewaySkillSha256` and `pluginManifestSha256` entries in the verifier's trusted `captureHashes`; they are computed from the candidate archive, not taken on trust from the Worker. An old personal plugin with different bytes fails even if its CLI handshake reports the correct package version. The actual absolute skill path is recorded, never guessed from the repository path or a previous installation. These hashes establish byte bindings, not independent App-provider provenance.
+
+`reviewResult` uses Core's external envelope, not `schemas/review-result.schema.json`'s local process output shape:
+
+```json
+{
+  "protocol": "codex-workflow-external-strict-task-review-v1",
+  "packetHash": "<packet.packetHash>",
+  "repositorySealHash": "<packet.repositorySealHash>",
+  "reviewerThreadId": "<actual independent reviewer ID>",
+  "reviewMode": "ordinary",
+  "review": {
+    "status": "passed",
+    "reviewer": "<actual independent reviewer actor>",
+    "summary": "<reviewer's original summary>",
+    "findings": []
+  }
+}
+```
+
+The two displayed objects are closed. Step packets use `codex-workflow-external-strict-step-review-v1`. `reviewMode` is `ordinary` or `security`, matching the packet; **`external-sealed` is the Core recording mode, not a `reviewMode` value**. An admitted review has status `passed` and no findings. Worker/Coordinator must not author it.
+
+The original packet includes its `packet`, `packetHash`, `repositorySeal`, `repositorySealHash`, `reviewedCommit`, `taskId`, protocol, review mode and native runtime fields; preserve the entire returned value. Packet and seal hashes are SHA-256 of Core's recursively key-sorted canonical JSON, unlike ordinary artifact byte hashes. The sealed repository HEAD must equal `reviewedCommit`. This reviewed commit is the disposable product commit, not the workflow package candidate commit.
+
+The lifecycle must contain that exact packet observation followed by Core's successful sealed-record response with matching packet hash, seal hash, reviewer thread, mode and Task. Actual `task run` returns a nested `value.task`; `task step-complete` returns the Task directly. The verifier follows these Core shapes and requires a later merged Task result. Merely supplying a favorable reviewer JSON file is insufficient.
+
+## Evidence attachment
+
+Prepare `evidence.json` with the exact `schema` and `payload` fields described above. No signature, owner attestation or release-decision field is accepted. Preserve the six original artifacts and their relative paths in the same directory; compute their hashes from the original file bytes. The bundle must bind the retained automated report and exact candidate archive.
+
+Place the intact directory under `.release/app/`, then run:
+
+```sh
+npm run release:passport -- --passport .release/passport.json --app .release/app/evidence.json
+npm run release:verify -- --passport .release/passport.json
+```
+
+Attachment verifies before replacing the passport. It does not publish or infer user consent, and needs no signing key. Release verification rechecks freshness, exact candidate bytes and all required records each time; the stored `releaseEligible` field cannot grant admission. Missing evidence or mismatched hashes blocks with an `APP_EVIDENCE_*` or `RELEASE_*` diagnostic. Preserve the evidence directory and diagnose the stated binding rather than editing old records to manufacture green.
+
+The verifier checks artifact integrity, structure and cross-record consistency. It cannot independently authenticate App-provider provenance: supplied JSON and its hashes are not cryptographic proof of a live App run. Original live records and the independent reviewer remain required; automated fixtures cannot substitute for them. Publication requires separate explicit user authorization and configured registry/release access. R2's detached-process limitation and broader A4 autonomy limitations remain separate known findings even when this specific candidate has complete release evidence.