@mstar-harness/engine 3.10.3 → 3.11.0

package/dist/audit.d.ts

@@ -167,11 +167,47 @@ export type AuditFinding = {
     effort: AuditEffort;
     risk: AuditRisk;
     confidence: AuditConfidence;
-    evidence: readonly string[];
+    /** Free-text string (legacy form, rendered byte-for-byte) or a structured
+     * location. Authored JSON should prefer the structured form. */
+    evidence: readonly (string | AuditEvidence)[];
     priority: AuditPriority;
     fixSketch?: string;
     verification?: string;
     dependsOn?: string;
+    /** Source-derived root-cause identity (audit-finding-contract.md §4).
+     * Optional; never invented by the engine. */
+    fingerprint?: string;
+    /** Entry-point → propagation → sink path (§5). Supplements evidence. */
+    trace?: readonly AuditTraceStep[];
+    /** Author-supplied severity assessment (§6). Never inferred from
+     * priority/risk/confidence. */
+    severity?: AuditSeverity;
+};
+/** One structured evidence location. `file` is a safe repository-relative
+ * POSIX path; `line` is omitted when unknown (never invented). */
+export type AuditEvidence = {
+    file: string;
+    line?: number;
+    description: string;
+};
+/** Trace-step kind (§5): where data enters, how it travels, where it lands. */
+export type AuditTraceKind = "entrypoint" | "propagation" | "sink";
+/** One trace step. `line` is a positive safe integer; `scope` names the
+ * enclosing route/function/module. */
+export type AuditTraceStep = {
+    kind: AuditTraceKind;
+    file: string;
+    line: number;
+    scope: string;
+    description: string;
+};
+/** Severity rank ordinal labels (§6). Harness diagnostic `Severity` is a
+ * DIFFERENT enum (`nit`, no `informational`) — never conflate them. */
+export type AuditSeverityRank = "informational" | "low" | "medium" | "high" | "critical";
+export type AuditSeverity = {
+    likelihood: AuditSeverityRank;
+    impact: AuditSeverityRank;
+    overall: AuditSeverityRank;
 };
 /** Options for `scaffoldAuditPlan`. `plannedAt` defaults to the
  * `repoShortSha` + `date`; `date` defaults to today (YYYY-MM-DD). */
@@ -205,6 +241,21 @@ export type ScaffoldAuditPlanResult = {
     files: string[];
     nextNumber: number;
 };
