@kontourai/flow-agents 3.0.0 → 3.1.0

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 |

package/kits/knowledge/promote/fixtures/repo/docs/decisions/liveness-claim.md

@@ -0,0 +1,12 @@
+---
+status: current
+subject: Liveness Claim
+decided: 2026-06-20
+evidence:
+  - kind: issue
+    ref: https://github.com/kontourai/flow-agents/issues/166
+---
+
+# Liveness Claim
+
+Coordination is an advisory TTL-bounded liveness claim, not a hard lock.

package/kits/knowledge/promote/fixtures/session/acceptance.json

@@ -0,0 +1,9 @@
+{
+  "schema_version": "1.0",
+  "task_slug": "kontourai-flow-agents-287",
+  "status": "accepted",
+  "verdict": "PASS",
+  "criteria": [
+    { "id": "ac1", "status": "pass", "summary": "distinct actors per concurrent session; unset actor fails loud" }
+  ]
+}

package/kits/knowledge/promote/fixtures/session/agents/tool-planner/events.jsonl

@@ -0,0 +1 @@
+{"ts":"2026-07-02T19:55:00Z","event":"plan","summary":"actor struct + resolver plan"}

package/kits/knowledge/promote/fixtures/session/agents/tool-verifier/events.jsonl

@@ -0,0 +1 @@
+{"ts":"2026-07-02T22:10:00Z","event":"verify","summary":"test_actor_identity.sh green; distinct actors confirmed"}

package/kits/knowledge/promote/fixtures/session/agents/tool-worker-1-1/events.jsonl

@@ -0,0 +1 @@
+{"ts":"2026-07-02T20:30:00Z","event":"implement","summary":"actor resolver + fail-closed liveness write"}

package/kits/knowledge/promote/fixtures/session/kontourai-flow-agents-287--deliver.md

@@ -0,0 +1,47 @@
+# kontourai-flow-agents-287
+
+branch: agent/287-actor-identity
+worktree: /tmp/wt-287
+created: 2026-07-02T19:35:52Z
+status: delivered
+type: deliver
+iteration: 3
+
+## Plan
+
+Actor struct {runtime, session_id, host, human?} with a stable serialized id; SessionStart derives FLOW_AGENTS_ACTOR; the sidecar fails loudly on a missing/local actor for liveness writes.
+
+## Definition Of Done
+
+- **User outcome:** Actor identity is a stable serialized struct so two concurrent sessions on one host never collide in the liveness stream.
+- **Scope:** Workflow session artifacts and sidecars.
+- **Acceptance criteria:**
+  - [x] Two concurrent sessions on one host produce distinct actors; liveness status shows two holders; an unset actor on a liveness write fails with remediation.
+- **Durable docs target:** docs/decisions (actor identity)
+- **Sandbox mode:** local-edit
+
+## Decisions
+
+- **Actor identity** — Agent identity is a serialized struct {runtime, session_id, host, human?} with a stable id; the sidecar fails closed (loud) on a missing or `local` actor for any liveness write, so concurrent same-host sessions never collide.
+
+## Execution Progress
+
+- [x] Actor struct + resolver implemented; SessionStart derives FLOW_AGENTS_ACTOR.
+- [x] Liveness writes fail closed on unset/local actor.
+
+## Verification Report
+
+Build: [PASS]
+
+### Acceptance Criteria
+- [PASS] Two concurrent sessions produce distinct actors; unset actor fails loud - Evidence: integration eval test_actor_identity.sh.
+
+### Verdict: PASS
+
+## Goal Fit Gate
+
+- [x] Original user goal restated and met.
+
+## Final Acceptance
+
+- [x] CI/relevant checks passed.

package/kits/knowledge/promote/fixtures/session/learning.json

