@kontourai/flow-agents 2.3.0 → 3.0.0

package/schemas/knowledge/node.schema.json

@@ -0,0 +1,49 @@
+{
+  "$schema": "http://json-schema.org/draft-07/schema#",
+  "$id": "https://flow-agents.dev/schemas/knowledge/node.schema.json",
+  "title": "Knowledge Graph Node",
+  "description": "A typed node in the Knowledge Kit graph model. type is EXTENSIBLE: the recommended core vocabulary is note, decision, issue, session, person, but providers MAY emit additional types. Every node carries provenance so any assertion can be traced back to the store it came from.",
+  "type": "object",
+  "additionalProperties": false,
+  "required": ["id", "type", "title", "provenance"],
+  "properties": {
+    "id": {
+      "type": "string",
+      "minLength": 1,
+      "description": "Provider-scoped stable identifier, unique within a single readGraph result."
+    },
+    "type": {
+      "type": "string",
+      "minLength": 1,
+      "description": "Node type. Recommended core vocabulary: note, decision, issue, session, person. Extensible — unknown types MUST NOT be rejected."
+    },
+    "title": {
+      "type": "string",
+      "minLength": 1,
+      "description": "Human-readable title used for display and duplicate detection."
+    },
+    "body": {
+      "type": "string",
+      "description": "Primary content. Format is provider/type-specific."
+    },
+    "attributes": {
+      "type": "object",
+      "description": "Provider-specific structured fields (e.g. issue state/labels, decision status, note category/tags)."
+    },
+    "provenance": { "$ref": "#/$defs/provenance" }
+  },
+  "$defs": {
+    "provenance": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": ["provider", "source", "retrieved_at"],
+      "properties": {
+        "provider": { "type": "string", "minLength": 1, "description": "Provider id that produced this element (e.g. markdown-vault, git-repo, work-item)." },
+        "source": { "type": "string", "minLength": 1, "description": "The concrete origin: a file path, an issue ref, or a URL." },
+        "locator": { "type": "string", "description": "Optional finer locator within the source (line, anchor, frontmatter field)." },
+        "retrieved_at": { "type": "string", "minLength": 1, "description": "ISO-8601 timestamp the element was read." },
+        "agent": { "type": "string", "description": "Optional agent/process id that performed the read." }
+      }
+    }
+  }
+}

package/schemas/knowledge/proposal.schema.json

@@ -0,0 +1,53 @@
+{
+  "$schema": "http://json-schema.org/draft-07/schema#",
+  "$id": "https://flow-agents.dev/schemas/knowledge/proposal.schema.json",
+  "title": "Knowledge Store Write Proposal",
+  "description": "The ONLY write artifact a knowledge store provider may emit. Providers over human-curated stores are proposals-only: proposeWrite() never mutates the store and can only ever return a Proposal whose status is the const \"proposed\". Enactment happens downstream (a human edit, the decision-registry promote step, or a gh comment/label the operator files) — never inside the provider. The `rendered` field carries the provider-native form the enactor would apply (decision-registry topic frontmatter for git-repo; an issue comment/label body for work-item; a vault note with frontmatter+wikilinks for markdown-vault).",
+  "type": "object",
+  "additionalProperties": false,
+  "required": ["schema_version", "provider", "kind", "target", "status", "provenance"],
+  "properties": {
+    "schema_version": { "const": "1.0" },
+    "provider": { "type": "string", "minLength": 1 },
+    "kind": {
+      "type": "string",
+      "enum": ["create-node", "update-node", "add-edge", "comment", "label", "decision-topic"],
+      "description": "The shape of the proposed change."
+    },
+    "target": {
+      "type": "object",
+      "description": "Where the change would land if enacted (file path, issue number, store id). Descriptive only — the provider does not touch it."
+    },
+    "payload": {
+      "type": "object",
+      "description": "The structured node/edge/field the proposal would introduce."
+    },
+    "rendered": {
+      "type": "string",
+      "description": "The provider-native rendered form an enactor would apply (topic-file frontmatter, gh comment body, vault note)."
+    },
+    "status": {
+      "const": "proposed",
+      "description": "Always the literal \"proposed\". A provider can NEVER return an applied proposal — this const is the structural expression of proposals-only discipline."
+    },
+    "rationale": {
+      "type": "string",
+      "description": "Why the change is proposed."
+    },
+    "provenance": { "$ref": "#/$defs/provenance" }
+  },
+  "$defs": {
+    "provenance": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": ["provider", "source", "retrieved_at"],
+      "properties": {
+        "provider": { "type": "string", "minLength": 1 },
+        "source": { "type": "string", "minLength": 1 },
+        "locator": { "type": "string" },
+        "retrieved_at": { "type": "string", "minLength": 1 },
+        "agent": { "type": "string" }
+      }
+    }
+  }
+}