+/**
+ * Deterministic finding gates (audit-finding-contract.md §§2–6): fingerprint
+ * grammar / exact uniqueness / ordinal ordering of the supplied subsequence,
+ * `severity.overall ≤ severity.impact`, nonempty trace topology, positive
+ * safe-integer trace lines, safe typed paths, visible well-formed text, and
+ * opaque-field credential rejection (a fingerprint or typed location that
+ * `redactSecrets` would alter is REJECTED, never redacted into a different
+ * identity). Contextual judgement (reportability, semantic exclusion,
+ * coverage) stays in skill prose (§2).
+ *
+ * Violation codes are stable `audit.finding.<family>.<rule>`; messages carry
+ * `findings[index].field` paths only — never raw submitted values. Pure:
+ * the input is never mutated and nothing is sorted or repaired.
+ */
+export declare function validateAuditFindingGates(findings: readonly AuditFinding[]): GateResult;
 /**
  * Scaffold an audit plan directory (`{PLAN_DIR}/audit-<date>/` layout,
  * mstar-audit SKILL.md § Plan output (all variants)): numbered `NNN-<slug>.md` plan files from

package/dist/audit.js

@@ -1944,6 +1944,176 @@ function slugify(title) {
 }
 var escapeCell = (value) => value.replace(/\|/g, "\\|");
 var truncate = (value, max) => value.length > max ? `${value.slice(0, max)}…` : value;
+var collapseEvidenceWs = (value) => value.replace(/\s*[\r\n]\s*/g, " ");
+var evidenceText = (item) => typeof item === "string" ? item : `${item.file}${item.line !== undefined ? `:${item.line}` : ""} — ${item.description}`;
+var hasEnrichedMetadata = (finding) => finding.fingerprint !== undefined || finding.trace !== undefined || finding.severity !== undefined || finding.evidence.some((item) => typeof item !== "string");
+var AUDIT_FINGERPRINT_RE = /^[A-Za-z0-9][A-Za-z0-9._:/@+-]*(?![\s\S])/;
+var AUDIT_SEVERITY_ORDER = { informational: 0, low: 1, medium: 2, high: 3, critical: 4 };
+var DEFAULT_IGNORABLE_RE = /[\u00AD\u034F\u061C\u115F\u1160\u17B4\u17B5\u180B-\u180F\u200B-\u200F\u202A-\u202E\u2060-\u206F\u3164\uFE00-\uFE0F\uFEFF\uFFA0\uFFF0-\uFFF8\u{1BCA0}-\u{1BCA3}\u{1D173}-\u{1D17A}\u{E0000}-\u{E0FFF}]/u;
+var LONE_SURROGATE_RE = /[\uD800-\uDBFF](?![\uDC00-\uDFFF])|(?<![\uD800-\uDBFF])[\uDC00-\uDFFF]/;
+var isPlainObject3 = (value) => typeof value === "object" && value !== null && !Array.isArray(value);
+function isVisibleText(value) {
+  if (LONE_SURROGATE_RE.test(value))
+    return false;
+  for (const ch of value) {
+    if (!/\p{White_Space}/u.test(ch) && !DEFAULT_IGNORABLE_RE.test(ch))
+      return true;
+  }
+  return false;
+}
+function safeAuditPath(value) {
+  if (typeof value !== "string")
+    return false;
+  if (value === "")
+    return false;
+  if (value.includes("\\"))
+    return false;
+  if (/[\u0000-\u001F\u007F-\u009F]/.test(value))
+    return false;
+  if (LONE_SURROGATE_RE.test(value))
+    return false;
+  if (value.startsWith("/"))
+    return false;
+  if (/^[A-Za-z]:/.test(value))
+    return false;
+  for (const segment of value.split("/")) {
+    if (segment === "" || segment === "." || segment === "..")
+      return false;
+    if (segment.endsWith(".") || segment.endsWith(" "))
+      return false;
+  }
+  return true;
+}
+function validateAuditFindingGates(findings) {
+  const violations = [];
+  const seen = new Map;
+  let previousFingerprint;
+  if (!Array.isArray(findings)) {
+    violations.push(violation4("high", "audit.finding.shape", "findings — audit.finding.shape"));
+    return { ok: false, violations };
+  }
+  findings.forEach((finding, index) => {
+    const at = (field) => `findings[${index}].${field}`;
+    const push = (code, field) => {
+      violations.push(violation4("high", code, `${at(field)} — ${code}`));
+    };
+    if (!isPlainObject3(finding)) {
+      violations.push(violation4("high", "audit.finding.shape", `findings[${index}] — audit.finding.shape`));
+      return;
+    }
+    if (finding.fingerprint !== undefined) {
+      const fingerprint = finding.fingerprint;
+      if (typeof fingerprint !== "string" || !AUDIT_FINGERPRINT_RE.test(fingerprint))
+        push("audit.finding.fingerprint.grammar", "fingerprint");
+      else if (redactSecrets(fingerprint).text !== fingerprint)
+        push("audit.finding.fingerprint.secret", "fingerprint");
+      else {
+        const firstAt = seen.get(fingerprint);
+        if (firstAt !== undefined)
+          push("audit.finding.fingerprint.duplicate", "fingerprint");
+        else
+          seen.set(fingerprint, index);
+        if (previousFingerprint !== undefined && fingerprint < previousFingerprint) {
+          push("audit.finding.fingerprint.order", "fingerprint");
+        }
+        previousFingerprint = fingerprint;
+      }
+    }
+    if (finding.severity !== undefined) {
+      if (!isPlainObject3(finding.severity)) {
+        push("audit.finding.severity.shape", "severity");
+      } else {
+        const { likelihood, impact, overall } = finding.severity;
+        const rankOf = (r) => AUDIT_SEVERITY_ORDER[r];
+        for (const [field, value] of [
+          ["likelihood", likelihood],
+          ["impact", impact],
+          ["overall", overall]
+        ]) {
+          if (rankOf(value) === undefined)
+            push("audit.finding.severity.rank", `severity.${field}`);
+        }
+        const impactRank = rankOf(impact);
+        const overallRank = rankOf(overall);
+        if (impactRank !== undefined && overallRank !== undefined && overallRank > impactRank) {
+          push("audit.finding.severity.overall-exceeds-impact", "severity.overall");
+        }
+      }
+    }
+    const textViolation = (field, value) => {
+      if (value === undefined)
+        return;
+      if (typeof value !== "string")
+        push("audit.finding.text.type", field);
+      else if (LONE_SURROGATE_RE.test(value))
+        push("audit.finding.text.surrogate", field);
+      else if (!isVisibleText(value))
+        push("audit.finding.text.invisible", field);
+    };
+    if (finding.trace !== undefined) {
+      if (!Array.isArray(finding.trace))
+        push("audit.finding.trace.shape", "trace");
+      else if (finding.trace.length === 0)
+        push("audit.finding.trace.empty", "trace");
+      else {
+        const kinds = finding.trace.map((s) => isPlainObject3(s) ? s.kind : undefined);
+        const topologyOk = finding.trace.length === 1 ? kinds[0] === "entrypoint" || kinds[0] === "sink" : kinds[0] === "entrypoint" && kinds[kinds.length - 1] === "sink" && kinds.slice(1, -1).every((k) => k === "propagation");
+        if (!topologyOk)
+          push("audit.finding.trace.topology", "trace");
+        finding.trace.forEach((step, stepIndex) => {
+          const stepAt = `trace[${stepIndex}]`;
+          if (!isPlainObject3(step)) {
+            push("audit.finding.trace.shape", stepAt);
+            return;
+          }
+          if (typeof step.line !== "number" || !Number.isSafeInteger(step.line) || step.line <= 0) {
+            push("audit.finding.trace.line", `${stepAt}.line`);
+          }
+          const stepFile = step.file;
+          if (typeof stepFile !== "string" || !safeAuditPath(stepFile))
+            push("audit.finding.path.unsafe", `${stepAt}.file`);
+          else if (redactSecrets(stepFile).text !== stepFile)
+            push("audit.finding.path.secret", `${stepAt}.file`);
+          if (step.scope === undefined)
+            push("audit.finding.trace.shape", `${stepAt}.scope`);
+          else
+            textViolation(`${stepAt}.scope`, step.scope);
+          if (step.description === undefined)
+            push("audit.finding.trace.shape", `${stepAt}.description`);
+          else
+            textViolation(`${stepAt}.description`, step.description);
+        });
+      }
+    }
+    if (!Array.isArray(finding.evidence))
+      push("audit.finding.evidence.shape", "evidence");
+    else
+      finding.evidence.forEach((item, itemIndex) => {
+        if (typeof item === "string") {
+          textViolation(`evidence[${itemIndex}]`, item);
+          return;
+        }
+        if (!isPlainObject3(item)) {
+          push("audit.finding.evidence.shape", `evidence[${itemIndex}]`);
+          return;
+        }
+        const itemFile = item.file;
+        if (typeof itemFile !== "string" || !safeAuditPath(itemFile))
+          push("audit.finding.path.unsafe", `evidence[${itemIndex}].file`);
+        else if (redactSecrets(itemFile).text !== itemFile)
+          push("audit.finding.path.secret", `evidence[${itemIndex}].file`);
+        if (item.line !== undefined && (typeof item.line !== "number" || !Number.isSafeInteger(item.line) || item.line <= 0)) {
+          push("audit.finding.evidence.line", `evidence[${itemIndex}].line`);
+        }
+        textViolation(`evidence[${itemIndex}].description`, item.description);
+      });
+    textViolation("title", finding.title);
+    textViolation("impact", finding.impact);
+    textViolation("fixSketch", finding.fixSketch);
+    textViolation("verification", finding.verification);
+  });
+  return { ok: violations.length === 0, violations };
+}
 function renderPlanFile(finding, plannedAt) {
   const sections = [
     `# ${finding.title}`,
@@ -1952,15 +2122,22 @@ function renderPlanFile(finding, plannedAt) {
     `- **Priority**: ${finding.priority}`,
     `- **Effort**: ${finding.effort}`,
     `- **Risk**: ${finding.risk}`,
+    ...finding.confidence !== "MED" || hasEnrichedMetadata(finding) ? [`- **Confidence**: ${finding.confidence}`] : [],
+    ...finding.fingerprint !== undefined ? [`- **Fingerprint**: ${finding.fingerprint}`] : [],
+    ...finding.severity !== undefined ? [`- **Likelihood**: ${finding.severity.likelihood}`, `- **Severity impact**: ${finding.severity.impact}`, `- **Severity**: ${finding.severity.overall}`] : [],
     `- **Depends on**: ${finding.dependsOn ?? "none"}`,
     `- **Category**: ${finding.category}`,
+    ...finding.evidence.length > 0 ? [`- **Evidence**: ${collapseEvidenceWs(evidenceText(finding.evidence[0]))}`] : [],
     `- **Planned at**: commit \`${plannedAt.commit}\`, ${plannedAt.date}`,
     "",
     "## Impact",
     finding.impact
   ];
   if (finding.evidence.length > 0) {
-    sections.push("", "## Evidence", ...finding.evidence.map((e) => `- ${e}`));
+    sections.push("", "## Evidence", ...finding.evidence.map((item) => `- ${evidenceText(item)}`));
+  }
+  if (finding.trace !== undefined) {
+    sections.push("", "## Trace", "", "| Kind | Location | Scope / Description |", "|------|----------|---------------------|", ...finding.trace.map((step) => `| ${escapeCell(step.kind)} | ${escapeCell(`${step.file}:${step.line}`)} | ${escapeCell(`${step.scope} — ${step.description}`).replace(/\r\n|\r|\n/g, "\\n")} |`));
   }
   if (finding.fixSketch !== undefined) {
     sections.push("", "## Fix sketch", finding.fixSketch);
@@ -1980,7 +2157,8 @@ function redactFinding(finding) {
     ...finding,
     title: redactText(finding.title),
     impact: redactText(finding.impact),
-    evidence: finding.evidence.map(redactText),
+    evidence: finding.evidence.map((item) => typeof item === "string" ? redactText(item) : { ...item, description: redactText(item.description) }),
+    ...finding.trace !== undefined ? { trace: finding.trace.map((step) => ({ ...step, scope: redactText(step.scope), description: redactText(step.description) })) } : {},
     ...finding.fixSketch !== undefined ? { fixSketch: redactText(finding.fixSketch) } : {},
     ...finding.verification !== undefined ? { verification: redactText(finding.verification) } : {}
   };
@@ -2002,7 +2180,10 @@ function extractSecurityDispositionSections(text) {
 }
 function renderIndex(params) {
   const { date, repoName, repoShortSha, rows, rejected, needsVerification, hardeningChecked } = params;
-  const findingsRows = rows.map((r) => `| ${r.num} | ${escapeCell(r.title)} | ${r.category} | ${escapeCell(truncate(r.impact, 80))} | ${r.effort} | ${r.risk} | ${r.confidence} | ${escapeCell(truncate(r.evidence, 80))} |`).join(`
+  const showFingerprint = rows.some((r) => r.fingerprint !== undefined);
+  const showSeverity = rows.some((r) => r.likelihood !== undefined || r.severityImpact !== undefined || r.severity !== undefined);
+  const cell = (value) => escapeCell(value ?? "—");
+  const findingsRows = rows.map((r) => `| ${r.num} | ${escapeCell(r.title)} | ${r.category} | ${escapeCell(truncate(r.impact, 80))} | ${r.effort} | ${r.risk} | ${r.confidence} | ${escapeCell(truncate(r.evidence, 80))}` + (showFingerprint ? ` | ${cell(r.fingerprint)}` : "") + (showSeverity ? ` | ${cell(r.likelihood)} | ${cell(r.severityImpact)} | ${cell(r.severity)}` : "") + " |").join(`
 `);
   const directionRows = rows.filter((r) => r.category === "direction").map((r) => `- ${escapeCell(r.title)} — ${escapeCell(truncate(r.impact, 120))}`).join(`
 `);
@@ -2015,8 +2196,8 @@ function renderIndex(params) {
     "",
     "## Findings",
     "",
-    "| # | Finding | Category | Impact | Effort | Risk | Confidence | Evidence |",
-    "|---|---------|----------|--------|--------|------|------------|----------|",
+    "| # | Finding | Category | Impact | Effort | Risk | Confidence | Evidence" + (showFingerprint ? " | Fingerprint" : "") + (showSeverity ? " | Likelihood | Severity impact | Severity" : "") + " |",
+    "|---|---------|----------|--------|--------|------|------------|----------" + (showFingerprint ? "|------------" : "") + (showSeverity ? "|------------|-----------------|----------" : "") + "|",
     findingsRows
   ];
   if (directionRows !== "") {
@@ -2040,6 +2221,11 @@ function renderIndex(params) {
 function scaffoldAuditPlan(outDir, findings, options = {}) {
   const date = options.date ?? new Date().toISOString().slice(0, 10);
   const plannedAt = options.plannedAt ?? { commit: options.repoShortSha ?? "unknown", date };
+  const gate = validateAuditFindingGates(findings);
+  if (!gate.ok) {
+    const first = gate.violations[0];
+    throw new TypeError(`invalid audit findings — ${first.code}: ${first.message}`);
+  }
   mkdirSync5(outDir, { recursive: true });
   const existingReadme = join9(outDir, "README.md");
   const carried = existsSync7(existingReadme) ? extractSecurityDispositionSections(readFileSync7(existingReadme, "utf8")) : { needsVerification: [], hardeningChecked: [] };
@@ -2074,10 +2260,14 @@ function scaffoldAuditPlan(outDir, findings, options = {}) {
       impact: "see plan file",
       effort: fields.get("Effort") ?? "—",
       risk: fields.get("Risk") ?? "—",
-      confidence: "—",
+      confidence: fields.get("Confidence") ?? "—",
       evidence: fields.get("Evidence") ?? "—",
       priority: fields.get("Priority") ?? "—",
-      dependsOn: fields.get("Depends on") ?? "—"
+      dependsOn: fields.get("Depends on") ?? "—",
+      fingerprint: fields.get("Fingerprint"),
+      likelihood: fields.get("Likelihood"),
+      severityImpact: fields.get("Severity impact"),
+      severity: fields.get("Severity")
     };
   });
   const byNum = new Map(rows.map((r) => [r.num, r]));
@@ -2092,9 +2282,13 @@ function scaffoldAuditPlan(outDir, findings, options = {}) {
       row.effort = finding.effort;
       row.risk = finding.risk;
       row.confidence = finding.confidence;
-      row.evidence = finding.evidence[0] ?? "";
+      row.evidence = finding.evidence.length > 0 ? collapseEvidenceWs(evidenceText(finding.evidence[0])) : "";
       row.priority = finding.priority;
       row.dependsOn = finding.dependsOn ?? "none";
+      row.fingerprint = finding.fingerprint;
+      row.likelihood = finding.severity?.likelihood;
+      row.severityImpact = finding.severity?.impact;
+      row.severity = finding.severity?.overall;
     }
   });
   const needsVerificationLines = options.needsVerification !== undefined ? options.needsVerification.map((nv) => `- ${escapeCell(redactText(nv.lead))}: ${escapeCell(redactText(nv.how))}${nv.evidence ? ` (${escapeCell(redactText(nv.evidence))})` : ""}`) : carried.needsVerification;
@@ -2281,5 +2475,6 @@ export {
   scaffoldAuditPlan,
   scanSecrets,
   supplyChainChecks,
+  validateAuditFindingGates,
   validateAuditStatusBlocks
 };

package/dist/engine.js

@@ -2084,6 +2084,158 @@ async function registerPlanWorkflow(workflowId, options) {
     return { workflowId, snapshotPath, recovered: false };
   });
 }
+function iterationWorkflowRegistrationIdentity(snapshot) {
+  const coordinator = snapshot.coordination?.coordinator;
+  return stableJson({
+    id: snapshot.id,
+    type: snapshot.type,
+    status: snapshot.status,
+    compass_ref: snapshot.compass_ref ?? null,
+    branch: snapshot.branch ?? null,
+    project: snapshot.project ?? null,
+    plans: snapshot.plans,
+    coordinator: coordinator ? { session_id: coordinator.session_id, session_file: coordinator.session_file } : null
+  });
+}
+async function registerIterationWorkflow(workflowId, options) {
+  const refuse = (detail) => new Error(`registerIterationWorkflow: ${detail}`);
+  if (typeof options !== "object" || options === null || Array.isArray(options)) {
+    throw refuse("options must be an object (harnessDir, compassRef, branch, rows)");
+  }
+  if (typeof options.harnessDir !== "string" || options.harnessDir.trim() === "") {
+    throw refuse("options.harnessDir is required (must contain status.json + workflows/)");
+  }
+  assertSafePathComponent(workflowId, "workflow id");
+  if (typeof options.compassRef !== "string" || options.compassRef.trim() === "") {
+    throw refuse("options.compassRef must be a non-empty string");
+  }
+  if (typeof options.branch !== "object" || options.branch === null || Array.isArray(options.branch)) {
+    throw refuse("options.branch must be an object (base, integration, target)");
+  }
+  for (const anchor of ["base", "integration", "target"]) {
+    const value = options.branch[anchor];
+    if (typeof value !== "string" || value.trim() === "") {
+      throw refuse(`options.branch.${anchor} must be a non-empty string`);
+    }
+  }
+  if (options.project !== undefined && (typeof options.project !== "string" || options.project.trim() === "")) {
+    throw refuse("options.project must be a non-empty string when given");
+  }
+  const rows = options.rows;
+  if (!Array.isArray(rows) || rows.length === 0) {
+    throw refuse("options.rows must be a non-empty array of { id, title, file }");
+  }
+  const seenRowIds = new Set;
+  for (const row of rows) {
+    if (typeof row !== "object" || row === null || Array.isArray(row)) {
+      throw refuse("each row must be an object ({ id, title, file })");
+    }
+    for (const field of ["id", "title", "file"]) {
+      if (typeof row[field] !== "string" || row[field].trim() === "") {
+        throw refuse(`each row.${field} must be a non-empty string`);
+      }
+    }
+    if ("status" in row) {
+      throw refuse(`row ${JSON.stringify(row.id)} supplies a status — rows are always written status "Todo"; ` + "a state transition is requested through the lifecycle seams, never at registration");
+    }
+    if (seenRowIds.has(row.id)) {
+      throw refuse(`duplicate row id ${JSON.stringify(row.id)} — plan row ids are unique per workflow`);
+    }
+    seenRowIds.add(row.id);
+  }
+  const startedAt = options.startedAt ?? new Date().toISOString();
+  if (!isCloseTimestamp(startedAt)) {
+    throw refuse("options.startedAt must be a valid YYYY-MM-DD date or RFC3339 timestamp");
+  }
+  const harnessDir = resolve6(options.harnessDir);
+  const statusPath = join6(harnessDir, "status.json");
+  const workflowDir = join6(harnessDir, "workflows", workflowId);
+  const snapshotPath = join6(workflowDir, WORKFLOW_SNAPSHOT_FILE);
+  const store = getArtifactStore();
+  const snapshot = {
+    schema_version: 1,
+    id: workflowId,
+    type: "iteration",
+    status: "running",
+    started_at: startedAt,
+    updated_at: startedAt.slice(0, 10),
+    compass_ref: options.compassRef,
+    branch: { base: options.branch.base, integration: options.branch.integration, target: options.branch.target },
+    plans: rows.map((r) => ({
+      id: r.id,
+      title: r.title,
+      file: r.file,
+      status: "Todo",
+      metadata: {
+        iteration_refs: [options.compassRef],
+        spec_integration_branch: options.branch.integration,
+        merge_target: options.branch.integration
+      }
+    }))
+  };
+  if (options.project !== undefined)
+    snapshot.project = options.project;
+  const entry = {
+    id: workflowId,
+    type: "iteration",
+    started_at: snapshot.started_at,
+    dir: `workflows/${workflowId}`
+  };
+  const entryGate = validateWorkflowEntry(entry);
+  if (!entryGate.ok) {
+    throw new Error(`refusing to register invalid workflow entry: ${entryGate.violations.map((v) => v.message).join("; ")}`);
+  }
+  return withStatusWriteLock(statusPath, async () => {
+    const rootDoc = readJson(statusPath);
+    const workflows = Array.isArray(rootDoc.workflows) ? rootDoc.workflows : [];
+    if (workflows.some((candidate) => isPlainObject2(candidate) && candidate.id === workflowId)) {
+      throw new Error(`refusing to register workflow ${JSON.stringify(workflowId)}: it is already registered ` + `(root entry in ${statusPath}) — registration is create-only; ` + "remove that workflow before registering again");
+    }
+    if (existsSync4(snapshotPath)) {
+      const existing = readWorkflowSnapshot(workflowDir);
+      if (existing.snapshot.id !== workflowId || iterationWorkflowRegistrationIdentity(existing.snapshot) !== iterationWorkflowRegistrationIdentity(snapshot)) {
+        throw new Error(`refusing to register workflow ${JSON.stringify(workflowId)}: snapshot ${snapshotPath} already exists ` + "with a different registration identity — remove that workflow or register under a different id");
+      }
+      const recoveryEntry = {
+        id: workflowId,
+        type: "iteration",
+        started_at: existing.snapshot.started_at,
+        dir: `workflows/${workflowId}`
+      };
+      const recoveryGate = validateWorkflowEntry(recoveryEntry);
+      if (!recoveryGate.ok) {
+        throw new Error(`refusing to register invalid workflow entry: ${recoveryGate.violations.map((v) => v.message).join("; ")}`);
+      }
+      await registerWorkflowEntryLocked(statusPath, recoveryEntry);
+      return { workflowId, snapshotPath, recovered: true };
+    }
+    let createdVersion;
+    try {
+      await writeWorkflowSnapshot(snapshot, workflowDir, { createOnly: true });
+      createdVersion = readArtifactBytes(snapshotPath)?.version;
+      await registerWorkflowEntryLocked(statusPath, entry);
+    } catch (error) {
+      if (createdVersion !== undefined) {
+        await withStatusWriteLock(snapshotPath, async () => {
+          const current = readArtifactBytes(snapshotPath);
+          if (current === undefined || current.version !== createdVersion)
+            return;
+          const remove = store.delete?.bind(store);
+          if (remove !== undefined) {
+            await withProtectedWrite(snapshotPath, "delete", () => remove({ kind: "snapshot", key: workflowId }));
+          }
+        });
+      }
+      try {
+        if (readdirSync2(workflowDir).length === 0) {
+          rmdirSync2(workflowDir);
+        }
+      } catch {}
+      throw error;
+    }
+    return { workflowId, snapshotPath, recovered: false };
+  });
+}
 
 // src/status.ts
 var DATE_RE = /^\d{4}-\d{2}-\d{2}$/;
@@ -7627,6 +7779,176 @@ function slugify(title) {
 }
 var escapeCell = (value) => value.replace(/\|/g, "\\|");
 var truncate = (value, max) => value.length > max ? `${value.slice(0, max)}…` : value;
+var collapseEvidenceWs = (value) => value.replace(/\s*[\r\n]\s*/g, " ");
+var evidenceText = (item) => typeof item === "string" ? item : `${item.file}${item.line !== undefined ? `:${item.line}` : ""} — ${item.description}`;
+var hasEnrichedMetadata = (finding) => finding.fingerprint !== undefined || finding.trace !== undefined || finding.severity !== undefined || finding.evidence.some((item) => typeof item !== "string");
+var AUDIT_FINGERPRINT_RE = /^[A-Za-z0-9][A-Za-z0-9._:/@+-]*(?![\s\S])/;
+var AUDIT_SEVERITY_ORDER = { informational: 0, low: 1, medium: 2, high: 3, critical: 4 };
+var DEFAULT_IGNORABLE_RE = /[\u00AD\u034F\u061C\u115F\u1160\u17B4\u17B5\u180B-\u180F\u200B-\u200F\u202A-\u202E\u2060-\u206F\u3164\uFE00-\uFE0F\uFEFF\uFFA0\uFFF0-\uFFF8\u{1BCA0}-\u{1BCA3}\u{1D173}-\u{1D17A}\u{E0000}-\u{E0FFF}]/u;
+var LONE_SURROGATE_RE = /[\uD800-\uDBFF](?![\uDC00-\uDFFF])|(?<![\uD800-\uDBFF])[\uDC00-\uDFFF]/;
+var isPlainObject9 = (value) => typeof value === "object" && value !== null && !Array.isArray(value);
+function isVisibleText(value) {
+  if (LONE_SURROGATE_RE.test(value))
+    return false;
+  for (const ch of value) {
+    if (!/\p{White_Space}/u.test(ch) && !DEFAULT_IGNORABLE_RE.test(ch))
+      return true;
+  }
+  return false;
+}
+function safeAuditPath(value) {
+  if (typeof value !== "string")
+    return false;
+  if (value === "")
+    return false;
+  if (value.includes("\\"))
+    return false;
+  if (/[\u0000-\u001F\u007F-\u009F]/.test(value))
+    return false;
+  if (LONE_SURROGATE_RE.test(value))
+    return false;
+  if (value.startsWith("/"))
+    return false;
+  if (/^[A-Za-z]:/.test(value))
+    return false;
+  for (const segment of value.split("/")) {
+    if (segment === "" || segment === "." || segment === "..")
+      return false;
+    if (segment.endsWith(".") || segment.endsWith(" "))
+      return false;
+  }
+  return true;
+}
+function validateAuditFindingGates(findings) {
+  const violations = [];
+  const seen = new Map;
+  let previousFingerprint;
+  if (!Array.isArray(findings)) {
+    violations.push(violation10("high", "audit.finding.shape", "findings — audit.finding.shape"));
+    return { ok: false, violations };
+  }
+  findings.forEach((finding, index) => {
+    const at = (field) => `findings[${index}].${field}`;
+    const push = (code, field) => {
+      violations.push(violation10("high", code, `${at(field)} — ${code}`));
+    };
+    if (!isPlainObject9(finding)) {
+      violations.push(violation10("high", "audit.finding.shape", `findings[${index}] — audit.finding.shape`));
+      return;
+    }
+    if (finding.fingerprint !== undefined) {
+      const fingerprint = finding.fingerprint;
+      if (typeof fingerprint !== "string" || !AUDIT_FINGERPRINT_RE.test(fingerprint))
+        push("audit.finding.fingerprint.grammar", "fingerprint");
+      else if (redactSecrets(fingerprint).text !== fingerprint)
+        push("audit.finding.fingerprint.secret", "fingerprint");
+      else {
+        const firstAt = seen.get(fingerprint);
+        if (firstAt !== undefined)
+          push("audit.finding.fingerprint.duplicate", "fingerprint");
+        else
+          seen.set(fingerprint, index);
+        if (previousFingerprint !== undefined && fingerprint < previousFingerprint) {
+          push("audit.finding.fingerprint.order", "fingerprint");
+        }
+        previousFingerprint = fingerprint;
+      }
+    }
+    if (finding.severity !== undefined) {
+      if (!isPlainObject9(finding.severity)) {
+        push("audit.finding.severity.shape", "severity");
+      } else {
+        const { likelihood, impact, overall } = finding.severity;
+        const rankOf = (r) => AUDIT_SEVERITY_ORDER[r];
+        for (const [field, value] of [
+          ["likelihood", likelihood],
+          ["impact", impact],
+          ["overall", overall]
+        ]) {
+          if (rankOf(value) === undefined)
+            push("audit.finding.severity.rank", `severity.${field}`);
+        }
+        const impactRank = rankOf(impact);
+        const overallRank = rankOf(overall);
+        if (impactRank !== undefined && overallRank !== undefined && overallRank > impactRank) {
+          push("audit.finding.severity.overall-exceeds-impact", "severity.overall");
+        }
+      }
+    }
+    const textViolation = (field, value) => {
+      if (value === undefined)
+        return;
+      if (typeof value !== "string")
+        push("audit.finding.text.type", field);
+      else if (LONE_SURROGATE_RE.test(value))
+        push("audit.finding.text.surrogate", field);
+      else if (!isVisibleText(value))
+        push("audit.finding.text.invisible", field);
+    };
+    if (finding.trace !== undefined) {
+      if (!Array.isArray(finding.trace))
+        push("audit.finding.trace.shape", "trace");
+      else if (finding.trace.length === 0)
+        push("audit.finding.trace.empty", "trace");
+      else {
+        const kinds = finding.trace.map((s) => isPlainObject9(s) ? s.kind : undefined);
+        const topologyOk = finding.trace.length === 1 ? kinds[0] === "entrypoint" || kinds[0] === "sink" : kinds[0] === "entrypoint" && kinds[kinds.length - 1] === "sink" && kinds.slice(1, -1).every((k) => k === "propagation");
+        if (!topologyOk)
+          push("audit.finding.trace.topology", "trace");
+        finding.trace.forEach((step, stepIndex) => {
+          const stepAt = `trace[${stepIndex}]`;
+          if (!isPlainObject9(step)) {
+            push("audit.finding.trace.shape", stepAt);
+            return;
+          }
+          if (typeof step.line !== "number" || !Number.isSafeInteger(step.line) || step.line <= 0) {
+            push("audit.finding.trace.line", `${stepAt}.line`);
+          }
+          const stepFile = step.file;
+          if (typeof stepFile !== "string" || !safeAuditPath(stepFile))
+            push("audit.finding.path.unsafe", `${stepAt}.file`);
+          else if (redactSecrets(stepFile).text !== stepFile)
+            push("audit.finding.path.secret", `${stepAt}.file`);
+          if (step.scope === undefined)
+            push("audit.finding.trace.shape", `${stepAt}.scope`);
+          else
+            textViolation(`${stepAt}.scope`, step.scope);
+          if (step.description === undefined)
+            push("audit.finding.trace.shape", `${stepAt}.description`);
+          else
+            textViolation(`${stepAt}.description`, step.description);
+        });
+      }
+    }
+    if (!Array.isArray(finding.evidence))
+      push("audit.finding.evidence.shape", "evidence");
+    else
+      finding.evidence.forEach((item, itemIndex) => {
+        if (typeof item === "string") {
+          textViolation(`evidence[${itemIndex}]`, item);
+          return;
+        }
+        if (!isPlainObject9(item)) {
+          push("audit.finding.evidence.shape", `evidence[${itemIndex}]`);
+          return;
+        }
+        const itemFile = item.file;
+        if (typeof itemFile !== "string" || !safeAuditPath(itemFile))
+          push("audit.finding.path.unsafe", `evidence[${itemIndex}].file`);
+        else if (redactSecrets(itemFile).text !== itemFile)
+          push("audit.finding.path.secret", `evidence[${itemIndex}].file`);
+        if (item.line !== undefined && (typeof item.line !== "number" || !Number.isSafeInteger(item.line) || item.line <= 0)) {
+          push("audit.finding.evidence.line", `evidence[${itemIndex}].line`);
+        }
+        textViolation(`evidence[${itemIndex}].description`, item.description);
+      });
+    textViolation("title", finding.title);
+    textViolation("impact", finding.impact);
+    textViolation("fixSketch", finding.fixSketch);
+    textViolation("verification", finding.verification);
+  });
+  return { ok: violations.length === 0, violations };
+}
 function renderPlanFile(finding, plannedAt) {
   const sections = [
     `# ${finding.title}`,
@@ -7635,15 +7957,22 @@ function renderPlanFile(finding, plannedAt) {
     `- **Priority**: ${finding.priority}`,
     `- **Effort**: ${finding.effort}`,
     `- **Risk**: ${finding.risk}`,
+    ...finding.confidence !== "MED" || hasEnrichedMetadata(finding) ? [`- **Confidence**: ${finding.confidence}`] : [],
+    ...finding.fingerprint !== undefined ? [`- **Fingerprint**: ${finding.fingerprint}`] : [],
+    ...finding.severity !== undefined ? [`- **Likelihood**: ${finding.severity.likelihood}`, `- **Severity impact**: ${finding.severity.impact}`, `- **Severity**: ${finding.severity.overall}`] : [],
     `- **Depends on**: ${finding.dependsOn ?? "none"}`,
     `- **Category**: ${finding.category}`,
+    ...finding.evidence.length > 0 ? [`- **Evidence**: ${collapseEvidenceWs(evidenceText(finding.evidence[0]))}`] : [],
     `- **Planned at**: commit \`${plannedAt.commit}\`, ${plannedAt.date}`,
     "",
     "## Impact",
     finding.impact
   ];
   if (finding.evidence.length > 0) {
-    sections.push("", "## Evidence", ...finding.evidence.map((e) => `- ${e}`));
+    sections.push("", "## Evidence", ...finding.evidence.map((item) => `- ${evidenceText(item)}`));
+  }
+  if (finding.trace !== undefined) {
+    sections.push("", "## Trace", "", "| Kind | Location | Scope / Description |", "|------|----------|---------------------|", ...finding.trace.map((step) => `| ${escapeCell(step.kind)} | ${escapeCell(`${step.file}:${step.line}`)} | ${escapeCell(`${step.scope} — ${step.description}`).replace(/\r\n|\r|\n/g, "\\n")} |`));
   }
   if (finding.fixSketch !== undefined) {
     sections.push("", "## Fix sketch", finding.fixSketch);
@@ -7663,7 +7992,8 @@ function redactFinding(finding) {
     ...finding,
     title: redactText(finding.title),
     impact: redactText(finding.impact),
-    evidence: finding.evidence.map(redactText),
+    evidence: finding.evidence.map((item) => typeof item === "string" ? redactText(item) : { ...item, description: redactText(item.description) }),
+    ...finding.trace !== undefined ? { trace: finding.trace.map((step) => ({ ...step, scope: redactText(step.scope), description: redactText(step.description) })) } : {},
     ...finding.fixSketch !== undefined ? { fixSketch: redactText(finding.fixSketch) } : {},
     ...finding.verification !== undefined ? { verification: redactText(finding.verification) } : {}
   };
@@ -7685,7 +8015,10 @@ function extractSecurityDispositionSections(text) {
 }
 function renderIndex(params) {
   const { date, repoName, repoShortSha, rows, rejected, needsVerification, hardeningChecked } = params;
-  const findingsRows = rows.map((r) => `| ${r.num} | ${escapeCell(r.title)} | ${r.category} | ${escapeCell(truncate(r.impact, 80))} | ${r.effort} | ${r.risk} | ${r.confidence} | ${escapeCell(truncate(r.evidence, 80))} |`).join(`
+  const showFingerprint = rows.some((r) => r.fingerprint !== undefined);
+  const showSeverity = rows.some((r) => r.likelihood !== undefined || r.severityImpact !== undefined || r.severity !== undefined);
+  const cell = (value) => escapeCell(value ?? "—");
+  const findingsRows = rows.map((r) => `| ${r.num} | ${escapeCell(r.title)} | ${r.category} | ${escapeCell(truncate(r.impact, 80))} | ${r.effort} | ${r.risk} | ${r.confidence} | ${escapeCell(truncate(r.evidence, 80))}` + (showFingerprint ? ` | ${cell(r.fingerprint)}` : "") + (showSeverity ? ` | ${cell(r.likelihood)} | ${cell(r.severityImpact)} | ${cell(r.severity)}` : "") + " |").join(`
 `);
   const directionRows = rows.filter((r) => r.category === "direction").map((r) => `- ${escapeCell(r.title)} — ${escapeCell(truncate(r.impact, 120))}`).join(`
 `);
@@ -7698,8 +8031,8 @@ function renderIndex(params) {
     "",
     "## Findings",
     "",
-    "| # | Finding | Category | Impact | Effort | Risk | Confidence | Evidence |",
-    "|---|---------|----------|--------|--------|------|------------|----------|",
+    "| # | Finding | Category | Impact | Effort | Risk | Confidence | Evidence" + (showFingerprint ? " | Fingerprint" : "") + (showSeverity ? " | Likelihood | Severity impact | Severity" : "") + " |",
+    "|---|---------|----------|--------|--------|------|------------|----------" + (showFingerprint ? "|------------" : "") + (showSeverity ? "|------------|-----------------|----------" : "") + "|",
     findingsRows
   ];
   if (directionRows !== "") {
@@ -7723,6 +8056,11 @@ function renderIndex(params) {
 function scaffoldAuditPlan(outDir, findings, options = {}) {
   const date = options.date ?? new Date().toISOString().slice(0, 10);
   const plannedAt = options.plannedAt ?? { commit: options.repoShortSha ?? "unknown", date };
+  const gate2 = validateAuditFindingGates(findings);
+  if (!gate2.ok) {
+    const first = gate2.violations[0];
+    throw new TypeError(`invalid audit findings — ${first.code}: ${first.message}`);
+  }
   mkdirSync8(outDir, { recursive: true });
   const existingReadme = join16(outDir, "README.md");
   const carried = existsSync12(existingReadme) ? extractSecurityDispositionSections(readFileSync11(existingReadme, "utf8")) : { needsVerification: [], hardeningChecked: [] };
@@ -7757,10 +8095,14 @@ function scaffoldAuditPlan(outDir, findings, options = {}) {
       impact: "see plan file",
       effort: fields.get("Effort") ?? "—",
       risk: fields.get("Risk") ?? "—",
-      confidence: "—",
+      confidence: fields.get("Confidence") ?? "—",
       evidence: fields.get("Evidence") ?? "—",
       priority: fields.get("Priority") ?? "—",
-      dependsOn: fields.get("Depends on") ?? "—"
+      dependsOn: fields.get("Depends on") ?? "—",
+      fingerprint: fields.get("Fingerprint"),
+      likelihood: fields.get("Likelihood"),
+      severityImpact: fields.get("Severity impact"),
+      severity: fields.get("Severity")
     };
   });
   const byNum = new Map(rows.map((r) => [r.num, r]));
@@ -7775,9 +8117,13 @@ function scaffoldAuditPlan(outDir, findings, options = {}) {
       row.effort = finding.effort;
       row.risk = finding.risk;
       row.confidence = finding.confidence;
-      row.evidence = finding.evidence[0] ?? "";
+      row.evidence = finding.evidence.length > 0 ? collapseEvidenceWs(evidenceText(finding.evidence[0])) : "";
       row.priority = finding.priority;
       row.dependsOn = finding.dependsOn ?? "none";
+      row.fingerprint = finding.fingerprint;
+      row.likelihood = finding.severity?.likelihood;
+      row.severityImpact = finding.severity?.impact;
+      row.severity = finding.severity?.overall;
     }
   });
   const needsVerificationLines = options.needsVerification !== undefined ? options.needsVerification.map((nv) => `- ${escapeCell(redactText(nv.lead))}: ${escapeCell(redactText(nv.how))}${nv.evidence ? ` (${escapeCell(redactText(nv.evidence))})` : ""}`) : carried.needsVerification;
@@ -9013,7 +9359,7 @@ function computePrTally(input) {
 var REVIEW_SCHEMA_ID = "mstar.review/v1";
 var INSPECTOR_VERDICTS = ["comment", "request_changes", "approve"];
 var INSPECTOR_SEVERITIES = ["critical", "warning", "suggestion", "info"];
-function isPlainObject9(value) {
+function isPlainObject10(value) {
   return typeof value === "object" && value !== null && !Array.isArray(value);
 }
 var TALLY_COUNT_KEYS = ["mustFix", "shouldFix", "nit", "unverified"];
@@ -9024,7 +9370,7 @@ function checkProvidedTallyShape(tally, violations) {
   if (typeof tally.scorePct !== "number" || !Number.isInteger(tally.scorePct) || tally.scorePct < 0 || tally.scorePct > 100) {
     violations.push(violation15("high", "review.tally-malformed", `tally.scorePct must be an integer in [0, 100] - got ${String(tally.scorePct)}`));
   }
-  if (!isPlainObject9(tally.tally)) {
+  if (!isPlainObject10(tally.tally)) {
     violations.push(violation15("high", "review.tally-malformed", "tally.tally must be an object carrying the four class counts"));
   } else {
     for (const key of TALLY_COUNT_KEYS) {
@@ -9040,7 +9386,7 @@ function checkProvidedTallyShape(tally, violations) {
 }
 function validateMstarReviewV1(doc) {
   const violations = [];
-  if (!isPlainObject9(doc)) {
+  if (!isPlainObject10(doc)) {
     return {
       ok: false,
       violations: [violation15("high", "review.not-object", "review document must be a JSON object")]
@@ -9067,7 +9413,7 @@ function validateMstarReviewV1(doc) {
     violations.push(violation15("high", "review.findings-not-array", "findings must be an array"));
   } else {
     doc.findings.forEach((finding, index) => {
-      if (!isPlainObject9(finding)) {
+      if (!isPlainObject10(finding)) {
         violations.push(violation15("high", "review.invalid-finding", `findings[${index}] must be an object`));
         return;
       }
@@ -9107,7 +9453,7 @@ function validateMstarReviewV1(doc) {
     });
   }
   if (doc.tally !== undefined) {
-    if (!isPlainObject9(doc.tally)) {
+    if (!isPlainObject10(doc.tally)) {
       violations.push(violation15("high", "review.invalid-tally", "tally must be a PrTallyResult object"));
     } else {
       checkProvidedTallyShape(doc.tally, violations);
@@ -9117,7 +9463,7 @@ function validateMstarReviewV1(doc) {
     }
   }
   if (doc.target !== undefined) {
-    if (!isPlainObject9(doc.target)) {
+    if (!isPlainObject10(doc.target)) {
       violations.push(violation15("high", "review.invalid-target", "target must be an object"));
     } else {
       if (doc.target.owner !== undefined && typeof doc.target.owner !== "string") {
@@ -13430,6 +13776,7 @@ export {
   readWorkflowSnapshot,
   recordWorkflowDelivery,
   referenceExists,
+  registerIterationWorkflow,
   registerPlanWorkflow,
   registerWorkflow,
   releaseLease,
@@ -13474,6 +13821,7 @@ export {
   techDebtRollup,
   unregisterWorkflow,
   validateAssignmentFields,
+  validateAuditFindingGates,
   validateAuditStatusBlocks,
   validateCompassFrontmatter,
   validateDesignTokenFrontmatter,

package/dist/index.d.ts

@@ -45,8 +45,8 @@ export type { PlanRow, ResidualEntry, StatusDoc, StatusV2Doc, WorkflowEntry, } f
 export { normalizeSeverity, registerWorkflow, resolveCompassEnforcement, resolveMstarcEnforcement, resolveRepoEnforcement, unregisterWorkflow, validatePlanRow, validateResidual, validateStatus, validateStatusV2, validateWorkflowEntry, } from "./status.js";
 export type { ClaimLeaseFields, ExecutionLease, ExecutionLeaseLocations, IntegrationMergeLease, LeaseTransition, LeaseVerifyResult, } from "./lease.js";
 export { canSteal, claimLease, planExecutionLeaseLocations, releaseLease, sameHolderResume, validateExecutionLease, validateIntegrationMergeLease, verifyPlanExecutionLease, withStatusWriteLock, } from "./lease.js";
-export type { CloseWorkflowOptions, DeclareWorkflowDeliveryKindOptions, DeliveryRegistrationEvidence, RecordWorkflowDeliveryOptions, RecordWorkflowDeliveryResult, RegisterPlanWorkflowOptions, RegisterPlanWorkflowResult, WorkflowBranchAnchors, WorkflowCompoundOutcome, WorkflowDeliveryEvidence, WorkflowDeliveryKind, WorkflowExecutionPolicy, WorkflowLifecycleStatus, WorkflowLifecycleType, WorkflowSnapshot, WorkflowSnapshotRead, } from "./workflow.js";
-export { assertDeliveryRegistrationCoherence, closeWorkflow, consultDeliveryEvidence, declareWorkflowDeliveryKind, isTerminalSnapshot, LEGACY_WORKTREE_PATH_CODE, recordWorkflowDelivery, registerPlanWorkflow, WORKFLOW_COMPOUND_OUTCOMES, WORKFLOW_DELIVERY_KINDS, WORKFLOW_LIFECYCLE_STATUSES, WORKFLOW_LIFECYCLE_TYPES, WORKFLOW_SNAPSHOT_FILE, WORKFLOW_TERMINAL_STATUSES, readWorkflowSnapshot, validateWorkflowSnapshot, writeWorkflowSnapshot, } from "./workflow.js";
+export type { CloseWorkflowOptions, DeclareWorkflowDeliveryKindOptions, DeliveryRegistrationEvidence, RecordWorkflowDeliveryOptions, RecordWorkflowDeliveryResult, RegisterIterationWorkflowOptions, RegisterIterationWorkflowResult, RegisterPlanWorkflowOptions, RegisterPlanWorkflowResult, WorkflowBranchAnchors, WorkflowCompoundOutcome, WorkflowDeliveryEvidence, WorkflowDeliveryKind, WorkflowExecutionPolicy, WorkflowLifecycleStatus, WorkflowLifecycleType, WorkflowSnapshot, WorkflowSnapshotRead, } from "./workflow.js";
+export { assertDeliveryRegistrationCoherence, closeWorkflow, consultDeliveryEvidence, declareWorkflowDeliveryKind, isTerminalSnapshot, LEGACY_WORKTREE_PATH_CODE, recordWorkflowDelivery, registerIterationWorkflow, registerPlanWorkflow, WORKFLOW_COMPOUND_OUTCOMES, WORKFLOW_DELIVERY_KINDS, WORKFLOW_LIFECYCLE_STATUSES, WORKFLOW_LIFECYCLE_TYPES, WORKFLOW_SNAPSHOT_FILE, WORKFLOW_TERMINAL_STATUSES, readWorkflowSnapshot, validateWorkflowSnapshot, writeWorkflowSnapshot, } from "./workflow.js";
 export type { CleanupDecision, CleanupFacts, CleanupTarget, CleanupTargetKind, } from "./cleanup.js";
 export { planWorktreeCleanup } from "./cleanup.js";
 export type { EvidenceArtifactFact, EvidenceAssessment, EvidenceCaptureRequest, EvidenceCoverage, EvidenceEnvironmentKey, EvidenceExpectation, EvidenceInputEntry, EvidenceInputSnapshot, EvidenceInputSpec, EvidenceLimits, EvidenceLog, EvidenceOutcome, EvidenceToolFingerprint, SddEvidenceRecord, } from "./evidence.js";
@@ -67,8 +67,8 @@ export type { MigrateNotesFile, MigrateOptions, MigratePlan, MigrateRegister, Mi
 export { ARCHIVED_STATUS_V1_FILE, MIGRATE_STATUS_FILE, NOTES_LEDGER_FILE, applyMigratePlan, migrateHarnessTree, } from "./migrate.js";
 export type { CompletenessItem, CompletenessLevel, CompletenessPlaceholder, CompletenessResult, DesignFrontmatter, } from "./design-md.js";
 export { assertLightDarkParity, completenessLevel, parseDesignFrontmatter, validateDesignTokenFrontmatter, } from "./design-md.js";
-export type { AuditCategory, AuditConfidence, AuditEffort, AuditFinding, AuditPriority, AuditRisk, PromoteAuditPlansOptions, RedactResult, ScaffoldAuditPlanOptions, ScaffoldAuditPlanResult, ScannedSecret, SecretFinding, SupplyChainFinding, SupplyChainFindingKind, SupplyChainResult, } from "./audit.js";
-export { AUDIT_CATEGORIES, AUDIT_CONFIDENCES, AUDIT_EFFORTS, AUDIT_PRIORITIES, AUDIT_RISKS, promoteAuditPlans, scaffoldAuditPlan, scanSecrets, supplyChainChecks, validateAuditStatusBlocks, } from "./audit.js";
+export type { AuditCategory, AuditConfidence, AuditEffort, AuditEvidence, AuditFinding, AuditPriority, AuditRisk, AuditSeverity, AuditSeverityRank, AuditTraceKind, AuditTraceStep, PromoteAuditPlansOptions, RedactResult, ScaffoldAuditPlanOptions, ScaffoldAuditPlanResult, ScannedSecret, SecretFinding, SupplyChainFinding, SupplyChainFindingKind, SupplyChainResult, } from "./audit.js";
+export { AUDIT_CATEGORIES, AUDIT_CONFIDENCES, AUDIT_EFFORTS, AUDIT_PRIORITIES, AUDIT_RISKS, promoteAuditPlans, scaffoldAuditPlan, scanSecrets, supplyChainChecks, validateAuditFindingGates, validateAuditStatusBlocks, } from "./audit.js";
 export { KNOWLEDGE_BUG_PROBLEM_TYPES, KNOWLEDGE_CATEGORY_MAP, KNOWLEDGE_KNOWLEDGE_PROBLEM_TYPES, KNOWLEDGE_PROBLEM_TYPES, KNOWLEDGE_REQUIRED_FIELDS, KNOWLEDGE_RESOLUTION_TYPES, KNOWLEDGE_SEVERITIES, assertIndexRows, compoundRefreshScope, referenceExists, scopeGuard, validateSchemaYaml, } from "./compound.js";
 export type { ReferenceCheckResult } from "./compound.js";
 export type { EphemeralCitation, PlanQualityFinding, PlanQualityResult, ProvenanceCitation, SimplifyMarker, TemporaryMarker, TemporaryMarkerResult, } from "./lint.js";

package/dist/workflow.d.ts

@@ -522,3 +522,78 @@ export type RegisterPlanWorkflowResult = {
  * root could differ — the routed writers fail loud on a path mismatch.
  */
 export declare function registerPlanWorkflow(workflowId: string, options: RegisterPlanWorkflowOptions): Promise<RegisterPlanWorkflowResult>;
+/** Options for `registerIterationWorkflow`. `harnessDir` is required — the
+ * snapshot and `status.json` live under the harness root. */
+export type RegisterIterationWorkflowOptions = {
+    /** Absolute harness dir that contains `status.json` + `workflows/`. Required. */
+    harnessDir: string;
+    /** Harness-relative compass ref recorded on the snapshot, e.g. `iterations/<id>/delivery-compass.md`. Required. */
+    compassRef: string;
+    /** The three iteration branch anchors. All three required. */
+    branch: {
+        base: string;
+        integration: string;
+        target: string;
+    };
+    /** Initial plan rows. At least one. Every row is written `status: "Todo"`. */
+    rows: Array<{
+        id: string;
+        title: string;
+        file: string;
+    }>;
+    /** Project register id recorded on the snapshot. */
+    project?: string;
+    /** Registration timestamp (YYYY-MM-DD or RFC3339). Default: now. */
+    startedAt?: string;
+};
+export type RegisterIterationWorkflowResult = {
+    workflowId: string;
+    snapshotPath: string;
+    /**
+     * True on orphan recovery: existing snapshot bytes/timestamps are preserved
+     * and only the missing root entry is written.
+     */
+    recovered: boolean;
+};
+/**
+ * Register an iteration workflow (seam S1 sibling of `registerPlanWorkflow`).
+ * Builds the create-only `type: iteration` snapshot (workflow id, compass
+ * ref, the three branch anchors, Todo rows whose `metadata` —
+ * `iteration_refs`, `spec_integration_branch`, `merge_target` — is derived
+ * from the already-required compass/integration inputs; registration never
+ * authorizes implementation) and the root `workflows[]` entry, then writes
+ * BOTH under one atomic section of the root `withStatusWriteLock` — the same
+ * create-only `writeWorkflowSnapshot(..., { createOnly: true })` →
+ * `registerWorkflowEntryLocked` primitive sequence the plan producer uses —
+ * with rollback that removes ONLY the exact snapshot version this call
+ * created (plus the now-empty workflow dir; a non-empty directory is never
+ * force-removed).
+ *
+ * Refusals (fail-loud, before any write): non-empty `workflowId`
+ * (`assertSafePathComponent`), `harnessDir`, `compassRef`, all three branch
+ * anchors, `project` when given, and each row's `id`/`title`/`file`;
+ * non-empty row array; duplicate row ids; a SUPPLIED row `status` (a
+ * requested state transition is never treated as successful registration);
+ * `startedAt` must be a valid YYYY-MM-DD / RFC3339 timestamp. Rows are
+ * constructed from the declared fields — untrusted row objects are never
+ * spread.
+ *
+ * Already-registered refusals: inside the root lock, an existing entry for
+ * the requested id refuses BEFORE either branch — including a stale entry
+ * whose snapshot is missing. This producer is not the low-level upsert and
+ * does not repair/repoint an existing identity. Malformed/v1 roots refuse
+ * without replacing their bytes.
+ *
+ * Crash/retry recovery: a snapshot without its root entry (an orphan)
+ * re-registers only when `iterationWorkflowRegistrationIdentity` matches —
+ * the existing snapshot's bytes and timestamps are preserved verbatim and
+ * the root entry is written with the orphan's `started_at` (`recovered:
+ * true`). A differing identity (including a mismatched snapshot id or an
+ * existing coordinator binding) refuses; a failed recovery root write never
+ * deletes the orphan.
+ *
+ * The caller must pin the artifact store to the harness root first
+ * (`setArtifactStore(createFsStore(harnessDir))`) when the active store's
+ * root could differ — the routed writers fail loud on a path mismatch.
+ */
+export declare function registerIterationWorkflow(workflowId: string, options: RegisterIterationWorkflowOptions): Promise<RegisterIterationWorkflowResult>;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@mstar-harness/engine",
-  "version": "3.10.3",
+  "version": "3.11.0",
   "description": "Morning Star Harness Workflow Engine — deterministic workflow enforcement library (path, status, lease, dispatch, sdd, iteration, lint gates).",
   "license": "MIT",
   "repository": {