@kontourai/flow-agents 3.0.0 → 3.2.0

package/kits/builder/skills/execute-plan/SKILL.md

@@ -13,6 +13,19 @@ Plan artifact in, implemented code out. Fans out to tool-worker subagents in par
 |---|---|
 | tool-worker | Implementation per task spec (up to 4 parallel) |
 
+## Model Routing
+
+Worker slices (`tool-worker`) route by task shape: `delegate-implementation` for
+precisely-planned implementation (the default), `delegate-mechanical` for
+fully-specified mechanical slices (issue sync, doc/scan bookkeeping),
+`delegate-design` when a slice genuinely needs design latitude. Resolve the role
+from `.datum/config.json` (`npx @kontourai/datum resolve <role> --json`) and pass
+the model explicitly. On a review/verify gate failure of a slice, re-dispatch its
+fix one tier higher and record the escalation. See
+`context/contracts/execution-contract.md` § Delegation: Model Routing (and
+§ Escalation on gate failure). Fallback: inherit the session model when
+datum/config is absent, noted in the artifact.
+
 ## Orchestrator Rule
 
 You do not write source files. You read the plan artifact, fan out tasks to tool-worker, and update the session file between waves.

package/kits/builder/skills/fix-bug/SKILL.md

@@ -20,6 +20,23 @@ Inherited from primitives + diagnosis:
 | tool-verifier | verify-work |
 | tool-playwright | diagnosis (reproduce) + verify-work |
 
+## Model Routing
+
+Delegates are spawned with an explicit model override resolved from
+`.datum/config.json` via `npx @kontourai/datum resolve <role> --json` — see
+`context/contracts/execution-contract.md` § Delegation: Model Routing:
+
+| Delegate | Role |
+|---|---|
+| tool-worker | `delegate-mechanical` for fully-specified mechanical slices, `delegate-implementation` for precisely-planned implementation, `delegate-design` when a slice needs design latitude |
+| tool-planner | `delegate-design` |
+| tool-code-reviewer / tool-security-reviewer | `delegate-implementation` by default, raised to the worker's tier when higher — never below the tier of the checked work (Goodhart guard) |
+| tool-verifier / tool-playwright | `delegate-implementation` by default, raised to the worker's tier when higher — never below the tier of the checked work (Goodhart guard) |
+
+On a review/verify gate failure, re-dispatch the fix one tier higher and record
+the escalation (contract § Escalation on gate failure). Fallback: inherit the
+session model when datum/config is absent, noted in the artifact.
+
 ## Orchestrator Rule
 
 You never use `read`, `glob`, `grep`, or `code` on source files. All codebase analysis goes through tool-planner. All review goes through review-work. All verification goes through tool-verifier or tool-playwright.

package/kits/builder/skills/idea-to-backlog/SKILL.md

@@ -21,6 +21,16 @@ Convert raw ideas into shaped, prioritized, executable backlog without starting
 - Keep separate ideas separate until a shared outcome, hard dependency, or sequencing reason justifies bundling them.
 - Push back when the user blends unrelated ideas, and ask them to justify why the ideas belong together before shaping bundled work.
 
+## Model Routing
+
+When this skill delegates its shaping work (opportunity review, option
+exploration, slicing), resolve the `delegate-design` role from
+`.datum/config.json` (`npx @kontourai/datum resolve delegate-design --json`) and
+pass the resolved model explicitly — shaping a raw idea into a backlog needs
+design latitude, so it routes to the design tier. See
+`context/contracts/execution-contract.md` § Delegation: Model Routing. Fallback:
+inherit the session model when datum/config is absent, noted in the artifact.
+
 ## Artifact Contract
 
 Create or update `.kontourai/flow-agents/<slug>/<slug>--idea-to-backlog.md` with:

package/kits/builder/skills/pickup-probe/SKILL.md

