@kontourai/flow-agents 3.0.0 → 3.1.0

package/kits/knowledge/promote/ingest.js

@@ -0,0 +1,103 @@
+/**
+ * Step 1 — INGEST.
+ *
+ * Read a completed session directory (read-only) and collect its durable
+ * residue: the plan / Definition Of Done, verification evidence, review
+ * critique, learning records, and delegate transcripts. Ingest never mutates
+ * the session and never reads outside `sessionDir`.
+ *
+ * @module promote/ingest
+ */
+
+import * as fs from "node:fs";
+import * as path from "node:path";
+import { readIfExists, markdownSection, parseDecisionList } from "./lib.js";
+
+function readJson(file) {
+  const raw = readIfExists(file);
+  if (!raw) return null;
+  try { return JSON.parse(raw); } catch { return null; }
+}
+
+function findSessionMarkdown(sessionDir, slug) {
+  // Prefer the deliver session file, then plan-work, then any <slug>--*.md.
+  const preferred = [`${slug}--deliver.md`, `${slug}--plan-work.md`];
+  for (const name of preferred) {
+    const p = path.join(sessionDir, name);
+    if (fs.existsSync(p)) return p;
+  }
+  let names = [];
+  try { names = fs.readdirSync(sessionDir); } catch { return null; }
+  const md = names.find((n) => n.endsWith(".md") && n.startsWith(`${slug}--`)) || names.find((n) => n.endsWith(".md"));
+  return md ? path.join(sessionDir, md) : null;
+}
+
+function collectTranscriptRefs(sessionDir) {
+  const agentsDir = path.join(sessionDir, "agents");
+  const refs = [];
+  let agents = [];
+  try { agents = fs.readdirSync(agentsDir); } catch { return refs; }
+  for (const agent of agents) {
+    const events = path.join(agentsDir, agent, "events.jsonl");
+    if (fs.existsSync(events)) refs.push(path.join("agents", agent, "events.jsonl"));
+  }
+  return refs.sort();
+}
+
+/**
+ * @param {string} sessionDir absolute path to a completed session directory.
+ * @param {object} [options]
+ * @param {string} [options.slug] override the derived slug.
+ * @returns residue object consumed by distill/link/health.
+ */
+export function ingestSession(sessionDir, options = {}) {
+  if (!sessionDir || !fs.existsSync(sessionDir)) {
+    throw new Error(`ingestSession: session directory not found: ${sessionDir}`);
+  }
+  const state = readJson(path.join(sessionDir, "state.json")) || {};
+  const slug = options.slug || state.task_slug || path.basename(sessionDir);
+  const repo = state.repo || null;
+
+  const mdPath = findSessionMarkdown(sessionDir, slug);
+  const md = mdPath ? readIfExists(mdPath) : "";
+  const planSummary = markdownSection(md, "Plan");
+  const definitionOfDone = markdownSection(md, "Definition Of Done");
+  const decisionsSection = markdownSection(md, "Decisions");
+
+  const learning = readJson(path.join(sessionDir, "learning.json")) || {};
+  const learnings = Array.isArray(learning.records) ? learning.records : [];
+
+  const acceptance = readJson(path.join(sessionDir, "acceptance.json"));
+  const critique = readJson(path.join(sessionDir, "critique.json"));
+
+  // Structured decisions: explicit `## Decisions` list first, else derive one
+  // durable decision from the Definition Of Done outcome so a delivered session
+  // always yields at least one candidate delta (the operator refines the draft).
+  let decisions = parseDecisionList(decisionsSection);
+  if (decisions.length === 0 && definitionOfDone) {
+    const outcome = definitionOfDone.match(/User outcome:\*\*\s*(.+?)\s*$/im);
+    if (outcome) decisions = [{ subject: null, body: outcome[1].trim(), derived: true }];
+  }
+
+  const touchedFiles = new Set();
+  for (const rec of learnings) {
+    for (const ref of Array.isArray(rec.source_refs) ? rec.source_refs : []) touchedFiles.add(ref);
+  }
+
+  return {
+    sessionDir,
+    sessionMarkdown: mdPath ? path.basename(mdPath) : null,
+    slug,
+    repo,
+    status: state.status || null,
+    phase: state.phase || null,
+    planSummary,
+    definitionOfDone,
+    decisions,
+    learnings,
+    evidence: acceptance || (fs.existsSync(path.join(sessionDir, "trust.bundle")) ? { source: "trust.bundle" } : null),
+    critiqueSummary: critique && (critique.summary || critique.status) ? { status: critique.status, summary: critique.summary } : null,
+    transcriptRefs: collectTranscriptRefs(sessionDir),
+    touchedFiles: [...touchedFiles].sort(),
+  };
+}

