@kontourai/flow-agents 2.4.0 → 3.1.0

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/fixtures/git-repo/CONTEXT.md

@@ -0,0 +1,12 @@
+# Fixture Context
+
+## Glossary
+
+### Widget
+
+A demonstration domain noun used by the git-repo provider conformance fixture.
+_Avoid_: Gadget
+
+### Sprocket
+
+Another fixture vocabulary term with a short definition line.

package/kits/knowledge/providers/conformance/fixtures/git-repo/docs/decisions/old-sprocket-shape.md

@@ -0,0 +1,13 @@
+---
+status: merged
+subject: Old sprocket shape
+decided: 2026-07-02
+merged_into: sprocket-shape
+evidence:
+  - kind: pr
+    ref: https://github.com/kontourai/flow-agents/pull/319
+---
+
+# Old sprocket shape
+
+Merged into [sprocket-shape](./sprocket-shape.md).

package/kits/knowledge/providers/conformance/fixtures/git-repo/docs/decisions/sprocket-shape.md

@@ -0,0 +1,14 @@
+---
+status: current
+subject: Sprocket shape
+decided: 2026-07-02
+supersedes:
+  - old-sprocket-shape
+evidence:
+  - kind: pr
+    ref: https://github.com/kontourai/flow-agents/pull/319
+---
+
+# Sprocket shape
+
+Sprockets are round. Absorbs the old-sprocket-shape topic.

package/kits/knowledge/providers/conformance/fixtures/git-repo/docs/decisions/widget-format.md

@@ -0,0 +1,14 @@
+---
+status: current
+subject: Widget format
+decided: 2026-07-01
+evidence:
+  - kind: issue
+    ref: https://github.com/kontourai/flow-agents/issues/317
+  - kind: doc
+    ref: docs/learnings/fixture-learning.md
+---
+
+# Widget format
+
+Widgets are stored as JSON. Lean rationale linked via evidence.

package/kits/knowledge/providers/conformance/fixtures/git-repo/docs/learnings/fixture-learning.md

@@ -0,0 +1,7 @@
+---
+title: "Fixture Learning"
+---
+
+# Fixture Learning
+
+A durable learning used by the git-repo provider conformance fixture.

package/kits/knowledge/providers/conformance/fixtures/work-item/issues.json

@@ -0,0 +1,30 @@
+[
+  {
+    "number": 14,
+    "title": "Add dark mode toggle to settings",
+    "state": "OPEN",
+    "labels": [{ "name": "enhancement" }],
+    "body": "Users want a dark mode toggle in the settings screen.\n\n<!-- flow-agents:work-item-metadata\n{\n  \"schema_version\": \"1.0\",\n  \"blockers\": []\n}\n-->"
+  },
+  {
+    "number": 15,
+    "title": "Add dark-mode toggle to settings page",
+    "state": "OPEN",
+    "labels": [{ "name": "enhancement" }],
+    "body": "Duplicate of the dark mode toggle request. Settings page needs a dark-mode toggle."
+  },
+  {
+    "number": 20,
+    "title": "Ship theme system",
+    "state": "OPEN",
+    "labels": [{ "name": "feature" }],
+    "body": "Overarching theme work. Relates to #14.\n\n<!-- flow-agents:work-item-metadata\n{\n  \"schema_version\": \"1.0\",\n  \"blockers\": [\n    { \"repo\": \"seed/fixture\", \"number\": 14 },\n    { \"repo\": \"seed/fixture\", \"number\": 999 }\n  ]\n}\n-->"
+  },
+  {
+    "number": 21,
+    "title": "Document theme tokens",
+    "state": "OPEN",
+    "labels": [],
+    "body": "Blocked by #20. Also see #14 for the toggle."
+  }
+]

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