package/schemas/workflow-evidence.schema.json

@@ -174,7 +174,7 @@
           },
           "kind": {
             "type": "string",
-            "enum": ["build", "types", "lint", "test", "security", "diff", "browser", "runtime", "policy", "external"]
+            "enum": ["build", "types", "lint", "test", "command", "security", "diff", "browser", "runtime", "policy", "external"]
           },
           "status": {
             "type": "string",

package/schemas/workflow-state.schema.json

@@ -36,6 +36,11 @@
     "owner": {
       "type": "string"
     },
+    "branch": {
+      "type": "string",
+      "minLength": 1,
+      "description": "Routing branch for this session, e.g. agent/<actor>/<slug> (ADR 0021 \u00a73/\u00a75, issue #289). Optional for migration honesty: legacy/in-flight sessions predate this field. ensure-session always writes it for newly created sessions; validate-workflow-artifacts warns (does not fail) when it is absent."
+    },
     "created_at": {
       "type": "string",
       "format": "date-time"

package/scripts/README.md

@@ -52,7 +52,7 @@ renamed, or changes category, update the table and the validator together.
 | `codex-telemetry-hook.js` | telemetry shim | `evals/integration/test_hook_category_behaviors.sh`, `evals/integration/test_telemetry.sh` | Captures Codex hook telemetry and fails open. |
 | `run-hook.js` | hook runner | `evals/integration/test_hook_category_behaviors.sh`, `evals/integration/test_goal_fit_hook.sh`, `evals/integration/test_workflow_steering_hook.sh` | Applies profile/disable flags, traversal checks, and hook execution. |
 | `config-protection.js` | policy hook | `evals/integration/test_hook_category_behaviors.sh` | Blocks unsafe runtime config edits. |
-| `evidence-capture.js` | policy hook | `evals/integration/test_evidence_capture_hook.sh` | Deterministically captures command executions to `.flow-agents/<slug>/command-log.jsonl` so evidence is machine-recorded, not model-claimed (cross-referenced by stop-goal-fit). |
+| `evidence-capture.js` | policy hook | `evals/integration/test_evidence_capture_hook.sh` | Deterministically captures command executions to `.kontourai/flow-agents/<slug>/command-log.jsonl` so evidence is machine-recorded, not model-claimed (cross-referenced by stop-goal-fit). |
 | `governance-audit.sh` | policy hook | `evals/integration/test_hook_category_behaviors.sh`, `evals/integration/test_telemetry.sh` | Emits governance/Veritas audit context when configured. |
 | `opencode-hook-adapter.js` | runtime adapter | `evals/integration/test_bundle_install.sh` | Translates opencode plugin events into the shared hook runner contract. |
 | `opencode-telemetry-hook.js` | telemetry shim | `evals/integration/test_bundle_install.sh` | Captures opencode plugin telemetry and fails open. |
@@ -67,10 +67,15 @@ renamed, or changes category, update the table and the validator together.
 | `workflow-steering.js` | policy hook | `evals/integration/test_workflow_steering_hook.sh` | Provides workflow guidance from current artifact state. |
 | `pre-commit-quality.js` | repo guardrail hook | `evals/integration/test_hook_category_behaviors.sh` | Supports repository Git hook checks, not installed runtime hooks. |
 | `desktop-notify.sh` | local notification helper | `evals/integration/test_hook_category_behaviors.sh` | Optional local desktop notification helper. |
+| `lib/actor-identity.js` | shared hook library | `evals/integration/test_actor_identity.sh` | Shared runtime-agnostic actor identity resolver (`resolveActor`) consumed by `workflow-steering.js` and `workflow-sidecar.js` to retire the shared `"local"` liveness-actor default (issue #287). |
 | `lib/audit-transport.sh` | shared hook library | `evals/integration/test_hook_category_behaviors.sh`, `evals/integration/test_telemetry.sh` | Shared audit event transport functions. |
+| `lib/config-protection-remedies.js` | shared hook library | `evals/integration/test_hook_category_behaviors.sh` | Sanctioned-remedy table for `config-protection.js` (WS8/ADR 0020 extraction). |
 | `lib/hook-flags.js` | shared hook library | `evals/integration/test_hook_category_behaviors.sh` | Shared profile/disable flag parsing. |
+| `lib/liveness-heartbeat.js` | shared hook library | `evals/integration/test_liveness_heartbeat.sh` | Shared tool-activity liveness heartbeat (`maybeEmitHeartbeat`); rides `postToolUse` across all four telemetry hook wrappers, throttled and fail-open (issue #288). |
+| `lib/liveness-policy.js` | shared hook library | `evals/integration/test_workflow_sidecar_writer.sh`, `evals/integration/test_liveness_heartbeat.sh` | Shared liveness on/off predicate (`isLivenessEnabled`, default-on/opt-out) and TTL/heartbeat-throttle default resolution (issue #288). |
 | `lib/liveness-read.js` | shared hook library | `evals/integration/test_session_resume_roundtrip.sh` | Shared liveness event reader + freshness check (`readLivenessEvents`, `freshHolders`); consumed by the reground hook and `workflow-sidecar liveness status`. |
-| `lib/local-artifact-paths.js` | shared hook library | `evals/integration/test_migrate_local_artifacts.sh`, `evals/integration/test_workflow_sidecar_writer.sh` | Shared `.kontourai/flow-agents` artifact-root helpers with legacy `.flow-agents` read compatibility for CJS hooks. |
+| `lib/liveness-write.js` | shared hook library | `evals/integration/test_workflow_sidecar_writer.sh`, `evals/integration/test_liveness_heartbeat.sh` | Shared liveness event stream writer (`livenessStreamFile`, `appendLivenessEvent`), lifted from `workflow-sidecar.ts` so the CLI and hook wrappers share one writer (issue #288). |
+| `lib/local-artifact-paths.js` | shared hook library | `evals/integration/test_migrate_local_artifacts.sh`, `evals/integration/test_workflow_sidecar_writer.sh` | Shared `.kontourai/flow-agents` artifact-root helpers for CJS hooks. |
 | `lib/patterns.sh` | shared hook library | `evals/integration/test_hook_category_behaviors.sh`, `evals/integration/test_telemetry.sh` | Shared shell pattern constants. |
 | `lib/resolve-formatter.js` | shared hook library | `evals/integration/test_hook_category_behaviors.sh` | Shared formatter resolution helper. |
 
@@ -103,7 +108,7 @@ prompting. Add `--allow-network` to probe a non-local HTTPS Console endpoint.
 
 ## Install And Repo Utilities
 
-- `install-codex-home.sh`: installs the isolated generated Codex home.
+- `install-codex-home.sh`: installs the generated Codex bundle into `CODEX_HOME`, or `~/.codex` when `CODEX_HOME` is unset. A positional destination argument is the explicit override for isolated homes and tests.
 - `setup-repo-hooks.sh`: configures this clone's Git hook path.
 - `check-content-boundary.cjs`, `detect-tools.sh`, `discover-agents.sh`, `git-status.sh`: repo-local helper commands.
 - `context-budget/` and `statusline/`: specialized support tooling copied into bundles where needed.

package/scripts/check-content-boundary.cjs

@@ -42,7 +42,7 @@ function isIgnoredPath(filePath) {
 }
 
 function isWorkflowRuntimeArtifact(filePath) {
-  return filePath.startsWith(".flow-agents/");
+  return filePath.startsWith(".kontourai/flow-agents/") || filePath.startsWith(".flow-agents/");
 }
 
 function lineNumberFor(content, index) {

package/scripts/check-decisions.cjs

@@ -0,0 +1,356 @@
+#!/usr/bin/env node
+"use strict";
+
+// check-decisions.cjs — validator + index generator for the topic-keyed
+// decision registry (context/contracts/decision-registry-contract.md).
+//
+// Usage:
+//   node scripts/check-decisions.cjs check        # validate all topic files + assert index is current (default)
+//   node scripts/check-decisions.cjs gen-index    # (re)write docs/decisions/index.md deterministically
+//
+// Zero runtime dependencies (mirrors scripts/check-content-boundary.cjs): the
+// decision-record JSON schema at schemas/decision-record.schema.json is the
+// normative structural contract; this script enforces the same rules directly
+// so it runs in `npm ci` environments without a JSON-schema/YAML library.
+
+const fs = require("node:fs");
+const path = require("node:path");
+
+const ROOT = path.resolve(__dirname, "..");
+// FLOW_AGENTS_DECISIONS_DIR lets the eval suite point the validator/generator at
+// a throwaway fixture directory (mirrors FLOW_AGENTS_CONTENT_BOUNDARY_FILES).
+const DECISIONS_DIR = process.env.FLOW_AGENTS_DECISIONS_DIR
+  ? path.resolve(process.env.FLOW_AGENTS_DECISIONS_DIR)
+  : path.join(ROOT, "docs", "decisions");
+const INDEX_PATH = path.join(DECISIONS_DIR, "index.md");
+const INDEX_SLUG = "index";
+
+const STATUSES = ["current", "superseded", "merged", "needs-decision"];
+const EVIDENCE_KINDS = ["issue", "pr", "commit", "session-archive", "adr", "doc", "url"];
+const SLUG_RE = /^[a-z0-9]+(-[a-z0-9]+)*$/;
+const DATE_RE = /^\d{4}-\d{2}-\d{2}$/;
+
+// Secret-shaped literal detectors — mirror scripts/hooks/lib/patterns.sh so the
+// registry never captures a credential in an evidence ref.
+const SECRET_PATTERNS = [
+  { label: "aws access key id", re: /AKIA[A-Z0-9]{16}/ },
+  { label: "aws sts key id", re: /ASIA[A-Z0-9]{16}/ },
+  { label: "github token", re: /gh[pousr]_[A-Za-z0-9_]{36,}/ },
+  { label: "private key block", re: /BEGIN[A-Z ]*PRIVATE KEY/ },
+  { label: "jwt", re: /eyJ[A-Za-z0-9_-]{10,}\.eyJ[A-Za-z0-9_-]{10,}\.[A-Za-z0-9_-]{10,}/ },
+  {
+    label: "generic secret literal",
+    re: /(secret|password|token|api[_-]?key)\s*[:=]\s*["'][^"']{8,}/i,
+  },
+];
+
+function listTopicFiles() {
+  if (!fs.existsSync(DECISIONS_DIR)) return [];
+  return fs
+    .readdirSync(DECISIONS_DIR)
+    .filter((name) => name.endsWith(".md") && name !== "index.md")
+    .sort();
+}
+
+// Minimal, strict YAML-frontmatter reader. The decision-record frontmatter is a
+// flat map of scalars plus two list shapes (evidence[] as `- kind: .. ` blocks
+// and slug arrays as inline `[a, b]` or block `- slug`). We parse exactly that
+// shape and reject anything we do not understand rather than guessing.
+function parseFrontmatter(raw, errors) {
+  if (!raw.startsWith("---\n") && !raw.startsWith("---\r\n")) {
+    errors.push("file must begin with a YAML frontmatter block delimited by '---'");
+    return null;
+  }
+  const lines = raw.split(/\r?\n/);
+  let end = -1;
+  for (let i = 1; i < lines.length; i += 1) {
+    if (lines[i].trim() === "---") {
+      end = i;
+      break;
+    }
+  }
+  if (end === -1) {
+    errors.push("frontmatter block is not terminated by a closing '---'");
+    return null;
+  }
+  const body = lines.slice(1, end);
+  const data = {};
+  let cursorKey = null;
+
+  for (let i = 0; i < body.length; i += 1) {
+    const line = body[i];
+    if (line.trim() === "" || line.trim().startsWith("#")) continue;
+
+    const topMatch = line.match(/^([A-Za-z0-9_]+):\s*(.*)$/);
+    const listItem = line.match(/^\s*-\s+(.*)$/);
+
+    if (topMatch && !line.startsWith(" ")) {
+      const key = topMatch[1];
+      const rest = topMatch[2].trim();
+      cursorKey = key;
+      if (rest === "") {
+        data[key] = { __pending_list: true, items: [] };
+      } else if (rest.startsWith("[") && rest.endsWith("]")) {
+        const inner = rest.slice(1, -1).trim();
+        data[key] = inner === "" ? [] : inner.split(",").map((s) => stripScalar(s.trim()));
+      } else {
+        data[key] = stripScalar(rest);
+      }
+      continue;
+    }
+
+    if (listItem && cursorKey) {
+      const container = data[cursorKey];
+      if (!container || !container.__pending_list) {
+        errors.push(`unexpected list item under '${cursorKey}': ${line.trim()}`);
+        continue;
+      }
+      const itemBody = listItem[1].trim();
+      // Object list item: `- kind: pr, ref: ...` OR `- kind: pr` then following `  ref: ...`
+      const inlinePair = itemBody.match(/^([A-Za-z0-9_]+):\s*(.*)$/);
+      if (inlinePair) {
+        const obj = {};
+        obj[inlinePair[1]] = stripScalar(inlinePair[2].trim());
+        // consume subsequent indented `key: value` continuation lines
+        while (i + 1 < body.length && /^\s+[A-Za-z0-9_]+:\s*/.test(body[i + 1]) && !/^\s*-\s+/.test(body[i + 1])) {
+          const cont = body[i + 1].trim().match(/^([A-Za-z0-9_]+):\s*(.*)$/);
+          if (!cont) break;
+          obj[cont[1]] = stripScalar(cont[2].trim());
+          i += 1;
+        }
+        container.items.push(obj);
+      } else {
+        container.items.push(stripScalar(itemBody));
+      }
+      continue;
+    }
+
+    errors.push(`unparseable frontmatter line: ${line}`);
+  }
+
+  // Normalize pending lists to plain arrays.
+  for (const key of Object.keys(data)) {
+    if (data[key] && data[key].__pending_list) {
+      data[key] = data[key].items;
+    }
+  }
+  return data;
+}
+
+function stripScalar(value) {
+  let v = value.trim();
+  if ((v.startsWith('"') && v.endsWith('"')) || (v.startsWith("'") && v.endsWith("'"))) {
+    v = v.slice(1, -1);
+  }
+  return v;
+}
+
+function firstBodyLine(raw) {
+  const lines = raw.split(/\r?\n/);
+  let seenClose = false;
+  let count = 0;
+  for (const line of lines) {
+    if (line.trim() === "---") {
+      count += 1;
+      if (count === 2) seenClose = true;
+      continue;
+    }
+    if (!seenClose) continue;
+    const t = line.trim();
+    if (t === "") continue;
+    return t.replace(/^#+\s*/, "").trim();
+  }
+  return "";
+}
+
+function validateFile(slug, raw, knownSlugs) {
+  const errors = [];
+  const fm = parseFrontmatter(raw, errors);
+  if (!fm) return errors;
+
+  if (!SLUG_RE.test(slug)) {
+    errors.push(`filename slug '${slug}' is not a valid kebab-case topic slug`);
+  }
+
+  // status
+  if (!("status" in fm)) {
+    errors.push("missing required field: status");
+  } else if (!STATUSES.includes(fm.status)) {
+    errors.push(`unknown status '${fm.status}' (allowed: ${STATUSES.join(", ")})`);
+  }
+
+  // subject
+  if (!("subject" in fm) || typeof fm.subject !== "string" || fm.subject.trim() === "") {
+    errors.push("missing required field: subject (non-empty)");
+  }
+
+  // decided
+  if (!("decided" in fm)) {
+    errors.push("missing required field: decided");
+  } else if (typeof fm.decided !== "string" || !DATE_RE.test(fm.decided)) {
+    errors.push(`decided must be an ISO date (YYYY-MM-DD); got '${fm.decided}'`);
+  }
+
+  // evidence
+  if (!("evidence" in fm)) {
+    errors.push("missing required field: evidence[]");
+  } else if (!Array.isArray(fm.evidence) || fm.evidence.length === 0) {
+    errors.push("evidence must be a non-empty array of {kind, ref}");
+  } else {
+    fm.evidence.forEach((item, idx) => {
+      if (typeof item !== "object" || item === null || Array.isArray(item)) {
+        errors.push(`evidence[${idx}] must be an object {kind, ref}`);
+        return;
+      }
+      if (!EVIDENCE_KINDS.includes(item.kind)) {
+        errors.push(`evidence[${idx}].kind '${item.kind}' is not one of ${EVIDENCE_KINDS.join(", ")}`);
+      }
+      if (typeof item.ref !== "string" || item.ref.trim() === "") {
+        errors.push(`evidence[${idx}].ref must be a non-empty string`);
+        return;
+      }
+      for (const pat of SECRET_PATTERNS) {
+        if (pat.re.test(item.ref)) {
+          errors.push(`evidence[${idx}].ref contains a secret-shaped literal (${pat.label}); link durable provenance, never a credential`);
+          break;
+        }
+      }
+    });
+  }
+
+  // tombstone / relationship fields
+  const relSingles = ["superseded_by", "merged_into"];
+  for (const key of relSingles) {
+    if (key in fm) {
+      const target = fm[key];
+      if (typeof target !== "string" || !SLUG_RE.test(target)) {
+        errors.push(`${key} must be a single topic slug; got '${target}'`);
+      } else if (!knownSlugs.has(target)) {
+        errors.push(`${key} points at missing topic slug '${target}' (no docs/decisions/${target}.md)`);
+      } else if (target === slug) {
+        errors.push(`${key} must not point at its own slug`);
+      }
+    }
+  }
+  if ("supersedes" in fm) {
+    const arr = Array.isArray(fm.supersedes) ? fm.supersedes : [fm.supersedes];
+    arr.forEach((target) => {
+      if (typeof target !== "string" || !SLUG_RE.test(target)) {
+        errors.push(`supersedes entry must be a topic slug; got '${target}'`);
+      } else if (!knownSlugs.has(target)) {
+        errors.push(`supersedes points at missing topic slug '${target}'`);
+      }
+    });
+  }
+
+  // status-conditional relationship rules
+  if (fm.status === "current" || fm.status === "needs-decision") {
+    if ("superseded_by" in fm || "merged_into" in fm) {
+      errors.push(`status '${fm.status}' must not carry superseded_by or merged_into`);
+    }
+  }
+  if (fm.status === "superseded") {
+    if (!("superseded_by" in fm)) errors.push("status 'superseded' requires superseded_by");
+    if ("merged_into" in fm) errors.push("status 'superseded' must not carry merged_into");
+  }
+  if (fm.status === "merged") {
+    if (!("merged_into" in fm)) errors.push("status 'merged' requires merged_into");
+    if ("superseded_by" in fm) errors.push("status 'merged' must not carry superseded_by");
+  }
+
+  return errors;
+}
+
+function readTopics() {
+  const files = listTopicFiles();
+  const knownSlugs = new Set(files.map((f) => f.replace(/\.md$/, "")));
+  return files.map((file) => {
+    const slug = file.replace(/\.md$/, "");
+    const raw = fs.readFileSync(path.join(DECISIONS_DIR, file), "utf8");
+    const errors = validateFile(slug, raw, knownSlugs);
+    const fm = parseFrontmatter(raw, []);
+    return { slug, raw, fm: fm || {}, errors };
+  });
+}
+
+function oneLiner(topic) {
+  const subject = topic.fm && typeof topic.fm.subject === "string" ? topic.fm.subject.trim() : "";
+  if (subject) return subject;
+  const body = firstBodyLine(topic.raw);
+  return body || topic.slug;
+}
+
+function renderIndex(topics) {
+  const lines = [];
+  lines.push("---");
+  lines.push("title: Decision Index");
+  lines.push("---");
+  lines.push("");
+  lines.push("# Decision Index");
+  lines.push("");
+  lines.push("Generated by `npm run gen:decisions-index`. Do not edit by hand.");
+  lines.push("Topic-keyed living decision records per `context/contracts/decision-registry-contract.md`.");
+  lines.push("Numbered ADRs under `docs/adr/` are frozen history and are not listed here.");
+  lines.push("");
+  lines.push("| Topic | Status | Decision |");
+  lines.push("| --- | --- | --- |");
+  const sorted = [...topics].sort((a, b) => a.slug.localeCompare(b.slug));
+  for (const topic of sorted) {
+    const status = topic.fm && typeof topic.fm.status === "string" ? topic.fm.status : "unknown";
+    const summary = oneLiner(topic).replace(/\|/g, "\\|");
+    lines.push(`| [${topic.slug}](./${topic.slug}.md) | ${status} | ${summary} |`);
+  }
+  lines.push("");
+  return lines.join("\n");
+}
+
+function cmdGenIndex() {
+  fs.mkdirSync(DECISIONS_DIR, { recursive: true });
+  const topics = readTopics();
+  const content = renderIndex(topics);
+  fs.writeFileSync(INDEX_PATH, content, "utf8");
+  console.log(`Wrote ${path.relative(ROOT, INDEX_PATH)} (${topics.length} topic${topics.length === 1 ? "" : "s"}).`);
+  return 0;
+}
+
+function cmdCheck() {
+  const topics = readTopics();
+  let failed = false;
+
+  for (const topic of topics) {
+    if (topic.errors.length > 0) {
+      failed = true;
+      console.error(`FAIL docs/decisions/${topic.slug}.md`);
+      for (const err of topic.errors) console.error(`  - ${err}`);
+    }
+  }
+
+  // Index freshness: check regenerates deterministically and must match on disk
+  // (this is what makes regeneration idempotent + diff-clean, AC2).
+  const expectedIndex = renderIndex(topics);
+  const actualIndex = fs.existsSync(INDEX_PATH) ? fs.readFileSync(INDEX_PATH, "utf8") : null;
+  if (actualIndex === null) {
+    failed = true;
+    console.error("FAIL docs/decisions/index.md is missing; run `npm run gen:decisions-index`");
+  } else if (actualIndex !== expectedIndex) {
+    failed = true;
+    console.error("FAIL docs/decisions/index.md is stale; run `npm run gen:decisions-index`");
+  }
+
+  if (failed) {
+    console.error("Decision registry check failed.");
+    return 1;
+  }
+  console.log(`Decision registry check passed (${topics.length} topic${topics.length === 1 ? "" : "s"}).`);
+  return 0;
+}
+
+function main() {
+  const mode = process.argv[2] || "check";
+  if (mode === "check") return process.exit(cmdCheck());
+  if (mode === "gen-index") return process.exit(cmdGenIndex());
+  console.error(`Unknown mode '${mode}'. Usage: check-decisions.cjs [check|gen-index]`);
+  return process.exit(2);
+}
+
+main();

package/scripts/ci/derive-claim-status.mjs

@@ -0,0 +1,74 @@
+#!/usr/bin/env node
+// derive-claim-status.mjs — WS8 (AC1/finding-3) CI-side status re-derivation helper.
+//
+// The trust reconciler MUST NOT trust a bundle's self-reported `claim.status`. This helper
+// re-derives each claim's status from the bundle's OWN evidence/events/policies using
+// @kontourai/surface's canonical `deriveClaimStatus` — the exact function the producer used
+// — so the reconciler can detect a status-misassertion (asserted status != derived status).
+//
+// It is a separate ESM module because @kontourai/surface is ESM-only while
+// scripts/ci/trust-reconcile.js is CommonJS with a synchronous entrypoint; the reconciler
+// invokes this via spawnSync and parses the JSON on stdout. Surface is resolved from THIS
+// file's location (the reconciler's own node_modules), NOT the target repo-root, so an
+// adopter repo without Surface still gets CI-side re-derivation from the anchor's copy.
+//
+// Usage: node derive-claim-status.mjs <bundle-path>
+// Output (stdout): {"claimId": "<TrustStatus>", ...}  — value is null if that claim threw.
+// Exit: 0 on success (Surface loaded); 2 if Surface is unavailable; 3 on bad input.
+
+import { readFileSync } from "node:fs";
+
+async function main() {
+  const bundlePath = process.argv[2];
+  if (!bundlePath) { process.stderr.write("derive-claim-status: bundle path argument required\n"); return 3; }
+
+  let surface;
+  try {
+    surface = await import("@kontourai/surface");
+  } catch (err) {
+    process.stderr.write(`derive-claim-status: @kontourai/surface unavailable: ${err && err.message ? err.message : String(err)}\n`);
+    return 2;
+  }
+  const { deriveClaimStatus } = surface;
+  if (typeof deriveClaimStatus !== "function") {
+    process.stderr.write("derive-claim-status: @kontourai/surface deriveClaimStatus missing\n");
+    return 2;
+  }
+
+  let bundle;
+  try {
+    bundle = JSON.parse(readFileSync(bundlePath, "utf8"));
+  } catch (err) {
+    process.stderr.write(`derive-claim-status: cannot read bundle: ${err && err.message ? err.message : String(err)}\n`);
+    return 3;
+  }
+
+  const claims = Array.isArray(bundle.claims) ? bundle.claims : [];
+  const allEvidence = Array.isArray(bundle.evidence) ? bundle.evidence : [];
+  const allEvents = Array.isArray(bundle.events) ? bundle.events : [];
+  const allPolicies = Array.isArray(bundle.policies) ? bundle.policies : [];
+
+  const out = {};
+  for (const claim of claims) {
+    if (!claim || !claim.id) continue;
+    // Filter evidence by claimId (deriveTrustStatus does NOT filter evidence internally — it
+    // only filters events — so passing the whole array would let another claim's evidence
+    // type/blocking-failure bleed in). Events are filtered internally by claimId; policies are
+    // resolved per-claim via verificationPolicyId. This mirrors the producer's per-claim call.
+    const evidence = allEvidence.filter((e) => e && e.claimId === claim.id);
+    try {
+      const { status } = deriveClaimStatus({ claim, evidence, events: allEvents, policies: allPolicies });
+      out[claim.id] = status;
+    } catch {
+      out[claim.id] = null;
+    }
+  }
+
+  process.stdout.write(JSON.stringify(out));
+  return 0;
+}
+
+main().then((code) => process.exit(code)).catch((err) => {
+  process.stderr.write(`derive-claim-status: ${err && err.message ? err.message : String(err)}\n`);
+  process.exit(2);
+});