@deksden-com/dd-flow-cli 0.4.2 → 0.6.0

package/CHANGELOG.md

@@ -1,5 +1,17 @@
 # @deksden-com/dd-flow-cli
 
+## 0.6.0
+
+### Minor Changes
+
+- 47cd270: Add SPC-006 bootstrap stage start/context packets and sealed stage finish, while repairing Memory Bank upgrade stage routing, Codex hook event identity, PATH-stable per-home hook installation, canonical Codex session registration, session coverage projections, terminal orchestrator closure, and safe reconciliation of runs whose legacy authority and workspace are gone.
+
+## 0.5.0
+
+### Minor Changes
+
+- 43bf9c2: Cut over runtime execution to the canonical SQLite-backed flow contract with a single PreToolUse binding, canonical plan progress, resumable worker coverage, and validated `stage-report.json`, `stage-report.md`, and `stage-report.html` artifacts.
+
 ## 0.4.2
 
 ### Patch Changes
@@ -8,19 +20,36 @@
 
 ## 0.4.1
 
+> Release-accounting correction: the entries below were already present in
+> the published `0.4.1` tarball built from `6f85c04`, but their pending
+> Changesets had not been consumed.
+
+### Minor Changes
+
+- Add `dd-flow prompt render` for deterministic RUN-local worker prompts,
+  including validated semantic context and checked `run://` reads.
+
 ### Patch Changes
 
 - Preserve `--project-root` through engine routing, compatibility preflight, protocol services, nested lookups, merge-queue commands, and post-mutation dashboard refresh. Duplicate rootless protocol ids fail closed without side effects, while successful mutations remain successful when an optional dashboard projection fails.
 
 - Include production dependencies in installed engine snapshots, so a routed CLI works outside the source checkout.
 
-## Unreleased
+- Expand `dd-flow run timeline` with stage durations, session roster, usage
+  coverage, artifact references and repeatable `--hide` controls.
 
-### Patch Changes
+- Update canonical Memory Bank resolution for the `mb-upgrade` `05-review`
+  stage instead of requiring a separate top-level `mb-upgrade-review.md`.
+
+- Make typed `PRT-*` and `RUN-*` identity project-scoped and monotonic across
+  registered projects, migrate legacy global keys without renumbering, and
+  ignore legacy date-based protocol ids during allocation.
 
-- Make `PRT-*` and `RUN-*` allocation, persistence and resolution project-scoped. SQLite migrates legacy global primary keys without renumbering ids, including databases whose columns were appended in historical order; duplicate full ids may coexist across projects, and ambiguous context-free protocol lookup fails closed with project candidates.
+- Add source-aware flow-flag snapshots, provenance revisions, grouped session
+  coverage and privacy-safe timing/usage projections.
 
-- Allow `prompt render` to preserve validated RUN-local `required_read` and discovery references through `run://<relative-path>`, while keeping write scopes project-local and rejecting traversal or environment-secret paths.
+- Validate the complete flow-contract catalog before mutable RUN/protocol
+  starts and expose exact read-only diagnostics for invalid catalogs.
 
 ## 0.4.0
 

package/README.md

@@ -75,10 +75,10 @@ dd-flow protocol register HANDSHAKE-001 --project-root "$PWD" --json
 dd-flow protocol status PRT-HANDSHAKE-001 --project-root "$PWD" --json
 ```
 
-Attach and update a plan:
+Inspect the canonical plan and update its SQLite progress projection:
 
 ```bash