@@ -0,0 +1,143 @@
+/**
+ * Knowledge Store Provider — Conformance Suite (issue #317, AC3).
+ *
+ * One parameterized suite every provider must pass. Proves that markdown-vault,
+ * git-repo, and work-item all satisfy the read + proposals-only interface and
+ * emit schema-valid nodes/edges/proposals. Run:
+ *   node --test kits/knowledge/providers/conformance/suite.test.js
+ */
+
+import { test, describe, before, after } 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 { 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";
+
+const __dirname = path.dirname(fileURLToPath(import.meta.url));
+const FIXTURES = path.join(__dirname, "fixtures");
+const schemas = loadSchemas();
+
+function assertSchema(value, schema, label) {
+  const { valid, errors } = validate(value, schema);
+  assert.ok(valid, `${label} not schema-valid:\n  ${errors.join("\n  ")}`);
+}
+
+// --- per-provider fixture builders --------------------------------------
+
+async function buildVault() {
+  const dir = fs.mkdtempSync(path.join(os.tmpdir(), "kg-vault-conf-"));
+  const store = new DefaultKnowledgeStore({ storeRoot: dir });
+  const rawId = await store.create({ type: "raw", title: "Raw source", body: "raw material", category: "eng", provenance: { agent: "test" } });
+  const compiledId = await store.create({ type: "compiled", title: "Compiled note", body: "distilled", category: "eng", provenance: { agent: "test" } });
+  await store.link(compiledId, [{ target_id: rawId, kind: "source" }], { agent: "test" });
+  const provider = new MarkdownVaultProvider({ store, storeRoot: dir, agent: "test" });
+  return { provider, proposeIntent: { title: "Proposed note", body: "content", category: "eng" }, cleanup: () => fs.rmSync(dir, { recursive: true, force: true }) };
+}
+
+async function buildGitRepo() {
+  const provider = new GitRepoProvider({ repoRoot: path.join(FIXTURES, "git-repo"), agent: "test" });
+  return { provider, proposeIntent: { subject: "Fixture decision", body: "the answer", evidence: [{ kind: "issue", ref: "#317" }] }, cleanup: () => {} };
+}
+
+async function buildWorkItem() {
+  const issues = fs.readFileSync(path.join(FIXTURES, "work-item", "issues.json"), "utf8");
+  const runner = async () => issues;
+  const provider = new WorkItemProvider({ repo: "seed/fixture", runner, agent: "test" });
+  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) {
+  describe(`conformance: ${name}`, () => {
+    let ctx;
+    before(async () => { ctx = await build(); });
+    after(() => ctx.cleanup());
+
+    test("capabilities() declares proposals-only, non-writable", () => {
+      const cap = ctx.provider.capabilities();
+      assert.equal(cap.id, expectedId);
+      assert.equal(cap.writable, false);
+      assert.equal(cap.write_mode, "proposals-only");
+      assert.ok(Array.isArray(cap.proposal_targets) && cap.proposal_targets.length > 0);
+    });
+
+    test("readNodes() returns schema-valid nodes with unique ids and provider provenance", async () => {
+      const nodes = await ctx.provider.readNodes();
+      assert.ok(Array.isArray(nodes) && nodes.length > 0, "expected at least one node");
+      const ids = new Set();
+      for (const n of nodes) {
+        assertSchema(n, schemas.node, `${name} node ${n.id}`);
+        assert.equal(n.provenance.provider, expectedId);
+        assert.ok(!ids.has(n.id), `duplicate node id ${n.id}`);
+        ids.add(n.id);
+      }
+    });
+
+    test("readEdges() returns schema-valid edges in the closed edge vocabulary", async () => {
+      const edges = await ctx.provider.readEdges();
+      assert.ok(Array.isArray(edges));
+      for (const e of edges) {
+        assertSchema(e, schemas.edge, `${name} edge ${e.id}`);
+        assert.ok(EDGE_TYPES.includes(e.type), `edge type ${e.type} outside closed vocabulary`);
+        assert.equal(e.provenance.provider, expectedId);
+      }
+    });
+
+    test("queryByType() is a consistent subset of readNodes()", async () => {
+      const nodes = await ctx.provider.readNodes();
+      const types = [...new Set(nodes.map((n) => n.type))];
+      for (const t of types) {
+        const q = await ctx.provider.queryByType(t);
+        assert.ok(q.every((n) => n.type === t), `queryByType(${t}) returned off-type node`);
+        assert.equal(q.length, nodes.filter((n) => n.type === t).length);
+      }
+    });
+
+    test("readGraph() returns { nodes, edges }", async () => {
+      const g = await ctx.provider.readGraph();
+      assert.ok(Array.isArray(g.nodes) && Array.isArray(g.edges));
+    });
+
+    test("proposeWrite() returns a schema-valid 'proposed' proposal and mutates nothing", async () => {
+      const before = await ctx.provider.readNodes();
+      const p = await ctx.provider.proposeWrite(ctx.proposeIntent);
+      assertSchema(p, schemas.proposal, `${name} proposal`);
+      assert.equal(p.status, "proposed");
+      assert.equal(p.provider, expectedId);
+      assert.equal(typeof p.rendered, "string");
+      const after = await ctx.provider.readNodes();
+      assert.equal(after.length, before.length, "proposeWrite must not add nodes to the store");
+    });
+  });
+}