@kontourai/flow-agents 2.4.0 → 3.0.0

package/kits/knowledge/providers/git-repo/index.js

@@ -0,0 +1,236 @@
+/**
+ * git-repo knowledge-store provider.
+ *
+ * Reads durable git-tracked knowledge as a typed graph:
+ *   - docs/decisions/<slug>.md  -> `decision` nodes; tombstones (superseded_by /
+ *     merged_into / supersedes[]) -> supersedes / merged-into edges; evidence[]
+ *     -> evidence-of edges (external, resolved:false).
+ *   - CONTEXT.md glossary terms   -> `note` nodes (vocabulary).
+ *   - docs/learnings/*.md         -> `note` nodes (learnings).
+ *
+ * Read side is authoritative here. The write side is proposals-only and renders
+ * a decision-registry topic file shaped for the promote sub-flow (the same
+ * frontmatter schemas/decision-record.schema.json validates) — the provider
+ * never writes to disk.
+ *
+ * @module providers/git-repo
+ */
+
+import * as fs from "node:fs";
+import * as path from "node:path";
+import { node, edge, proposal, provenance } from "../lib/model.js";
+import { parseMarkdown } from "../../adapters/shared/codec.js";
+
+const PROVIDER_ID = "git-repo";
+
+function slugify(text) {
+  return String(text)
+    .toLowerCase()
+    .replace(/[^a-z0-9]+/g, "-")
+    .replace(/^-+|-+$/g, "");
+}
+
+/** Derive a stable external node id for a decision evidence ref. */
+function evidenceNodeId(kind, ref) {
+  const tail = String(ref).replace(/^https?:\/\/github\.com\/[^/]+\/[^/]+\/(issues|pull)\//, "");
+  return `${kind}:${slugify(tail).slice(0, 60) || "ref"}`;
+}
+
+export class GitRepoProvider {
+  constructor({ repoRoot, agent } = {}) {
+    if (!repoRoot) throw new Error("GitRepoProvider requires { repoRoot }");
+    this.repoRoot = path.resolve(repoRoot);
+    this.agent = agent;
+    this.id = PROVIDER_ID;
+  }
+
+  capabilities() {
+    return {
+      id: PROVIDER_ID,
+      node_types: ["decision", "note"],
+      edge_types: ["supersedes", "merged-into", "evidence-of"],
+      writable: false,
+      write_mode: "proposals-only",
+      proposal_targets: ["decision-topic"],
+      source_of_truth: "git-tracked docs (decision registry, CONTEXT.md, learnings)",
+    };
+  }
+
+  _decisionsDir() {
+    return path.join(this.repoRoot, "docs", "decisions");
+  }
+
+  _readDecisions() {
+    const dir = this._decisionsDir();
+    if (!fs.existsSync(dir)) return [];
+    return fs
+      .readdirSync(dir)
+      .filter((f) => f.endsWith(".md") && f !== "index.md")
+      .map((f) => {
+        const slug = f.replace(/\.md$/, "");
+        const raw = fs.readFileSync(path.join(dir, f), "utf8");
+        const { meta, body } = parseMarkdown(raw);
+        return { slug, meta: meta || {}, body, rel: `docs/decisions/${f}` };
+      });
+  }
+
+  _readVocabulary() {
+    const file = path.join(this.repoRoot, "CONTEXT.md");
+    if (!fs.existsSync(file)) return [];
+    const text = fs.readFileSync(file, "utf8");
+    const lines = text.split("\n");
+    const terms = [];
+    let inGlossary = false;
+    let current = null;
+    for (const line of lines) {
+      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) {
+        if (current) terms.push(current);
+        current = { term: h[1].trim(), body: "" };
+      } else if (current && line.trim() && !line.startsWith("_Avoid_")) {
+        if (!current.body) current.body = line.trim();
+      }
+    }
+    if (current) terms.push(current);
+    return terms;
+  }
+
+  _readLearnings() {
+    const dir = path.join(this.repoRoot, "docs", "learnings");
+    if (!fs.existsSync(dir)) return [];
+    return fs
+      .readdirSync(dir)
+      .filter((f) => f.endsWith(".md"))
+      .map((f) => {
+        const raw = fs.readFileSync(path.join(dir, f), "utf8");
+        const { meta, body } = parseMarkdown(raw);
+        const title = (meta && meta.title) || f.replace(/\.md$/, "");
+        return { file: f, title, body, rel: `docs/learnings/${f}` };
+      });
+  }
+
+  async readNodes(options = {}) {
+    const nodes = [];
+    const now = new Date().toISOString();
+
+    for (const d of this._readDecisions()) {
+      const attributes = { registry_status: d.meta.status || "current" };
+      if (d.meta.decided) attributes.decided = d.meta.decided;
+      nodes.push(
+        node({
+          id: `decision:${d.slug}`,
+          type: "decision",
+          title: d.meta.subject || d.slug,
+          body: d.body || "",
+          attributes,
+          provenance: provenance({ provider: PROVIDER_ID, source: d.rel, retrievedAt: now, agent: this.agent }),
+        }),
+      );
+    }
+
+    for (const v of this._readVocabulary()) {
+      nodes.push(
+        node({
+          id: `vocab:${slugify(v.term)}`,
+          type: "note",
+          title: v.term,
+          body: v.body || "",
+          attributes: { kind: "vocabulary" },
+          provenance: provenance({ provider: PROVIDER_ID, source: "CONTEXT.md", locator: `glossary#${v.term}`, retrievedAt: now, agent: this.agent }),
+        }),
+      );
+    }
+
+    for (const l of this._readLearnings()) {
+      nodes.push(
+        node({
+          id: `learning:${slugify(l.file.replace(/\.md$/, ""))}`,
+          type: "note",
+          title: l.title,
+          body: l.body || "",
+          attributes: { kind: "learning" },
+          provenance: provenance({ provider: PROVIDER_ID, source: l.rel, retrievedAt: now, agent: this.agent }),
+        }),
+      );
+    }
+
+    if (options.type) return nodes.filter((n) => n.type === options.type);
+    return nodes;
+  }
+
+  async readEdges() {
+    const edges = [];
+    const now = new Date().toISOString();
+    for (const d of this._readDecisions()) {
+      const self = `decision:${d.slug}`;
+      const prov = (loc) => provenance({ provider: PROVIDER_ID, source: d.rel, locator: loc, retrievedAt: now, agent: this.agent });
+
+      // superseded_by: this subject moved to another slug -> that slug supersedes this
+      if (d.meta.superseded_by) {
+        edges.push(edge({ id: `${d.meta.superseded_by}--supersedes--${d.slug}`, type: "supersedes", from: `decision:${d.meta.superseded_by}`, to: self, provenance: prov("superseded_by") }));
+      }
+      // merged_into: this folded into another slug
+      if (d.meta.merged_into) {
+        edges.push(edge({ id: `${d.slug}--merged-into--${d.meta.merged_into}`, type: "merged-into", from: self, to: `decision:${d.meta.merged_into}`, provenance: prov("merged_into") }));
+      }
+      // supersedes[]: this file absorbed those slugs
+      for (const absorbed of Array.isArray(d.meta.supersedes) ? d.meta.supersedes : []) {
+        edges.push(edge({ id: `${d.slug}--supersedes--${absorbed}`, type: "supersedes", from: self, to: `decision:${absorbed}`, provenance: prov("supersedes") }));
+      }
+      // evidence[]: external provenance -> evidence-of (resolved:false, external ref)
+      for (const ev of Array.isArray(d.meta.evidence) ? d.meta.evidence : []) {
+        if (!ev || !ev.kind || !ev.ref) continue;
+        edges.push(edge({ id: `${d.slug}--evidence-of--${evidenceNodeId(ev.kind, ev.ref)}`, type: "evidence-of", from: self, to: evidenceNodeId(ev.kind, ev.ref), resolved: false, attributes: { evidence_kind: ev.kind, ref: ev.ref }, provenance: prov("evidence") }));
+      }
+    }
+    return edges;
+  }
+
+  async queryByType(type) {
+    return this.readNodes({ type });
+  }
+
+  async readGraph() {
+    const [nodes, edges] = await Promise.all([this.readNodes(), this.readEdges()]);
+    return { nodes, edges };
+  }
+
+  /**
+   * Propose a decision-registry topic file. Renders frontmatter compatible with
+   * schemas/decision-record.schema.json + the promote sub-flow. Never writes.
+   */
+  async proposeWrite(intent = {}) {
+    const { subject, body = "", decided, evidence = [] } = intent;
+    if (!subject) throw new Error("git-repo proposeWrite requires intent.subject");
+    const slug = intent.slug || slugify(subject);
+    const evLines = (evidence.length ? evidence : [{ kind: "doc", ref: "TODO: link durable provenance" }])
+      .flatMap((e) => [`  - kind: ${e.kind}`, `    ref: ${e.ref}`]);
+    const rendered = [
+      "---",
+      "status: current",
+      `subject: ${subject}`,
+      `decided: ${decided || new Date().toISOString().slice(0, 10)}`,
+      "evidence:",
+      ...evLines,
+      "---",
+      "",
+      `# ${subject}`,
+      "",
+      body,
+    ].join("\n");
+    return proposal({
+      provider: PROVIDER_ID,
+      kind: "decision-topic",
+      target: { path: `docs/decisions/${slug}.md`, slug },
+      payload: { subject, slug, decided, evidence, body },
+      rendered,
+      rationale: intent.rationale || "Proposed decision topic — enact via the promote sub-flow (write docs/decisions/<slug>.md, add the subject noun to CONTEXT.md, run check:decisions).",
+      provenance: provenance({ provider: PROVIDER_ID, source: `docs/decisions/${slug}.md`, agent: this.agent }),
+    });
+  }
+}
+
+export default GitRepoProvider;

