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

package/CHANGELOG.md

@@ -1,5 +1,11 @@
 # @deksden-com/dd-flow-cli
 
+## 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 +14,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/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.5.0",
+  "cli_commit": "64b75acbb2e62c9e80eb29c501f5f3481f86cf20",
+  "built_at": "2026-08-11T10:20:58.455Z",
   "built_with_canon": {
-    "version": "2.17.0",
-    "commit": "2fe1fdc33a0ac43ac223c973c7c05eef0066213a",
-    "flow_contract": "dd-flow-canonical-2026-06",
+    "version": "3.0.0",
+    "commit": "1e8c39078ed7a34adde93315a9cdcf2bbfc15374",
+    "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.
@@ -150,13 +151,23 @@ 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 finish <RUN-ID|RUN-short-id> --project-root <root> --stage <name> [--status done|blocked|failed] [--semantic-file <RUN-local-json>] --json
+
+stage start attaches the stage, archives an earlier attempt when needed and writes one RUN-local stage-prompt.md. stage finish derives a bounded report 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,28 @@ async function dispatch(args, context, io, scopeProjectRoot = null) {
             ...(workspaceRoot ? { workspaceRoot } : {})
         });
     }
+    if (family === "stage" && command === "start") {
+        const dir = optionalOption(parsed, "dir");
+        return startStage(context, {
+            projectRoot: requiredOption(parsed, "project-root"),
+            runId: requiredPosition(parsed, 0, "run-id"),
+            stage: requiredOption(parsed, "stage"),
+            ...(dir ? { dir } : {})
+        });
+    }
+    if (family === "stage" && command === "finish") {
+        const dir = optionalOption(parsed, "dir");
+        const status = 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 } : {}),
+            ...(status ? { status } : {}),
+            ...(semanticFile ? { semanticFile } : {})
+        });
+    }
     if (family === "lane") {
         return dispatchLane(context, command, parsed);
     }
@@ -1313,7 +1329,7 @@ function dispatchCodexHook(context, parsed, stdin) {
     if (action === "handle") {
         return handleCodexHook(context, {
             event: requiredOption(parsed, "event"),
-            projectRoot: requiredOption(parsed, "project-root"),
+            projectRoot: optionalOption(parsed, "project-root"),
             stdin
         });
     }
@@ -1591,9 +1607,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 +1637,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 +1687,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

@@ -360,9 +360,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) {
+        return normalizeCanonicalRuntimeContract(value, id, version);
+    }
+    if (version > 5)
         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 +399,82 @@ 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"] : [])
+        ],
+        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/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;

package/dist/schemas/code-stage-report.schema.json

@@ -124,10 +124,10 @@
     "run": {
       "type": "object",
       "additionalProperties": true,
-      "required": ["run_id", "run_index"],
+      "required": ["run_id", "run_state"],
       "properties": {
         "run_id": { "type": "string", "pattern": "^RUN-[0-9]{3}-[a-z0-9]+(?:-[a-z0-9]+)*$" },
-        "run_index": { "type": "string", "minLength": 1 }
+        "run_state": { "type": "string", "minLength": 1 }
       }
     },
     "stage": {