@@ -0,0 +1,35 @@
+{
+  "schema_version": "1.0",
+  "task_slug": "kontourai-flow-agents-287",
+  "repo": "kontourai/flow-agents",
+  "status": "learned",
+  "updated_at": "2026-07-02T22:40:06Z",
+  "records": [
+    {
+      "recorded_at": "2026-07-02T22:40:06Z",
+      "id": "learn-287-ci-eval-gap",
+      "outcome": "mixed",
+      "summary": "Integration eval suite not wired into CI; resume-roundtrip eval broken at baseline invisibly. Manifest registration is what makes agent evidence reconcilable.",
+      "source_refs": ["evals/run.sh", "evals/ci/run-baseline.sh"],
+      "correction": {
+        "needed": true,
+        "type": "tooling",
+        "recurrence_key": "integration-evals-not-in-ci",
+        "prevention": { "target": "backlog", "action": "wire integration evals into CI required lanes", "status": "completed" }
+      }
+    },
+    {
+      "recorded_at": "2026-07-02T22:40:06Z",
+      "id": "learn-287-env-drift",
+      "outcome": "mixed",
+      "summary": "node_modules drifted from lockfile: phantom eval failures and record-evidence hard-blocked until npm ci.",
+      "source_refs": ["package-lock.json"],
+      "correction": {
+        "needed": true,
+        "type": "process",
+        "recurrence_key": "node-modules-lockfile-drift",
+        "prevention": { "target": "docs", "action": "document npm ci before verification phases", "status": "completed" }
+      }
+    }
+  ]
+}

package/kits/knowledge/promote/fixtures/session/state.json

@@ -0,0 +1,19 @@
+{
+  "schema_version": "1.0",
+  "task_slug": "kontourai-flow-agents-287",
+  "repo": "kontourai/flow-agents",
+  "status": "accepted",
+  "phase": "learning",
+  "created_at": "2026-07-02T19:50:44Z",
+  "updated_at": "2026-07-02T22:40:06Z",
+  "artifact_paths": [
+    "acceptance.json",
+    "kontourai-flow-agents-287--deliver.md",
+    "learning.json",
+    "state.json"
+  ],
+  "next_action": {
+    "status": "continue",
+    "summary": "287 delivered clean after 2 fix iterations; process learnings routed"
+  }
+}

package/kits/knowledge/promote/health.js

