@kontourai/flow-agents 3.0.0 → 3.1.0

package/kits/knowledge/providers/neo4j/sync.js

@@ -0,0 +1,235 @@
+/**
+ * Sync / materialize: import the file/work-item providers into Neo4j.
+ *
+ * The file stores remain the SOURCE OF TRUTH; the graph is a queryable
+ * materialized view. Sync reuses the #317 providers as READERS (no forked
+ * extractors) and MERGEs their combined graph into Neo4j with MERGE semantics,
+ * so a re-sync of unchanged data reports zero writes (AC1). A snapshot digest +
+ * timestamp is recorded on the graph so the second run can short-circuit and so
+ * the graph is point-in-time attributable.
+ *
+ * Marker tolerance (spike finding 3: 3/19 metadata markers failed JSON.parse in
+ * the wild): a provider that throws while reading MUST NOT kill the whole sync.
+ * Each provider is read behind a guard that falls back to an empty contribution
+ * and records the error; the work-item provider already falls back from a
+ * malformed metadata marker to prose refs, and this guard covers the rest.
+ *
+ * Pure planning (planSync/computeDigest) is separated from IO (syncToNeo4j) so
+ * idempotency is unit-testable with no driver and no Docker.
+ *
+ * @module providers/neo4j/sync
+ */
+
+import { createHash } from "node:crypto";
+import {
+  typeToLabel,
+  edgeTypeToRel,
+  nodeToProps,
+  edgeToProps,
+  SNAPSHOT_LABEL,
+  SNAPSHOT_ID,
+  READ_SNAPSHOT_CYPHER,
+} from "./cypher.js";
+
+/** Deterministic JSON (sorted keys) for hashing. */
+function canonical(value) {
+  if (Array.isArray(value)) return `[${value.map(canonical).join(",")}]`;
+  if (value && typeof value === "object") {
+    return `{${Object.keys(value)
+      .sort()
+      .map((k) => `${JSON.stringify(k)}:${canonical(value[k])}`)
+      .join(",")}}`;
+  }
+  return JSON.stringify(value);
+}
+
+/**
+ * The graph is a materialized view keyed on CONTENT, not on when it was read.
+ * Provenance carries volatile fields (retrieved_at, agent) that change every
+ * read — including them would defeat idempotency (a re-sync of unchanged stores
+ * would rewrite every element). Strip them for identity; the snapshot's
+ * synced_at records the point-in-time separately.
+ */
+function contentIdentity(el) {
+  const clone = JSON.parse(JSON.stringify(el));
+  if (clone.provenance) {
+    delete clone.provenance.retrieved_at;
+    delete clone.provenance.agent;
+  }
+  return clone;
+}
+
+/** Content hash of a single node/edge (drives the idempotent hash-guarded SET). */
+export function hashElement(el) {
+  return createHash("sha256").update(canonical(contentIdentity(el))).digest("hex").slice(0, 16);
+}
+
+/** Digest of the whole materialized graph (drives the zero-write short-circuit). */
+export function computeDigest(graph) {
+  const nodes = [...(graph.nodes || [])].map(contentIdentity).sort((a, b) => a.id.localeCompare(b.id));
+  const edges = [...(graph.edges || [])].map(contentIdentity).sort((a, b) => a.id.localeCompare(b.id));
+  return createHash("sha256").update(canonical({ nodes, edges })).digest("hex");
+}
+
+/** Read one provider's graph behind a guard; never let one provider kill sync. */
+async function safeReadGraph(provider, errors) {
+  try {
+    const g = await provider.readGraph();
+    return { nodes: g.nodes || [], edges: g.edges || [] };
+  } catch (err) {
+    errors.push({ provider: provider?.id || provider?.constructor?.name || "unknown", error: String(err && err.message || err) });
+    return { nodes: [], edges: [] };
+  }
+}
+
+/**
+ * Materialize the combined graph from the provider readers. Dedupes nodes and
+ * edges by id (last write wins on id collision across providers).
+ * @param {object[]} providers  #317 provider instances (vault, git-repo, work-item, …)
+ * @returns {Promise<{ nodes:object[], edges:object[], errors:object[] }>}
+ */
+export async function materializeGraph(providers) {
+  const errors = [];
+  const nodeById = new Map();
+  const edgeById = new Map();
+  for (const provider of providers) {
+    const { nodes, edges } = await safeReadGraph(provider, errors);
+    for (const n of nodes) nodeById.set(n.id, n);
+    for (const e of edges) edgeById.set(e.id, e);
+  }
+  return { nodes: [...nodeById.values()], edges: [...edgeById.values()], errors };
+}
+
+/**
+ * Pure sync plan. Given the materialized graph and the prior snapshot digest,
+ * decide whether anything changed and produce the parameterized MERGE
+ * statements. When the digest is unchanged, the plan is a no-op (AC1: second run
+ * reports zero writes) unless `force` is set.
+ *
+ * @param {{nodes:object[],edges:object[]}} graph
+ * @param {string|null} priorDigest
+ * @param {object} [options]
+ * @param {boolean} [options.force=false] emit statements even when unchanged
+ * @returns {{ digest:string, unchanged:boolean, statements:{cypher:string,params:object}[] }}
+ */
+export function planSync(graph, priorDigest, options = {}) {
+  const digest = computeDigest(graph);
+  const unchanged = digest === priorDigest;
+  if (unchanged && !options.force) {
+    return { digest, unchanged, statements: [] };
+  }
+
+  const statements = [];
+
+  // Nodes grouped by contract type -> one MERGE per Neo4j label. Hash-guarded
+  // SET so an unchanged node produces zero propertiesSet on re-run.
+  const nodesByLabel = new Map();
+  for (const n of graph.nodes || []) {
+    const label = typeToLabel(n.type);
+    if (!nodesByLabel.has(label)) nodesByLabel.set(label, []);
+    nodesByLabel.get(label).push(nodeToProps(n, hashElement(n)));
+  }
+  for (const [label, rows] of nodesByLabel) {
+    statements.push({
+      cypher: `UNWIND $rows AS r MERGE (n:${label} {id:r.id}) WITH n, r WHERE coalesce(n._kg_hash,'') <> r._kg_hash SET n += r`,
+      params: { rows },
+    });
+  }
+
+  // Edges grouped by rel type. Endpoints matched by id regardless of label
+  // (spike: polyglot property bags "just work"); edges to a not-yet-synced node
+  // are skipped by the MATCH (external/dangling refs stay out of the view).
+  const edgesByRel = new Map();
+  for (const e of graph.edges || []) {
+    const rel = edgeTypeToRel(e.type);
+    if (!edgesByRel.has(rel)) edgesByRel.set(rel, []);
+    edgesByRel.get(rel).push(edgeToProps(e, hashElement(e)));
+  }
+  for (const [rel, rows] of edgesByRel) {
+    statements.push({
+      cypher: `UNWIND $rows AS r MATCH (a {id:r.from}) MATCH (b {id:r.to}) MERGE (a)-[x:${rel} {id:r.id}]->(b) WITH x, r WHERE coalesce(x._kg_hash,'') <> r._kg_hash SET x += r`,
+      params: { rows },
+    });
+  }
+
+  return { digest, unchanged, statements };
+}
+
+/** Read the prior snapshot digest from Neo4j (null if never synced). */
+async function readPriorDigest(session) {
+  const res = await session.run(READ_SNAPSHOT_CYPHER, { id: SNAPSHOT_ID });
+  const rec = res.records && res.records[0];
+  if (!rec) return null;
+  const props = rec.get("props");
+  return (props && props.digest) || null;
+}
+
+function sumWrites(counters) {
+  const u = typeof counters.updates === "function" ? counters.updates() : counters;
+  return (u.nodesCreated || 0) + (u.relationshipsCreated || 0) + (u.propertiesSet || 0);
+}
+
+/**
+ * Materialize the providers and MERGE them into Neo4j idempotently.
+ *
+ * @param {object} options
+ * @param {object} options.driver          neo4j driver (or the injected fake)
+ * @param {string} [options.database]
+ * @param {object[]} [options.providers]   #317 providers to read (or pass graph)
+ * @param {{nodes,edges}} [options.graph]  a pre-materialized graph (skips readers)
+ * @param {boolean} [options.force=false]  re-run MERGEs even if the digest matches
+ * @returns {Promise<{ writes:number, unchanged:boolean, digest:string, nodes:number, edges:number, snapshot:object, errors:object[] }>}
+ */
+export async function syncToNeo4j(options = {}) {
+  const { driver, database, force = false } = options;
+  let errors = [];
+  let graph = options.graph;
+  if (!graph) {
+    const mat = await materializeGraph(options.providers || []);
+    graph = { nodes: mat.nodes, edges: mat.edges };
+    errors = mat.errors;
+  }
+
+  const session = driver.session(database ? { database } : undefined);
+  try {
+    const priorDigest = await readPriorDigest(session);
+    const plan = planSync(graph, priorDigest, { force });
+
+    if (plan.unchanged && !force) {
+      return {
+        writes: 0,
+        unchanged: true,
+        digest: plan.digest,
+        nodes: graph.nodes.length,
+        edges: graph.edges.length,
+        snapshot: { digest: plan.digest },
+        errors,
+      };
+    }
+
+    let writes = 0;
+    for (const stmt of plan.statements) {
+      const res = await session.run(stmt.cypher, stmt.params);
+      writes += sumWrites(res.summary.counters);
+    }
+
+    const syncedAt = new Date().toISOString();
+    const snapRes = await session.run(
+      `MERGE (s:${SNAPSHOT_LABEL} {id:$id}) WITH s, $digest AS d WHERE coalesce(s.digest,'') <> d SET s.digest = d, s.synced_at = $syncedAt, s.node_count = $nc, s.edge_count = $ec`,
+      { id: SNAPSHOT_ID, digest: plan.digest, syncedAt, nc: graph.nodes.length, ec: graph.edges.length },
+    );
+    writes += sumWrites(snapRes.summary.counters);
+
+    return {
+      writes,
+      unchanged: plan.unchanged,
+      digest: plan.digest,
+      nodes: graph.nodes.length,
+      edges: graph.edges.length,
+      snapshot: { digest: plan.digest, synced_at: syncedAt },
+      errors,
+    };
+  } finally {
+    await session.close();
+  }
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@kontourai/flow-agents",
-  "version": "3.0.0",
+  "version": "3.1.0",
   "description": "Flow Agents — a Kontour product that applies Flow and Veritas discipline as a portable process layer inside the agent tools you already use: Claude Code, Codex, Kiro, opencode, pi, and GitHub Actions — with framework adapters (AWS Strands preview) on the same policy-engine contract.",
   "keywords": [
     "agents",
@@ -139,6 +139,7 @@
     "check:content-boundary": "node scripts/check-content-boundary.cjs",
     "check:decisions": "node scripts/check-decisions.cjs check",
     "gen:decisions-index": "node scripts/check-decisions.cjs gen-index",
+    "freeze:adrs": "node scripts/freeze-adrs.mjs",
     "prepack": "npm run build --silent && npm run validate:source --",
     "kit": "npm run build --silent && node build/src/cli.js kit"
   },
@@ -152,6 +153,7 @@
   },
   "optionalDependencies": {
     "@kontourai/surface": "^2.0.0",
-    "hachure": "^0.9.0"
+    "hachure": "^0.9.0",
+    "neo4j-driver": "^5.28.0"
   }
 }