package/kits/knowledge/providers/health/health-pass.test.js

@@ -0,0 +1,99 @@
+/**
+ * Provider-agnostic health verbs — AC1 + AC2 (issue #317).
+ *
+ *   AC1: the SAME health command over the vault provider and the git-repo
+ *        provider yields schema-valid reports (R1, R2, R4).
+ *   AC2: a backlog pass over the work-item adapter flags a SEEDED duplicate and
+ *        a SEEDED broken blocker link, from a fixture — never the real board
+ *        (R3, R4).
+ *
+ * Run: node --test kits/knowledge/providers/health/health-pass.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 { 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 DefaultKnowledgeStore from "../../adapters/default-store/index.js";
+import { detectDuplicates, checkDependencyLinkIntegrity } from "./index.js";
+import { loadSchemas } from "../lib/model.js";
+import { validate } from "../lib/schema-validate.js";
+
+const __dirname = path.dirname(fileURLToPath(import.meta.url));
+const FIXTURES = path.join(__dirname, "../conformance/fixtures");
+const { healthReport: REPORT_SCHEMA } = loadSchemas();
+
+function assertReport(report, expectCheck, expectProvider) {
+  const { valid, errors } = validate(report, REPORT_SCHEMA);
+  assert.ok(valid, `report not schema-valid:\n  ${errors.join("\n  ")}`);
+  assert.equal(report.check, expectCheck);
+  assert.equal(report.provider, expectProvider);
+  assert.equal(report.summary.finding_count, report.findings.length);
+}
+
+async function vaultGraph() {
+  const dir = fs.mkdtempSync(path.join(os.tmpdir(), "kg-vault-health-"));
+  const store = new DefaultKnowledgeStore({ storeRoot: dir });
+  const a = await store.create({ type: "compiled", title: "Caching strategy", body: "use LRU", category: "eng", provenance: { agent: "t" } });
+  const b = await store.create({ type: "compiled", title: "Caching strategy", body: "use LRU everywhere", category: "eng", provenance: { agent: "t" } });
+  await store.link(b, [{ target_id: a, kind: "refines" }], { agent: "t" });
+  const provider = new MarkdownVaultProvider({ store, storeRoot: dir, agent: "t" });
+  const graph = await provider.readGraph();
+  fs.rmSync(dir, { recursive: true, force: true });
+  return graph;
+}
+
+describe("AC1: same health command over two providers yields schema-valid reports", () => {
+  test("vault provider: duplicate + integrity reports are schema-valid", async () => {
+    const graph = await vaultGraph();
+    assertReport(detectDuplicates(graph, { provider: "markdown-vault" }), "duplicate-detection", "markdown-vault");
+    assertReport(checkDependencyLinkIntegrity(graph, { provider: "markdown-vault" }), "dependency-link-integrity", "markdown-vault");
+  });
+
+  test("git-repo provider: duplicate + integrity reports are schema-valid", async () => {
+    const provider = new GitRepoProvider({ repoRoot: path.join(FIXTURES, "git-repo"), agent: "t" });
+    const graph = await provider.readGraph();
+    assertReport(detectDuplicates(graph, { provider: "git-repo" }), "duplicate-detection", "git-repo");
+    assertReport(checkDependencyLinkIntegrity(graph, { provider: "git-repo" }), "dependency-link-integrity", "git-repo");
+  });
+});
+
+describe("AC2: backlog pass over the work-item adapter flags seeded dupe + broken blocker", () => {
+  async function workItemGraph() {
+    const issues = fs.readFileSync(path.join(FIXTURES, "work-item", "issues.json"), "utf8");
+    const provider = new WorkItemProvider({ repo: "seed/fixture", runner: async () => issues, agent: "t" });
+    return provider.readGraph();
+  }
+
+  test("duplicate detection flags the seeded #14 ~ #15 pair", async () => {
+    const graph = await workItemGraph();
+    const report = detectDuplicates(graph, { provider: "work-item" });
+    assertReport(report, "duplicate-detection", "work-item");
+    const dupe = report.findings.find(
+      (f) => f.node_ids.includes("issue:14") && f.node_ids.includes("issue:15"),
+    );
+    assert.ok(dupe, "expected a duplicate finding for issue:14 ~ issue:15");
+    assert.equal(dupe.kind, "duplicate-nodes");
+  });
+
+  test("dependency-link integrity flags the seeded broken blocker (#999 -> #20)", async () => {
+    const graph = await workItemGraph();
+    const report = checkDependencyLinkIntegrity(graph, { provider: "work-item" });
+    assertReport(report, "dependency-link-integrity", "work-item");
+    const broken = report.findings.find(
+      (f) => f.node_ids.includes("issue:999") && f.node_ids.includes("issue:20"),
+    );
+    assert.ok(broken, "expected a broken-blocker finding for issue:999 -> issue:20");
+    assert.equal(broken.kind, "broken-dependency-link");
+    assert.equal(broken.severity, "error");
+    // the valid blocker #14 -> #20 must NOT be flagged
+    const falsePositive = report.findings.find((f) => f.node_ids.includes("issue:14") && f.node_ids.includes("issue:20"));
+    assert.ok(!falsePositive, "valid blocker #14 -> #20 must not be flagged");
+  });
+});

package/kits/knowledge/providers/health/index.js

@@ -0,0 +1,153 @@
+/**
+ * Provider-agnostic knowledge-health verbs.
+ *
+ * Each verb takes a graph ({ nodes, edges }) produced by ANY provider that
+ * implements the read side of the knowledge-store contract and returns a
+ * schema-valid Knowledge Health Report (schemas/knowledge/health-report.schema.json).
+ * The verbs never inspect provider internals — that is what lets the SAME health
+ * command run identically over the vault, git-repo, and work-item providers
+ * (AC1, AC2, R4).
+ *
+ * @module providers/health
+ */
+
+import { loadSchemas } from "../lib/model.js";
+import { assertValid } from "../lib/schema-validate.js";
+
+const { healthReport: HEALTH_SCHEMA } = loadSchemas();
+
+/** Normalise a title into a comparable token set. */
+function tokenize(title) {
+  return new Set(
+    String(title || "")
+      .toLowerCase()
+      .replace(/[^a-z0-9\s]/g, " ")
+      .split(/\s+/)
+      .filter(Boolean),
+  );
+}
+
+function jaccard(a, b) {
+  if (a.size === 0 && b.size === 0) return 0;
+  let inter = 0;
+  for (const t of a) if (b.has(t)) inter++;
+  const union = a.size + b.size - inter;
+  return union === 0 ? 0 : inter / union;
+}
+
+function finalize(report) {
+  report.summary.finding_count = report.findings.length;
+  assertValid(report, HEALTH_SCHEMA, `health report (${report.check})`);
+  return report;
+}
+
+/**
+ * Duplicate detection: flag node PAIRS whose titles are the same or highly
+ * similar (token Jaccard >= threshold). Scoped to same-type pairs by default so
+ * a decision and an issue with a shared word are not conflated.
+ *
+ * @param {{nodes: object[], edges: object[]}} graph
+ * @param {object} [options]
+ * @param {string} [options.provider="unknown"]
+ * @param {number} [options.threshold=0.7]
+ * @param {boolean} [options.crossType=false] compare across node types when true
+ * @param {string} [options.generatedAt]
+ */
+export function detectDuplicates(graph, options = {}) {
+  const nodes = graph.nodes || [];
+  const edges = graph.edges || [];
+  const threshold = typeof options.threshold === "number" ? options.threshold : 0.7;
+  const crossType = options.crossType === true;
+
+  const report = {
+    schema_version: "1.0",
+    check: "duplicate-detection",
+    provider: options.provider || "unknown",
+    generated_at: options.generatedAt || new Date().toISOString(),
+    summary: { nodes_examined: nodes.length, edges_examined: edges.length, finding_count: 0 },
+    findings: [],
+  };
+
+  const tokenized = nodes.map((n) => ({ node: n, tokens: tokenize(n.title) }));
+  for (let i = 0; i < tokenized.length; i++) {
+    for (let j = i + 1; j < tokenized.length; j++) {
+      const a = tokenized[i];
+      const b = tokenized[j];
+      if (!crossType && a.node.type !== b.node.type) continue;
+      const score = jaccard(a.tokens, b.tokens);
+      if (score >= threshold) {
+        report.findings.push({
+          kind: "duplicate-nodes",
+          severity: "warning",
+          node_ids: [a.node.id, b.node.id],
+          message: `Possible duplicate ${a.node.type} nodes: "${a.node.title}" ~ "${b.node.title}" (similarity ${score.toFixed(2)})`,
+          evidence: {
+            similarity: Number(score.toFixed(4)),
+            threshold,
+            title_a: a.node.title,
+            title_b: b.node.title,
+            type: a.node.type,
+          },
+        });
+      }
+    }
+  }
+  return finalize(report);
+}
+
+/**
+ * Dependency-link integrity: flag dependency edges whose endpoints do not
+ * resolve to a node present in the graph. An edge marked resolved:false is a
+ * deliberate external reference and is skipped.
+ *
+ * @param {{nodes: object[], edges: object[]}} graph
+ * @param {object} [options]
+ * @param {string} [options.provider="unknown"]
+ * @param {string[]} [options.dependencyTypes=["blocks"]] edge types treated as dependency links
+ * @param {string} [options.generatedAt]
+ */
+export function checkDependencyLinkIntegrity(graph, options = {}) {
+  const nodes = graph.nodes || [];
+  const edges = graph.edges || [];
+  const depTypes = new Set(options.dependencyTypes || ["blocks"]);
+  const ids = new Set(nodes.map((n) => n.id));
+
+  const report = {
+    schema_version: "1.0",
+    check: "dependency-link-integrity",
+    provider: options.provider || "unknown",
+    generated_at: options.generatedAt || new Date().toISOString(),
+    summary: { nodes_examined: nodes.length, edges_examined: edges.length, finding_count: 0 },
+    findings: [],
+  };
+
+  for (const e of edges) {
+    if (!depTypes.has(e.type)) continue;
+    if (e.resolved === false) continue; // deliberate external ref
+    const sourceMissing = !ids.has(e.from);
+    const targetMissing = !ids.has(e.to);
+    if (!sourceMissing && !targetMissing) continue;
+    report.findings.push({
+      kind: "broken-dependency-link",
+      severity: "error",
+      edge_ids: [e.id],
+      node_ids: [e.from, e.to],
+      message: `Broken ${e.type} link ${e.from} -> ${e.to}: ${
+        targetMissing ? `target '${e.to}' not found` : ""
+      }${targetMissing && sourceMissing ? "; " : ""}${sourceMissing ? `source '${e.from}' not found` : ""}`.trim(),
+      evidence: {
+        edge_type: e.type,
+        from: e.from,
+        to: e.to,
+        source_missing: sourceMissing,
+        target_missing: targetMissing,
+      },
+    });
+  }
+  return finalize(report);
+}
+
+export const HEALTH_VERBS = Object.freeze({
+  "duplicate-detection": detectDuplicates,
+  "dependency-link-integrity": checkDependencyLinkIntegrity,
+});