-dd-flow plan set PRT-HANDSHAKE-001 --project-root "$PWD" --file plan.json --json
+dd-flow plan status PRT-HANDSHAKE-001 --project-root "$PWD" --json
 dd-flow plan item start PRT-HANDSHAKE-001 P1 --project-root "$PWD" --json
 dd-flow plan item done PRT-HANDSHAKE-001 P1 --project-root "$PWD" --summary "Implemented" --evidence "pnpm test" --json
 ```

package/dist/build-info.json

@@ -1,12 +1,12 @@
 {
   "cli_package": "@deksden-com/dd-flow-cli",
-  "cli_version": "0.4.2",
-  "cli_commit": "5443eeea84ccea3740546a8b0bc3867161ac340b",
-  "built_at": "2026-08-09T09:53:08.521Z",
+  "cli_version": "0.6.0",
+  "cli_commit": "22cf9c8f5293168dae76212c9a4b74b90a1efeab",
+  "built_at": "2026-08-12T05:09:56.163Z",
   "built_with_canon": {
-    "version": "2.17.0",
-    "commit": "2fe1fdc33a0ac43ac223c973c7c05eef0066213a",
-    "flow_contract": "dd-flow-canonical-2026-06",
+    "version": "3.1.0",
+    "commit": "c201167b896a039ff4881d6d816b9735fba2f799",
+    "flow_contract": "dd-flow-canonical-2026-08",
     "repo_root": "/Users/deksden/Documents/_Projects/dd-memorybank",
     "memorybank_root": "/Users/deksden/Documents/_Projects/dd-memorybank/.memory-bank",
     "flow_root": "/Users/deksden/Documents/_Projects/dd-memorybank/.memory-bank/dd-flow",

package/dist/cli/help.js

@@ -21,8 +21,9 @@ Core commands:
   migration impact/plan/report/verify Assess release impact and prepare mb-upgrade migration evidence.
   cleanup scan/apply            Detect and repair stale local runtime state.
   run start/status/list/timeline/usage/flags Track concrete flow executions, timing, source-aware usage and RUN-local flow flags.
+  stage start/finish           Run the canonical two-command stage lifecycle and generate evidence.
   id next                       Preview next typed ids for protocol or run allocation.
-  plan set/status/item          Attach and update protocol plans.
+  plan status/item              Inspect canonical plans and update SQLite progress.
   prompt render                 Render one bounded, RUN-local worker launch prompt.
   lane workspace/lock/status    Manage shared workspace lanes and leases.
   merge status/one-shot/bundle  Inspect, claim, or complete merge work from the current session.
@@ -142,7 +143,7 @@ Usage:
   dd-flow id next --type protocol|run --project-root <root> --slug <slug> --json
   dd-flow run status <RUN-ID|RUN-short-id> --project-root <root> --json
   dd-flow run list --project-root <root> --json
-  dd-flow run timeline <RUN-ID|RUN-short-id> --project-root <root> [--hide stages|events|sessions|usage|artifacts] --json
+  dd-flow run timeline <RUN-ID|RUN-short-id> --project-root <root> --json
   dd-flow run usage <RUN-ID|RUN-short-id> --project-root <root> [--group-by session|role|stage|aspect|plan-item] --json
   dd-flow run flags status <RUN-ID|RUN-short-id> --project-root <root> --json
   dd-flow run flags revise <RUN-ID|RUN-short-id> --project-root <root> --expected-revision <n> --idempotency-key <key> [--preset <name>] [--flag key=value] [--flag key=value] [--allow-downgrade --reason <text>] --json
@@ -150,13 +151,24 @@ Usage:
   dd-flow run complete-stage <RUN-ID|RUN-short-id> --project-root <root> --stage <name> --status <status> [--stage-report <path>] [--data <path>] [--data-schema-id <id>] [--report <path>] [--alias <path>] --json
   dd-flow run complete <RUN-ID|RUN-short-id> --project-root <root> --status done|blocked|cancelled|failed [--verdict <text>] [--next-action <text>] --json
 
-RUN-* is the execution envelope for one concrete flow launch. Semantic truth remains in protocol, experiment, DEF, scenario, evidence, and Memory Bank documents. New run artifacts are stored under DD_FLOW_HOME/projects/<PRJ-ID-slug>/runs/<RUN-ID-slug>/ with run.json, run-index.json and an append-only timeline together. Timeline is the compact full run report: summary is always present, while --hide may suppress bulky sections. The run usage command reconciles registered local Codex transcript counters before reporting; unavailable data is explicit rather than zero.
+RUN-* is the execution envelope for one concrete flow launch. Semantic truth remains in protocol, experiment, DEF, scenario, evidence, and Memory Bank documents. New run artifacts are stored under DD_FLOW_HOME/projects/<PRJ-ID-slug>/runs/<RUN-ID-slug>/ with one run.json projection and an append-only timeline.jsonl. Timeline is the compact full run report: summary is always present, while --hide may suppress bulky sections. The run usage command reconciles registered local Codex transcript counters before reporting; unavailable data is explicit rather than zero.
 
 Examples:
   dd-flow run start --project-root "$PWD" --flow-kind mb_sdlc --subject-type protocol --subject-id PRT-001-demo --slug demo --json
   dd-flow id next --type run --project-root "$PWD" --slug demo --json
   dd-flow run attach-stage RUN-001 --project-root "$PWD" --stage plan --dir 01-plan --status running --json
-  dd-flow run complete-stage RUN-001 --project-root "$PWD" --stage plan --status done --data 01-plan/stage-report.json --stage-report 01-plan/stage-report.html --report 01-plan/report.md --json`
+  dd-flow run complete-stage RUN-001 --project-root "$PWD" --stage plan --status done --data 01-plan/stage-report.json --stage-report 01-plan/stage-report.html --report 01-plan/stage-report.md --json`
+    ],
+    [
+        "stage",
+        `dd-flow stage - execute one bounded stage lifecycle
+
+Usage:
+  dd-flow stage start <RUN-ID|RUN-short-id> --project-root <root> --stage <name> [--dir <NN-stage-slug>] --json
+  dd-flow stage start --bootstrap --project-root <root> --stage specify --subject <safe-subject> [--intake-file <path>] --json
+  dd-flow stage finish <RUN-ID|RUN-short-id> --project-root <root> --stage <name> [--outcome done|blocked|failed] [--semantic-file <RUN-local-json>] --json
+
+stage start is the worker's first practical flow command. It performs deterministic setup and returns a ready-to-use, stage-specific work packet with trusted runtime facts, compatibility and permission preflight, aliases, write boundary and exact finish command. The same packet is written to RUN-local stage-prompt.md and stage-prompt.json. --bootstrap creates the initial protocol/RUN envelope and copies the supplied intake into the RUN home before starting specify. stage finish defaults to @stage/stage-input.json, accepts semantic --outcome and always generates validated JSON, Markdown, template-backed HTML and a durable protocol-summary projection. Raw intake and telemetry remain RUN-local.`
     ],
     [
         "id",

package/dist/cli/run-cli.js

@@ -5,7 +5,7 @@ import { AppError, isAppError } from "../shared/errors.js";
 import { writeJson } from "../shared/json.js";
 import { archiveProject, getProjectStatus, migrateProjectIds, registerProject, resolveProject } from "../services/projects.js";
 import { cancelProtocol, getProtocolBlockers, getProtocolStatus, getReadyProtocols, implementProtocol, readyForMerge, registerProtocol, requireProtocol, syncProtocolFromRun, transitionProtocol } from "../services/protocols.js";
-import { blockPlanItem, completePlanItem, getPlanStatus, setProtocolPlan, skipPlanItem, startPlanItem } from "../services/plans.js";
+import { blockPlanItem, completePlanItem, getPlanStatus, skipPlanItem, startPlanItem } from "../services/plans.js";
 import { cancelMergeQueueJob, claimNextMergeJob, claimMergeBundle, completeMergeBundle, completeMergeJob, failMergeBundle, failMergeJob, getMergeBundleStatus, getMergeQueueStatus, noteMergeJob, waitNextMergeJob } from "../services/merge-queue.js";
 import { getMergeWorkerStatus, oneShotMergeClaim, startMergeWorker, stopProjectMergeWorker } from "../services/merge-worker.js";
 import { cleanupApply, cleanupScan } from "../services/cleanup.js";
@@ -31,6 +31,7 @@ import { resolveProjectRoot } from "../storage/paths.js";
 import { doctorEngines, engineInfo, installCurrentEngine, listEngines, resolveEngine, resolveOperationProjectRoot, routeArgsThroughEngine } from "../services/engines.js";
 import { preflightCliCompatibility } from "../services/compatibility-preflight.js";
 import { renderWorkerPrompt } from "../services/prompts.js";
+import { finishStage, startStage } from "../services/stage-lifecycle.js";
 const defaultIo = {
     stdout: process.stdout,
     stderr: process.stderr,
@@ -151,7 +152,8 @@ function progressForCommand(args) {
         family === "merge-worker" ||
         (family === "protocol" && command === "cancel") ||
         (family === "project" && command === "archive") ||
-        family === "run") {
+        family === "run" ||
+        family === "stage") {
         return [
             { phase: "start", message: `Starting ${family} ${command}`, at: "" },
             { phase: "done", message: `${family} ${command} finished`, at: "" }
@@ -518,14 +520,6 @@ async function dispatch(args, context, io, scopeProjectRoot = null) {
             ...(reason ? { reason } : {})
         });
     }
-    if (family === "plan" && command === "set") {
-        const protocolId = requiredPosition(parsed, 0, "protocol-id");
-        return setProtocolPlan(context, {
-            protocolId,
-            projectRoot: requiredScopeProjectRoot(scopeProjectRoot, "plan set"),
-            file: requiredOption(parsed, "file")
-        });
-    }
     if (family === "plan" && command === "status") {
         const protocolId = requiredPosition(parsed, 0, "protocol-id");
         return getPlanStatus(context, { protocolId, projectRoot: requiredScopeProjectRoot(scopeProjectRoot, "plan status") });
@@ -545,6 +539,33 @@ async function dispatch(args, context, io, scopeProjectRoot = null) {
             ...(workspaceRoot ? { workspaceRoot } : {})
         });
     }
+    if (family === "stage" && command === "start") {
+        const dir = optionalOption(parsed, "dir");
+        const bootstrap = hasOption(parsed, "bootstrap");
+        const subject = optionalOption(parsed, "subject");
+        const intakeFile = optionalOption(parsed, "intake-file");
+        const sessionId = optionalOption(parsed, "session-id");
+        return startStage(context, {
+            projectRoot: requiredOption(parsed, "project-root"),
+            ...(bootstrap ? { bootstrap: { subject: subject ?? requiredOption(parsed, "subject"), ...(intakeFile ? { intakeFile } : {}) } } : { runId: requiredPosition(parsed, 0, "run-id") }),
+            stage: requiredOption(parsed, "stage"),
+            ...(sessionId ? { sessionId } : {}),
+            ...(dir ? { dir } : {})
+        });
+    }
+    if (family === "stage" && command === "finish") {
+        const dir = optionalOption(parsed, "dir");
+        const outcome = optionalOption(parsed, "outcome") ?? optionalOption(parsed, "status");
+        const semanticFile = optionalOption(parsed, "semantic-file") ?? optionalOption(parsed, "data");
+        return finishStage(context, {
+            projectRoot: requiredOption(parsed, "project-root"),
+            runId: requiredPosition(parsed, 0, "run-id"),
+            stage: requiredOption(parsed, "stage"),
+            ...(dir ? { dir } : {}),
+            ...(outcome ? { outcome } : {}),
+            ...(semanticFile ? { semanticFile } : {})
+        });
+    }
     if (family === "lane") {
         return dispatchLane(context, command, parsed);
     }
@@ -1311,11 +1332,15 @@ function dispatchCodexHome(context, parsed) {
 function dispatchCodexHook(context, parsed, stdin) {
     const action = requiredPosition(parsed, 0, "codex hook action");
     if (action === "handle") {
-        return handleCodexHook(context, {
+        const result = handleCodexHook(context, {
             event: requiredOption(parsed, "event"),
-            projectRoot: requiredOption(parsed, "project-root"),
+            projectRoot: optionalOption(parsed, "project-root"),
             stdin
         });
+        if (result && typeof result === "object" && !Array.isArray(result) && "hookSpecificOutput" in result) {
+            return { hookSpecificOutput: result.hookSpecificOutput };
+        }
+        return {};
     }
     throw new AppError("usage", `Unknown codex hook action: ${action}`, 2);
 }
@@ -1591,9 +1616,6 @@ function projectRootForMutation(context, args, result, resolvedScope) {
         const transitionParsed = parseArgs([command ?? "", ...rest]);
         return protocolProjectRoot(context, requiredPosition(transitionParsed, 0, "protocol-id"));
     }
-    if (family === "plan" && command === "set") {
-        return protocolProjectRoot(context, requiredPosition(parsed, 0, "protocol-id"));
-    }
     if (family === "plan" && command === "item") {
         return protocolProjectRoot(context, requiredPosition(parsed, 1, "protocol-id"));
     }
@@ -1624,11 +1646,14 @@ function projectRootForMutation(context, args, result, resolvedScope) {
     if (family === "run" && ["start", "attach-stage", "complete-stage", "complete", "flags"].includes(command ?? "")) {
         return requiredOption(parsed, "project-root");
     }
+    if (family === "stage" && ["start", "finish"].includes(command ?? "")) {
+        return requiredOption(parsed, "project-root");
+    }
     if (family === "worktree" && ["create", "bootstrap", "close"].includes(command ?? "")) {
         return protocolProjectRoot(context, requiredOption(parsed, "protocol-id"));
     }
     if (family === "codex" && command === "hook" && requiredPosition(parsed, 0, "codex hook action") === "handle") {
-        return requiredOption(parsed, "project-root");
+        return optionalOption(parsed, "project-root");
     }
     if (family === "codex" && command === "hooks") {
         const action = requiredPosition(parsed, 0, "codex hooks action");
@@ -1671,7 +1696,7 @@ function isScopedProtocolMutation(family, command) {
     if (family === "protocol")
         return ["transition", "sync-from-run", "ready-for-merge", "cancel"].includes(command ?? "");
     if (family === "plan")
-        return command === "set" || command === "item";
+        return command === "item";
     if (family === "worktree")
         return ["create", "bootstrap", "close"].includes(command ?? "");
     if (family === "merge-queue")

package/dist/domain/flow-contract.js

@@ -332,7 +332,6 @@ function flagStrength(key, value, definition) {
         "subagents.route": ["self_check", "grouped_subagent", "focused_subagent", "mixed"],
         "subagents.grouping": ["off", "allowlisted"],
         "subagents.pool_fallback": ["one", "runtime"],
-        "observability.detail": ["compact", "normal", "full"],
         "knowledge.extract": ["skip", "conditional", "required"],
         "knowledge.promote": ["skip", "conditional", "required"],
         "workspace.bootstrap.mode": ["not_required", "revalidate", "required"],
@@ -360,9 +359,12 @@ function numberValue(value) {
     return typeof value === "number" && Number.isInteger(value) ? value : null;
 }
 export function normalizeFlowContract(value) {
-    const id = requireString(value.id, "/id");
     const version = requireNumber(value.version, "/version");
-    if (version > 3)
+    const id = requireString(value.id, "/id");
+    if (version === 4 || version === 5 || version === 6) {
+        return normalizeCanonicalRuntimeContract(value, id, version);
+    }
+    if (version > 6)
         fail("/version", `unsupported flow-contract version: ${version}`);
     if (version === 3 && !/^dd-flow-canonical-[0-9]{4}-[0-9]{2}$/.test(id)) {
         fail("/id", "must identify a canonical version 3 flow contract");
@@ -396,6 +398,83 @@ export function normalizeFlowContract(value) {
         ...(flowFlags ? { flow_flags: flowFlags } : {})
     };
 }
+/**
+ * Canonical 2026-08 deliberately owns runtime mechanics rather than the
+ * protocol transition graph. Keep the latter as a CLI-owned derived adapter
+ * so existing protocol services can make the same guarded decisions while
+ * the project file remains the canonical v4/v5 contract.
+ */
+function normalizeCanonicalRuntimeContract(value, id, version) {
+    if (id !== "dd-flow-canonical-2026-08") {
+        fail("/id", "must identify the canonical 2026-08 runtime contract");
+    }
+    const stages = {
+        registered: { terminal: false },
+        priming: { terminal: false },
+        specify: { terminal: false },
+        plan: { terminal: false },
+        interactive: { terminal: false },
+        consolidation: { terminal: false },
+        hardening: { terminal: false },
+        implementation: { terminal: false },
+        readiness: { terminal: false },
+        ready_for_merge: { terminal: false },
+        queued_for_merge: { terminal: false },
+        integration: { terminal: false },
+        cancelled: { terminal: true },
+        closed: { terminal: true },
+        blocked: { terminal: false },
+        waiting_for_user: { terminal: false }
+    };
+    const legacyAliases = {
+        f: "priming",
+        prime_intake: "specify",
+        g0: "specify",
+        m1: "readiness",
+        m2: "integration",
+        prime: "priming"
+    };
+    const transitions = {
+        registered: ["priming", "specify", "interactive", "blocked", "waiting_for_user"],
+        priming: ["specify", "interactive", "closed", "blocked", "waiting_for_user"],
+        specify: ["plan", "implementation", "blocked", "waiting_for_user"],
+        plan: ["implementation", "blocked", "waiting_for_user"],
+        interactive: ["consolidation", "blocked", "waiting_for_user"],
+        consolidation: ["hardening", "blocked", "waiting_for_user"],
+        hardening: ["readiness", "blocked", "waiting_for_user"],
+        implementation: ["readiness", "blocked", "waiting_for_user"],
+        readiness: ["ready_for_merge", "closed", "blocked", "waiting_for_user"],
+        ready_for_merge: ["queued_for_merge", "integration", "closed", "blocked", "waiting_for_user"],
+        queued_for_merge: ["integration", "blocked", "waiting_for_user"],
+        integration: ["closed", "blocked", "waiting_for_user"],
+        cancelled: [],
+        closed: [],
+        blocked: ["specify", "plan", "interactive", "consolidation", "hardening", "implementation", "readiness", "ready_for_merge", "closed"],
+        waiting_for_user: ["specify", "plan", "interactive", "consolidation", "hardening", "implementation", "readiness", "ready_for_merge", "blocked", "closed"]
+    };
+    const entrypoints = recordValue(value.stage_lifecycle);
+    const autoPolicy = recordValue(value.validation);
+    return {
+        id,
+        version,
+        capabilities: [
+            "flow_run_snapshot.v1",
+            "session_coverage_units.v1",
+            "privacy_safe_observability.v1",
+            ...(version >= 5 ? ["canonical_protocol_plan.v1"] : []),
+            ...(version >= 6 ? ["stage_bootstrap_context_packet.v1"] : [])
+        ],
+        stages,
+        transitions,
+        readiness: { command: "ready-for-merge", allowed_from: ["readiness", "ready_for_merge"], target_stage: "ready_for_merge" },
+        merge_queue: { complete: { target_stage: "closed", next_action: "none" } },
+        defaults: { registered_next_action: "prime_or_protocol" },
+        legacy_aliases: legacyAliases,
+        ...(entrypoints ? { entrypoints } : {}),
+        ...(autoPolicy ? { auto_policy: autoPolicy } : {}),
+        route_aliases: { none: "no_plan", short: "compact_plan", full_plan: "full_plan" }
+    };
+}
 function findProjectFlowContractPath(projectRoot) {
     const basePath = path.join(projectRoot, ".memory-bank", "dd-flow", "flow-contract");
     for (const extension of [".json", ".yaml", ".yml"]) {

package/dist/domain/session-coverage.js

@@ -0,0 +1,88 @@
+export function reconcileSessionCoverageRows(sessions) {
+    const sessionCounts = countValues(sessions.map((session) => session.session_id));
+    const duplicateSessionIds = duplicates(sessionCounts);
+    const invalidSessionIds = [];
+    const parsed = sessions.map((session) => {
+        try {
+            return { session, units: normalizeCoverageUnits(JSON.parse(session.coverage_units_json || "[]")) };
+        }
+        catch {
+            invalidSessionIds.push(session.session_id);
+            return { session, units: [] };
+        }
+    });
+    const orchestrators = parsed.filter(({ session }) => session.session_kind === "orchestrator");
+    const workers = parsed.filter(({ session }) => session.session_kind !== "orchestrator");
+    const expectedCounts = countValues(orchestrators.flatMap(({ units }) => units.map((unit) => unit.unit_id)));
+    const expectedUnitIds = [...expectedCounts.keys()].sort();
+    const duplicateExpectedUnitIds = duplicates(expectedCounts);
+    const observedOwners = new Map();
+    for (const { session, units } of workers) {
+        for (const unit of units) {
+            const owners = observedOwners.get(unit.unit_id) ?? [];
+            owners.push(session.session_id);
+            observedOwners.set(unit.unit_id, owners);
+        }
+    }
+    const observedUnitIds = [...observedOwners.keys()].sort();
+    const missingUnitIds = expectedUnitIds.filter((unitId) => !observedOwners.has(unitId));
+    const duplicateUnitIds = [...observedOwners.entries()]
+        .filter(([, owners]) => new Set(owners).size > 1)
+        .map(([id]) => id)
+        .sort();
+    const diagnostics = [];
+    if (orchestrators.length === 0)
+        diagnostics.push("orchestrator_session_missing");
+    if (orchestrators.length > 1)
+        diagnostics.push("multiple_orchestrator_sessions");
+    if (workers.length > 0 && expectedUnitIds.length === 0)
+        diagnostics.push("expected_worker_units_missing");
+    if (missingUnitIds.length > 0)
+        diagnostics.push("expected_worker_units_unobserved");
+    if (duplicateUnitIds.length > 0 || duplicateExpectedUnitIds.length > 0)
+        diagnostics.push("duplicate_coverage_binding");
+    if (duplicateSessionIds.length > 0)
+        diagnostics.push("duplicate_session_binding");
+    if (invalidSessionIds.length > 0)
+        diagnostics.push("invalid_coverage_units");
+    const unavailable = orchestrators.length === 0 || invalidSessionIds.length > 0;
+    const partial = orchestrators.length !== 1
+        || (workers.length > 0 && expectedUnitIds.length === 0)
+        || missingUnitIds.length > 0
+        || duplicateUnitIds.length > 0
+        || duplicateExpectedUnitIds.length > 0
+        || duplicateSessionIds.length > 0;
+    return {
+        status: unavailable ? "unavailable" : partial ? "partial" : "complete",
+        expected_unit_ids: expectedUnitIds,
+        observed_unit_ids: observedUnitIds,
+        missing_unit_ids: missingUnitIds,
+        duplicate_unit_ids: duplicateUnitIds,
+        duplicate_expected_unit_ids: duplicateExpectedUnitIds,
+        duplicate_session_ids: duplicateSessionIds,
+        orchestrator_session_ids: orchestrators.map(({ session }) => session.session_id).sort(),
+        invalid_session_ids: [...new Set(invalidSessionIds)].sort(),
+        diagnostics
+    };
+}
+function normalizeCoverageUnits(value) {
+    if (!Array.isArray(value))
+        throw new Error("coverage_units must be an array");
+    return value.map((item) => {
+        if (!item || typeof item !== "object" || Array.isArray(item))
+            throw new Error("coverage unit must be an object");
+        const unitId = item.unit_id;
+        if (typeof unitId !== "string" || unitId.length === 0)
+            throw new Error("coverage unit requires unit_id");
+        return { unit_id: unitId };
+    });
+}
+function countValues(values) {
+    const counts = new Map();
+    for (const value of values)
+        counts.set(value, (counts.get(value) ?? 0) + 1);
+    return counts;
+}
+function duplicates(counts) {
+    return [...counts.entries()].filter(([, count]) => count > 1).map(([id]) => id).sort();
+}

package/dist/domain/validation.js

@@ -1,6 +1,11 @@
+import fs from "node:fs";
+import path from "node:path";
+import { fileURLToPath } from "node:url";
+import { Ajv } from "ajv/dist/ajv.js";
 import { AppError } from "../shared/errors.js";
-import { allowedPlanKinds, allowedPlanStatuses, isAllowedStage } from "./contracts.js";
+import { isAllowedStage } from "./contracts.js";
 import { normalizeStage } from "./flow-contract.js";
+let validateCanonicalPlan;
 export function requireStage(value, contract) {
     if (!isAllowedStage(value, contract)) {
         throw new AppError("validation", `Unknown protocol stage: ${value}`, 2);
@@ -8,77 +13,100 @@ export function requireStage(value, contract) {
     return contract ? normalizeStage(value, contract) : value;
 }
 export function validatePlan(input, expectedProtocolId) {
-    const plan = input;
-    if (!plan || typeof plan !== "object" || Array.isArray(plan)) {
+    if (!input || typeof input !== "object" || Array.isArray(input)) {
         throw new AppError("validation", "Plan must be a JSON object", 2);
     }
-    requireString(plan.schema_version, "schema_version");
-    requireString(plan.plan_id, "plan_id");
-    requireString(plan.protocol_id, "protocol_id");
-    requireString(plan.title, "title");
+    validateCanonicalPlanStructure(input);
+    const plan = input;
+    const errors = [];
     if (expectedProtocolId && plan.protocol_id !== expectedProtocolId) {
-        throw new AppError("validation", "Plan protocol_id does not match command protocol id", 2, {
+        errors.push({
+            path: "/protocol_id",
+            message: "Plan protocol_id does not match command protocol id",
             expectedProtocolId,
             actualProtocolId: plan.protocol_id
         });
     }
     if (!Array.isArray(plan.items)) {
-        throw new AppError("validation", "Plan items must be an array", 2);
+        errors.push({ path: "/items", message: "Plan items must be an array" });
+        throw new AppError("validation", "Plan validation failed", 2, { errors });
     }
     const ids = new Set();
-    const items = plan.items.map((item, index) => validatePlanItem(item, index));
+    const items = [];
+    plan.items.forEach((item, index) => {
+        try {
+            items.push(validatePlanItem(item, index));
+        }
+        catch (error) {
+            errors.push(validationIssue(error, `/items/${index}`));
+        }
+    });
     for (const item of items) {
         if (ids.has(item.id)) {
-            throw new AppError("validation", `Duplicate plan item id: ${item.id}`, 2);
+            errors.push({ path: "/items", message: `Duplicate plan item id: ${item.id}` });
         }
         ids.add(item.id);
     }
     for (const item of items) {
         for (const dep of item.depends_on) {
             if (!ids.has(dep)) {
-                throw new AppError("validation", `Plan item ${item.id} depends on missing item ${dep}`, 2);
+                errors.push({ path: `/items/${item.id}/depends_on`, message: `Plan item ${item.id} depends on missing item ${dep}` });
             }
         }
     }
+    if (errors.length > 0) {
+        throw new AppError("validation", "Plan validation failed", 2, { errors });
+    }
     return { ...plan, items };
 }
-function validatePlanItem(input, index) {
+function validationIssue(error, path) {
+    return {
+        path,
+        message: error instanceof AppError ? error.message : String(error)
+    };
+}
+export function validatePlanItem(input, index) {
     const item = input;
     if (!item || typeof item !== "object" || Array.isArray(item)) {
         throw new AppError("validation", `Plan item ${index} must be an object`, 2);
     }
     const id = requireString(item.id, `items[${index}].id`);
     const kind = requireString(item.kind, `items[${index}].kind`);
-    if (!allowedPlanKinds.includes(kind)) {
-        throw new AppError("validation", `Invalid plan item kind for ${id}: ${kind}`, 2);
-    }
-    const status = requireString(item.status, `items[${index}].status`);
-    if (!allowedPlanStatuses.includes(status)) {
-        throw new AppError("validation", `Invalid plan item status for ${id}: ${status}`, 2);
-    }
     if (!Array.isArray(item.depends_on) || item.depends_on.some((dep) => typeof dep !== "string")) {
         throw new AppError("validation", `Plan item ${id} depends_on must be a string array`, 2);
     }
-    if (!Array.isArray(item.evidence) || item.evidence.some((entry) => typeof entry !== "string")) {
-        throw new AppError("validation", `Plan item ${id} evidence must be a string array`, 2);
-    }
+    const targetStage = requireString(item.target_stage, `items[${index}].target_stage`);
     return {
+        ...item,
         id,
-        kind: kind,
+        kind,
         title: requireString(item.title, `items[${index}].title`),
-        status: status,
+        status: "pending",
         depends_on: item.depends_on,
-        stage: requireString(item.stage, `items[${index}].stage`),
+        stage: targetStage === "code" ? "implementation" : targetStage,
+        target_stage: targetStage,
         required: requireBoolean(item.required, `items[${index}].required`),
         owner: requireString(item.owner, `items[${index}].owner`),
-        summary: typeof item.summary === "string" ? item.summary : "",
-        evidence: item.evidence,
+        summary: requireString(item.summary, `items[${index}].summary`),
+        evidence: [],
         ...(item.semantic_spine ? { semantic_spine: validateSemanticSpine(item.semantic_spine, id) } : {}),
         ...(item.execution_context ? { execution_context: validateExecutionContext(item.execution_context, id) } : {}),
         ...(typeof item.block_reason === "string" ? { block_reason: item.block_reason } : {}),
         ...(typeof item.user_required === "boolean" ? { user_required: item.user_required } : {})
     };
 }
+function validateCanonicalPlanStructure(input) {
+    const validate = validateCanonicalPlan ??= new Ajv({ allErrors: true, strict: false, validateFormats: false }).compile(JSON.parse(fs.readFileSync(path.resolve(path.dirname(fileURLToPath(import.meta.url)), "..", "schemas", "protocol-plan.schema.json"), "utf8")));
+    if (validate(input))
+        return;
+    throw new AppError("validation", "Plan validation failed", 2, {
+        errors: (validate.errors ?? []).map((error) => ({
+            path: error.instancePath || "/",
+            message: error.message ?? "schema validation failed",
+            keyword: error.keyword
+        }))
+    });
+}
 function validateExecutionContext(input, itemId) {
     const context = requireRecord(input, `Plan item ${itemId} execution_context`);
     return {

package/dist/protocol/local-files.js

@@ -2,7 +2,7 @@ import fs from "node:fs";
 import path from "node:path";
 import { schemaVersion } from "../domain/contracts.js";
 import { loadProjectFlowContract } from "../domain/flow-contract.js";
-import { ensureDir, planJsonPath, protocolDir, stateJsonPath } from "../storage/paths.js";
+import { ensureDir, protocolDir, stateJsonPath } from "../storage/paths.js";
 export function ensureProtocolFiles(input) {
     const storageRoot = input.storageRoot ?? input.projectRoot;
     const dir = protocolDir(storageRoot, input.protocolId);
@@ -120,21 +120,6 @@ export function readStateFile(file, protocolId) {
 export function writeState(file, state) {
     fs.writeFileSync(file, `${JSON.stringify(state, null, 2)}\n`);
 }
-export function readPlan(projectRoot, protocolId) {
-    return readPlanFile(planJsonPath(projectRoot, protocolId));
-}
-export function readPlanFile(file) {
-    if (!fs.existsSync(file)) {
-        return undefined;
-    }
-    return JSON.parse(fs.readFileSync(file, "utf8"));
-}
-export function writePlan(projectRoot, protocolId, plan) {
-    writePlanFile(planJsonPath(projectRoot, protocolId), plan);
-}
-export function writePlanFile(file, plan) {
-    fs.writeFileSync(file, `${JSON.stringify(plan, null, 2)}\n`);
-}
 function readStateIfExists(file) {
     if (!fs.existsSync(file)) {
         return undefined;