package/kits/knowledge/promote/lib.js

@@ -0,0 +1,132 @@
+/**
+ * Shared helpers for the knowledge promote sub-flow.
+ *
+ * Zero external dependencies (mirrors scripts/check-decisions.cjs and
+ * providers/lib/schema-validate.js) so the sub-flow runs in any node:test lane.
+ *
+ * @module promote/lib
+ */
+
+import * as fs from "node:fs";
+import * as path from "node:path";
+
+/** Read a file, returning "" when it is absent (ingest is tolerant of shape). */
+export function readIfExists(file) {
+  try {
+    return fs.readFileSync(file, "utf8");
+  } catch {
+    return "";
+  }
+}
+
+/** kebab-case slug from a subject noun phrase (matches the registry slug rule). */
+export function slugify(text) {
+  return String(text || "")
+    .toLowerCase()
+    .replace(/[^a-z0-9]+/g, "-")
+    .replace(/^-+|-+$/g, "");
+}
+
+/**
+ * Extract the body of a `## <Heading>` section from a markdown session file.
+ * Returns the lines between the heading and the next `## ` heading.
+ */
+export function markdownSection(md, heading) {
+  const lines = String(md || "").split(/\r?\n/);
+  const out = [];
+  let inSection = false;
+  for (const line of lines) {
+    if (/^##\s+/.test(line)) {
+      inSection = new RegExp(`^##\\s+${heading}\\s*$`, "i").test(line);
+      continue;
+    }
+    if (inSection) out.push(line);
+  }
+  return out.join("\n").trim();
+}
+
+/**
+ * Parse `## Decisions` list items of the form:
+ *   - **Subject noun** — the current decision body.
+ * Returns [{ subject, body }]. Tolerant of `-` or `*` bullets and `—`/`-` dashes.
+ */
+export function parseDecisionList(sectionText) {
+  const items = [];
+  for (const raw of String(sectionText || "").split(/\r?\n/)) {
+    const m = raw.match(/^\s*[-*]\s+\*\*(.+?)\*\*\s*[—-]\s*(.+?)\s*$/);
+    if (m) items.push({ subject: m[1].trim(), body: m[2].trim() });
+  }
+  return items;
+}
+
+/** Read the `## Glossary` term set from a repo CONTEXT.md (lowercased term names). */
+export function readGlossaryTerms(repoRoot) {
+  const text = readIfExists(path.join(repoRoot, "CONTEXT.md"));
+  const terms = new Set();
+  let inGlossary = false;
+  for (const line of text.split(/\r?\n/)) {
+    if (/^##\s+Glossary\s*$/.test(line)) { inGlossary = true; continue; }
+    if (/^##\s+/.test(line) && !/^##\s+Glossary/.test(line)) inGlossary = false;
+    if (!inGlossary) continue;
+    const h = line.match(/^###\s+(.+?)\s*$/);
+    if (h) terms.add(h[1].trim().toLowerCase());
+  }
+  return terms;
+}
+
+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}$/;
+const SECRET_PATTERNS = [
+  /AKIA[A-Z0-9]{16}/,
+  /ASIA[A-Z0-9]{16}/,
+  /gh[pousr]_[A-Za-z0-9_]{36,}/,
+  /BEGIN[A-Z ]*PRIVATE KEY/,
+  /eyJ[A-Za-z0-9_-]{10,}\.eyJ[A-Za-z0-9_-]{10,}\.[A-Za-z0-9_-]{10,}/,
+  /(secret|password|token|api[_-]?key)\s*[:=]\s*["'][^"']{8,}/i,
+];
+
+/**
+ * Validate a draft decision delta against the decision-record contract (#310)
+ * BEFORE it is proposed. Mirrors schemas/decision-record.schema.json /
+ * scripts/check-decisions.cjs rules directly (zero-dep, same discipline).
+ * Returns a list of error strings; empty means schema-valid.
+ */
+export function validateDecisionDelta(delta) {
+  const errors = [];
+  const { subject, slug, decided, evidence, status = "current" } = delta;
+  if (!["current", "superseded", "merged", "needs-decision"].includes(status)) {
+    errors.push(`status '${status}' is not a valid decision-record status`);
+  }
+  if (typeof subject !== "string" || subject.trim() === "") errors.push("subject must be a non-empty noun phrase");
+  if (typeof slug !== "string" || !SLUG_RE.test(slug)) errors.push(`slug '${slug}' is not valid kebab-case`);
+  if (typeof decided !== "string" || !DATE_RE.test(decided)) errors.push(`decided '${decided}' must be an ISO date (YYYY-MM-DD)`);
+  if (!Array.isArray(evidence) || evidence.length === 0) {
+    errors.push("evidence must be a non-empty array of {kind, ref}");
+  } else {
+    evidence.forEach((e, i) => {
+      if (!e || typeof e !== "object") { errors.push(`evidence[${i}] must be an object`); return; }
+      if (!EVIDENCE_KINDS.includes(e.kind)) errors.push(`evidence[${i}].kind '${e.kind}' is not one of ${EVIDENCE_KINDS.join(", ")}`);
+      if (typeof e.ref !== "string" || e.ref.trim() === "") { errors.push(`evidence[${i}].ref must be a non-empty string`); return; }
+      if (SECRET_PATTERNS.some((re) => re.test(e.ref))) errors.push(`evidence[${i}].ref contains a secret-shaped literal; link durable provenance, never a credential`);
+    });
+  }
+  return errors;
+}
+
+/** Recursively hash every file under a directory into a {relpath: sha} map (for AC3 diff proof). */
+export function snapshotDir(dir) {
+  const out = {};
+  const walk = (d, rel) => {
+    let entries;
+    try { entries = fs.readdirSync(d, { withFileTypes: true }); } catch { return; }
+    for (const ent of entries) {
+      const abs = path.join(d, ent.name);
+      const r = rel ? `${rel}/${ent.name}` : ent.name;
+      if (ent.isDirectory()) walk(abs, r);
+      else out[r] = fs.readFileSync(abs, "utf8");
+    }
+  };
+  walk(dir, "");
+  return out;
+}

package/kits/knowledge/promote/link.js

@@ -0,0 +1,84 @@
+/**
+ * Step 3 — LINK.
+ *
+ * Attach provenance to every draft delta: the pull request, the merge commit
+ * SHA, the archived session artifact path, and the touched decision topics.
+ * The provenance links become evidence[] refs on the draft decision topics so a
+ * reader can trace each proposed delta back to the delivery that produced it.
+ *
+ * Rendering the decision topic is delegated to the #317 git-repo provider's
+ * proposeWrite (proposals-only, never writes) so the sub-flow reuses the same
+ * decision-topic renderer the provider contract defines — no forked writer.
+ *
+ * @module promote/link
+ */
+
+import { GitRepoProvider } from "../providers/git-repo/index.js";
+import { validateDecisionDelta } from "./lib.js";
+import { loadSchemas } from "../providers/lib/model.js";
+import { assertValid } from "../providers/lib/schema-validate.js";
+
+const { proposal: PROPOSAL_SCHEMA } = loadSchemas();
+
+/**
+ * @param {{decisions:object[], vocabulary:object[], learnings:object[]}} distilled
+ * @param {object} provenance
+ * @param {string} [provenance.pr]                 PR URL/number.
+ * @param {string} [provenance.mergeSha]           merge commit SHA.
+ * @param {string} [provenance.sessionArchivePath] path to the archived session artifact.
+ * @param {object} [options]
+ * @param {string} [options.repoRoot]              repo root for the git-repo provider.
+ * @param {string} [options.agent]
+ * @returns {{decisions:object[], vocabulary:object[], learnings:object[], manifest:object}}
+ */
+export function link(distilled, provenance = {}, options = {}) {
+  const provider = new GitRepoProvider({ repoRoot: options.repoRoot || process.cwd(), agent: options.agent });
+  const touchedTopics = distilled.decisions.map((d) => d.slug);
+
+  const provEvidence = [];
+  if (provenance.pr) provEvidence.push({ kind: "pr", ref: provenance.pr });
+  if (provenance.mergeSha) provEvidence.push({ kind: "commit", ref: provenance.mergeSha });
+  if (provenance.sessionArchivePath) provEvidence.push({ kind: "session-archive", ref: provenance.sessionArchivePath });
+
+  const decisions = distilled.decisions.map((delta) => {
+    // Fold provenance links into evidence[], de-duplicated by kind+ref.
+    const seen = new Set(delta.evidence.map((e) => `${e.kind}:${e.ref}`));
+    const evidence = [...delta.evidence];
+    for (const e of provEvidence) {
+      const key = `${e.kind}:${e.ref}`;
+      if (!seen.has(key)) { evidence.push(e); seen.add(key); }
+    }
+    const linked = { ...delta, evidence };
+
+    // Re-validate the linked delta before proposing (R2 discipline holds after linking too).
+    const errors = validateDecisionDelta(linked);
+    if (errors.length) throw new Error(`linked decision draft '${linked.slug}' failed validation: ${errors.join("; ")}`);
+
+    // Render via the git-repo provider's proposals-only proposeWrite.
+    const rendered = provider.proposeWrite({
+      subject: linked.subject,
+      slug: linked.slug,
+      body: linked.body,
+      decided: linked.decided,
+      evidence: linked.evidence,
+      rationale: `Promoted from session ${linked.derived ? "(derived from Definition Of Done) " : ""}— enact by writing docs/decisions/${linked.slug}.md, adding the subject noun to CONTEXT.md, and running check:decisions.`,
+    });
+    // provider.proposeWrite is async in the contract; call synchronously-resolved value.
+    return Promise.resolve(rendered).then((prop) => {
+      assertValid(prop, PROPOSAL_SCHEMA, `decision-topic proposal '${linked.slug}'`);
+      return { ...linked, proposal: prop, rendered: prop.rendered };
+    });
+  });
+
+  return Promise.all(decisions).then((resolvedDecisions) => ({
+    decisions: resolvedDecisions,
+    vocabulary: distilled.vocabulary,
+    learnings: distilled.learnings,
+    manifest: {
+      pr: provenance.pr || null,
+      merge_sha: provenance.mergeSha || null,
+      session_archive: provenance.sessionArchivePath || null,
+      touched_topics: touchedTopics,
+    },
+  }));
+}

package/kits/knowledge/promote/promote.test.js

@@ -0,0 +1,174 @@
+/**
+ * Knowledge promote sub-flow — AC1..AC3 (issue #313).
+ *
+ *   AC1: running the sub-flow on a completed session dir emits >=1 schema-valid
+ *        draft decision delta with correct provenance links (R1, R2). The draft
+ *        is validated against #310's REAL registry validator
+ *        (scripts/check-decisions.cjs) as command evidence. The session fixture
+ *        is modeled faithfully on the real completed session
+ *        `.kontourai/flow-agents/kontourai-flow-agents-287` (actor-identity work,
+ *        status accepted) — a portable, committed copy so the lane is
+ *        deterministic and CI-runnable.
+ *   AC2: a fixture registry with a seeded contradiction (two CURRENT topics, one
+ *        subject noun, divergent content) yields a contradiction report naming
+ *        BOTH topics and a merge-repair proposal naming a merge target (R3).
+ *   AC3: a filesystem diff during a run shows zero writes outside the
+ *        session/proposal dir (R4).
+ *
+ * Run: node --test kits/knowledge/promote/promote.test.js
+ */
+
+import { test, describe } from "node:test";
+import assert from "node:assert/strict";
+import * as fs from "node:fs";
+import * as os from "node:os";
+import * as path from "node:path";
+import { execFileSync } from "node:child_process";
+import { fileURLToPath } from "node:url";
+
+import { runPromote, health } from "./index.js";
+import { snapshotDir } from "./lib.js";
+import { GitRepoProvider } from "../providers/git-repo/index.js";
+import { loadSchemas } from "../providers/lib/model.js";
+import { validate } from "../providers/lib/schema-validate.js";
+
+const __dirname = path.dirname(fileURLToPath(import.meta.url));
+const REPO_ROOT = path.resolve(__dirname, "../../..");
+const FIX = path.join(__dirname, "fixtures");
+const SESSION = path.join(FIX, "session");
+const CLEAN_REPO = path.join(FIX, "repo");
+const CONTRADICTION_REPO = path.join(FIX, "contradiction-registry");
+const CONFORMANCE_GIT = path.resolve(__dirname, "../providers/conformance/fixtures/git-repo");
+const { proposal: PROPOSAL_SCHEMA, healthReport: REPORT_SCHEMA } = loadSchemas();
+
+function tmpOut(tag) {
+  return fs.mkdtempSync(path.join(os.tmpdir(), `promote-${tag}-`));
+}
+
+const PROVENANCE = {
+  pr: "https://github.com/kontourai/flow-agents/pull/391",
+  mergeSha: "abc1234def5678",
+  sessionArchivePath: ".kontourai/flow-agents/kontourai-flow-agents-287/archive/kontourai-flow-agents-287--deliver.md",
+};
+
+describe("AC1: real completed session -> schema-valid draft delta with provenance", () => {
+  test("emits >=1 decision delta carrying PR + merge SHA + session-archive links", async () => {
+    const outDir = tmpOut("ac1");
+    const result = await runPromote({ sessionDir: SESSION, repoRoot: CLEAN_REPO, provenance: PROVENANCE, outDir });
+
+    assert.ok(result.decisions.length >= 1, "expected at least one draft decision delta");
+    const delta = result.decisions.find((d) => d.slug === "actor-identity") || result.decisions[0];
+    const kinds = new Set(delta.evidence.map((e) => e.kind));
+    assert.ok(kinds.has("pr"), "delta must link the PR");
+    assert.ok(kinds.has("commit"), "delta must link the merge SHA (commit)");
+    assert.ok(kinds.has("session-archive"), "delta must link the archived session artifact");
+    const prRef = delta.evidence.find((e) => e.kind === "pr").ref;
+    assert.equal(prRef, PROVENANCE.pr);
+
+    // The draft topic file was written under the proposals dir.
+    const draftFile = path.join(outDir, "decisions", `${delta.slug}.md`);
+    assert.ok(fs.existsSync(draftFile), "draft topic file written under proposals/decisions");
+
+    // Command evidence (R2): the REAL #310 validator accepts the drafts.
+    const decisionsDir = path.join(outDir, "decisions");
+    const env = { ...process.env, FLOW_AGENTS_DECISIONS_DIR: decisionsDir, FORCE_COLOR: "0" };
+    execFileSync("node", [path.join(REPO_ROOT, "scripts/check-decisions.cjs"), "gen-index"], { env, cwd: REPO_ROOT });
+    const checkOut = execFileSync("node", [path.join(REPO_ROOT, "scripts/check-decisions.cjs"), "check"], { env, cwd: REPO_ROOT, encoding: "utf8" });
+    assert.match(checkOut, /Decision registry check passed/, "drafts must pass the real #310 registry validator");
+
+    fs.rmSync(outDir, { recursive: true, force: true });
+  });
+
+  test("ingests plan, learnings, and transcripts from the session", async () => {
+    const result = await runPromote({ sessionDir: SESSION, repoRoot: CLEAN_REPO, provenance: PROVENANCE, write: false });
+    assert.ok(result.learnings.length >= 1, "expected learning deltas from learning.json");
+    assert.ok(result.ingested.transcript_refs.length >= 1, "expected delegate transcript refs");
+    assert.equal(result.ingested.status, "accepted");
+  });
+});
+
+describe("AC2: seeded contradiction -> report naming both topics + merge proposal", () => {
+  test("duplicate-detection report names both topics and a merge-repair proposal is emitted", async () => {
+    const { report, mergeProposals } = await health({ repoRoot: CONTRADICTION_REPO });
+
+    const { valid, errors } = validate(report, REPORT_SCHEMA);
+    assert.ok(valid, `report not schema-valid:\n  ${errors.join("\n  ")}`);
+    const finding = report.findings.find(
+      (f) => f.node_ids.includes("decision:cache-eviction-policy") && f.node_ids.includes("decision:cache-eviction"),
+    );
+    assert.ok(finding, "expected a contradiction finding naming BOTH cache-eviction topics");
+
+    assert.equal(mergeProposals.length, 1, "expected exactly one merge-repair proposal");
+    const mp = mergeProposals[0];
+    const p = validate(mp, PROPOSAL_SCHEMA);
+    assert.ok(p.valid, `merge-repair proposal not schema-valid:\n  ${p.errors.join("\n  ")}`);
+    assert.equal(mp.status, "proposed", "merge-repair must be proposals-only (never auto-applied)");
+    assert.equal(mp.kind, "decision-topic");
+    assert.deepEqual([...mp.target.topics].sort(), ["cache-eviction", "cache-eviction-policy"]);
+    // Merge target = the more-recently-decided topic (cache-eviction @ 2026-06-25).
+    assert.equal(mp.target.merge_into, "cache-eviction");
+    assert.match(mp.rendered, /merged_into: cache-eviction/);
+  });
+
+  test("a resolved supersede/merge pair is NOT flagged as a contradiction", async () => {
+    // The conformance git-repo fixture has sprocket-shape (current) + old-sprocket-shape (merged
+    // tombstone) — a RESOLVED pair. It must not produce a merge-repair proposal.
+    const { mergeProposals } = await health({ repoRoot: CONFORMANCE_GIT });
+    const badPair = mergeProposals.find((mp) => mp.target.topics.includes("old-sprocket-shape"));
+    assert.ok(!badPair, "a resolved merge tombstone must not be re-flagged as a contradiction");
+  });
+});
+
+describe("AC3: zero writes outside the session/proposal dir", () => {
+  test("the source repo registry is byte-identical before and after a run", async () => {
+    const before = snapshotDir(CONTRADICTION_REPO);
+    const beforeSession = snapshotDir(SESSION);
+    const outDir = tmpOut("ac3");
+
+    const result = await runPromote({ sessionDir: SESSION, repoRoot: CONTRADICTION_REPO, provenance: PROVENANCE, outDir });
+
+    // The read source (repoRoot) and the read session are untouched.
+    assert.deepEqual(snapshotDir(CONTRADICTION_REPO), before, "repoRoot registry must be untouched");
+    assert.deepEqual(snapshotDir(SESSION), beforeSession, "session dir must be untouched");
+
+    // Every written path is under outDir.
+    assert.ok(result.written.length > 0, "expected drafts to be written");
+    for (const rel of result.written) {
+      const abs = path.resolve(outDir, rel);
+      assert.ok(abs.startsWith(path.resolve(outDir) + path.sep), `write escaped outDir: ${rel}`);
+    }
+    fs.rmSync(outDir, { recursive: true, force: true });
+  });
+
+  test("default outDir lands under the session directory", async () => {
+    // Copy the session fixture to a temp dir so the default proposals/ write is isolated.
+    const tmpSession = tmpOut("ac3-default");
+    for (const rel of Object.keys(snapshotDir(SESSION))) {
+      const src = path.join(SESSION, rel);
+      const dst = path.join(tmpSession, rel);
+      fs.mkdirSync(path.dirname(dst), { recursive: true });
+      fs.copyFileSync(src, dst);
+    }
+    const result = await runPromote({ sessionDir: tmpSession, repoRoot: CLEAN_REPO, provenance: PROVENANCE });
+    assert.equal(result.out_dir, path.join(tmpSession, "proposals"));
+    assert.ok(fs.existsSync(path.join(tmpSession, "proposals", "README.md")));
+    fs.rmSync(tmpSession, { recursive: true, force: true });
+  });
+});
+
+describe("R1: the FlowDefinition is composable (true sub-flow nesting)", () => {
+  test("promote.flow.json exports every gate claim so a parent uses_flow step resolves", () => {
+    const flow = JSON.parse(fs.readFileSync(path.join(REPO_ROOT, "kits/knowledge/flows/promote.flow.json"), "utf8"));
+    assert.equal(flow.id, "knowledge.promote");
+    const stepIds = flow.steps.map((s) => s.id);
+    for (const step of ["ingest", "distill", "link", "health"]) {
+      assert.ok(stepIds.includes(step), `missing step ${step}`);
+      const gate = Object.values(flow.gates).find((g) => g.step === step);
+      assert.ok(gate, `missing gate for step ${step}`);
+      const claimType = gate.expects[0].bundle_claim.claimType;
+      // Every gate claim MUST be exported for a parent step's uses_flow edge to
+      // resolve (src/lib/flow-resolver.ts requires all child expects be exported).
+      assert.ok(flow.exports.includes(claimType), `gate claim ${claimType} must be exported for composability`);
+    }
+  });
+});

package/kits/knowledge/providers/conformance/suite.test.js

@@ -17,6 +17,9 @@ import { fileURLToPath } from "node:url";
 import { MarkdownVaultProvider } from "../markdown-vault/index.js";
 import { GitRepoProvider } from "../git-repo/index.js";
 import { WorkItemProvider } from "../work-item/index.js";
+import { Neo4jProvider } from "../neo4j/index.js";
+import { syncToNeo4j } from "../neo4j/sync.js";
+import { makeFakeDriver } from "../neo4j/fake-driver.js";
 import DefaultKnowledgeStore from "../../adapters/default-store/index.js";
 import { loadSchemas, EDGE_TYPES } from "../lib/model.js";
 import { validate } from "../lib/schema-validate.js";
@@ -54,10 +57,25 @@ async function buildWorkItem() {
   return { provider, proposeIntent: { issue: 14, commentBody: "draft comment" }, cleanup: () => {} };
 }
 
+async function buildNeo4j() {
+  // Materialize the same git-repo + work-item fixtures the other providers use
+  // into an injected fake driver, then read them back through the neo4j provider.
+  // This exercises the read side over the graph store with no Docker (issue #327
+  // CI proof: conformance passes for the neo4j read side via an injected mock).
+  const gitRepo = new GitRepoProvider({ repoRoot: path.join(FIXTURES, "git-repo"), agent: "test" });
+  const issues = fs.readFileSync(path.join(FIXTURES, "work-item", "issues.json"), "utf8");
+  const workItem = new WorkItemProvider({ repo: "seed/fixture", runner: async () => issues, agent: "test" });
+  const driver = makeFakeDriver();
+  await syncToNeo4j({ driver, providers: [gitRepo, workItem] });
+  const provider = new Neo4jProvider({ driver, agent: "test" });
+  return { provider, proposeIntent: { kind: "create-node", type: "note", title: "Proposed graph note" }, cleanup: () => {} };
+}
+
 const PROVIDERS = [
   { name: "markdown-vault", build: buildVault, expectedId: "markdown-vault" },
   { name: "git-repo", build: buildGitRepo, expectedId: "git-repo" },
   { name: "work-item", build: buildWorkItem, expectedId: "work-item" },
+  { name: "neo4j", build: buildNeo4j, expectedId: "neo4j" },
 ];
 
 for (const { name, build, expectedId } of PROVIDERS) {

package/kits/knowledge/providers/index.js

@@ -11,6 +11,7 @@
 export { MarkdownVaultProvider } from "./markdown-vault/index.js";
 export { GitRepoProvider } from "./git-repo/index.js";
 export { WorkItemProvider, parseWorkItemMetadata } from "./work-item/index.js";
+export { Neo4jProvider } from "./neo4j/index.js";
 export { detectDuplicates, checkDependencyLinkIntegrity, HEALTH_VERBS } from "./health/index.js";
 export {
   EDGE_TYPES,

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

@@ -0,0 +1,121 @@
+/**
+ * Connection + selection for the neo4j knowledge-store provider.
+ *
+ * Credentials are resolved BY REFERENCE, never hardcoded: the standard
+ * neo4j-driver environment variables NEO4J_URI / NEO4J_USER / NEO4J_PASSWORD.
+ * (This repo does not yet consume @kontourai/datum — PR #365's model-routing
+ * adoption stayed config-file based — so we follow the existing env-reference
+ * precedent rather than inventing a datum coupling. If/when datum lands, resolve
+ * these three names through it without touching call sites.)
+ *
+ * The driver is a LAZY, OPTIONAL dependency: neo4j-driver is an
+ * optionalDependency, imported on first use inside a try/catch. A missing module
+ * OR an unreachable server both degrade to the file providers (AC4) — the graph
+ * is never a hard dependency of any repo or workflow.
+ *
+ * @module providers/neo4j/connection
+ */
+
+/**
+ * Resolve connection config by reference. Returns { uri, user, password,
+ * database } or null when NEO4J_URI is unset (the "no graph configured" signal).
+ * @param {object} [env=process.env]
+ */
+export function resolveNeo4jConfig(env = process.env) {
+  const uri = env.NEO4J_URI;
+  if (!uri) return null;
+  return {
+    uri,
+    user: env.NEO4J_USER || "neo4j",
+    password: env.NEO4J_PASSWORD || "",
+    database: env.NEO4J_DATABASE || "neo4j",
+  };
+}
+
+/**
+ * Lazily import neo4j-driver and construct a driver. Returns null if the module
+ * is not installed (optional dependency absent) — the caller degrades.
+ * @param {object} config from resolveNeo4jConfig
+ */
+export async function createDriver(config) {
+  if (!config) return null;
+  let neo4j;
+  try {
+    neo4j = (await import("neo4j-driver")).default;
+  } catch {
+    return null; // optional dependency not installed -> degrade
+  }
+  const driver = neo4j.driver(config.uri, neo4j.auth.basic(config.user, config.password));
+  // Real (non-fake) driver: the live Cypher analytics backend is available.
+  driver.supportsCypherAnalytics = true;
+  driver._kgDatabase = config.database;
+  return driver;
+}
+
+/**
+ * Probe whether a Neo4j server is reachable with these credentials. Never
+ * throws — returns false on any failure. Used by selectKnowledgeProvider so a
+ * down/absent server degrades cleanly instead of erroring.
+ * @param {object} driver
+ */
+export async function isReachable(driver, { timeoutMs = 4000 } = {}) {
+  if (!driver) return false;
+  try {
+    await withTimeout(driver.verifyConnectivity(), timeoutMs);
+    return true;
+  } catch {
+    return false;
+  }
+}
+
+function withTimeout(promise, ms) {
+  return Promise.race([
+    promise,
+    new Promise((_, reject) => setTimeout(() => reject(new Error("timeout")), ms).unref?.()),
+  ]);
+}
+
+/**
+ * Select the knowledge provider set. The default is the file providers; the
+ * neo4j graph is an OPT-IN personal default. Selection is config-driven:
+ * `preference` (from repo/user config or KNOWLEDGE_PROVIDER env) chooses neo4j;
+ * anything else, or an unreachable/absent Neo4j, falls back to the file
+ * providers with a single clear message (AC4).
+ *
+ * @param {object} options
+ * @param {"neo4j"|"file"} [options.preference] explicit preference (default from env)
+ * @param {() => object[]|Promise<object[]>} options.fileProviders factory for the file provider set
+ * @param {(cfg:object)=>Promise<object>} [options.neo4jFactory] builds the neo4j provider (driver injected)
+ * @param {object} [options.env=process.env]
+ * @param {(msg:string)=>void} [options.log] one-line status sink (default console.error)
+ * @returns {Promise<{ provider:string, providers:object[], graph:object|null, message:string }>}
+ */
+export async function selectKnowledgeProvider(options = {}) {
+  const env = options.env || process.env;
+  const log = options.log || ((m) => console.error(m));
+  const preference = options.preference || env.KNOWLEDGE_PROVIDER || "file";
+
+  const fallback = async (message) => {
+    log(message);
+    return { provider: "file", providers: await options.fileProviders(), graph: null, message };
+  };
+
+  if (preference !== "neo4j") {
+    return { provider: "file", providers: await options.fileProviders(), graph: null, message: "" };
+  }
+
+  const config = resolveNeo4jConfig(env);
+  if (!config) {
+    return fallback("knowledge: neo4j selected but NEO4J_URI is unset — using file providers.");
+  }
+  const driver = options.driver || (await createDriver(config));
+  if (!driver) {
+    return fallback("knowledge: neo4j-driver not installed — using file providers (run `npm install neo4j-driver`).");
+  }
+  if (!(await isReachable(driver))) {
+    await driver.close?.();
+    return fallback(`knowledge: no Neo4j reachable at ${config.uri} — using file providers.`);
+  }
+  const provider = await options.neo4jFactory({ driver, database: config.database });
+  return { provider: "neo4j", providers: [provider], graph: provider, message: `knowledge: neo4j provider selected (${config.uri}).` };
+}