package/kits/knowledge/providers/index.js

@@ -0,0 +1,24 @@
+/**
+ * Knowledge Kit store providers — public entry point.
+ *
+ * Typed graph model (nodes / edges / provenance) with pluggable providers behind
+ * one read + proposals-only write interface, plus provider-agnostic health verbs.
+ * See context/contracts/knowledge-store-contract.md.
+ *
+ * @module providers
+ */
+
+export { MarkdownVaultProvider } from "./markdown-vault/index.js";
+export { GitRepoProvider } from "./git-repo/index.js";
+export { WorkItemProvider, parseWorkItemMetadata } from "./work-item/index.js";
+export { detectDuplicates, checkDependencyLinkIntegrity, HEALTH_VERBS } from "./health/index.js";
+export {
+  EDGE_TYPES,
+  CORE_NODE_TYPES,
+  loadSchemas,
+  node,
+  edge,
+  proposal,
+  provenance,
+} from "./lib/model.js";
+export { validate, assertValid } from "./lib/schema-validate.js";

package/kits/knowledge/providers/lib/model.js

@@ -0,0 +1,91 @@
+/**
+ * Knowledge graph model helpers: node / edge / proposal / provenance
+ * constructors, the closed edge-type vocabulary, the recommended node-type
+ * vocabulary, and loaders for the JSON schemas that define them.
+ *
+ * @module providers/lib/model
+ */
+
+import * as fs from "node:fs";
+import * as path from "node:path";
+import { fileURLToPath } from "node:url";
+
+const __dirname = path.dirname(fileURLToPath(import.meta.url));
+const SCHEMA_DIR = path.resolve(__dirname, "../../../../schemas/knowledge");
+
+/** Closed vocabulary of edge types (schema-enforced). */
+export const EDGE_TYPES = Object.freeze([
+  "supersedes",
+  "merged-into",
+  "blocks",
+  "evidence-of",
+  "mentions",
+  "relates",
+]);
+
+/** Recommended core node types. EXTENSIBLE — providers may emit others. */
+export const CORE_NODE_TYPES = Object.freeze([
+  "note",
+  "decision",
+  "issue",
+  "session",
+  "person",
+]);
+
+let _schemaCache = null;
+/** Load and cache the four graph schemas. */
+export function loadSchemas() {
+  if (_schemaCache) return _schemaCache;
+  const read = (name) => JSON.parse(fs.readFileSync(path.join(SCHEMA_DIR, name), "utf8"));
+  _schemaCache = {
+    node: read("node.schema.json"),
+    edge: read("edge.schema.json"),
+    proposal: read("proposal.schema.json"),
+    healthReport: read("health-report.schema.json"),
+  };
+  return _schemaCache;
+}
+
+/** Build a provenance object. */
+export function provenance({ provider, source, locator, retrievedAt, agent }) {
+  const p = {
+    provider,
+    source,
+    retrieved_at: retrievedAt || new Date().toISOString(),
+  };
+  if (locator) p.locator = locator;
+  if (agent) p.agent = agent;
+  return p;
+}
+
+/** Build a node. Omits empty optional fields so schema additionalProperties holds. */
+export function node({ id, type, title, body, attributes, provenance: prov }) {
+  const n = { id, type, title, provenance: prov };
+  if (body !== undefined) n.body = body;
+  if (attributes && Object.keys(attributes).length) n.attributes = attributes;
+  return n;
+}
+
+/** Build an edge. `resolved` defaults to true (an internal dependency link). */
+export function edge({ id, type, from, to, resolved, attributes, provenance: prov }) {
+  const e = { id, type, from, to, provenance: prov };
+  if (resolved === false) e.resolved = false;
+  if (attributes && Object.keys(attributes).length) e.attributes = attributes;
+  return e;
+}
+
+/** Build a proposal. status is always "proposed" — proposals-only by construction. */
+export function proposal({ provider, kind, target, payload, rendered, rationale, provenance: prov }) {
+  const p = {
+    schema_version: "1.0",
+    provider,
+    kind,
+    target: target || {},
+    status: "proposed",
+    provenance: prov,
+  };
+  if (payload) p.payload = payload;
+  if (rendered !== undefined) p.rendered = rendered;
+  if (rationale) p.rationale = rationale;
+  return p;
+}