package/scripts/README.md

@@ -70,6 +70,7 @@ renamed, or changes category, update the table and the validator together.
 | `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/current-pointer.js` | shared hook library | `evals/integration/test_current_json_per_actor.sh` | Shared per-actor "current" pointer reader/writer (`readCurrentPointer`, `writePerActorCurrent`) — the compat-shim fallback (per-actor `current/<actor>.json` first, legacy global `current.json` fallback) every actor-aware consumer routes through (issue #291). |
 | `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). |

package/scripts/freeze-adrs.mjs

@@ -0,0 +1,364 @@
+#!/usr/bin/env node
+// freeze-adrs.mjs — ADR freeze-and-index tooling for flow-agents.
+//
+// Freezes numbered ADRs under docs/adr/ as immutable history and seeds the
+// topic-keyed decision registry (docs/decisions/) with `needs-decision` stubs
+// that carry the frozen ADR(s) as provenance evidence.
+//
+// Origin & provenance: this is the portable, zero-runtime-dependency standalone
+// script (node >=22, ESM) piloted in kontourai/traverse per
+// https://github.com/kontourai/flow-agents/issues/314 and rolled out across the
+// portfolio (traverse#17, surface#115, flow#103, survey#108, and a fifth repo). This
+// copy is the flow-agents cutover (https://github.com/kontourai/flow-agents/issues/332),
+// the 6th application. It carries the two rollout fixes proven in the prior
+// applications (surface#115 / flow#103):
+//   FIX 1 (frontmatter-aware banner placement): every flow-agents ADR opens with
+//     a YAML frontmatter block (`---\ntitle: ...\n---`). The traverse-original
+//     always prepended the banner at byte 0, which would push the frontmatter
+//     off the literal first line. `insertBanner()` detects a leading frontmatter
+//     block and inserts the banner AFTER its closing `---` instead.
+//   FIX 2 (whole-phrase lowercasing for Title Case terms): the traverse-original
+//     `defaultStubBody` only lowercased the first character of a subject when
+//     used mid-sentence, which read fine for traverse's sentence-case subjects
+//     but produced "trust Bundle" for Title Case glossary terms. `lowerPhrase()`
+//     lowercases every simple Title Case word (^[A-Z][a-z]+$) while preserving
+//     acronyms (MCP), CamelCase (TypeScript-first), and symbol tokens (`/`) —
+//     the flow-agents vocabulary contains all three.
+//
+// It does NOT vendor a copy of the registry validator or schema: flow-agents is
+// the source of truth for both (scripts/check-decisions.cjs,
+// schemas/decision-record.schema.json, wired as `npm run check:decisions` /
+// `npm run gen:decisions-index` per #316). This script points at the existing
+// validator to regenerate docs/decisions/index.md.
+//
+// Behavior (idempotent, content-preserving):
+//   1. For each docs/adr/NNNN-*.md: insert a frozen banner as the ONLY body
+//      change (after any leading YAML frontmatter). Skipped if already present.
+//   2. Generate docs/adr/index.md deterministically. A second run is diff-clean.
+//   3. For each SUBJECT_GROUPS entry, create/update a `status: needs-decision`
+//      topic stub in docs/decisions/<slug>.md whose evidence[] links the frozen
+//      ADR(s). Existing stub frontmatter (status/decided) is preserved across
+//      reruns; only missing evidence entries are appended.
+//
+// Usage:  node scripts/freeze-adrs.mjs   (npm run freeze:adrs)
+
+import fs from "node:fs";
+import path from "node:path";
+import { fileURLToPath } from "node:url";
+import { execFileSync } from "node:child_process";
+
+const __dirname = path.dirname(fileURLToPath(import.meta.url));
+const ROOT = path.resolve(__dirname, "..");
+const ADR_DIR = path.join(ROOT, "docs", "adr");
+const ADR_INDEX_PATH = path.join(ADR_DIR, "index.md");
+const DECISIONS_DIR = path.join(ROOT, "docs", "decisions");
+
+const FROZEN_BANNER_MARKER = "FROZEN — immutable history.";
+const FROZEN_BANNER =
+  "> **FROZEN — immutable history.** Superseding/current decisions live in " +
+  "[`docs/decisions/`](../decisions/index.md). Do not edit.\n\n";
+
+// --- Subject grouping (flow-agents-specific, reviewed by hand) --------------
+//
+// Each ADR's decision subject is a NOUN drawn from (or added to) CONTEXT.md's
+// domain vocabulary, per context/contracts/decision-registry-contract.md's slug
+// rule. Multiple ADRs answering the same subject share one stub with multiple
+// evidence refs (contract: "one file per decision SUBJECT"). Groups reference
+// explicit ADR *filenames* (not numbers) because 0007 has two files sharing the
+// number (0007-flow-skill-kit-tool-boundary.md and 0007-skill-audit.md), which a
+// number-keyed map would collide.
+//
+// The four existing living topics (decision-records, promotion-gate,
+// knowledge-store-provider, standing-directives) are NOT touched: none of the
+// 22 numbered ADRs is about those subjects, so there is no evidence-merge case
+// here — every frozen ADR subject gets a fresh needs-decision stub.
+const SUBJECT_GROUPS = [
+  { slug: "workflow-enforcement", subject: "Workflow Enforcement", adrFiles: ["0001-flow-agents-consumes-flow.md"] },
+  { slug: "flow-kit", subject: "Flow Kit", adrFiles: ["0002-flow-kits-as-extension-unit.md", "0003-flow-agents-coordinates-kits-and-adapters.md"] },
+  { slug: "workflow-trust-state", subject: "Workflow trust state", adrFiles: ["0004-gates-expect-surface-claims.md", "0010-workflow-trust-state-as-hachure-bundle.md"] },
+  { slug: "kontour-resource-contract", subject: "Kontour Resource Contract", adrFiles: ["0005-kubernetes-inspired-resource-contracts.md"] },
+  { slug: "typescript-source-policy", subject: "TypeScript-first source policy", adrFiles: ["0006-typescript-first-source-policy.md"] },
+  { slug: "flow-skill-kit-tool-boundary", subject: "Flow / Skill / Kit / Tool boundary", adrFiles: ["0007-flow-skill-kit-tool-boundary.md", "0007-skill-audit.md"] },
+  { slug: "kit-operation-boundary", subject: "Kit operation boundary", adrFiles: ["0008-kit-operation-boundary.md"] },
+  { slug: "hook-core-kit-boundary", subject: "Hook core/kit boundary", adrFiles: ["0009-canonical-hook-core-kit-boundary.md"] },
+  { slug: "mcp-posture", subject: "MCP posture", adrFiles: ["0011-mcp-posture.md"] },
+  { slug: "agent-coordination", subject: "Agent coordination", adrFiles: ["0012-agent-coordination-as-liveness-claims.md", "0021-assignment-leases-and-stale-claim-takeover.md"] },
+  { slug: "context-lifecycle", subject: "Context lifecycle", adrFiles: ["0013-context-lifecycle.md"] },
+  { slug: "core-domain-kit-boundary", subject: "Core vs domain kit boundary", adrFiles: ["0014-core-vs-domain-kit-boundary.md"] },
+  { slug: "flow-flow-agents-boundary", subject: "Flow / Flow Agents boundary", adrFiles: ["0015-flow-flow-agents-boundary-reconciliation.md"] },
+  { slug: "three-hard-boundary-model", subject: "Three-hard-boundary model", adrFiles: ["0016-three-hard-boundary-model.md"] },
+  { slug: "anti-gaming-trust-security", subject: "Anti-gaming trust security", adrFiles: ["0017-anti-gaming-trust-security-model.md", "0018-freeze-local-shell-heuristics.md"] },
+  { slug: "kit-dependency-ownership", subject: "Kit dependency ownership", adrFiles: ["0019-kit-dependency-ownership.md"] },
+  { slug: "trust-reconcile", subject: "Trust-reconcile and delivery reconciliation", adrFiles: ["0020-trust-reconcile-manifest-and-claim-classification.md", "0022-fail-closed-delivery-reconciliation-with-governed-exemptions.md"] },
+];
+
+function listAdrFiles() {
+  if (!fs.existsSync(ADR_DIR)) return [];
+  return fs
+    .readdirSync(ADR_DIR)
+    .filter((name) => /^\d{4}-.*\.md$/.test(name))
+    .sort();
+}
+
+function adrNumberFromFilename(name) {
+  return parseInt(name.slice(0, 4), 10);
+}
+
+// FIX 1: frontmatter-aware banner insertion. If the file opens with a YAML
+// frontmatter block, insert the banner immediately after its closing `---`
+// (and the blank line that follows), never before the frontmatter.
+function insertBanner(raw) {
+  if (raw.startsWith("---\n") || raw.startsWith("---\r\n")) {
+    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) {
+      // Skip a single blank line after the closing fence so the banner lands
+      // between the frontmatter and the first heading with clean spacing.
+      let insertAt = end + 1;
+      if (insertAt < lines.length && lines[insertAt].trim() === "") insertAt += 1;
+      const before = lines.slice(0, insertAt).join("\n");
+      const after = lines.slice(insertAt).join("\n");
+      return `${before}\n${FROZEN_BANNER}${after}`;
+    }
+  }
+  return FROZEN_BANNER + raw;
+}
+
+function freezeOne(file) {
+  const full = path.join(ADR_DIR, file);
+  const raw = fs.readFileSync(full, "utf8");
+  if (raw.includes(FROZEN_BANNER_MARKER)) {
+    return { file, changed: false, raw };
+  }
+  const frozen = insertBanner(raw);
+  fs.writeFileSync(full, frozen, "utf8");
+  return { file, changed: true, raw: frozen };
+}
+
+// Best-effort title/date extraction (index display only — never touches frozen
+// ADR content). Widened for flow-agents' header forms: `# ADR NNNN: Title`
+// headings and `Date:` / `**Date:**` / parenthesized `(YYYY-MM-DD)` date lines.
+function parseAdrMeta(file, raw) {
+  const number = adrNumberFromFilename(file);
+  const lines = raw.split(/\r?\n/);
+  let title = file;
+  for (const line of lines) {
+    const m = line.match(/^#\s+(.*)$/);
+    if (m) {
+      title = m[1].trim().replace(/^ADR\s+\d+\s*[:—-]\s*/, "");
+      break;
+    }
+  }
+  const dateMatch =
+    raw.match(/^\s*\*{0,2}Date:?\*{0,2}\s*(\d{4}-\d{2}-\d{2})/m) ||
+    raw.match(/\((\d{4}-\d{2}-\d{2})\)/);
+  const date = dateMatch ? dateMatch[1] : null;
+  return { number, file, title, date };
+}
+
+function renderAdrIndex(entries) {
+  const sorted = [...entries].sort((a, b) => (a.number - b.number) || a.file.localeCompare(b.file));
+  const lines = [];
+  lines.push("---");
+  lines.push("title: ADR Index");
+  lines.push("---");
+  lines.push("");
+  lines.push("# ADR Index");
+  lines.push("");
+  lines.push("Generated by `node scripts/freeze-adrs.mjs` (`npm run freeze:adrs`). Do not edit by hand.");
+  lines.push(
+    "Numbered ADRs below are FROZEN immutable history (see the banner on each " +
+      "file). Current and superseding decisions live in " +
+      "[docs/decisions/](../decisions/index.md); a frozen ADR's subject is " +
+      "carried forward there as a `needs-decision` stub or a ratified decision."
+  );
+  lines.push("");
+  lines.push("| Number | Title | Date | Link |");
+  lines.push("| --- | --- | --- | --- |");
+  for (const e of sorted) {
+    const num = String(e.number).padStart(4, "0");
+    const date = e.date || "unknown";
+    lines.push(`| ${num} | ${e.title} | ${date} | [${e.file}](./${e.file}) |`);
+  }
+  lines.push("");
+  return lines.join("\n");
+}
+
+function readExistingStub(slug) {
+  const full = path.join(DECISIONS_DIR, `${slug}.md`);
+  if (!fs.existsSync(full)) return null;
+  const raw = fs.readFileSync(full, "utf8");
+  const fmMatch = raw.match(/^---\n([\s\S]*?)\n---\n([\s\S]*)$/);
+  if (!fmMatch) return null;
+  const [, fmBlock, body] = fmMatch;
+  const statusMatch = fmBlock.match(/^status:\s*(.+)$/m);
+  const decidedMatch = fmBlock.match(/^decided:\s*(.+)$/m);
+  const evidence = [];
+  const evidenceBlockMatch = fmBlock.match(/^evidence:\n([\s\S]*?)(?:\n[a-z_]+:|$)/m);
+  if (evidenceBlockMatch) {
+    const itemRe = /-\s*kind:\s*(\S+)\n\s*ref:\s*(.+)/g;
+    let m;
+    while ((m = itemRe.exec(evidenceBlockMatch[1])) !== null) {
+      evidence.push({ kind: m[1].trim(), ref: m[2].trim() });
+    }
+  }
+  return {
+    status: statusMatch ? statusMatch[1].trim() : null,
+    decided: decidedMatch ? decidedMatch[1].trim() : null,
+    evidence,
+    body,
+  };
+}
+
+function evidenceKey(e) {
+  return `${e.kind}::${e.ref}`;
+}
+
+function renderStub({ subject, decided, evidence, body }) {
+  const lines = [];
+  lines.push("---");
+  lines.push("status: needs-decision");
+  lines.push(`subject: ${subject}`);
+  lines.push(`decided: ${decided}`);
+  lines.push("evidence:");
+  for (const e of evidence) {
+    lines.push(`  - kind: ${e.kind}`);
+    lines.push(`    ref: ${e.ref}`);
+  }
+  lines.push("---");
+  lines.push(body);
+  return lines.join("\n");
+}
+
+// FIX 2: whole-phrase lowercasing for Title Case terms, acronym/CamelCase-safe.
+function lowerPhrase(s) {
+  return s
+    .split(/(\s+)/)
+    .map((tok) => (/^[A-Z][a-z]+$/.test(tok) ? tok.toLowerCase() : tok))
+    .join("");
+}
+
+function defaultStubBody(subject, adrFiles) {
+  const adrLinks = adrFiles.map((f) => `[${f}](../adr/${f})`).join(", ");
+  return `
+# ${subject}
+
+This subject has provenance in frozen ADR history (${adrLinks}) but no living
+decision has been ratified yet under the topic-keyed decision registry
+(\`context/contracts/decision-registry-contract.md\`). This stub records that the
+subject is open and links the frozen ADR(s) as provenance; it is not a decision.
+
+When a living decision is ratified for ${lowerPhrase(subject)}, update this
+file's \`status\` to \`current\`, add rationale, and keep the \`adr\` evidence
+links as provenance for the history that led here.
+`.trimStart();
+}
+
+function todayIso() {
+  return new Date().toISOString().slice(0, 10);
+}
+
+function upsertStub(group) {
+  const adrFiles = group.adrFiles;
+  const desiredEvidence = [
+    ...adrFiles.map((f) => ({ kind: "adr", ref: `docs/adr/${f}` })),
+    ...(group.extraEvidence || []),
+  ];
+
+  const existing = readExistingStub(group.slug);
+  const decided = existing?.decided || todayIso();
+  const body = existing?.body || defaultStubBody(group.subject, adrFiles);
+
+  const mergedEvidence = [];
+  const seen = new Set();
+  const source = existing ? existing.evidence.concat(desiredEvidence) : desiredEvidence;
+  for (const e of source) {
+    const key = evidenceKey(e);
+    if (seen.has(key)) continue;
+    seen.add(key);
+    mergedEvidence.push(e);
+  }
+
+  const content = renderStub({ subject: group.subject, decided, evidence: mergedEvidence, body });
+
+  const full = path.join(DECISIONS_DIR, `${group.slug}.md`);
+  const priorRaw = fs.existsSync(full) ? fs.readFileSync(full, "utf8") : null;
+  if (priorRaw === content) {
+    return { slug: group.slug, changed: false };
+  }
+  fs.mkdirSync(DECISIONS_DIR, { recursive: true });
+  fs.writeFileSync(full, content, "utf8");
+  return { slug: group.slug, changed: true };
+}
+
+// Fail loudly if any numbered ADR file is unassigned or double-assigned, or a
+// group references a missing file — silent drop of an ADR is exactly the bug a
+// freeze must never ship.
+function assertCoverage(adrFilenames) {
+  const assigned = new Map();
+  for (const g of SUBJECT_GROUPS) {
+    for (const f of g.adrFiles) {
+      if (assigned.has(f)) {
+        throw new Error(`ADR ${f} is assigned to two groups (${assigned.get(f)} and ${g.slug})`);
+      }
+      assigned.set(f, g.slug);
+      if (!adrFilenames.includes(f)) {
+        throw new Error(`group ${g.slug} references missing ADR file ${f}`);
+      }
+    }
+  }
+  const unassigned = adrFilenames.filter((f) => !assigned.has(f));
+  if (unassigned.length > 0) {
+    throw new Error(`ADR file(s) not assigned to any subject group: ${unassigned.join(", ")}`);
+  }
+}
+
+function main() {
+  const adrFilenames = listAdrFiles();
+  if (adrFilenames.length === 0) {
+    console.log("No docs/adr/NNNN-*.md files found; nothing to freeze.");
+    return 0;
+  }
+
+  assertCoverage(adrFilenames);
+
+  const frozen = adrFilenames.map(freezeOne);
+  const bannerChanged = frozen.filter((f) => f.changed);
+  for (const f of bannerChanged) {
+    console.log(`Froze ${path.relative(ROOT, path.join(ADR_DIR, f.file))} (banner inserted).`);
+  }
+
+  const meta = frozen.map((f) => parseAdrMeta(f.file, f.raw));
+  const adrIndexContent = renderAdrIndex(meta);
+  const priorIndex = fs.existsSync(ADR_INDEX_PATH) ? fs.readFileSync(ADR_INDEX_PATH, "utf8") : null;
+  if (priorIndex !== adrIndexContent) {
+    fs.writeFileSync(ADR_INDEX_PATH, adrIndexContent, "utf8");
+    console.log(`Wrote ${path.relative(ROOT, ADR_INDEX_PATH)}.`);
+  }
+
+  const stubResults = SUBJECT_GROUPS.map((g) => upsertStub(g));
+  for (const r of stubResults.filter((r) => r.changed)) {
+    console.log(`Wrote docs/decisions/${r.slug}.md (needs-decision stub).`);
+  }
+
+  // Chain the existing (not vendored) registry index generator so a single
+  // `npm run freeze:adrs` leaves docs/decisions/index.md current too.
+  const checkDecisions = path.join(ROOT, "scripts", "check-decisions.cjs");
+  if (fs.existsSync(checkDecisions)) {
+    execFileSync(process.execPath, [checkDecisions, "gen-index"], { cwd: ROOT, stdio: "inherit" });
+  }
+
+  const anyChange =
+    bannerChanged.length > 0 ||
+    priorIndex !== adrIndexContent ||
+    stubResults.some((r) => r.changed);
+  console.log(
+    anyChange ? "freeze-adrs: changes written." : "freeze-adrs: no-op (already frozen and current)."
+  );
+  return 0;
+}
+
+process.exit(main());

package/scripts/hooks/config-protection.js

@@ -131,6 +131,18 @@ function checkProtectedPathPattern(filePath) {
     };
   }
 
+  // .kontourai/flow-agents/current/<actor>.json (#291) — the per-actor projection of the same
+  // pointer above. An agent could forge active_flow_id/active_step_id here exactly as it could
+  // via the legacy global file, so this is protected identically (same reason text).
+  // SAFE: the workflow CLI writes this via writePerActorCurrent → fs.writeFileSync,
+  // NOT via the Write/Edit tool — blocking the tool path does not break legit sidecar.
+  if (/(?:^|\/)(?:\.kontourai\/flow-agents|\.flow-agents)\/current\/[^/]+\.json$/.test(norm)) {
+    return {
+      name: '.kontourai/flow-agents/current/<actor>.json',
+      reason: 'an agent could forge active_flow_id/active_step_id to route the gate to a permissive FlowDefinition',
+    };
+  }
+
   // .kontourai/flow-agents/.goal-fit-block-streak.json controls soft-block
   // release counting. An agent could force early advisory-gate release by
   // writing a high count.
@@ -403,12 +415,13 @@ function checkCommandForBypass(command) {
  * Regex that matches a normalized (forward-slash) path ending with a protected
  * kill-switch file: shell profiles, .claude/settings*.json,
  * .kontourai/flow-agents/current.json,
+ * .kontourai/flow-agents/current/<actor>.json (#291 per-actor projection),
  * .kontourai/flow-agents/.goal-fit-block-streak.json,
  * .kontourai/flow-agents/<slug>/state.json,
  * .kontourai/flow-agents/<slug>/trust.bundle, and deprecated runtime-shaped
  * .flow-agents equivalents.
  */
-const REDIRECT_PROTECTED_RE = /(?:^|\/|~\/)(\.bash_profile|\.bashrc|\.profile|\.zprofile|\.zshrc)$|(?:^|\/)\.claude\/settings(?:\.local)?\.json$|(?:^|\/)(?:\.kontourai\/flow-agents|\.flow-agents)\/current\.json$|(?:^|\/)(?:\.kontourai\/flow-agents|\.flow-agents)\/\.goal-fit-block-streak\.json$|(?:^|\/)(?:\.kontourai\/flow-agents|\.flow-agents)\/[^/]+\/state\.json$|(?:^|\/)(?:\.kontourai\/flow-agents|\.flow-agents)\/[^/]+\/trust\.bundle$|(?:^|\/)delivery\/trust\.bundle$|(?:^|\/)delivery\/trust\.checkpoint\.json$/;
+const REDIRECT_PROTECTED_RE = /(?:^|\/|~\/)(\.bash_profile|\.bashrc|\.profile|\.zprofile|\.zshrc)$|(?:^|\/)\.claude\/settings(?:\.local)?\.json$|(?:^|\/)(?:\.kontourai\/flow-agents|\.flow-agents)\/current\.json$|(?:^|\/)(?:\.kontourai\/flow-agents|\.flow-agents)\/current\/[^/]+\.json$|(?:^|\/)(?:\.kontourai\/flow-agents|\.flow-agents)\/\.goal-fit-block-streak\.json$|(?:^|\/)(?:\.kontourai\/flow-agents|\.flow-agents)\/[^/]+\/state\.json$|(?:^|\/)(?:\.kontourai\/flow-agents|\.flow-agents)\/[^/]+\/trust\.bundle$|(?:^|\/)delivery\/trust\.bundle$|(?:^|\/)delivery\/trust\.checkpoint\.json$/;
 
 /**
  * Return true when a token (an unquoted redirect target or tee argument) matches