@mstar-harness/engine 3.9.4 → 3.10.0

package/dist/audit.d.ts

@@ -1,4 +1,5 @@
 import type { GateResult } from "./core.js";
+import { type WorkflowDeliveryKind } from "./workflow.js";
 /** Priority values (mstar-audit SKILL.md § Plan output (all variants) Status block). */
 export declare const AUDIT_PRIORITIES: readonly ["P1", "P2", "P3"];
 export type AuditPriority = (typeof AUDIT_PRIORITIES)[number];
@@ -226,6 +227,20 @@ export type PromoteAuditPlansOptions = {
     harnessDir: string;
     /** Default: basename of `outDir` (e.g. `audit-2026-08-22`). */
     workflowId?: string;
+    /**
+     * Delivery kind declared for the promoted plans (contract §1/§4a). Required —
+     * the promoted lifecycle is a `type: plan` workflow, so its delivery kind is
+     * declared at registration, never inferred and never defaulted in code (an
+     * audit promotion that left it unset minted an active snapshot no close path
+     * could complete).
+     */
+    deliveryKind: WorkflowDeliveryKind;
+    /** Delivery source branch, recorded as `branch.source`. Required for `development`. */
+    branchSource?: string;
+    /** Delivery target branch, recorded as `branch.target`. Required for `development`. */
+    branchTarget?: string;
+    /** Completion policy for `verification/report-only` promotions. Required for that kind. */
+    completionPolicy?: string;
 };
 /**
  * Promote selected audit plans into the v2 workflow lifecycle as a

package/dist/audit.js

@@ -1,7 +1,7 @@
 // src/audit.ts
 import { execFileSync as execFileSync2 } from "node:child_process";
-import { existsSync as existsSync7, mkdirSync as mkdirSync5, readdirSync as readdirSync4, readFileSync as readFileSync7, rmdirSync as rmdirSync2, writeFileSync as writeFileSync4 } from "node:fs";
-import { basename as basename5, join as join9, resolve as resolve8, sep as sep3 } from "node:path";
+import { existsSync as existsSync7, mkdirSync as mkdirSync5, readdirSync as readdirSync5, readFileSync as readFileSync7, rmdirSync as rmdirSync3, writeFileSync as writeFileSync4 } from "node:fs";
+import { basename as basename5, join as join9, resolve as resolve9, sep as sep3 } from "node:path";
 
 // src/lease.ts
 import { mkdirSync, rmdirSync, statSync, unlinkSync, writeFileSync } from "node:fs";
@@ -500,9 +500,9 @@ function isArtifactVersion(value) {
 }
 
 // src/path.ts
-import { existsSync as existsSync6, mkdirSync as mkdirSync4, readdirSync as readdirSync3, readFileSync as readFileSync6, realpathSync as realpathSync3, statSync as statSync3, writeFileSync as writeFileSync3 } from "node:fs";
+import { existsSync as existsSync6, mkdirSync as mkdirSync4, readdirSync as readdirSync4, readFileSync as readFileSync6, realpathSync as realpathSync3, statSync as statSync3, writeFileSync as writeFileSync3 } from "node:fs";
 import { execFileSync } from "node:child_process";
-import { basename as basename4, dirname as dirname6, isAbsolute as isAbsolute6, join as join8, relative as relative2, resolve as resolve7 } from "node:path";
+import { basename as basename4, dirname as dirname6, isAbsolute as isAbsolute6, join as join8, relative as relative2, resolve as resolve8 } from "node:path";
 
 // src/mstarc.ts
 import { readFileSync as readFileSync2, statSync as statSync2 } from "node:fs";
@@ -626,8 +626,8 @@ function writeJson(filePath, value) {
 }
 
 // src/status.ts
-import { existsSync as existsSync5, readFileSync as readFileSync5, readdirSync as readdirSync2, realpathSync as realpathSync2 } from "node:fs";
-import { dirname as dirname5, join as join7, resolve as resolve6, sep as sep2 } from "node:path";
+import { existsSync as existsSync5, readFileSync as readFileSync5, readdirSync as readdirSync3, realpathSync as realpathSync2 } from "node:fs";
+import { dirname as dirname5, join as join7, resolve as resolve7, sep as sep2 } from "node:path";
 
 // src/store.ts
 import { existsSync as existsSync3, readdirSync, unlinkSync as unlinkSync3 } from "node:fs";
@@ -789,12 +789,14 @@ function assertFsStorePath(store, ref, expectedPath) {
 }
 
 // src/workflow.ts
-import { existsSync as existsSync4, mkdirSync as mkdirSync3, readFileSync as readFileSync4 } from "node:fs";
-import { isAbsolute as isAbsolute5, join as join6 } from "node:path";
+import { existsSync as existsSync4, mkdirSync as mkdirSync3, readFileSync as readFileSync4, readdirSync as readdirSync2, rmdirSync as rmdirSync2 } from "node:fs";
+import { isAbsolute as isAbsolute5, join as join6, resolve as resolve6 } from "node:path";
 var WORKFLOW_SNAPSHOT_FILE = "snapshot.json";
 var WORKFLOW_LIFECYCLE_STATUSES = ["running", "paused", "completed", "failed", "stopped"];
 var WORKFLOW_TERMINAL_STATUSES = ["completed", "failed", "stopped"];
 var WORKFLOW_LIFECYCLE_TYPES = ["plan", "iteration"];
+var WORKFLOW_DELIVERY_KINDS = ["development", "verification/report-only"];
+var WORKFLOW_COMPOUND_OUTCOMES = ["created", "updated", "skipped"];
 function stableJson(value) {
   if (Array.isArray(value))
     return `[${value.map(stableJson).join(",")}]`;
@@ -819,6 +821,61 @@ function validateWorktreePathValue(violations, value, field) {
     violations.push(violation2("high", "workflow.snapshot.invalid-integration-worktree-path", `${field} must be a non-empty absolute path — got ${JSON.stringify(value)}`, "record the absolute integration checkout path (integration_worktree_path)"));
   }
 }
+function deliveryEvidenceViolations(value, what) {
+  const violations = [];
+  const invalid2 = (message) => {
+    violations.push(violation2("medium", "workflow.snapshot.invalid-delivery-evidence", `${what}: ${message}`));
+  };
+  if (!isPlainObject2(value)) {
+    invalid2("must be an object");
+    return violations;
+  }
+  const members = ["compound", "pr", "merge", "completion"];
+  const unknownMembers = Object.keys(value).filter((key) => !members.includes(key));
+  if (unknownMembers.length > 0)
+    invalid2(`unknown member(s) ${unknownMembers.join(", ")} — expected ${members.join(" | ")}`);
+  const compound = value.compound;
+  if (compound !== undefined) {
+    if (!isPlainObject2(compound))
+      invalid2("compound must be an object");
+    else {
+      const unknown = Object.keys(compound).filter((key) => key !== "outcome" && key !== "reason");
+      if (unknown.length > 0)
+        invalid2(`compound has unknown key(s) ${unknown.join(", ")}`);
+      if (typeof compound.outcome !== "string" || !WORKFLOW_COMPOUND_OUTCOMES.includes(compound.outcome)) {
+        invalid2(`compound.outcome must be one of ${WORKFLOW_COMPOUND_OUTCOMES.join(" | ")} — got ${JSON.stringify(compound.outcome)}`);
+      } else if (compound.outcome === "skipped" && (typeof compound.reason !== "string" || compound.reason.trim() === "")) {
+        invalid2("compound reason is required when the disposition outcome is 'skipped' (contract §4c)");
+      } else if (compound.reason !== undefined && (typeof compound.reason !== "string" || compound.reason.trim() === "")) {
+        invalid2("compound.reason must be a non-empty string when given");
+      }
+    }
+  }
+  const stringMembers = {
+    pr: ["repo", "head", "target"],
+    merge: ["provider", "evidence"],
+    completion: ["policy", "evidence"]
+  };
+  for (const member of ["pr", "merge", "completion"]) {
+    const block = value[member];
+    if (block === undefined)
+      continue;
+    if (!isPlainObject2(block)) {
+      invalid2(`${member} must be an object`);
+      continue;
+    }
+    const fields = stringMembers[member];
+    const unknown = Object.keys(block).filter((key) => !fields.includes(key));
+    if (unknown.length > 0)
+      invalid2(`${member} has unknown key(s) ${unknown.join(", ")}`);
+    for (const field of fields) {
+      if (typeof block[field] !== "string" || block[field].trim() === "") {
+        invalid2(`${member}.${field} must be a non-empty string`);
+      }
+    }
+  }
+  return violations;
+}
 function validateWorkflowSnapshot(doc) {
   const violations = [];
   if (!isPlainObject2(doc)) {
@@ -884,7 +941,7 @@ function validateWorkflowSnapshot(doc) {
     if (!isPlainObject2(doc.branch)) {
       violations.push(violation2("medium", "workflow.snapshot.invalid-branch", "branch must be an object"));
     } else {
-      for (const key of ["base", "integration", "target"]) {
+      for (const key of ["base", "source", "integration", "target"]) {
         if (doc.branch[key] !== undefined && (typeof doc.branch[key] !== "string" || doc.branch[key].trim() === "")) {
           violations.push(violation2("medium", "workflow.snapshot.invalid-branch", `branch.${key} must be a non-empty string`));
         }
@@ -910,6 +967,20 @@ function validateWorkflowSnapshot(doc) {
   if (doc.compass_ref !== undefined) {
     validateNonEmptyString2(violations, doc.compass_ref, "compass_ref", "workflow.snapshot.missing-compass-ref", "workflow.snapshot.invalid-compass-ref");
   }
+  if (doc.delivery_kind !== undefined) {
+    if (typeof doc.delivery_kind !== "string" || !WORKFLOW_DELIVERY_KINDS.includes(doc.delivery_kind)) {
+      violations.push(violation2("medium", "workflow.snapshot.invalid-delivery-kind", `delivery_kind must be one of ${WORKFLOW_DELIVERY_KINDS.join(" | ")} — got ${JSON.stringify(doc.delivery_kind)}`));
+    }
+  }
+  if (doc.project !== undefined) {
+    validateNonEmptyString2(violations, doc.project, "project", "workflow.snapshot.missing-project", "workflow.snapshot.invalid-project");
+  }
+  if (doc.completion_policy !== undefined) {
+    validateNonEmptyString2(violations, doc.completion_policy, "completion_policy", "workflow.snapshot.missing-completion-policy", "workflow.snapshot.invalid-completion-policy");
+  }
+  if (doc.delivery !== undefined) {
+    violations.push(...deliveryEvidenceViolations(doc.delivery, "delivery"));
+  }
   const terminal = typeof doc.status === "string" && WORKFLOW_TERMINAL_STATUSES.includes(doc.status);
   if (terminal) {
     if (doc.ended_at === undefined) {
@@ -986,6 +1057,22 @@ function mergePhaseProjection(stored, incoming) {
   }
   return next;
 }
+function nonEmptyString(value) {
+  return typeof value === "string" && value.trim() !== "";
+}
+function assertDeliveryRegistrationCoherence(kind, evidence, what) {
+  if (kind === "development" && (!nonEmptyString(evidence.branchSource) || !nonEmptyString(evidence.branchTarget))) {
+    throw new Error(`${what}: a development workflow requires its delivery source and target branches (--branch-source/--branch-target) — missing branch fields are incomplete registration, not an exempt workflow (contract §1/§4a)`);
+  }
+  if (kind === "verification/report-only" && !nonEmptyString(evidence.completionPolicy)) {
+    throw new Error(`${what}: a verification/report-only workflow requires the completion policy (--completion-policy) naming the evidence that completes it (contract §1)`);
+  }
+  for (const [field, value] of Object.entries({ branchSource: evidence.branchSource, branchTarget: evidence.branchTarget, completionPolicy: evidence.completionPolicy })) {
+    if (value !== undefined && !nonEmptyString(value)) {
+      throw new Error(`${what}: ${field} must be a non-empty string when given`);
+    }
+  }
+}
 
 // src/status.ts
 var DATE_RE = /^\d{4}-\d{2}-\d{2}$/;
@@ -1080,7 +1167,7 @@ function validateStatusV2(docOrPath, opts = {}) {
   if (typeof docOrPath === "string") {
     try {
       doc = readJson(docOrPath);
-      harnessDir = dirname5(resolve6(docOrPath));
+      harnessDir = dirname5(resolve7(docOrPath));
     } catch (error) {
       return {
         ok: false,
@@ -1239,14 +1326,14 @@ function readRegisteredSnapshot(snapshotPath) {
 
 // src/path.ts
 function resolveHarnessDir(startDir = process.cwd(), opts = {}) {
-  const start = resolve7(startDir);
+  const start = resolve8(startDir);
   const explicit = opts.harnessDir ?? process.env.MSTAR_HARNESS_DIR;
   if (explicit)
-    return resolve7(start, explicit);
-  const boundary = resolve7(start, opts.workspaceRoot ?? defaultWorkspaceRoot(start));
+    return resolve8(start, explicit);
+  const boundary = resolve8(start, opts.workspaceRoot ?? defaultWorkspaceRoot(start));
   const rc = loadMstarc(start, boundary);
   if (rc !== null && rc.config.harnessDir)
-    return resolve7(rc.dir, rc.config.harnessDir);
+    return resolve8(rc.dir, rc.config.harnessDir);
   let dir = start;
   for (;; ) {
     if (!isAtOrBelow2(dir, boundary))
@@ -1277,7 +1364,7 @@ function defaultWorkspaceRoot(startDir) {
       if (segment && segment !== ".")
         boundary = dirname6(boundary);
     }
-    return resolve7(boundary);
+    return resolve8(boundary);
   } catch {}
   return startDir;
 }
@@ -1286,10 +1373,10 @@ function isAtOrBelow2(dir, root) {
   return rel === "" || !rel.startsWith("..") && !isAbsolute6(rel);
 }
 function mstarcDirOverride(harnessDir, key) {
-  const dir = resolve7(harnessDir);
+  const dir = resolve8(harnessDir);
   const rc = loadMstarc(dir, dirname6(dir));
   const declared = rc?.config[key];
-  return declared ? resolve7(rc.dir, declared) : null;
+  return declared ? resolve8(rc.dir, declared) : null;
 }
 function assertSafePathComponent(value, what) {
   if (value === "" || value === "." || value === ".." || !/^[A-Za-z0-9._-]+$/.test(value)) {
@@ -1299,10 +1386,10 @@ function assertSafePathComponent(value, what) {
 function resolveHarnessSubdir(startDir, opts, key, fallback) {
   const harness = resolveHarnessDir(startDir, opts);
   if (harness === null) {
-    throw new Error(`harness dir not found from ${resolve7(startDir)} — cannot resolve the ${fallback} dir (run \`mstar harness scaffold\`, pass opts.harnessDir, or set MSTAR_HARNESS_DIR)`);
+    throw new Error(`harness dir not found from ${resolve8(startDir)} — cannot resolve the ${fallback} dir (run \`mstar harness scaffold\`, pass opts.harnessDir, or set MSTAR_HARNESS_DIR)`);
   }
   const declared = mstarcDirOverride(harness, key);
-  return declared !== null ? declared : join8(resolve7(harness), fallback);
+  return declared !== null ? declared : join8(resolve8(harness), fallback);
 }
 function resolveWorkflowDir(startDir = process.cwd(), opts = {}) {
   return resolveHarnessSubdir(startDir, opts, "workflowDir", "workflows");
@@ -1696,7 +1783,7 @@ var LOCKFILE_NAMES = [
 function rootLockfiles(root) {
   let entries;
   try {
-    entries = readdirSync4(root, { withFileTypes: true });
+    entries = readdirSync5(root, { withFileTypes: true });
   } catch {
     return [];
   }
@@ -1729,7 +1816,7 @@ function supplyChainChecks(repoRoot) {
   const workflowsDir = join9(repoRoot, ".github", "workflows");
   let wfEntries = [];
   try {
-    wfEntries = readdirSync4(workflowsDir, { withFileTypes: true });
+    wfEntries = readdirSync5(workflowsDir, { withFileTypes: true });
   } catch {
     wfEntries = [];
   }
@@ -1895,7 +1982,7 @@ function scaffoldAuditPlan(outDir, findings, options = {}) {
   mkdirSync5(outDir, { recursive: true });
   const existingReadme = join9(outDir, "README.md");
   const carried = existsSync7(existingReadme) ? extractSecurityDispositionSections(readFileSync7(existingReadme, "utf8")) : { needsVerification: [], hardeningChecked: [] };
-  const existing = readdirSync4(outDir).filter((f) => /^\d{3}-.*\.md$/.test(f));
+  const existing = readdirSync5(outDir).filter((f) => /^\d{3}-.*\.md$/.test(f));
   let next = existing.reduce((max, f) => Math.max(max, Number(f.slice(0, 3))), 0) + 1;
   const redactedFindings = findings.map(redactFinding);
   const written = [];
@@ -1960,7 +2047,7 @@ function scaffoldAuditPlan(outDir, findings, options = {}) {
     needsVerification: needsVerificationLines,
     hardeningChecked: hardeningCheckedLines
   }));
-  return { outDir: resolve8(outDir), date, files: written, nextNumber: next };
+  return { outDir: resolve9(outDir), date, files: written, nextNumber: next };
 }
 async function promoteAuditPlans(outDir, selected, options) {
   if (selected.length === 0) {
@@ -1969,9 +2056,13 @@ async function promoteAuditPlans(outDir, selected, options) {
   if (typeof options.harnessDir !== "string" || options.harnessDir.trim() === "") {
     throw new Error("promoteAuditPlans: options.harnessDir is required (must contain status.json + workflows/)");
   }
-  const workflowId = options.workflowId ?? basename5(resolve8(outDir));
+  if (typeof options.deliveryKind !== "string" || !WORKFLOW_DELIVERY_KINDS.includes(options.deliveryKind)) {
+    throw new Error(`promoteAuditPlans: options.deliveryKind must be one of ${WORKFLOW_DELIVERY_KINDS.join(" | ")} — got ${JSON.stringify(options.deliveryKind)} (a promoted plan workflow declares its delivery kind at registration; it is never inferred and never defaulted)`);
+  }
+  assertDeliveryRegistrationCoherence(options.deliveryKind, options, "promoteAuditPlans");
+  const workflowId = options.workflowId ?? basename5(resolve9(outDir));
   assertSafePathComponent(workflowId, "workflow id");
-  const harnessDir = resolve8(options.harnessDir);
+  const harnessDir = resolve9(options.harnessDir);
   const statusPath = join9(harnessDir, "status.json");
   const workflowDir = join9(harnessDir, "workflows", workflowId);
   const snapshotPath = join9(workflowDir, WORKFLOW_SNAPSHOT_FILE);
@@ -1998,8 +2089,17 @@ async function promoteAuditPlans(outDir, selected, options) {
     status: "running",
     started_at: now.toISOString(),
     updated_at: now.toISOString().slice(0, 10),
-    plans
+    plans,
+    delivery_kind: options.deliveryKind
   };
+  if (options.branchSource !== undefined || options.branchTarget !== undefined) {
+    snapshot.branch = {
+      ...options.branchSource !== undefined ? { source: options.branchSource } : {},
+      ...options.branchTarget !== undefined ? { target: options.branchTarget } : {}
+    };
+  }
+  if (options.completionPolicy !== undefined)
+    snapshot.completion_policy = options.completionPolicy;
   const entry = {
     id: workflowId,
     type: "plan",
@@ -2032,8 +2132,8 @@ async function promoteAuditPlans(outDir, selected, options) {
         });
       }
       try {
-        if (readdirSync4(workflowDir).length === 0) {
-          rmdirSync2(workflowDir);
+        if (readdirSync5(workflowDir).length === 0) {
+          rmdirSync3(workflowDir);
         }
       } catch {}
       throw error;
@@ -2043,7 +2143,7 @@ async function promoteAuditPlans(outDir, selected, options) {
   return { workflowId, snapshotPath };
 }
 function resolveSelectedPlanFiles(outDir, selected) {
-  const files = readdirSync4(outDir).filter((f) => /^\d{3}-.*\.md$/.test(f)).sort();
+  const files = readdirSync5(outDir).filter((f) => /^\d{3}-.*\.md$/.test(f)).sort();
   const byNum = new Map;
   const byStem = new Map;
   for (const file of files) {
@@ -2058,7 +2158,7 @@ function resolveSelectedPlanFiles(outDir, selected) {
   for (const id of selected) {
     const file = byNum.get(id) ?? byStem.get(id) ?? byStem.get(id.replace(/\.md$/, ""));
     if (file === undefined) {
-      throw new Error(`promoteAuditPlans: selected plan ${JSON.stringify(id)} does not match any NNN-*.md file in ${resolve8(outDir)}`);
+      throw new Error(`promoteAuditPlans: selected plan ${JSON.stringify(id)} does not match any NNN-*.md file in ${resolve9(outDir)}`);
     }
     if (!seen.has(file)) {
       seen.add(file);
@@ -2097,7 +2197,7 @@ function readExecutionOrderIndex(outDir) {
   return rows;
 }
 function planFileRel(outDir, planFile) {
-  const resolved = resolve8(outDir);
+  const resolved = resolve9(outDir);
   const parts = resolved.split(sep3);
   const plansIdx = parts.lastIndexOf("plans");
   if (plansIdx >= 0) {

package/dist/coordination-write.d.ts

@@ -1,6 +1,6 @@
 import type { ValidationResult } from "./core.js";
 /** Stable refusal codes of the scoped coordination surface (spec §C4). */
