@kontourai/flow-agents 2.3.0 → 3.0.0

package/kits/builder/skills/verify-work/SKILL.md

@@ -39,7 +39,7 @@ This skill owns orchestration and routing. The verification contract owns phases
 
 ## Input
 
-- **Session file path**: the session file in `.flow-agents/<slug>/` (preferred)
+- **Session file path**: the session file in `.kontourai/flow-agents/<slug>/` (preferred)
 - The session file references the plan artifact (which has acceptance criteria) and execution progress (which has modified files)
 - If NO session file exists, delegate to tool-verifier directly (see Standalone Verification below)
 
@@ -84,6 +84,13 @@ Skip session file lookup — go straight to delegation.
 7. Write or update `evidence.json` with verification checks, top-level verdict, and `not_verified_gaps`
    - use `npm run workflow:sidecar -- record-evidence <artifact-dir> --verdict ... --check-json ...` when the repository provides it
    - `checks[].artifact_refs` must use structured evidence ref objects, not legacy strings
+   - for multi-repo or cross-product work, preserve a coverage matrix in the
+     evidence report or check summaries that lists each affected root and its
+     build/test, dependency/security, provider/CI, and accepted-gap status
+   - if external dependency audit or provider checks are blocked by approval,
+     privacy, credentials, network, or missing change-provider state, record the
+     affected roots as `not_verified` instead of collapsing the lane into a
+     generic pass/fail
 8. Update `acceptance.json` with criterion statuses and structured evidence refs
    - `criteria[].evidence_refs` must use structured evidence refs and map each AC id to command/test proof plus source refs for behavior claims
    - when source refs are missing for a behavior claim, mark the criterion `not_verified` or record an accepted gap instead of using broad prose-only evidence

package/kits/catalog.json

@@ -18,6 +18,12 @@
       "name": "Release Evidence Kit",
       "path": "kits/release-evidence",
       "description": "Minimal flows-only kit for proving agentless gate evaluation over surface claims in CI. One gate expects a trusted release.evidence claim."
+    },
+    {
+      "id": "veritas-governance",
+      "name": "Veritas Governance Kit",
+      "path": "kits/veritas-governance",
+      "description": "Agentless kit that gates a real `veritas readiness` verdict as a trust.bundle software-readiness-verdict claim. Wraps @kontourai/veritas via CLI + a kit-local adapter; does not reimplement standards evaluation."
     }
   ]
 }

package/kits/knowledge/kit.json

@@ -91,6 +91,31 @@
       "id": "knowledge.obsidian-store",
       "path": "adapters/obsidian-store/index.js",
       "description": "Obsidian store adapter: each record is one human-canonical Obsidian markdown note. Frontmatter carries all contract fields; body rendered with callouts (raw), readable prose + Sources/Related wikilink sections (compiled/concept/snapshot). Category dots map to folder hierarchy; title-slugified filenames with collision suffix; superseded records move to archive/ (supersede-not-delete invariant). Backed by shared codec with default-store."
+    },
+    {
+      "id": "knowledge.markdown-vault-provider",
+      "path": "providers/markdown-vault/index.js",
+      "description": "Knowledge store PROVIDER (issue #317): adapts the markdown-vault store behind the typed graph model (nodes/edges/provenance). Thin read + proposals-only wrapper over an existing store adapter; existing skills unaffected."
+    },
+    {
+      "id": "knowledge.git-repo-provider",
+      "path": "providers/git-repo/index.js",
+      "description": "Knowledge store PROVIDER (issue #317): reads git-tracked docs (docs/decisions/* tombstones+evidence, CONTEXT.md glossary, docs/learnings/*) as decision/note nodes with supersedes/merged-into/evidence-of edges. Write side = decision-topic proposals shaped for the promote sub-flow."
+    },
+    {
+      "id": "knowledge.work-item-provider",
+      "path": "providers/work-item/index.js",
+      "description": "Knowledge store PROVIDER/source-sink adapter (issue #317): maps GitHub issues to issue nodes and flow-agents:work-item-metadata blockers + prose refs to blocks/relates edges via an injectable gh runner. Write side = draft comment/label proposals. Enables backlog hygiene as a knowledge-health pass."
+    },
+    {
+      "id": "knowledge.health-verbs",
+      "path": "providers/health/index.js",
+      "description": "Provider-agnostic knowledge-health verbs (issue #317): detectDuplicates + checkDependencyLinkIntegrity over any provider's graph, returning schema-valid health reports (schemas/knowledge/health-report.schema.json)."
+    },
+    {
+      "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."
     }
   ],
   "evals": [
@@ -153,6 +178,16 @@
       "id": "knowledge.hygiene-review-suite",
       "path": "evals/hygiene-review/suite.test.js",
       "description": "Eval cases for hygiene-review (#106 hygiene #5, closes the issue): opt-in orchestration (omitted audit block is skipped; empty review does nothing); each opted-in audit runs via its existing flow-runner method and its findings are collected verbatim (no detection reimplemented); proposals are normalized to adopt/retire/merge and each cites its sourceFlow + evidence; thin-orchestrator/consume-never-fork invariants — read-only by default mutates no record, no new gate is forked, the only mutation (glossary apply:true) is delegated to glossarySync's own gated propose→apply (verified via proposes-link + mutation-log on the resulting concept); sub-flow telemetry is folded in plus hygiene-review's own orchestrate-gate + review-gate; module-level export delegates to the runner."
+    },
+    {
+      "id": "knowledge.provider-conformance-suite",
+      "path": "providers/conformance/suite.test.js",
+      "description": "Conformance suite (issue #317, AC3): parameterized suite every knowledge store provider (markdown-vault, git-repo, work-item) must pass — read interface returns schema-valid nodes/edges with provenance, closed edge vocabulary, queryByType subset consistency, and proposeWrite returns a schema-valid 'proposed' proposal that mutates nothing (proposals-only)."
+    },
+    {
+      "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."
     }
   ],
   "skills": [

package/kits/knowledge/providers/conformance/fixtures/git-repo/CONTEXT.md

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

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

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

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

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

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

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

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

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

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

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

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

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

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