npm - @kontourai/flow-agents - Versions diffs - 2.4.0 → 3.1.0 - Mend

@kontourai/flow-agents 2.4.0 → 3.1.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.

Files changed (195) hide show

package/kits/knowledge/docs/store-contract.md CHANGED Viewed

@@ -26,6 +26,7 @@ The store holds three record types. Every record, regardless of type, shares a c
 | `body` | string | yes | Primary content. Format is type-specific (see below). |
 | `category` | string | yes | Dot-separated hierarchical category string, e.g. `"engineering.api"`. Must be non-empty. |
 | `tags` | string[] | no | Flat list of tag strings for secondary classification. |
+| `aliases` | string[] | no | Human-readable, category-scoped slug aliases resolvable via `get`/`getLinks` (Addendum H). Append-only; never changes `id`. |
 | `links` | Link[] | no | Outbound links from this record (see §2). |
 | `provenance` | Provenance | yes | Immutable creation provenance (see §4). |
 | `created_at` | ISO-8601 string | yes | Creation timestamp in UTC. |
@@ -342,11 +343,14 @@ The adapter MUST implement:
 | Method | Signature | Description |
 |---|---|---|
-| `get` | `(id: string) => Record \| null` | Retrieve record by id. Returns null if not found. |
-| `getLinks` | `(id: string) => { forward: Link[], reverse: Link[] }` | Return all links for a record from the graph index. |
+| `get` | `(idOrHandle: string) => Record \| null` | Retrieve a record. `idOrHandle` may be a full id, a slug alias, or an unambiguous id prefix (Addendum H). Returns null if it resolves to nothing; throws `AMBIGUOUS_ID` on an ambiguous prefix. |
+| `getLinks` | `(idOrHandle: string) => { forward: Link[], reverse: Link[] }` | Return all links for a record from the graph index. Accepts the same handle forms as `get`; an unresolved handle yields empty arrays, an ambiguous prefix throws `AMBIGUOUS_ID`. |
 | `listByCategory` | `(category: string, options?: { prefix?: boolean }) => Record[]` | List records by exact category match. If `prefix` is true, match all records whose category starts with the given string. |
 | `listByType` | `(type: RecordType) => Record[]` | List all records of a given type. |
+> **Identity resolution** (`get`/`getLinks`) is specified in full in **Addendum H**. The `prefix`
+> option on `listByCategory` is unrelated — it filters by *category* prefix, not by id.
 ---
 ## 8. Adapter Contract Summary
@@ -374,6 +378,15 @@ missing. The thrown error MUST have a `code` property set to `"MISSING_EVIDENCE"
 human-readable `message`. This enables the contract suite to distinguish enforcement failures
 from unexpected errors.
+### 8.1 Error Codes
+| `code` | Raised by | Meaning |
+|---|---|---|
+| `MISSING_EVIDENCE` | any mutation op; `create`/`update` when an `aliases` entry is malformed | A required evidence/provenance field is missing, or supplied input is invalid. |
+| `NOT_FOUND` | `link` (unknown `target_id`) and other ops that require an existing target | A referenced record id does not exist. |
+| `AMBIGUOUS_ID` | `get`, `getLinks` | An id prefix matched more than one record (Addendum H). The error carries a `matches` array of the colliding ids. MUST NOT be swallowed into a `null` return. |
+| `SLUG_CONFLICT` | `create`, `update` | A supplied slug alias is already assigned to a *different* record. |
 ---
 ## 9. YAML Frontmatter Convention (Default Adapter)
@@ -387,6 +400,7 @@ type: <raw|compiled|concept>
 title: <title>
 category: <category>
 tags: [<tag>, ...]
+aliases: [<slug>, ...]        # optional — human-readable, category-scoped (Addendum H)
 created_at: <ISO-8601>
 updated_at: <ISO-8601>
 provenance:
@@ -409,8 +423,9 @@ mutation_log:
 <body text, may include [[wikilinks]]>
 ```
-Files are stored as `<store_root>/records/<id>.md`. The graph index lives at
-`<store_root>/graph-index.json`.
+Files are stored as `<store_root>/records/<id>.md` — keyed by the full `id`, unchanged by this
+addendum. The graph index lives at `<store_root>/graph-index.json`; the slug alias map (Addendum H)
+lives at `<store_root>/alias-index.json`.
 ---