@@ -0,0 +1,137 @@
+/**
+ * Step 4 — HEALTH.
+ *
+ * Contradiction detection over the decision-registry topic files, via the #317
+ * knowledge-store provider interface. The git-repo provider is the SAME reader
+ * every provider shares (no forked reader): its graph is folded together with
+ * the proposed draft decisions, and the provider-agnostic duplicate-detection
+ * health verb flags topics whose subject nouns overlap. 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 is a schema-valid
+ * knowledge-store proposal (proposals-only by construction) the operator applies
+ * through the registry's own supersede/merge edit.
+ *
+ * @module promote/health
+ */
+
+import { GitRepoProvider } from "../providers/git-repo/index.js";
+import { detectDuplicates } from "../providers/health/index.js";
+import { node, proposal, provenance } from "../providers/lib/model.js";
+import { loadSchemas } from "../providers/lib/model.js";
+import { assertValid } from "../providers/lib/schema-validate.js";
+
+const { proposal: PROPOSAL_SCHEMA } = loadSchemas();
+
+/** Build draft decision nodes (same id scheme as the git-repo provider) from linked deltas. */
+function draftNodes(draftDecisions, agent) {
+  const now = new Date().toISOString();
+  return draftDecisions.map((d) =>
+    node({
+      id: `decision:${d.slug}`,
+      type: "decision",
+      title: d.subject,
+      body: d.body || "",
+      attributes: { registry_status: d.status || "current", draft: true },
+      provenance: provenance({ provider: "git-repo", source: `docs/decisions/${d.slug}.md`, locator: "draft", retrievedAt: now, agent }),
+    }),
+  );
+}
+
+function nodeStatus(n) {
+  return (n.attributes && n.attributes.registry_status) || "current";
+}
+
+/**
+ * @param {object} options
+ * @param {string} options.repoRoot            repo whose registry is read via the git-repo provider.
+ * @param {object[]} [options.draftDecisions]  linked draft decision deltas to fold in.
+ * @param {string} [options.agent]
+ * @param {number} [options.threshold]         duplicate similarity threshold (default 0.7).
+ * @returns {Promise<{report:object, mergeProposals:object[]}>}
+ */
+export async function health(options = {}) {
+  const { repoRoot, draftDecisions = [], agent, threshold = 0.7 } = options;
+  const provider = new GitRepoProvider({ repoRoot, agent });
+  const existing = await provider.readGraph();
+
+  const nodes = [...existing.nodes, ...draftNodes(draftDecisions, agent)];
+  const graph = { nodes, edges: existing.edges };
+
+  // Reuse the provider-agnostic duplicate-detection verb: overlapping subject
+  // nouns => a schema-valid duplicate-detection report naming BOTH topics.
+  const report = detectDuplicates(graph, { provider: "git-repo", threshold });
+
+  const byId = new Map(nodes.map((n) => [n.id, n]));
+  const mergeProposals = [];
+
+  for (const finding of report.findings) {
+    const [idA, idB] = finding.node_ids;
+    const a = byId.get(idA);
+    const b = byId.get(idB);
+    if (!a || !b || a.type !== "decision" || b.type !== "decision") continue;
+    // Contradiction = both current AND divergent content. A resolved pair (one
+    // already a merged/superseded tombstone) is not a contradiction.
+    const aCurrent = nodeStatus(a) === "current";
+    const bCurrent = nodeStatus(b) === "current";
+    if (!aCurrent || !bCurrent) continue;
+    if ((a.body || "").trim() === (b.body || "").trim()) continue;
+
+    // Merge target: keep the more-recently-decided topic; the other is folded in.
+    const decidedA = (a.attributes && a.attributes.decided) || "";
+    const decidedB = (b.attributes && b.attributes.decided) || "";
+    let survivor = a, absorbed = b;
+    if (decidedB > decidedA) { survivor = b; absorbed = a; }
+    else if (decidedB === decidedA && b.id < a.id) { survivor = b; absorbed = a; }
+
+    const survivorSlug = survivor.id.replace(/^decision:/, "");
+    const absorbedSlug = absorbed.id.replace(/^decision:/, "");
+
+    const rendered = [
+      "---",
+      "status: merged",
+      `subject: ${absorbed.title}`,
+      `decided: ${new Date().toISOString().slice(0, 10)}`,
+      `merged_into: ${survivorSlug}`,
+      "evidence:",
+      "  - kind: doc",
+      `    ref: docs/decisions/${survivorSlug}.md`,
+      "---",
+      "",
+      `# ${absorbed.title}`,
+      "",
+      `Merged into [${survivorSlug}](./${survivorSlug}.md). This subject was carried by two`,
+      `current topics with divergent content; the current answer now lives in ${survivorSlug}.`,
+    ].join("\n");
+
+    const prop = proposal({
+      provider: "git-repo",
+      kind: "decision-topic",
+      target: {
+        merge_repair: true,
+        merge_into: survivorSlug,
+        tombstone: absorbedSlug,
+        topics: [survivorSlug, absorbedSlug],
+        path: `docs/decisions/${absorbedSlug}.md`,
+      },
+      payload: {
+        contradiction: {
+          topics: [survivor.id, absorbed.id],
+          subject_a: survivor.title,
+          subject_b: absorbed.title,
+          divergence: { survivor: survivor.body || "", absorbed: absorbed.body || "" },
+          similarity: finding.evidence && finding.evidence.similarity,
+        },
+        merge_target: survivorSlug,
+      },
+      rendered,
+      rationale: `Two CURRENT decision topics ('${survivor.title}' @ ${survivor.id}, '${absorbed.title}' @ ${absorbed.id}) share a subject noun with divergent content — a registry contradiction. Proposed merge target: ${survivorSlug}; fold ${absorbedSlug} in as a merged tombstone. Merge-repair is a PROPOSAL: apply it via the registry's own edit, never auto-written.`,
+      provenance: provenance({ provider: "git-repo", source: `docs/decisions/${absorbedSlug}.md`, locator: "merge-repair", agent }),
+    });
+    assertValid(prop, PROPOSAL_SCHEMA, `merge-repair proposal (${absorbedSlug} -> ${survivorSlug})`);
+    mergeProposals.push(prop);
+  }
+
+  return { report, mergeProposals };
+}