@@ -115,15 +115,15 @@ When the gate fails, record `--status fail` with `--expectation pickup-probe-rea
 
 
 
-## Docs And ADR Policy
+## Docs-Write Policy: Two-Delta Emission
 
-`pickup-probe` may identify durable terminology and decision gaps, but it must keep documentation changes narrow:
+`pickup-probe` may identify durable terminology and decision gaps, but it must keep documentation changes narrow. Per `context/contracts/probe-docs-write-contract.md`, a **decision subject** crystallizing during pickup probing (a durable, reusable answer to a named domain question — not an implementation detail or transient planning choice) gets both deltas in the same motion:
 
-- Update `CONTEXT.md` inline only for glossary-style durable terminology decisions, using tight one- or two-sentence definitions and `_Avoid_` terms when useful. Keep implementation details out of `CONTEXT.md`.
+- Update `CONTEXT.md` inline only for glossary-style durable terminology decisions, using tight one- or two-sentence definitions and `_Avoid_` terms when useful. Keep implementation details out of `CONTEXT.md`. Coin the subject term first if it is not already a glossary entry — vocabulary is the decision registry's topic namespace (`context/contracts/decision-registry-contract.md` § Slug rules) — or refine the existing entry when a decision changes what it says.
 - If a `CONTEXT-MAP.md` exists, update the relevant context instead of assuming the root glossary owns the term.
 - Create a lazy context file only when a resolved term or workflow concept has no existing home.
 - Do not create context files for transient planning notes, open questions, or provider snapshots.
-- Propose or create ADRs sparingly, only when all three are true: the decision is hard to reverse, surprising without context, and the result of a real trade-off.
+- Record a decision delta at `docs/decisions/<slug>.md`: consult `docs/decisions/index.md` first and propose revise-vs-create (an existing topic file, including a `needs-decision` stub, is revised in place; only an uncovered subject gets a new file), then run `npm run gen:decisions-index && npm run check:decisions`. Link this Probe's own session artifact as a `session-archive` evidence ref (transcript provenance). Never propose or create a numbered ADR — `docs/adr/` is frozen history; decisions go into the topic-keyed registry.
 - Prefer workflow artifacts for pickup decisions, unresolved questions, accepted gaps, and route reasons until the work is accepted.
 
 ## Handoff To Plan Work

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

@@ -13,6 +13,15 @@ Goal + directory in, structured plan artifact out. Pure planning primitive.
 |---|---|
 | tool-planner | Codebase analysis, structured execution plan, writes plan artifact |
 
+## Model Routing
+
+Planning delegation (`tool-planner`) resolves the `delegate-design` role from
+`.datum/config.json` (`npx @kontourai/datum resolve delegate-design --json`) and
+passes the resolved model explicitly — turning a goal into a plan needs design
+latitude, so it routes to the design tier. See
+`context/contracts/execution-contract.md` § Delegation: Model Routing. Fallback:
+inherit the session model when datum/config is absent, noted in the artifact.
+
 ## Orchestrator Rule
 
 You do not read source files. You delegate to tool-planner and read the artifact it produces.

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

@@ -26,6 +26,16 @@ Select ready backlog work and prepare a bounded execution handoff without implem
 - Every pull-work artifact must correlate to selected backlog refs, shepherding refs for active PRs/sidecars/issues being finished before new work, or `backlog_gap=true` with a route to `idea-to-backlog`; direct audits with no new selection must record `shepherding_item_ids` or `backlog_gap`, not free-floating implementation scope.
 - A stale broad continuation instruction, such as "keep going", "pick up the next two", or "continue after merge", may allow queue inspection but must not bypass per-item pickup Probe evidence.
 
+## Model Routing
+
+Board selection, WIP/shepherding scans, dependency joins, liveness preflight, and
+issue-sync-style bookkeeping are fully-specified mechanical work: when this skill
+delegates them, resolve the `delegate-mechanical` role from `.datum/config.json`
+(`npx @kontourai/datum resolve delegate-mechanical --json`) and pass the resolved
+model explicitly. See `context/contracts/execution-contract.md` § Delegation:
+Model Routing. Fallback: inherit the session model when datum/config is absent,
+noted in the artifact.
+
 ## Inputs
 
 - Repository or working directory.

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

@@ -29,6 +29,17 @@ Keeping them separate makes failures route cleanly:
 | tool-dependencies-updater | Dependency review when package manifests, dependency manifests, package manager config, or lockfiles change |
 | configured architecture/domain/IaC/policy reviewer | Optional reviewer when the project or user configures one |
 
+## Model Routing
+
+Review roles never resolve **below** the tier of the work they check (Goodhart
+guard): default `delegate-implementation`, raised to match or exceed the tier
+that produced the work under review — a reviewer of `delegate-design` work
+resolves `delegate-design` or `orchestrator`, never a cheaper tier. Resolve the
+role from `.datum/config.json` (`npx @kontourai/datum resolve <role> --json`) and
+pass the model explicitly. See `context/contracts/execution-contract.md`
+§ Delegation: Model Routing and § Goodhart guard. Fallback: inherit the session
+model when datum/config is absent, noted in the artifact.
+
 ## Shared Contracts
 
 Follow:

package/kits/builder/skills/tdd-workflow/SKILL.md

@@ -25,6 +25,23 @@ Same as deliver (inherited from primitives):
 | tool-verifier | verify-work (with coverage check) |
 | tool-playwright | verify-work (if UI) |
 
+## Model Routing
+
+Delegates are spawned with an explicit model override resolved from
+`.datum/config.json` via `npx @kontourai/datum resolve <role> --json` — see
+`context/contracts/execution-contract.md` § Delegation: Model Routing:
+
+| Delegate | Role |
+|---|---|
+| tool-worker | `delegate-mechanical` for fully-specified mechanical slices, `delegate-implementation` for precisely-planned implementation (RED/GREEN/REFACTOR), `delegate-design` when a slice needs design latitude |
+| tool-planner | `delegate-design` |
+| tool-code-reviewer / tool-security-reviewer | `delegate-implementation` by default, raised to the worker's tier when higher — never below the tier of the checked work (Goodhart guard) |
+| tool-verifier / tool-playwright | `delegate-implementation` by default, raised to the worker's tier when higher — never below the tier of the checked work (Goodhart guard) |
+
+On a review/verify gate failure, re-dispatch the fix one tier higher and record
+the escalation (contract § Escalation on gate failure). Fallback: inherit the
+session model when datum/config is absent, noted in the artifact.
+
 ## Orchestrator Rule
 
 Same as deliver: you never touch source files. You coordinate the primitives with TDD-specific context.

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

@@ -16,6 +16,17 @@ Verification is not critique. Run `review-work` first when the task needs mainta
 | tool-verifier | Code verification, acceptance criteria checking, structured verdicts |
 | tool-playwright | Visual verification, screenshots, accessibility checks |
 
+## Model Routing
+
+Verify roles never resolve **below** the tier of the work they check (Goodhart
+guard): default `delegate-implementation`, raised to match or exceed the tier
+that produced the work under verification — a verifier of `delegate-design` work
+resolves `delegate-design` or `orchestrator`, never a cheaper tier. Resolve the
+role from `.datum/config.json` (`npx @kontourai/datum resolve <role> --json`) and
+pass the model explicitly. See `context/contracts/execution-contract.md`
+§ Delegation: Model Routing and § Goodhart guard. Fallback: inherit the session
+model when datum/config is absent, noted in the artifact.
+
 ## Orchestrator Rule
 
 You do not review source files. You delegate to tool-verifier and tool-playwright, then read the verdict artifact.

package/kits/knowledge/adapters/default-store/index.js

@@ -16,6 +16,22 @@ import * as fs from "node:fs";
 import * as path from "node:path";
 import { randomUUID } from "node:crypto";
 
+// Record-identity resolution layer (short-id prefix + slug aliases, issue #339).
+// Single-sourced in the shared codec so both bundled adapters resolve
+// identically; the rest of this adapter keeps its own zero-import helpers.
+import {
+  resolveRecordId,
+  normalizeAliases,
+  emptyAliasIndex,
+  loadAliasIndex,
+  saveAliasIndex,
+  registerAliases,
+  // Record-carried freshness + derived staleness (issue #341, Addendum J).
+  freshnessPatch,
+  decodeFreshnessFields,
+  isRecordStale,
+} from "../shared/codec.js";
+
 // ---------------------------------------------------------------------------
 // Error helpers
 // ---------------------------------------------------------------------------
@@ -140,7 +156,17 @@ function parseYamlLines(lines, start, baseIndent) {
 }
 
 function unquote(s) {
-  if ((s.startsWith('"') && s.endsWith('"')) || (s.startsWith("'") && s.endsWith("'"))) {
+  if (s.startsWith('"') && s.endsWith('"')) {
+    // Double-quoted scalars are escaped by yamlScalar; reverse those escapes
+    // (backslash, quote, newline, carriage-return, tab) left-to-right so a
+    // frontmatter value can carry newlines/quotes and round-trip intact. This
+    // keeps every scalar on ONE physical line, so an embedded "\n---\n" can
+    // never be mistaken for the frontmatter/body terminator (parseMarkdown).
+    return s.slice(1, -1).replace(/\\(["\\nrt])/g, (_, c) =>
+      c === "n" ? "\n" : c === "r" ? "\r" : c === "t" ? "\t" : c
+    );
+  }
+  if (s.startsWith("'") && s.endsWith("'")) {
     return s.slice(1, -1);
   }
   return s;
@@ -198,9 +224,20 @@ function serializeYaml(obj, indent = 0) {
 
 function yamlScalar(v) {
   if (typeof v === "string") {
-    // Quote if it contains special chars
-    if (/[:#\[\]{},&*?|<>=!%@`"'\n]/.test(v) || v.trim() !== v || v === "") {
-      return `"${v.replace(/\\/g, "\\\\").replace(/"/g, '\\"')}"`;
+    // Quote if it contains special chars (incl. any whitespace control char that
+    // would otherwise span lines — newline, carriage-return, tab).
+    if (/[:#\[\]{},&*?|<>=!%@`"'\n\r\t]/.test(v) || v.trim() !== v || v === "") {
+      // Escape backslash first, then quote and the control chars, so the value
+      // stays on ONE physical line. Reversed by unquote(). Without newline
+      // escaping a value like a multi-section proposal body would inject a raw
+      // "\n---\n" into the frontmatter and corrupt the record on read.
+      const escaped = v
+        .replace(/\\/g, "\\\\")
+        .replace(/"/g, '\\"')
+        .replace(/\n/g, "\\n")
+        .replace(/\r/g, "\\r")
+        .replace(/\t/g, "\\t");
+      return `"${escaped}"`;
     }
     return v;
   }
@@ -340,6 +377,7 @@ export class DefaultKnowledgeStore {
     this._root = path.resolve(storeRoot);
     this._recordsDir = path.join(this._root, "records");
     this._graphPath = path.join(this._root, "graph-index.json");
+    this._aliasPath = path.join(this._root, "alias-index.json");
     fs.mkdirSync(this._recordsDir, { recursive: true });
   }
 
@@ -351,12 +389,42 @@ export class DefaultKnowledgeStore {
     return path.join(this._recordsDir, `${id}.md`);
   }
 
+  // -- Record-identity resolution (short-id prefix + slug alias, issue #339) --
+
+  /** Does a record file exist for this exact full id? */
+  _idExists(id) {
+    return fs.existsSync(this._recordPath(id));
+  }
+
+  /** All full record ids, derived cheaply from the records/ directory. */
+  _listIds() {
+    if (!fs.existsSync(this._recordsDir)) return [];
+    return fs.readdirSync(this._recordsDir)
+      .filter((f) => f.endsWith(".md"))
+      .map((f) => f.slice(0, -3));
+  }
+
+  /**
+   * Resolve a query token (exact id, slug alias, or unambiguous id prefix) to a
+   * single full record id, or null when it resolves to nothing. Throws
+   * AMBIGUOUS_ID when a prefix matches more than one record.
+   */
+  _resolveId(input) {
+    const aliasIndex = loadAliasIndex(this._aliasPath);
+    return resolveRecordId(input, {
+      idExists: (rid) => this._idExists(rid),
+      listIds: () => this._listIds(),
+      bySlug: aliasIndex.by_slug,
+    });
+  }
+
   _readRecord(id) {
     const p = this._recordPath(id);
     if (!fs.existsSync(p)) return null;
     const text = fs.readFileSync(p, "utf8");
     const { meta, body } = parseMarkdown(text);
-    return { ...meta, body };
+    // Coerce record-carried freshness fields to canonical types (#341).
+    return decodeFreshnessFields({ ...meta, body });
   }
 
   _writeRecord(record) {
@@ -393,6 +461,19 @@ export class DefaultKnowledgeStore {
     const id = input.id || randomUUID();
     const now = this._now();
 
+    // Validate slug aliases (issue #339) and reserve them in the alias map
+    // BEFORE any write, so a SLUG_CONFLICT aborts create without a partial record.
+    const aliases = normalizeAliases(input.aliases);
+    let aliasIndex = null;
+    if (aliases.length) {
+      aliasIndex = loadAliasIndex(this._aliasPath);
+      registerAliases(aliasIndex, id, aliases);
+    }
+
+    // Validate optional freshness fields (#341) before any write, so a malformed
+    // expires_at / ttl_seconds aborts create without a partial record.
+    const fresh = freshnessPatch(input);
+
     // Merge explicit links + wikilinks from body
     const explicitLinks = input.links || [];
     const wikilinks = extractWikilinks(input.body || "");
@@ -404,9 +485,11 @@ export class DefaultKnowledgeStore {
       title: input.title,
       category: input.category,
       tags: input.tags || [],
+      ...(aliases.length ? { aliases } : {}),
       status: "active",
       created_at: now,
       updated_at: now,
+      ...fresh,
       provenance: {
         agent: input.provenance.agent,
         ...(input.provenance.session_id ? { session_id: input.provenance.session_id } : {}),
@@ -425,6 +508,9 @@ export class DefaultKnowledgeStore {
     addLinksToGraph(graph, id, links);
     saveGraph(this._graphPath, graph);
 
+    // Persist the alias map only after the record is on disk.
+    if (aliasIndex) saveAliasIndex(this._aliasPath, aliasIndex);
+
     return id;
   }
 
@@ -439,7 +525,7 @@ export class DefaultKnowledgeStore {
     const record = this._readRecord(id);
     if (!record) throw notFoundError(id);
 
-    const mutableKeys = ["title", "body", "category", "tags", "links"];
+    const mutableKeys = ["title", "body", "category", "tags", "links", "aliases", "expires_at", "ttl_seconds"];
     const supplied = mutableKeys.filter((k) => fields[k] !== undefined);
     if (supplied.length === 0)
       throw missingEvidenceError("update: at least one mutable field must be supplied");
@@ -447,8 +533,24 @@ export class DefaultKnowledgeStore {
     if (fields.category !== undefined && !validateCategory(fields.category))
       throw missingEvidenceError(`update: invalid category: ${fields.category}`);
 
+    // Validate/normalize supplied freshness fields (#341). A field set to null/""
+    // clears it (patch value undefined → dropped by the serializer).
+    const fresh = freshnessPatch(fields);
+
     const now = this._now();
 
+    // Slug aliases are append-only: supplied aliases are UNIONED with existing
+    // ones so a previously issued slug keeps resolving after a restructure (R3).
+    let mergedAliases = Array.isArray(record.aliases) ? record.aliases.slice() : [];
+    let aliasIndex = null;
+    if (fields.aliases !== undefined) {
+      const incoming = normalizeAliases(fields.aliases);
+      const seen = new Set(mergedAliases);
+      for (const s of incoming) if (!seen.has(s)) { seen.add(s); mergedAliases.push(s); }
+      aliasIndex = loadAliasIndex(this._aliasPath);
+      registerAliases(aliasIndex, id, mergedAliases);
+    }
+
     // Merge links if updated
     let newLinks = record.links || [];
     if (fields.links !== undefined) {
@@ -465,6 +567,8 @@ export class DefaultKnowledgeStore {
       ...(fields.body !== undefined ? { body: fields.body } : {}),
       ...(fields.category !== undefined ? { category: fields.category } : {}),
       ...(fields.tags !== undefined ? { tags: fields.tags } : {}),
+      ...(mergedAliases.length ? { aliases: mergedAliases } : {}),
+      ...fresh,
       links: newLinks,
       updated_at: now,
       mutation_log: [
@@ -486,6 +590,8 @@ export class DefaultKnowledgeStore {
     saveGraph(this._graphPath, graph);
 
     this._writeRecord(updated);
+
+    if (aliasIndex) saveAliasIndex(this._aliasPath, aliasIndex);
   }
 
   // -------------------------------------------------------------------------
@@ -843,7 +949,12 @@ export class DefaultKnowledgeStore {
   // -------------------------------------------------------------------------
 
   async get(id) {
-    return this._readRecord(id);
+    // Accept an exact id, a slug alias, or an unambiguous id prefix (issue #339).
+    // Unresolved → null (unchanged missing-record semantics); ambiguous prefix
+    // → throws AMBIGUOUS_ID.
+    const resolvedId = this._resolveId(id);
+    if (!resolvedId) return null;
+    return this._readRecord(resolvedId);
   }
 
   // -------------------------------------------------------------------------
@@ -851,10 +962,13 @@ export class DefaultKnowledgeStore {
   // -------------------------------------------------------------------------
 
   async getLinks(id) {
+    // Resolve prefix/slug to a full id; fall back to the raw token when it
+    // resolves to nothing so unknown ids still return empty arrays (not throw).
+    const key = this._resolveId(id) || id;
     const graph = loadGraph(this._graphPath);
     return {
-      forward: (graph.forward[id] || []).map((l) => ({ ...l })),
-      reverse: (graph.reverse[id] || []).map((l) => ({ ...l })),
+      forward: (graph.forward[key] || []).map((l) => ({ ...l })),
+      reverse: (graph.reverse[key] || []).map((l) => ({ ...l })),
     };
   }
 
@@ -865,18 +979,19 @@ export class DefaultKnowledgeStore {
   async listByCategory(category, options = {}) {
     const records = this._allRecords();
     const includeRetired = options.includeRetired === true;
+    // Derived staleness filter (#341): keep only records past their own effective
+    // expiry at `now` (injectable for tests). Absent → no staleness filtering.
+    const staleOnly = options.stale === true;
+    const nowMs = options.now !== undefined ? new Date(options.now).getTime() : Date.now();
+    const keep = (r) =>
+      (includeRetired || (r.status || "active") !== "retired") &&
+      (!staleOnly || isRecordStale(r, nowMs));
     if (options.prefix) {
       return records.filter(
-        (r) =>
-          (r.category === category || r.category.startsWith(`${category}.`)) &&
-          (includeRetired || (r.status || "active") !== "retired")
+        (r) => (r.category === category || r.category.startsWith(`${category}.`)) && keep(r)
       );
     }
-    return records.filter(
-      (r) =>
-        r.category === category &&
-        (includeRetired || (r.status || "active") !== "retired")
-    );
+    return records.filter((r) => r.category === category && keep(r));
   }
 
   // -------------------------------------------------------------------------
@@ -885,10 +1000,14 @@ export class DefaultKnowledgeStore {
 
   async listByType(type, options = {}) {
     const includeRetired = options.includeRetired === true;
+    // Derived staleness filter (#341) — see listByCategory.
+    const staleOnly = options.stale === true;
+    const nowMs = options.now !== undefined ? new Date(options.now).getTime() : Date.now();
     return this._allRecords().filter(
       (r) =>
         r.type === type &&
-        (includeRetired || (r.status || "active") !== "retired")
+        (includeRetired || (r.status || "active") !== "retired") &&
+        (!staleOnly || isRecordStale(r, nowMs))
     );
   }
 
@@ -911,6 +1030,16 @@ export class DefaultKnowledgeStore {
     const links = Object.values(rebuilt.forward).reduce((n, arr) => n + arr.length, 0);
     const changed = canonicalGraph(loadGraph(this._graphPath)) !== canonicalGraph(rebuilt);
     saveGraph(this._graphPath, rebuilt);
+
+    // The alias map is likewise derived from records' `aliases` — rebuild it so
+    // a lost/hand-edited alias-index.json recovers on the same recovery path.
+    const rebuiltAliases = emptyAliasIndex();
+    for (const record of records) {
+      const slugs = normalizeAliases(record.aliases);
+      if (slugs.length) registerAliases(rebuiltAliases, record.id, slugs);
+    }
+    saveAliasIndex(this._aliasPath, rebuiltAliases);
+
     return {
       records: records.length,
       links,