-export declare const COORDINATION_ERROR_CODES: readonly ["coordination.harness-not-found", "coordination.workflow-not-found", "coordination.plan-not-found", "coordination.scope-mismatch", "coordination.path-mismatch", "coordination.assignment-invalid", "coordination.assignment-stale", "coordination.not-prepared", "coordination.duplicate-holder", "coordination.session-mismatch", "coordination.session-not-found", "coordination.session-role", "coordination.version-conflict", "coordination.expected-version-required", "coordination.invalid-transition", "coordination.invalid-input", "coordination.forbidden-field", "coordination.not-in-git", "coordination.git-unavailable", "coordination.git-proof", "coordination.evidence-stale", "coordination.integration-unresolved", "coordination.integration-diverged", "coordination.local-store-required", "coordination.direct-write-refused", "coordination.scoped-writer-required", "coordination.unknown-operation", "coordination.not-implemented", "coordination.lock", "coordination.store"];
+export declare const COORDINATION_ERROR_CODES: readonly ["coordination.harness-not-found", "coordination.workflow-not-found", "coordination.plan-not-found", "coordination.scope-mismatch", "coordination.path-mismatch", "coordination.assignment-invalid", "coordination.assignment-stale", "coordination.not-prepared", "coordination.duplicate-holder", "coordination.session-mismatch", "coordination.session-not-found", "coordination.session-role", "coordination.version-conflict", "coordination.expected-version-required", "coordination.invalid-transition", "coordination.invalid-input", "coordination.forbidden-field", "coordination.not-in-git", "coordination.git-unavailable", "coordination.git-proof", "coordination.evidence-stale", "coordination.integration-unresolved", "coordination.integration-diverged", "coordination.local-store-required", "coordination.direct-write-refused", "coordination.scoped-writer-required", "coordination.unknown-operation", "coordination.store", "coordination.prepare-amendment.stale", "coordination.prepare-amendment.invalid-patch", "coordination.prepare-amendment.not-prepare", "coordination.prepare-amendment.execution-started", "coordination.prepare-amendment.duplicate-plan", "coordination.prepare-amendment.invalid-plan", "coordination.prepare-amendment.compass-mismatch", "coordination.prepare-amendment.invalid-worktree"];
 export type CoordinationErrorCode = (typeof COORDINATION_ERROR_CODES)[number];
 /**
  * Stable exception of the coordination surface: `code` is the consumer

package/dist/coordination.d.ts

@@ -282,3 +282,88 @@ export declare function mutatePlanCoordination(request: CoordinationRequest): Pr
  * they refuse explicitly instead of silently no-opping.
  */
 export declare function replaceCoordinatedArtifact(input: CoordinatedReplacement): Promise<VersionedArtifact>;
