@kontourai/flow-agents 3.0.0 → 3.2.0

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;

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(),
+  };
+}