@@ -1034,3 +1049,96 @@ interface ContradictionFlag {
 counts the in-scope compiled records, `compared` counts the similar pairs the contradiction fn
 judged, and `flags` lists the conflicting pairs. Gate telemetry is emitted at `collect-gate` and
 `flag-gate` (`knowledge.detect-contradictions`).
+## Addendum H — Record Identity Resolution (short-id prefix + slug aliases, #339)
+### H.1 Motivation
+On-disk identity is a full `id` (§1.1) plus a file path (§9). Prose that cites a record — a
+curated doc, a commit message, an issue comment — cannot practically carry a full 36-char UUID, so
+the field partner cites **8-char short ids** (`12cc5573`, `f5df7b4c`) and would prefer
+**human-readable slugs**. Neither resolves against exact-id `get`, and a store restructure that
+re-files a record silently severs every inbound short-id/slug reference.
+This addendum adds a **resolution layer** over the unchanged on-disk identity. It changes nothing
+about how records are stored (H.6) — it only widens what `get`/`getLinks` accept as input.
+### H.2 Resolvable Handle Forms
+`get(handle)` and `getLinks(handle)` MUST resolve, in this precedence order:
+1. **Exact full id** — `handle` equals a stored record `id`. (Unchanged §7 behavior; the O(1)
+   hot path.)
+2. **Slug alias** — `handle` is a registered alias in the alias map (H.4) whose target still exists.
+3. **Unambiguous id prefix** — `handle` is at least `MIN_ID_PREFIX` (**8**) characters and is a
+   prefix of **exactly one** record `id`.
+The first form that matches wins. A `handle` that matches none of the three resolves to *nothing*.
+### H.3 Resolution Outcomes
+| Situation | `get` | `getLinks` |
+|---|---|---|
+| Resolves to exactly one record | returns that record | returns that record's `{ forward, reverse }` |
+| Resolves to nothing (no exact id, no alias, no ≥8-char single-match prefix) | returns `null` | returns `{ forward: [], reverse: [] }` |
+| Prefix (≥8 chars) matches **more than one** record | **throws `AMBIGUOUS_ID`** | **throws `AMBIGUOUS_ID`** |
+An `AMBIGUOUS_ID` error MUST have `code === "AMBIGUOUS_ID"`, a human-readable `message`, and a
+`matches` array of the colliding full ids. An ambiguous prefix MUST NOT be silently resolved to one
+arbitrary record, nor collapsed to `null` — ambiguity is a distinct, surfaced condition.
+A `handle` **shorter than `MIN_ID_PREFIX`** is never treated as a prefix (it can still match an
+exact id or a slug). This keeps a stray short token from matching a large, surprising set.
+### H.4 Slug Aliases
+- A slug is a lowercase, category-scoped, human-readable handle, e.g.
+  `decision.strategy/2026-07-03-gtm-direction`. It MUST match
+  `^[a-z0-9]([a-z0-9._/-]*[a-z0-9])?$` (≤ 200 chars). Malformed slugs are rejected at
+  `create`/`update` with `MISSING_EVIDENCE`.
+- Slugs are **caller-supplied** via the optional `aliases: string[]` field on `create` and
+  `update`. The store does **not** auto-derive slugs (auto-slugging is a future concern) — the
+  date-stamped examples cannot be derived from title alone.
+- Aliases are **append-only**: `update` with an `aliases` field UNIONs the supplied slugs with the
+  record's existing aliases; it never drops a previously issued slug. This is what guarantees H.5.
+- A slug already assigned to a *different* record is a `SLUG_CONFLICT` (a slug identifies at most
+  one record). Re-supplying a record's own slug is an idempotent no-op.
+### H.5 Restructure Survival (the alias map)
+The alias map is a store-level structure `{ slug → id }`. It is keyed by **full id** — never by
+category or file path. Therefore:
+- Recategorizing a record via `update` (which, in the Obsidian adapter, **relocates the note's
+  file**) leaves both the `id` and the `slug → id` mapping untouched.
+- The id still resolves (it is the record's stable key); the short-id prefix still resolves (it is
+  a prefix of that unchanged id); the slug still resolves (the map still points it at that id).
+So a previously issued short-id prefix or slug MUST still resolve to the same record after a
+restructure. Note the slug is a **stable alias**, not a value recomputed from the current category:
+a slug minted under `decision.strategy/…` keeps resolving even after the record moves to
+`decision.gtm`.
+Like the graph index (§5.2), the alias map is a **derived cache** — each record's own `aliases`
+array is the source of truth, so an adapter that persists the map SHOULD rebuild it on `reindex()`.
+The default adapter persists it at `<store_root>/alias-index.json`
+(`{ schema_version, by_slug: { <slug>: <id> } }`).
+### H.6 On-Disk Identity Is Unchanged (non-goals)
+- The `id` in the §1.1 envelope and the `records/<id>.md` file naming (§9) are **unchanged**.
+  Aliases are a resolution layer, not a rename.
+- Exact-id `get`/`getLinks` behavior is byte-for-byte unchanged.
+- This addendum does **not** migrate existing stores or repair already-broken citations — an
+  adapter/repo may seed its own alias map for legacy short ids, but that is out of scope here.
+- Full-text/semantic search is out of scope.
+### H.7 Resolution Constants
+| Constant | Value | Meaning |
+|---|---|---|
+| `MIN_ID_PREFIX` | `8` | Minimum handle length eligible for prefix resolution. |
+| slug pattern | `^[a-z0-9]([a-z0-9._/-]*[a-z0-9])?$` | Valid slug alias shape (≤ 200 chars). |
+An independent adapter conforms to this addendum when the `identity: *` sections of the contract
+suite (`evals/contract-suite/suite.test.js`, §15–§17) pass against it.

package/kits/knowledge/evals/contract-suite/suite.test.js CHANGED Viewed

@@ -873,4 +873,180 @@ describe("Knowledge Kit Store Contract Suite", () => {
       assert.ok(typeof record.body === "string", "body is a string");
     });
   });