+/**
+ * The guarded, coordinator-authenticated Prepare-stage amendment (§ New API and
+ * CLI, frozen). One approved plan row: the plan markdown that carries it plus
+ * the metadata the row records. Nothing else is addressable — the verb cannot
+ * edit an existing row.
+ */
+export type PreparePlanAppend = Readonly<{
+    id: string;
+    title: string;
+    file: string;
+    metadata: Readonly<{
+        primary_spec: string;
+        spec_refs: readonly string[];
+        iteration_compass: string;
+        iteration_refs: readonly string[];
+        working_branch: string;
+        spec_integration_branch: string;
+        merge_target: string;
+    }>;
+}>;
+/**
+ * The whole structural delta one amendment may apply (§ Admission and mutation
+ * step 5): the caller's main-worktree branch, the approved plan appends, the
+ * reviewed integration checkout, and the single approved execution-policy key.
+ */
+export type PrepareWorkflowPatch = Readonly<{
+    mainWorktreeBranch: string;
+    appendPlans: readonly PreparePlanAppend[];
+    integrationWorktreePath?: string;
+    planParallelism?: "serial" | "parallel";
+}>;
+/** What a coordinator observes about one workflow before amending it. */
+export type PrepareWorkflowView = Readonly<{
+    workflowId: string;
+    /** `sha256:<64 hex>` of the snapshot bytes (the amendment CAS token). */
+    snapshotVersion: string;
+    /** `sha256:<64 hex>` of the reviewed compass Markdown bytes (CAS token). */
+    compassVersion: string;
+    /** Plan ids in row order — including this call's own appends on success. */
+    planIds: readonly string[];
+    /** `true` when `amendPrepareWorkflow` is admitted with fresh tokens. */
+    allowed: boolean;
+    /** One `<reason>: <message>` line per admission blocker; empty when allowed. */
+    blockers: readonly string[];
+}>;
+/** Success shape of the verb: the existing envelope with a workflow view. */
+export type PrepareWorkflowResult = Omit<CoordinationResult, "view"> & {
+    view: PrepareWorkflowView;
+};
+/**
+ * Read the workflow-level Prepare view of one coordinator-bound workflow
+ * (spec § New API and CLI). Read-only: no snapshot lock, nothing written. The
+ * two byte versions are the tokens `amendPrepareWorkflow` requires, and
+ * `allowed`/`blockers` report the Prepare/no-execution admission exactly as the
+ * mutation evaluates it — an inadmissible *lifecycle state* is readable, not an
+ * error, so a caller can inspect a workflow before deciding to amend it.
+ * Problems that make the documents or the caller's identity unusable — a
+ * missing/foreign/mismatched envelope, an unregistered or unreadable snapshot,
+ * an unreadable or borrowed compass — still refuse with their own code, because
+ * no trustworthy answer can be produced from them.
+ */
+export declare function showPrepareWorkflow(input: Readonly<{
+    sessionPath: string;
+    cwd?: string;
+}>): Promise<PrepareWorkflowResult>;
+/**
+ * Apply one approved Prepare structural amendment (spec § Admission and
+ * mutation). The CAS read, both version comparisons, the admission, the whole
+ * patch validation, the compass recheck and the single atomic write all run
+ * under the canonical snapshot write lock, so two callers presenting the same
+ * tokens cannot both succeed: the loser inspects the winner's bytes and
+ * refuses as `stale`. Every refusal happens before any write — the protected
+ * snapshot, root register, other workflows and the compass stay byte-identical.
+ *
+ * A lock that cannot be acquired refuses explicitly (the shared
+ * `withStatusWriteLock` Blocked error); Git-unavailable probes refuse through
+ * the existing `coordination.git-unavailable`.
+ */
+export declare function amendPrepareWorkflow(input: Readonly<{
+    sessionPath: string;
+    cwd?: string;
+    expectedSnapshotVersion: string;
+    expectedCompassVersion: string;
+    patch: PrepareWorkflowPatch;
+}>): Promise<PrepareWorkflowResult>;

