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

package/README.md

@@ -13,10 +13,18 @@ automation do not import anything from the parent V1 project.
 - Discovery precedes Task or Milestone identifiers and branches;
 - Project Knowledge Map approval binds Plans to current canonical files;
 - safe Task Plan knowledge rebind preserves Step evidence and requires fresh authorization;
+- delegated content-only context refresh composes map refresh, rebind, and reauthorization
+  without hiding classification changes;
 - optional `codebase-memory-mcp` product and workflow graph bindings with explicit fallback;
 - one writer lease and one atomic Git commit per completed Step;
 - explicit execution authorization, independent review, and a state-bound human final-acceptance gate;
+- high-risk Plan guidance and a mandatory separate corrective audit after two failed reviews;
+- executable proof obligations with hostile counterexamples for every guarded failure mode;
+- read-only update preflight for clean checkout, running-Step, and writer-lease blockers;
+- narrow, read-only alpha.6 strict-review rescue preflight for the lifecycle deadlock fixed in alpha.7;
 - optional time-bound delegated approval with project/Milestone/Task scope and an explicit audit trail;
+- one bounded Milestone Autonomy Contract for approvals, guarded content-only context refresh,
+  and membership-only Task-graph evolution;
 - Milestones aggregate already merged Tasks on the base branch, without an integration branch;
 - V1 transition is snapshot-only and never performs semantic import.
 
@@ -28,8 +36,8 @@ cross-machine synchronization are not part of its contract.
 Node.js 22 or newer is required. Consumers pin the exact package version:
 
 ```bash
-npm install --save-dev --save-exact codex-workflow-v2@2.0.0-alpha.4
-npx codex-workflow gateway handshake
+npm install --save-dev --save-exact codex-workflow-v2@2.0.0-alpha.7
+npx codex-workflow gateway handshake --repo .
 npx codex-workflow doctor --repo .
 ```
 
@@ -44,10 +52,21 @@ npm run plugin:check
 npm run release:check
 ```
 
-## Typical Task flow
+## Alpha.7 Task flow
 
 The CLI emits JSON. Every update after creation requires the current state revision.
 
+For a fresh alpha.7 project, registration writes the adoption posture automatically. For an
+existing schema 2 project, apply adoption before execution:
+
+```bash
+codex-workflow update preflight --repo .
+codex-workflow state adoption-prepare --repo .
+codex-workflow state adoption-apply --repo . --actor user:owner --confirmation-code ADA-...
+```
+
+Do not use `state migrate` for schema-2 adoption.
+
 ```bash
 codex-workflow project-memory scan --repo .
 codex-workflow project-memory approve --repo . --expected-revision 1 --file selections.json
@@ -56,22 +75,63 @@ codex-workflow discovery start --repo . --goal "..." --outcome "..." \
 codex-workflow discovery materialize --repo . --id DISC-... \
   --expected-revision 1 --kind task --title "..."
 codex-workflow task plan-set --repo . --id TASK-... \
-  --expected-revision 1 --file plan.json
+  --expected-revision 1 --file plan.json --risk-audit-file plan-risk-audit.json
 codex-workflow task authorize --repo . --id TASK-... \
   --expected-revision 2 --actor user
 codex-workflow task start --repo . --id TASK-... \
   --expected-revision 3 --workspace-owner local
 codex-workflow task run --repo . --id TASK-... --step STEP-001 \
   --expected-revision 4 --owner worker
