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

package/README.md

@@ -13,9 +13,14 @@ 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;
+- read-only update preflight for clean checkout, running-Step, and writer-lease blockers;
+- narrow alpha.6 C1 strict-review rescue without deleting or rotating the bound writer lease;
 - optional time-bound delegated approval with project/Milestone/Task scope and an explicit audit trail;
 - 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 +33,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.6.1
+npx codex-workflow gateway handshake --repo .
 npx codex-workflow doctor --repo .
 ```
 
@@ -44,10 +49,48 @@ npm run plugin:check
 npm run release:check
 ```
 
-## Typical Task flow
+## Alpha.6 Task flow
 
 The CLI emits JSON. Every update after creation requires the current state revision.
 
+For a fresh alpha.6 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 alpha.6 adoption.
+
+### Alpha.6 claimed-C1 strict-review rescue
+
+`2.0.0-alpha.6.1` is a narrow external rescue runner for an exact deadlock: the project still
+declares `2.0.0-alpha.6`, one guarded Step has a pending review at the clean completion HEAD,
+the Project Knowledge Map advanced after that commit, and the Task retains its claimed C1
+lease and original bound writer token. It does not update the project dependency or migrate
+state.
+
+Run the read-only preflight from the exact `2.0.0-alpha.6.1` package. Continue only when it
+returns `eligible=true` and one `update rescue-review` action. The rescue command requires the
+exact Task, Step, revision, claimant actor, and original writer token returned by the C1 lease.
+It preserves and heartbeats that lease; never run `locks repair` first.
+
+```bash
+npx --yes --package codex-workflow-v2@2.0.0-alpha.6.1 -- \
+  codex-workflow update rescue-preflight --repo .
+npx --yes --package codex-workflow-v2@2.0.0-alpha.6.1 -- \
+  codex-workflow update rescue-review --repo . --id TASK-... --step STEP-... \
+  --expected-revision ... --actor agent:task-worker --writer-token <BOUND-TOKEN>
+```
+
+The preflight and CLI output never expose the plaintext token. A missing lease, wrong actor or
+token, dirty checkout, advanced HEAD, unrelated writer lease, or ambiguous
+pending review fails closed without repairing state. After a successful review, follow `next`
+through ordinary Knowledge reconcile/rebind and reach a safe update boundary before changing
+the installed package.
+
 ```bash
 codex-workflow project-memory scan --repo .
 codex-workflow project-memory approve --repo . --expected-revision 1 --file selections.json
@@ -56,22 +99,60 @@ 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.6 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. `split-required` and `stop-escalate` block authorization.
+
+`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.6 sidecars
+
+Alpha.6 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`
+
+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 +170,33 @@ 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; Project Knowledge Map approval requires project scope. Alpha.6 does not
+extend this allow-list to adoption apply, Milestone scope change, or other new human-only
+actions. Revocation is immediate for future uses. The original human path remains available
+and unchanged.
+
+## 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. 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.6 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;