+  // -----------------------------------------------------------------------
+  // §15  identity resolution — short-id prefix (AC1, R1)
+  //
+  // `get`/`getLinks` accept an unambiguous id prefix (>= 8 chars). An ambiguous
+  // prefix throws AMBIGUOUS_ID (a distinct code), never guesses or returns null.
+  // On-disk identity is unchanged (R4): records are still keyed by full id.
+  // -----------------------------------------------------------------------
+  describe("identity: short-id prefix resolution (AC1)", () => {
+    let dir, store;
+    before(() => { dir = makeTempDir(); store = makeStore(dir); });
+    after(() => fs.rmSync(dir, { recursive: true, force: true }));
+    test("get resolves a unique 8-char id prefix to the record", async () => {
+      const id = await store.create({
+        type: "concept", title: "Prefix Target", body: "b",
+        category: "decision.strategy", provenance: { agent: "tester" },
+      });
+      const prefix = id.slice(0, 8);
+      assert.equal(prefix.length, 8, "sanity: prefix is 8 chars");
+      const rec = await store.get(prefix);
+      assert.ok(rec, "8-char prefix resolves to a record");
+      assert.equal(rec.id, id, "prefix resolves to the correct full id");
+    });
+    test("getLinks resolves a unique 8-char id prefix", async () => {
+      const targetId = await store.create({
+        type: "concept", title: "PrefixLinkTarget", body: "t",
+        category: "test", provenance: { agent: "tester" },
+      });
+      const sourceId = await store.create({
+        type: "raw", title: "PrefixLinkSource", body: "s", category: "test",
+        links: [{ target_id: targetId, kind: "related" }],
+        provenance: { agent: "tester" },
+      });
+      const { forward } = await store.getLinks(sourceId.slice(0, 8));
+      assert.ok(forward.some((l) => l.target_id === targetId && l.kind === "related"),
+        "getLinks via an 8-char prefix returns the record's forward links");
+    });
+    test("an ambiguous prefix throws AMBIGUOUS_ID (never returns null)", async () => {
+      // Two records whose full ids deliberately share an 8-char prefix. create
+      // accepts an explicit id (§1.1: adapter MAY generate), so the collision is
+      // deterministic without depending on random UUIDs colliding.
+      await store.create({
+        id: "abcdef12-0000-0000-0000-000000000001",
+        type: "raw", title: "Ambiguous One", body: "1", category: "test",
+        provenance: { agent: "tester" },
+      });
+      await store.create({
+        id: "abcdef12-0000-0000-0000-000000000002",
+        type: "raw", title: "Ambiguous Two", body: "2", category: "test",
+        provenance: { agent: "tester" },
+      });
+      await assert.rejects(
+        () => store.get("abcdef12"),
+        (err) => {
+          assert.equal(err.code, "AMBIGUOUS_ID",
+            `expected AMBIGUOUS_ID, got code=${err.code}: ${err.message}`);
+          return true;
+        }
+      );
+    });
+    test("a prefix shorter than the 8-char minimum does not resolve (null)", async () => {
+      await store.create({
+        id: "deadbeef-1111-1111-1111-111111111111",
+        type: "raw", title: "Short Prefix Guard", body: "x", category: "test",
+        provenance: { agent: "tester" },
+      });
+      assert.equal(await store.get("dead"), null, "a <8-char token is never a prefix match");
+    });
+    test("exact full-id get is unchanged (R4)", async () => {
+      const id = await store.create({
+        type: "raw", title: "Exact Id", body: "e", category: "test",
+        provenance: { agent: "tester" },
+      });
+      const rec = await store.get(id);
+      assert.equal(rec.id, id, "exact-id get still returns the record");
+    });
+  });
+  // -----------------------------------------------------------------------
+  // §16  identity resolution — slug aliases (AC2, R2)
+  //
+  // Records carry human-readable, category-scoped slug aliases; `get`/`getLinks`
+  // resolve them through the same surface, whether set at create or via update.
+  // -----------------------------------------------------------------------
+  describe("identity: slug alias resolution (AC2)", () => {
+    let dir, store;
+    before(() => { dir = makeTempDir(); store = makeStore(dir); });
+    after(() => fs.rmSync(dir, { recursive: true, force: true }));
+    test("a record created with a slug alias resolves via get(slug) and getLinks(slug)", async () => {
+      const slug = "decision.strategy/2026-07-03-gtm-direction";
+      const targetId = await store.create({
+        type: "concept", title: "GTM Target", body: "t",
+        category: "decision.strategy", provenance: { agent: "tester" },
+      });
+      const id = await store.create({
+        type: "compiled", title: "GTM Direction", body: "the decision",
+        category: "decision.strategy", aliases: [slug],
+        links: [{ target_id: targetId, kind: "related" }],
+        provenance: { agent: "tester" },
+      });
+      const rec = await store.get(slug);
+      assert.ok(rec, "slug resolves to a record");
+      assert.equal(rec.id, id, "get(slug) returns the aliased record");
+      const { forward } = await store.getLinks(slug);
+      assert.ok(forward.some((l) => l.target_id === targetId),
+        "getLinks(slug) returns the aliased record's links");
+    });
+    test("a slug alias added via update resolves through the same surface", async () => {
+      const id = await store.create({
+        type: "concept", title: "Later Slug", body: "b",
+        category: "decision.strategy", provenance: { agent: "tester" },
+      });
+      await store.update(id, { aliases: ["decision.strategy/added-later"] }, { agent: "tester" });
+      const rec = await store.get("decision.strategy/added-later");
+      assert.ok(rec, "update-added slug resolves");
+      assert.equal(rec.id, id, "get(added slug) returns the record");
+    });
+    test("a malformed slug alias is rejected at create (MISSING_EVIDENCE)", () =>
+      assertMissingEvidence(
+        () => store.create({
+          type: "raw", title: "Bad Slug", body: "b", category: "test",
+          aliases: ["Not A Valid Slug!"], provenance: { agent: "tester" },
+        }),
+        "malformed slug alias"
+      ));
+  });
+  // -----------------------------------------------------------------------
+  // §17  identity resolution — survives restructure (AC3, R3)
+  //
+  // After `update` recategorizes a record (obsidian: the file relocates folders),
+  // the previously issued slug AND short-id prefix still resolve to the same
+  // record — the alias map is keyed by full id, never by category or path.
+  // -----------------------------------------------------------------------
+  describe("identity: alias resolution survives restructure (AC3)", () => {
+    let dir, store;
+    before(() => { dir = makeTempDir(); store = makeStore(dir); });
+    after(() => fs.rmSync(dir, { recursive: true, force: true }));
+    test("old slug and short-id prefix still resolve after a recategorize", async () => {
+      const slug = "decision.strategy/2026-06-18-market-fork";
+      const id = await store.create({
+        type: "concept", title: "Market Fork Decision", body: "original",
+        category: "decision.strategy", aliases: [slug],
+        provenance: { agent: "tester" },
+      });
+      const prefix = id.slice(0, 8);
+      // Pre-move sanity: both handles resolve.
+      assert.equal((await store.get(slug)).id, id, "slug resolves before move");
+      assert.equal((await store.get(prefix)).id, id, "prefix resolves before move");
+      // Restructure: recategorize. In the obsidian adapter this relocates the
+      // note from decision/strategy/ to decision/gtm/.
+      await store.update(id, { category: "decision.gtm" }, { agent: "tester" });
+      const moved = await store.get(id);
+      assert.equal(moved.category, "decision.gtm", "category changed on disk");
+      // The whole point of the alias map: old handles survive the restructure.
+      assert.equal((await store.get(slug)).id, id, "old slug survives the restructure");
+      assert.equal((await store.get(prefix)).id, id, "short-id prefix survives the restructure");
+      const { reverse } = await store.getLinks(id);
+      assert.ok(Array.isArray(reverse), "getLinks still answers for the moved record");
+    });
+  });
 });

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

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

package/kits/knowledge/kit.json CHANGED Viewed

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

package/kits/knowledge/promote/distill.js ADDED Viewed

@@ -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 ADDED Viewed

@@ -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 ADDED Viewed

@@ -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 ADDED Viewed

@@ -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 ADDED Viewed

@@ -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 ADDED Viewed

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