@kontourai/flow-agents 3.0.0 → 3.2.0

package/kits/knowledge/evals/supersede-propagation/suite.test.js

@@ -0,0 +1,384 @@
+/**
+ * Knowledge Kit — Supersede/Retire Propagation Eval Suite  (#342)
+ *
+ * knowledge.flag-superseded-citers enumerates the first-degree inbound citers of
+ * a superseded / retired record and emits one flag per citer, each carrying the
+ * superseding context. Two citer sources:
+ *   - store records — the reverse-link index (store contract §5, getLinks.reverse)
+ *   - docs          — the #340 inbound-reference citation index (byRecord), scanned
+ *                     from caller-configured doc globs (opt-in)
+ *
+ * The operation is READ-ONLY (mutates no record, appends no mutation-log entry —
+ * the existing gated supersede/retire ops are untouched) and FAIL-CLOSED on the
+ * evidence guarantee: a flag can never be emitted without superseding context, so
+ * a record with no supersession evidence yields zero flags (no false flags).
+ *
+ * Field motivation (ops design partner, record 0e439c57): a "sell the
+ * combination" decision was superseded/lost in a store restructure and four docs
+ * cited it invisibly for weeks. Supersession preserves the record and surfaces
+ * store citers via reverse links, but doc citers stayed invisible — this op
+ * closes that loop.
+ *
+ * PARAMETERIZED by adapter module — set KNOWLEDGE_ADAPTER to an adapter's
+ * absolute path, or pass --adapter=<path>. Defaults to the bundled default-store
+ * adapter. AC4 runs this file for the default adapter AND the obsidian adapter.
+ *
+ * AC map (issue #342):
+ *   AC1 (R1) — a record with one store-record citer + one doc citer: the
+ *              enumeration returns both, sourced from the reverse-link index and
+ *              the citation index respectively.
+ *   AC2 (R2) — after supersede(newId,[oldId]) each flag carries citerRef + citedId
+ *              + newId; a superseded record with no citers yields an empty flag
+ *              list; a non-superseded record yields zero flags (no false flags);
+ *              retire-with-supersededByRef carries the retire evidence.
+ *   AC3 (R3) — read-only invariant (byte-identical store before/after).
+ *   AC4 (R4) — parameterized across adapters (this file, run per KNOWLEDGE_ADAPTER);
+ *              contract addendum documents the operation + flag shape.
+ *
+ * Run:
+ *   node --test kits/knowledge/evals/supersede-propagation/suite.test.js
+ *   KNOWLEDGE_ADAPTER=kits/knowledge/adapters/obsidian-store/index.js \
+ *     node --test kits/knowledge/evals/supersede-propagation/suite.test.js
+ */
+
+import { test, describe, beforeEach, afterEach } from "node:test";
+import assert from "node:assert/strict";
+import * as fs from "node:fs";
+import * as path from "node:path";
+import * as os from "node:os";
+import { fileURLToPath } from "node:url";
+
+const __dirname = path.dirname(fileURLToPath(import.meta.url));
+const KIT_ROOT = path.resolve(__dirname, "../..");
+const REPO_ROOT = path.resolve(KIT_ROOT, "../..");
+
+// ---------------------------------------------------------------------------
+// Adapter resolution — same convention as evals/inbound-references/suite.test.js
+// ---------------------------------------------------------------------------
+
+function resolveAdapterPath() {
+  const flag = process.argv.find((a) => a.startsWith("--adapter="));
+  if (flag) return path.resolve(flag.slice("--adapter=".length));
+  if (process.env.KNOWLEDGE_ADAPTER) return path.resolve(process.env.KNOWLEDGE_ADAPTER);
+  return path.join(KIT_ROOT, "adapters/default-store/index.js");
+}
+
+const adapterPath = resolveAdapterPath();
+const adapterModule = await import(adapterPath);
+const AdapterClass = adapterModule.default || adapterModule.DefaultKnowledgeStore;
+const ADAPTER_LABEL = path.relative(REPO_ROOT, adapterPath);
+
+const runnerPath = path.join(KIT_ROOT, "adapters/flow-runner/index.js");
+const { KnowledgeFlowRunner, flagSupersededCiters } = await import(runnerPath);
+
+// ---------------------------------------------------------------------------
+// Helpers
+// ---------------------------------------------------------------------------
+
+function makeTempDir(tag) {
+  return fs.mkdtempSync(path.join(os.tmpdir(), `knowledge-supersede-prop-${tag}-`));
+}
+
+function makeStore(dir) {
+  return new AdapterClass({ storeRoot: dir });
+}
+
+// The runner's workspace (telemetry sink) is kept SEPARATE from the store dir so
+// gate telemetry never lands inside the store — letting AC3 assert the whole
+// store tree is byte-identical, not just its record files.
+function makeRunner(store, workspaceDir) {
+  return new KnowledgeFlowRunner({
+    store,
+    workspace: workspaceDir,
+    agent: "supersede-prop-test-runner",
+    sessionId: "supersede-prop-session-001",
+  });
+}
+
+function writeDoc(root, rel, body) {
+  const abs = path.join(root, rel);
+  fs.mkdirSync(path.dirname(abs), { recursive: true });
+  fs.writeFileSync(abs, body, "utf8");
+}
+
+/** Recursive { relPath -> content } snapshot of every file under a dir. */
+function snapshotTree(root) {
+  const out = {};
+  const walk = (abs, rel) => {
+    for (const e of fs.readdirSync(abs, { withFileTypes: true })) {
+      const r = rel ? `${rel}/${e.name}` : e.name;
+      if (e.isDirectory()) walk(path.join(abs, e.name), r);
+      else if (e.isFile()) out[r] = fs.readFileSync(path.join(abs, e.name), "utf8");
+    }
+  };
+  walk(root, "");
+  return out;
+}
+
+// Deterministic, valid-hex UUIDs.
+const OLD = "aaaaaaaa-1111-4111-8111-111111111111"; // the superseded decision
+const NEW = "bbbbbbbb-2222-4222-8222-222222222222"; // the superseding decision
+const CITER = "cccccccc-3333-4333-8333-333333333333"; // a store record that cites OLD
+const LONE = "dddddddd-4444-4444-8444-444444444444"; // superseded, no citers
+const LONE_NEW = "eeeeeeee-5555-4555-8555-555555555555"; // supersedes LONE
+const LIVE = "ffffffff-6666-4666-8666-666666666666"; // never superseded, but cited
+const LIVE_CITER = "abababab-7777-4777-8777-777777777777"; // cites LIVE
+const RET = "cdcdcdcd-8888-4888-8888-888888888888"; // retired-with-supersededByRef
+const RET_CITER = "efefefef-9999-4999-8999-999999999999"; // cites RET
+
+async function record(store, id, title, category) {
+  await store.create({
+    id, type: "compiled", title, body: `Body of ${title}`,
+    category, provenance: { agent: "fixture" },
+  });
+}
+
+// ---------------------------------------------------------------------------
+// Suite
+// ---------------------------------------------------------------------------
+
+describe(`Knowledge Kit Supersede/Retire Propagation Suite (#342) [adapter: ${ADAPTER_LABEL}]`, () => {
+  let storeDir;
+  let workspaceDir;
+  let store;
+  let runner;
+
+  beforeEach(() => {
+    storeDir = makeTempDir("store");
+    workspaceDir = makeTempDir("ws");
+    store = makeStore(storeDir);
+    runner = makeRunner(store, workspaceDir);
+  });
+
+  afterEach(() => {
+    if (storeDir) fs.rmSync(storeDir, { recursive: true, force: true });
+    if (workspaceDir) fs.rmSync(workspaceDir, { recursive: true, force: true });
+  });
+
+  test("AC1: a record with one store-record citer + one doc citer enumerates BOTH, from the two indexes", async () => {
+    const docsRoot = makeTempDir("ac1-docs");
+    try {
+      await record(store, OLD, "Sell the combination (6/17 decision)", "decision.strategy");
+      await record(store, NEW, "GTM direction (7/3)", "decision.strategy");
+      await record(store, CITER, "Vision doc mirror", "decision.strategy");
+      // Store-record citer: CITER --related--> OLD (reverse-link index, §5).
+      await store.link(CITER, [{ target_id: OLD, kind: "related" }], { agent: "fixture" });
+      // Supersede OLD with NEW (Addendum A.5).
+      await store.supersede(NEW, [OLD], {
+        agent: "fixture",
+        rationale: "GTM direction supersedes the 6/17 sell-the-combination decision.",
+      });
+      // Doc citer: NOW.md cites OLD by full UUID (#340 citation index).
+      writeDoc(docsRoot, "NOW.md", `# NOW\n\nAnchored on decision ${OLD}.\n`);
+
+      const result = await runner.flagSupersededCiters(OLD, {
+        docGlobs: ["NOW.md"],
+        docsRoot,
+      });
+
+      assert.equal(result.superseded, true, "OLD is superseded");
+      assert.equal(result.storeCiters, 1, "one store-record citer from the reverse-link index");
+      assert.equal(result.docCiters, 1, "one doc citer from the #340 citation index");
+      assert.equal(result.flags.length, 2, "both citers flagged");
+
+      const recordFlag = result.flags.find((f) => f.citerKind === "record");
+      const docFlag = result.flags.find((f) => f.citerKind === "doc");
+      assert.ok(recordFlag, "a store-record citer flag is present");
+      assert.equal(recordFlag.citerRef, CITER, "record flag names the citing record id");
+      assert.equal(recordFlag.linkKind, "related", "record flag carries the reverse link kind (index-sourced)");
+
+      assert.ok(docFlag, "a doc citer flag is present");
+      assert.equal(docFlag.doc, "NOW.md", "doc flag names the citing doc path");
+      assert.equal(docFlag.token, OLD, "doc flag names the cited token (citation index)");
+      assert.equal(typeof docFlag.line, "number", "doc flag names a line");
+    } finally {
+      fs.rmSync(docsRoot, { recursive: true, force: true });
+    }
+  });
+
+  test("AC2: every emitted flag carries citerRef + citedId + the superseding record id (newId)", async () => {
+    const docsRoot = makeTempDir("ac2-ctx-docs");
+    try {
+      await record(store, OLD, "Old decision", "decision.strategy");
+      await record(store, NEW, "New decision", "decision.strategy");
+      await record(store, CITER, "Citer record", "decision.strategy");
+      await store.link(CITER, [{ target_id: OLD, kind: "related" }], { agent: "fixture" });
+      await store.supersede(NEW, [OLD], { agent: "fixture", rationale: "superseded." });
+      writeDoc(docsRoot, "strategy/vision.md", `# Vision\n\nSee ${OLD}.\n`);
+
+      const result = await runner.flagSupersededCiters(OLD, {
+        docGlobs: ["strategy/*.md"],
+        docsRoot,
+      });
+
+      assert.equal(result.flags.length, 2);
+      for (const f of result.flags) {
+        assert.ok(f.citerRef, "flag carries a citer ref");
+        assert.equal(f.citedId, OLD, "flag names the cited (superseded) id");
+        assert.ok(
+          Array.isArray(f.supersededByIds) && f.supersededByIds.includes(NEW),
+          "flag carries the superseding record id (newId) as evidence"
+        );
+      }
+    } finally {
+      fs.rmSync(docsRoot, { recursive: true, force: true });
+    }
+  });
+
+  test("AC2: a superseded record with NO citers yields an empty flag list (no false flags)", async () => {
+    await record(store, LONE, "Lonely superseded decision", "decision.pricing");
+    await record(store, LONE_NEW, "Replacement decision", "decision.pricing");
+    await store.supersede(LONE_NEW, [LONE], { agent: "fixture", rationale: "replaced." });
+
+    const result = await runner.flagSupersededCiters(LONE, {});
+    assert.equal(result.superseded, true, "record is superseded");
+    assert.deepEqual(result.flags, [], "no citers → no flags");
+    assert.equal(result.storeCiters, 0, "the superseding record itself is not counted as a citer");
+    assert.equal(result.docCiters, 0);
+  });
+
+  test("AC2: a NON-superseded record emits ZERO flags even when it has citers (evidence guarantee, fail closed)", async () => {
+    const docsRoot = makeTempDir("ac2-live-docs");
+    try {
+      await record(store, LIVE, "Live decision", "decision.strategy");
+      await record(store, LIVE_CITER, "Citer of live decision", "decision.strategy");
+      await store.link(LIVE_CITER, [{ target_id: LIVE, kind: "related" }], { agent: "fixture" });
+      writeDoc(docsRoot, "NOW.md", `# NOW\n\nCurrent authority ${LIVE}.\n`);
+
+      const result = await runner.flagSupersededCiters(LIVE, {
+        docGlobs: ["NOW.md"],
+        docsRoot,
+      });
+
+      assert.equal(result.superseded, false, "record shows no supersession evidence");
+      assert.deepEqual(result.supersededByIds, [], "no superseding record ids");
+      assert.equal(result.supersededByRef, null, "no retire supersededByRef");
+      assert.deepEqual(result.flags, [], "no supersession evidence → no flag can be emitted");
+      // The inbound edges are still visible via the counts (enumeration is R1),
+      // even though gating (R2) suppresses the flags.
+      assert.equal(result.storeCiters, 1, "enumeration still surfaces the store citer");
+      assert.equal(result.docCiters, 1, "enumeration still surfaces the doc citer");
+    } finally {
+      fs.rmSync(docsRoot, { recursive: true, force: true });
+    }
+  });
+
+  test("R2: retire-with-supersededByRef flags citers carrying the retire evidence", async () => {
+    await record(store, RET, "Retired-and-superseded decision", "decision.ops");
+    await record(store, RET_CITER, "Citer of retired decision", "decision.ops");
+    await store.link(RET_CITER, [{ target_id: RET, kind: "related" }], { agent: "fixture" });
+    // Retire RET pointing at a superseding artifact ref (Addendum B.4).
+    await store.retire(RET, "retired", {
+      agent: "fixture",
+      rationale: "Superseded by the new GTM record; archiving.",
+      supersededByRef: NEW,
+    });
+
+    const result = await runner.flagSupersededCiters(RET, {});
+    assert.equal(result.superseded, true, "retire-with-supersededByRef counts as supersession");
+    assert.equal(result.supersededByRef, NEW, "the retire supersededByRef is surfaced");
+    assert.equal(result.retiredStatus, "retired", "retired status is surfaced");
+    assert.equal(result.flags.length, 1, "the store citer is flagged");
+    const [f] = result.flags;
+    assert.equal(f.citerRef, RET_CITER);
+    assert.equal(f.citedId, RET);
+    assert.equal(f.supersededByRef, NEW, "flag carries the retire evidence");
+  });
+
+  test("AC3: read-only invariant — the store is byte-identical before and after the enumeration", async () => {
+    const docsRoot = makeTempDir("ac3-docs");
+    try {
+      await record(store, OLD, "Old decision", "decision.strategy");
+      await record(store, NEW, "New decision", "decision.strategy");
+      await record(store, CITER, "Citer record", "decision.strategy");
+      await store.link(CITER, [{ target_id: OLD, kind: "related" }], { agent: "fixture" });
+      await store.supersede(NEW, [OLD], { agent: "fixture", rationale: "superseded." });
+      writeDoc(docsRoot, "NOW.md", `# NOW\n\n${OLD}\n`);
+
+      const before = snapshotTree(storeDir);
+      await runner.flagSupersededCiters(OLD, { docGlobs: ["NOW.md"], docsRoot });
+      const after = snapshotTree(storeDir);
+
+      assert.deepEqual(after, before, "no store file is created, deleted, or mutated by the enumeration");
+    } finally {
+      fs.rmSync(docsRoot, { recursive: true, force: true });
+    }
+  });
+
+  test("opt-in: with no doc globs the enumeration returns store citers only (no doc scan)", async () => {
+    await record(store, OLD, "Old decision", "decision.strategy");
+    await record(store, NEW, "New decision", "decision.strategy");
+    await record(store, CITER, "Citer record", "decision.strategy");
+    await store.link(CITER, [{ target_id: OLD, kind: "related" }], { agent: "fixture" });
+    await store.supersede(NEW, [OLD], { agent: "fixture", rationale: "superseded." });
+
+    const result = await runner.flagSupersededCiters(OLD, {});
+    assert.equal(result.storeCiters, 1, "store citer enumerated");
+    assert.equal(result.docCiters, 0, "no doc scan when globs are unconfigured");
+    assert.equal(result.flags.length, 1);
+    assert.equal(result.flags[0].citerKind, "record");
+  });
+
+  test("gate telemetry: collect-gate and flag-gate events are emitted", async () => {
+    await record(store, OLD, "Old decision", "decision.strategy");
+    await record(store, NEW, "New decision", "decision.strategy");
+    await store.supersede(NEW, [OLD], { agent: "fixture", rationale: "superseded." });
+
+    const result = await runner.flagSupersededCiters(OLD, {});
+    const names = result.telemetryEvents.map((e) => e.gate || (e.data && e.data.gate)).filter(Boolean);
+    assert.ok(
+      result.telemetryEvents.length >= 4,
+      "collect-gate + flag-gate produce at least 4 in/out events"
+    );
+    assert.ok(names.includes("collect-gate") || result.telemetryEvents.length >= 4, "collect-gate present");
+  });
+
+  test("module-level flagSupersededCiters export delegates to the runner", async () => {
+    const docsRoot = makeTempDir("mod-docs");
+    try {
+      await record(store, OLD, "Old decision", "decision.strategy");
+      await record(store, NEW, "New decision", "decision.strategy");
+      await record(store, CITER, "Citer record", "decision.strategy");
+      await store.link(CITER, [{ target_id: OLD, kind: "related" }], { agent: "fixture" });
+      await store.supersede(NEW, [OLD], { agent: "fixture", rationale: "superseded." });
+      writeDoc(docsRoot, "NOW.md", `# NOW\n\n${OLD}\n`);
+
+      const result = await flagSupersededCiters(OLD, {
+        store, workspace: workspaceDir, agent: "supersede-prop-test-runner",
+        docGlobs: ["NOW.md"], docsRoot,
+      });
+      assert.equal(result.superseded, true);
+      assert.equal(result.flags.length, 2, "delegated call enumerates both citers");
+    } finally {
+      fs.rmSync(docsRoot, { recursive: true, force: true });
+    }
+  });
+
+  test("missing record fails closed (never a silent empty pass)", async () => {
+    await assert.rejects(
+      () => runner.flagSupersededCiters("deadbeef-0000-4000-8000-000000000000", {}),
+      /record not found/,
+      "an unknown record id throws, not returns an empty flag list"
+    );
+  });
+});
+
+// ---------------------------------------------------------------------------
+// AC4 (doc claim) — the contract addendum is committed. Adapter-independent, so
+// run once (only under the default adapter to avoid duplicate reporting).
+// ---------------------------------------------------------------------------
+
+describe("Supersede/Retire Propagation — contract doc addendum (#342)", () => {
+  test("AC4: store-contract.md documents the operation as Addendum K", () => {
+    if (!ADAPTER_LABEL.includes("default-store")) return; // adapter-independent
+    const contract = fs.readFileSync(
+      path.join(KIT_ROOT, "docs/store-contract.md"), "utf8"
+    );
+    assert.match(contract, /## Addendum K —.*Supersede/i, "Addendum K heading present");
+    assert.match(contract, /flagSupersededCiters/, "documents the flow-runner operation name");
+    assert.match(contract, /supersededByIds/, "documents the flag superseding-context shape");
+    assert.match(contract, /read-only|read only/i, "documents the read-only invariant");
+    assert.match(contract, /no false flags|fail closed|fail-closed/i, "documents the evidence guarantee");
+    assert.match(contract, /byRecord|citation index/i, "documents the doc-citer citation-index source");
+  });
+});

package/kits/knowledge/flows/promote.flow.json

@@ -0,0 +1,84 @@
+{
+  "id": "knowledge.promote",
+  "version": "1.0",
+  "description": "Knowledge Kit promote sub-flow (the codebase-facing 'flow within a flow'): ingest a delivered session's artifacts -> distill durable draft deltas (decision topics per the registry contract, CONTEXT.md vocabulary, learnings) -> link provenance (PR, merge SHA, session archive, touched topics) -> health-check the registry for contradictions (overlapping subject nouns with divergent status/content) and propose merge-repair. Invokable standalone AND composable from the Builder promote step via uses_flow. PROPOSALS-ONLY: every output lands as a draft under <session>/proposals/ for the promote step's human/agent to apply; the sub-flow never writes docs directly.",
+  "steps": [
+    { "id": "ingest", "next": "distill" },
+    { "id": "distill", "next": "link" },
+    { "id": "link", "next": "health" },
+    { "id": "health", "next": "done" },
+    { "id": "done", "next": null }
+  ],
+  "exports": [
+    "knowledge.promote.ingest",
+    "knowledge.promote.distill",
+    "knowledge.promote.link",
+    "knowledge.promote.health"
+  ],
+  "gates": {
+    "ingest-gate": {
+      "step": "ingest",
+      "expects": [
+        {
+          "id": "session-residue-ingested",
+          "kind": "trust.bundle",
+          "required": true,
+          "description": "A completed session directory has been read (read-only) and its durable residue collected: the plan / Definition Of Done, verification evidence, review critique, learning records, and delegate transcripts. Ingest never mutates the session and never reads outside the given session directory. The residue is the raw material the remaining steps distill — nothing is proposed yet.",
+          "bundle_claim": {
+            "claimType": "knowledge.promote.ingest",
+            "subjectType": "artifact",
+            "accepted_statuses": ["trusted", "accepted"]
+          }
+        }
+      ]
+    },
+    "distill-gate": {
+      "step": "distill",
+      "expects": [
+        {
+          "id": "draft-deltas-schema-valid",
+          "kind": "trust.bundle",
+          "required": true,
+          "description": "The distilled residue is rendered as DRAFT deltas that validate BEFORE they are proposed: decision-registry topic files whose frontmatter satisfies schemas/decision-record.schema.json (one file per decision SUBJECT, the subject a CONTEXT.md vocabulary noun), CONTEXT.md vocabulary additions for any new subject noun, and docs/learnings entries. At least one schema-valid draft decision delta is produced for a session that ratified a durable decision. Every draft is written ONLY under <session>/proposals/ — the sub-flow proposes, it never writes into docs/.",
+          "bundle_claim": {
+            "claimType": "knowledge.promote.distill",
+            "subjectType": "artifact",
+            "accepted_statuses": ["trusted", "accepted"]
+          }
+        }
+      ]
+    },
+    "link-gate": {
+      "step": "link",
+      "expects": [
+        {
+          "id": "provenance-links-attached",
+          "kind": "trust.bundle",
+          "required": true,
+          "description": "Every draft delta carries its provenance: the pull request, the merge commit SHA, the archived session artifact path, and the touched decision topics. Links become evidence[] refs on the draft decision topics (kinds pr / commit / session-archive / doc) so a reader can trace each proposed delta back to the delivery that produced it. Secret-shaped refs are refused.",
+          "bundle_claim": {
+            "claimType": "knowledge.promote.link",
+            "subjectType": "artifact",
+            "accepted_statuses": ["trusted", "accepted"]
+          }
+        }
+      ]
+    },
+    "health-gate": {
+      "step": "health",
+      "expects": [
+        {
+          "id": "contradiction-report-and-merge-proposal",
+          "kind": "trust.bundle",
+          "required": true,
+          "description": "The registry is health-checked over the #317 git-repo provider interface (the SAME reader every provider shares — no forked reader): the proposed draft decisions are folded into the existing registry graph and the duplicate-detection health verb flags topics with overlapping subject nouns. Where two CURRENT decisions collide over one subject with divergent content, the step emits a merge-repair PROPOSAL naming BOTH topics and a merge target. Merge-repair is a proposal, never an auto-edit; it lands under <session>/proposals/health/ for the operator to apply through the registry's supersede/merge edit.",
+          "bundle_claim": {
+            "claimType": "knowledge.promote.health",
+            "subjectType": "artifact",
+            "accepted_statuses": ["trusted", "accepted"]
+          }
+        }
+      ]
+    }
+  }
+}

package/kits/knowledge/kit.json

@@ -59,6 +59,11 @@
       "id": "knowledge.hygiene-review",
       "path": "flows/hygiene-review.flow.json",
       "description": "Hygiene orchestrator (#106 #5, closes the issue): a THIN, opt-in orchestrator over the four hygiene flows (audit-freshness, detect-contradictions, glossary-sync, canonicalize-category). orchestrate → review-gate. Runs each opted-in audit via its EXISTING flow-runner method + gates (reimplements no detection), folds their findings into one operator-facing review of proposed actions normalized to adopt / retire / merge, each citing its sourceFlow + the evidence its origin flow's gate already vouched. Read-only by default; forks NO propose→approve gate — the operator enacts each decision through the source flow's existing gated op (retire via knowledge.retire; adopt via capture/compile or glossary-sync apply; merge via update/recategorize). The only mutation it can trigger is glossary apply, delegated verbatim to knowledge.glossary-sync's propose→apply lineage (consume-never-fork)."
+    },
+    {
+      "id": "knowledge.promote",
+      "path": "flows/promote.flow.json",
+      "description": "Knowledge promote sub-flow (issue #313, the codebase-facing 'flow within a flow'): ingest a delivered session's artifacts -> distill schema-valid DRAFT decision/vocabulary/learning deltas per the decision-registry contract -> link provenance (PR, merge SHA, session archive, touched topics) -> health-check the registry for contradictions (overlapping subject nouns + divergent content) and propose merge-repair. Invokable standalone AND composable from the Builder promote step via uses_flow. PROPOSALS-ONLY: outputs land under <session>/proposals/ for the promote step to apply; the sub-flow never writes docs directly. Executable logic: promote/index.js."
     }
   ],
   "docs": [
@@ -116,6 +121,11 @@
       "id": "knowledge.store-providers",
       "path": "providers/index.js",
       "description": "Public entry point for the knowledge store providers, health verbs, graph model helpers, and schema validator. See context/contracts/knowledge-store-contract.md."
+    },
+    {
+      "id": "knowledge.promote-runner",
+      "path": "promote/index.js",
+      "description": "Executable logic for the knowledge.promote sub-flow (issue #313): runPromote({sessionDir, repoRoot, provenance}) runs ingest -> distill -> link -> health and writes DRAFT proposals ONLY under <session>/proposals/. Builds on the #317 knowledge-store provider interface (git-repo provider as the shared registry reader; provider-agnostic duplicate-detection health verb) and validates every draft decision delta against schemas/decision-record.schema.json before proposing. Proposals-only by construction; never mutates docs/, CONTEXT.md, or any path outside the session dir."
     }
   ],
   "evals": [
@@ -188,6 +198,11 @@
       "id": "knowledge.provider-health-pass-suite",
       "path": "providers/health/health-pass.test.js",
       "description": "Health-pass suite (issue #317, AC1+AC2): the same health command over vault + git-repo providers yields schema-valid reports (AC1); a backlog pass over the work-item adapter driven by a seeded fixture flags a duplicate and a broken blocker link (AC2) — never the real board."
+    },
+    {
+      "id": "knowledge.promote-suite",
+      "path": "promote/promote.test.js",
+      "description": "Eval cases for the knowledge.promote sub-flow (issue #313): AC1 (a real-modeled completed session dir yields >=1 schema-valid draft decision delta with PR/merge-SHA/session-archive provenance, validated against the real #310 registry validator); AC2 (a seeded-contradiction registry fixture yields a duplicate-detection report naming BOTH topics + a schema-valid merge-repair proposal naming a merge target; a resolved supersede/merge pair is not re-flagged); AC3 (filesystem diff proves zero writes outside the session/proposal dir); R1 (the FlowDefinition exports every gate claim so a parent uses_flow step resolves it)."
     }
   ],
   "skills": [

package/kits/knowledge/promote/distill.js

@@ -0,0 +1,96 @@
+/**
+ * Step 2 — DISTILL.
+ *
+ * Turn the ingested residue into DRAFT deltas that validate BEFORE they are
+ * proposed (R2): decision-registry topic files (one per decision SUBJECT, the
+ * subject a CONTEXT.md vocabulary noun), CONTEXT.md vocabulary additions for any
+ * new subject noun, and docs/learnings entries. Nothing is written to disk here
+ * — distill returns draft objects; writing (only under <session>/proposals/)
+ * happens in the orchestrator.
+ *
+ * @module promote/distill
+ */
+
+import { slugify, readGlossaryTerms, validateDecisionDelta } from "./lib.js";
+
+function deriveSubject(decision) {
+  if (decision.subject) return decision.subject;
+  // Derive a rough noun-phrase subject from the outcome body (draft — the
+  // operator refines it at apply time). Take the leading clause, title-case.
+  const clause = String(decision.body || "").split(/[.;:]/)[0].trim().split(/\s+/).slice(0, 6).join(" ");
+  if (!clause) return "Delivered decision";
+  return clause.charAt(0).toUpperCase() + clause.slice(1);
+}
+
+/**
+ * @param {object} residue from ingestSession.
+ * @param {object} [options]
+ * @param {string} [options.repoRoot] repo whose CONTEXT.md is checked for vocabulary gaps.
+ * @param {string} [options.decided] ISO date to stamp on drafts (default: today).
+ * @returns {{ decisions: object[], vocabulary: object[], learnings: object[], warnings: string[] }}
+ */
+export function distill(residue, options = {}) {
+  const decided = options.decided || new Date().toISOString().slice(0, 10);
+  const glossary = options.repoRoot ? readGlossaryTerms(options.repoRoot) : new Set();
+  const warnings = [];
+
+  const decisions = [];
+  const vocabulary = [];
+  const seenSlugs = new Set();
+  const seenVocab = new Set();
+
+  for (const raw of residue.decisions || []) {
+    const subject = deriveSubject(raw);
+    const slug = slugify(subject);
+    if (!slug || seenSlugs.has(slug)) continue;
+    seenSlugs.add(slug);
+
+    // Base provenance so the draft is already schema-valid at distill time
+    // (R2: validate BEFORE proposing). link() enriches with PR + merge SHA.
+    const evidence = [
+      { kind: "session-archive", ref: `${residue.sessionDir}/${residue.sessionMarkdown || "state.json"}` },
+    ];
+
+    const newVocabulary = !glossary.has(subject.toLowerCase());
+    const delta = {
+      subject,
+      slug,
+      status: "current",
+      decided,
+      body: raw.body || subject,
+      evidence,
+      derived: !!raw.derived,
+      newVocabulary,
+    };
+    const errors = validateDecisionDelta(delta);
+    if (errors.length) {
+      warnings.push(`decision draft '${slug}' failed pre-proposal validation: ${errors.join("; ")}`);
+      continue;
+    }
+    decisions.push(delta);
+
+    if (newVocabulary && !seenVocab.has(slug)) {
+      seenVocab.add(slug);
+      vocabulary.push({
+        term: subject,
+        slug,
+        definition: (raw.body || subject).split(/[.;]/)[0].trim(),
+      });
+    }
+  }
+
+  const learnings = (residue.learnings || []).map((rec, i) => ({
+    id: rec.id || `learn-${residue.slug}-${i + 1}`,
+    title: rec.summary ? rec.summary.split(/[.;]/)[0].trim() : `Learning ${i + 1}`,
+    body: rec.summary || "",
+    outcome: rec.outcome || null,
+    source_refs: Array.isArray(rec.source_refs) ? rec.source_refs : [],
+    correction: rec.correction && rec.correction.needed ? {
+      type: rec.correction.type || null,
+      recurrence_key: rec.correction.recurrence_key || null,
+      prevention: rec.correction.prevention || null,
+    } : null,
+  }));
+
+  return { decisions, vocabulary, learnings, warnings };
+}

package/kits/knowledge/promote/fixtures/contradiction-registry/CONTEXT.md

@@ -0,0 +1,7 @@
+# Contradiction Fixture Context
+
+## Glossary
+
+### Cache Eviction Policy
+
+How cached entries are chosen for removal under memory pressure.

package/kits/knowledge/promote/fixtures/contradiction-registry/docs/decisions/cache-eviction-policy.md

@@ -0,0 +1,12 @@
+---
+status: current
+subject: Cache eviction policy
+decided: 2026-06-10
+evidence:
+  - kind: issue
+    ref: https://github.com/kontourai/flow-agents/issues/401
+---
+
+# Cache eviction policy
+
+Entries are evicted using a least-recently-used (LRU) policy.

package/kits/knowledge/promote/fixtures/contradiction-registry/docs/decisions/cache-eviction.md

@@ -0,0 +1,12 @@
+---
+status: current
+subject: Cache eviction policy
+decided: 2026-06-25
+evidence:
+  - kind: issue
+    ref: https://github.com/kontourai/flow-agents/issues/415
+---
+
+# Cache eviction policy
+
+Entries are evicted using a least-frequently-used (LFU) policy.

package/kits/knowledge/promote/fixtures/repo/CONTEXT.md

@@ -0,0 +1,11 @@
+# Fixture Repo Context
+
+## Glossary
+
+### Liveness Claim
+
+An advisory, TTL-bounded coordination claim marking who is actively holding a work item.
+
+### Workflow Sidecar
+
+The writer that maintains structured workflow state artifacts.

package/kits/knowledge/promote/fixtures/repo/docs/decisions/index.md

@@ -0,0 +1,9 @@
+---
+title: Decision Index
+---
+
+# Decision Index
+
+| Topic | Status | Decision |
+| --- | --- | --- |
+| [liveness-claim](./liveness-claim.md) | current | Liveness Claim |