+# Worker changes only allowed files and leaves them uncommitted.
+codex-workflow task step-complete --repo . --id TASK-... --step STEP-001 \
+  --expected-revision 5 --writer-token <TOKEN-FROM-TASK-RUN>
 ```
 
-`task run` returns the writer token and Worker context. `task review-launch` starts the
-strict read-only reviewer after submission. If a completed Step changes approved project
+`task run` returns the writer token and Worker context. The Worker must not stage or commit.
+`task step-complete` runs configured checks, creates the workflow-owned atomic commit, and
+either records completion immediately or leaves the Step non-terminal for `task step-review`
+when the current Plan Risk Audit marks it for strict review.
+
+The Plan Risk Audit is mandatory for every new alpha.7 Task before execution authorization,
+including a positive `approved` decision for a Plan with no guarded Steps. The audit sidecar
+must identify a Plan author and an independent auditor, classify every current Step exactly
+once, describe guarded failure modes, and bind required evidence to exact executable Step
+checks. Every guarded failure mode additionally needs one `proofObligations` entry containing
+the hostile `counterexample`, expected safe result, and an exact executable evidence command.
+`split-required` and `stop-escalate` block authorization. Historical alpha.6 audit sidecars
+remain readable for strict-review recovery, but newly recorded audits must use proof obligations.
+
+`task review-launch` starts the strict read-only reviewer after submission. If a completed Step changes approved project
 knowledge, reconcile and approve the map, then run `task knowledge-rebind --repo . --id
 TASK-... --expected-revision ...`. The rebind changes no Step definition, preserves runtime
 status and evidence, supersedes execution authorization, and requires `task authorize`
 before another Step or submission. Use `next` after transitions.
 
+When `next.contextRefresh` offers a delegated content-only option, the coordinator may use:
+
+```bash
+codex-workflow task context-refresh --repo . --id TASK-... \
+  --expected-task-revision ... --expected-map-revision ... \
+  --actor agent:deputy --delegation-grant DGR-...
+```
+
+New/removed sources, category/authority changes, gaps, or conflicts are never auto-approved.
+
+## Alpha.7 sidecars
+
+Alpha.7 keeps canonical entity JSON unchanged and stores guardrail evidence in append-only
+sidecars:
+
+- project: `adoption-posture.jsonl`
+- task: `plan-risk-audits.jsonl`, `step-review-events.jsonl`,
+  `reviewer-attestations.jsonl`, `remediation-events.jsonl`,
+  `corrective-decisions.jsonl`, `handoffs.jsonl`
+- milestone: `scope-change-events.jsonl`, `autonomy-contract-events.jsonl`
+
+Milestone scope-change recovery also uses Milestone-local `.transactions/` journal files.
+Broken JSONL, duplicate event ids, broken hash chains, stale revision/hash/commit bindings,
+or mismatched authority fail closed with structured diagnostics.
+
 ## Delegated approval
 
 Delegation never makes an agent a human actor. A user first approves an exact grant policy;
@@ -89,10 +149,54 @@ codex-workflow task authorize --repo . --id TASK-... --expected-revision 2 \
 
 Policies may allow only `project_memory.approve`, `task.execution_authorize`, `task.final_accept`,
 `milestone.execution_authorize`, and/or `milestone.final_accept`. Scope is one project,
-Milestone, or Task; Project Knowledge Map approval requires project scope. Revocation is immediate for future uses. The original human path remains
-available and unchanged.
-
-See [development flow](docs/development-flow.md), [delegated approval](docs/delegated-approval.md), [updating an existing project](docs/updating-existing-project.md), [project memory](docs/project-memory.md),
+Milestone, or Task; ordinary Project Knowledge Map approval requires project scope. Alpha.7 does
+not extend this allow-list. A separate Milestone Autonomy Contract may authorize membership-only
+evolution and the `project_memory.approve` half of an atomic, content-only Task context refresh
+for the same Milestone. It cannot approve Project Memory as a standalone operation. Outcome,
+success signal, acceptance, checks, discovery, and base branch remain cryptographically fixed.
+Adoption apply and semantic scope changes stay human-only. Revocation is immediate for future
+uses. The original human path remains available and unchanged.
+
+## Milestone autonomy and alpha.6 rescue
+
+Materialize all linked Task discoveries while the new Milestone remains in its initial planning
+posture, then call `milestone plan-set` once with the complete classified membership. Execution
+is unavailable until that full Plan exists. To approve a bounded autonomous run for up to 72
+hours, use `milestone autonomy-prepare` and, after confirming its `MAC-*` binding,
+`milestone autonomy-grant`. The resulting milestone-scoped grant covers Task/Milestone execution
+and final-acceptance approvals plus Project Memory approval only inside an atomic content-only
+Task context refresh for the same Milestone. `milestone autonomy-evolve` may change only
+memberships and always supersedes the current execution authorization; semantic changes require
+the ordinary human scope-change path.
+
+`update rescue-preflight` is a read-only compatibility route for one exact deadlock shape:
+the project is pinned to `2.0.0-alpha.6`, exactly one strict review is pending, the checkout and
+completion HEAD are exact, and no active lease exists. It returns only stale-lock repair and
+strict-review actions. It neither installs alpha.7 nor rewrites state.
+
+## C1 handoff and legacy adoption
+
+`C1` coordination uses `task handoff-prepare` (with `task handoff` retained as an alias),
+`task claim --claim-token ...`, and `task handback-create` (with `task handback` retained as
+an alias). `task handoff-show` returns the persisted safe bindings but never the plaintext
+claim token. If `--target-actor` is omitted, alpha.7 deterministically derives a distinct
+`agent:worker:<task-id>` actor. Preparation returns a one-time claim token and a prompt bound to `handoffId`, Task
+revision, Brief/Plan/Knowledge hashes, Milestone display positions, delegate/grant, expiry,
+and exact expected next action. Only the token hash is persisted. Milestone-linked Tasks must
+be claimed before start; terminal handback records result, evidence, review, knowledge,
+limitations, and recommended-next bindings. This does not prove a physically separate Codex
+thread.
+
+For legacy schema 2 projects:
+
+- accepted/cancelled Milestones stay terminal;
+- merged/cancelled Tasks stay terminal;
+- completed and skipped Steps in active Tasks keep their recorded status and evidence;
+- remaining non-completed, non-skipped legacy Steps need a bootstrap Plan Risk Audit at a
+  safe boundary;
+- newly created Milestones, Tasks, and Steps use the full alpha.7 contract.
+
+See [development flow](docs/development-flow.md), [autonomy guardrails](docs/autonomy-guardrails.md), [delegated approval](docs/delegated-approval.md), [updating an existing project](docs/updating-existing-project.md), [project memory](docs/project-memory.md),
 [accepted decisions](docs/decisions.md), [validation report](docs/validation-report.md), and
 [release policy](docs/release.md).
 

package/dist/src/alpha6/adoption.d.ts

@@ -0,0 +1,55 @@
+import type { AdoptionPostureEvent, AdoptionRepositoryIdentity, MilestoneState, TaskState } from '../contracts.js';
+import type { RepositoryIdentity } from '../repository.js';
+import type { FileStateStore } from '../state/store.js';
+export interface AdoptionSidecarInventoryEntry {
+    scope: 'project' | 'task' | 'milestone';
+    ownerId: string;
+    sidecarName: string;
+    contentHash: string;
+}
+export interface AdoptionPreparationInput {
+    projectId: string;
+    repositoryIdentity: AdoptionRepositoryIdentity | RepositoryIdentity;
+    packageVersion: string;
+    protocolVersion: number;
+    stateSchemaVersion: number;
+    tasks: TaskState[];
+    milestones: MilestoneState[];
+    sidecarInventory: AdoptionSidecarInventoryEntry[];
+    blockers: string[];
+    now: Date;
+}
+export interface AdoptionPreparation {
+    status: 'missing' | 'ready' | 'applied';
+    safe: boolean;
+    blockers: string[];
+    currentPosture: AdoptionPostureEvent | null;
+    baselineDigestHash: string;
+    sidecarBaselineHash: string;
+    confirmationCodeBindingHash: string | null;
+    confirmationCode: string | null;
+    candidateEvent: AdoptionPostureEvent | null;
+}
+export interface AdoptionStatus {
+    status: 'missing' | 'ready' | 'applied';
+    safe: boolean;
+    blockers: string[];
+    currentPosture: AdoptionPostureEvent | null;
+    baselineDigestHash: string;
+    sidecarBaselineHash: string;
+}
+export interface ProjectRegistrationAdoptionInput {
+    projectId: string;
+    repositoryIdentity: AdoptionRepositoryIdentity | RepositoryIdentity;
+    packageVersion: string;
+    protocolVersion: number;
+    stateSchemaVersion: number;
+    now: Date;
+}
+export declare function readCurrentAdoptionPosture(store: FileStateStore, projectId: string): AdoptionPostureEvent | null;
+export declare function status(input: AdoptionPreparationInput, currentPosture?: AdoptionPostureEvent | null): AdoptionStatus;
+export declare function buildAdoptionPreparation(input: AdoptionPreparationInput, currentPosture?: AdoptionPostureEvent | null): AdoptionPreparation;
+export declare function initializeProjectRegistrationAdoption(store: FileStateStore, input: ProjectRegistrationAdoptionInput): AdoptionPostureEvent;
+export declare function applyAdoptionPosture(store: FileStateStore, input: AdoptionPreparationInput, actor: string, confirmationCode: string): AdoptionPostureEvent;
+export declare function buildProjectRegistrationAdoptionEvent(input: AdoptionPreparationInput): AdoptionPostureEvent;
+export declare function assertAdoptionBaselinePreserved(posture: AdoptionPostureEvent, tasks: TaskState[], milestones: MilestoneState[]): void;