package/kits/knowledge/promote/index.js

@@ -0,0 +1,176 @@
+/**
+ * Knowledge promote sub-flow — orchestrator (the "flow within a flow").
+ *
+ * Runs ingest -> distill -> link -> health over a completed session directory
+ * and lands every output as a DRAFT under `<session>/proposals/` for the promote
+ * step's human/agent to apply. PROPOSALS-ONLY (R4): this module writes ONLY under
+ * `outDir` (default `<session>/proposals`) — never into docs/, CONTEXT.md, or any
+ * path outside the session directory. The Builder promote step names this sub-flow
+ * as its assisted path; the `promote` CLI stays the recording mechanism.
+ *
+ * FlowDefinition: kits/knowledge/flows/promote.flow.json (id `knowledge.promote`).
+ * See context/contracts/knowledge-store-contract.md and
+ * context/contracts/decision-registry-contract.md.
+ *
+ * @module promote
+ */
+
+import * as fs from "node:fs";
+import * as path from "node:path";
+import { ingestSession } from "./ingest.js";
+import { distill } from "./distill.js";
+import { link } from "./link.js";
+import { health } from "./health.js";
+
+export { ingestSession } from "./ingest.js";
+export { distill } from "./distill.js";
+export { link } from "./link.js";
+export { health } from "./health.js";
+export { snapshotDir, validateDecisionDelta } from "./lib.js";
+
+function renderVocabulary(vocabulary) {
+  const lines = [
+    "# Proposed CONTEXT.md vocabulary additions",
+    "",
+    "Add each subject noun to the `## Glossary` section of CONTEXT.md before its",
+    "decision topic is filed (the registry slug rule keys off CONTEXT.md vocabulary).",
+    "",
+  ];
+  for (const v of vocabulary) {
+    lines.push(`### ${v.term}`, "", v.definition || "(define this term)", "");
+  }
+  if (vocabulary.length === 0) lines.push("_No new vocabulary — every decision subject already exists in CONTEXT.md._", "");
+  return lines.join("\n");
+}
+
+function renderLearning(rec) {
+  const lines = [
+    "---",
+    `id: ${rec.id}`,
+    rec.outcome ? `outcome: ${rec.outcome}` : "outcome: neutral",
+    "---",
+    "",
+    `# ${rec.title}`,
+    "",
+    rec.body || "",
+    "",
+  ];
+  if (rec.source_refs && rec.source_refs.length) {
+    lines.push("## Source refs", "");
+    for (const r of rec.source_refs) lines.push(`- ${r}`);
+    lines.push("");
+  }
+  if (rec.correction) {
+    lines.push("## Correction", "", `- type: ${rec.correction.type || "n/a"}`, `- recurrence_key: ${rec.correction.recurrence_key || "n/a"}`, "");
+  }
+  return lines.join("\n");
+}
+
+function renderReadme(result) {
+  return [
+    `# Promote proposals — session ${result.slug}`,
+    "",
+    "Generated by the Knowledge Kit promote sub-flow (`knowledge.promote`).",
+    "Everything here is a DRAFT PROPOSAL. Nothing was written to docs/ or CONTEXT.md.",
+    "The promote step's human/agent applies these, then records them with the `promote` CLI.",
+    "",
+    "## Apply order",
+    "",
+    "1. `vocabulary.md` — add any new subject nouns to CONTEXT.md `## Glossary`.",
+    "2. `decisions/*.md` — file each as `docs/decisions/<slug>.md`, then `npm run gen:decisions-index` + `npm run check:decisions`.",
+    "3. `learnings/*.md` — record via the learning sink / `docs/learnings/`.",
+    "4. `health/` — if a contradiction report + merge-repair proposal is present, apply the merge target edit.",
+    "",
+    "## Contents",
+    "",
+    `- decisions: ${result.decisions.map((d) => d.slug).join(", ") || "(none)"}`,
+    `- vocabulary additions: ${result.vocabulary.map((v) => v.term).join(", ") || "(none)"}`,
+    `- learnings: ${result.learnings.length}`,
+    `- touched topics: ${result.manifest.touched_topics.join(", ") || "(none)"}`,
+    `- contradiction findings: ${result.health.report.summary.finding_count}`,
+    `- merge-repair proposals: ${result.health.mergeProposals.length}`,
+    "",
+  ].join("\n");
+}
+
+/** Write every draft ONLY under outDir. Returns the list of relative paths written. */
+function writeProposals(outDir, linked, healthResult, result) {
+  const written = [];
+  const write = (rel, content) => {
+    const abs = path.join(outDir, rel);
+    fs.mkdirSync(path.dirname(abs), { recursive: true });
+    fs.writeFileSync(abs, content, "utf8");
+    written.push(rel);
+  };
+
+  for (const d of linked.decisions) write(path.join("decisions", `${d.slug}.md`), d.rendered);
+  write("vocabulary.md", renderVocabulary(linked.vocabulary));
+  for (const rec of linked.learnings) write(path.join("learnings", `${rec.id}.md`), renderLearning(rec));
+  write("link-manifest.json", `${JSON.stringify(linked.manifest, null, 2)}\n`);
+  write(path.join("health", "contradiction-report.json"), `${JSON.stringify(healthResult.report, null, 2)}\n`);
+  if (healthResult.mergeProposals.length) {
+    write(path.join("health", "merge-proposals.json"), `${JSON.stringify(healthResult.mergeProposals, null, 2)}\n`);
+    for (const mp of healthResult.mergeProposals) {
+      write(path.join("health", `merge-repair-${mp.target.tombstone}.md`), mp.rendered);
+    }
+  }
+  write("promote-result.json", `${JSON.stringify(result, null, 2)}\n`);
+  write("README.md", renderReadme(result));
+  return written;
+}
+
+/**
+ * Run the promote sub-flow over a completed session directory.
+ *
+ * @param {object} opts
+ * @param {string} opts.sessionDir            absolute path to the completed session dir.
+ * @param {string} opts.repoRoot              repo root (registry + CONTEXT.md live here).
+ * @param {object} [opts.provenance]          { pr, mergeSha, sessionArchivePath }.
+ * @param {string} [opts.outDir]              proposals dir (default <sessionDir>/proposals).
+ * @param {string} [opts.decided]             ISO date stamped on drafts.
+ * @param {string} [opts.agent]
+ * @param {boolean} [opts.write=true]         write drafts to disk (still only under outDir).
+ * @returns {Promise<object>} the promote result.
+ */
+export async function runPromote(opts = {}) {
+  const { sessionDir, repoRoot, provenance = {}, decided, agent, write = true } = opts;
+  if (!sessionDir) throw new Error("runPromote requires { sessionDir }");
+  if (!repoRoot) throw new Error("runPromote requires { repoRoot }");
+  const outDir = opts.outDir || path.join(sessionDir, "proposals");
+
+  const residue = ingestSession(sessionDir, { agent });
+  const distilled = distill(residue, { repoRoot, decided });
+  const linked = await link(distilled, provenance, { repoRoot, agent });
+  const healthResult = await health({ repoRoot, draftDecisions: linked.decisions, agent });
+
+  const result = {
+    schema_version: "1.0",
+    flow: "knowledge.promote",
+    slug: residue.slug,
+    repo: residue.repo,
+    out_dir: outDir,
+    ingested: {
+      session_markdown: residue.sessionMarkdown,
+      status: residue.status,
+      decision_candidates: residue.decisions.length,
+      learning_records: residue.learnings.length,
+      transcript_refs: residue.transcriptRefs,
+      touched_files: residue.touchedFiles,
+    },
+    decisions: linked.decisions.map((d) => ({ slug: d.slug, subject: d.subject, evidence: d.evidence, new_vocabulary: d.newVocabulary })),
+    vocabulary: linked.vocabulary,
+    learnings: linked.learnings,
+    manifest: linked.manifest,
+    health: {
+      report: healthResult.report,
+      mergeProposals: healthResult.mergeProposals,
+    },
+    warnings: distilled.warnings,
+  };
+
+  const written = write ? writeProposals(outDir, linked, healthResult, result) : [];
+  result.written = written;
+  return result;
+}
+
+export default runPromote;