package/dist/dispatch.d.ts

@@ -19,6 +19,17 @@ export type AssignmentFields = {
      * violation code per field so the PM sees exactly which label is missing.
      */
     returnShape?: string;
+    /**
+     * `Task budget (implement / ops rounds)` — the declared capacity of ONE
+     * implementer round closing the task's declared Files list and verification
+     * gates (capacity contract spec § A1/A2; the value cites the task's
+     * `Effort (agent-oriented)` band). Required, presence-only, on the exact
+     * complement of the review/audit rounds — implement/ops rounds including
+     * non-audit docs/Prepare specialists and orientation roles. The value is
+     * prose; it is never parsed numerically (adequacy stays in PM's Prepare
+     * check).
+     */
+    taskBudget?: string;
 };
 export type ValidateAssignmentFieldsOptions = {
     /**
@@ -161,7 +172,10 @@ export declare function isReadOnlyAssignmentRole(roleId: string): boolean;
  * non-empty values (paste-only shells are caught here — every field missing).
  * Review-seat and audit rounds must additionally declare both round-bounding
  * fields, `Budget (review / QC seats)` and `Return shape (review / QC
- * seats)` (one violation code per missing label). Writable assignments must
+ * seats)` (one violation code per missing label). The complement — every
+ * implement/ops round, including non-audit docs/Prepare and orientation
+ * roles — must declare `Task budget (implement / ops rounds)`, presence-only.
+ * Writable assignments must
  * carry EXACTLY ONE branch form; `create <new>`
  * from <base>` without `<base>` (incl. the dangling `create <new> from`
  * / `create from <base>` typos) and `Branch policy` without branch/reason