@nurix/etna 0.19.7 → 0.19.9

package/data/harnesses/kb-agi/scripts/kb-export.mjs

@@ -0,0 +1,167 @@
+#!/usr/bin/env node
+// plugins/kb-agi/scripts/kb-export.mjs - Build the vault's derived wikilink graph.
+//
+// Run from the vault root (the directory holding meta/): `node .claude/scripts/kb-export.mjs`.
+// Walks every content note, parses frontmatter hints and [[wikilinks]] per the dialect pinned
+// in meta/contract.md, and writes meta/_derived/graph.json — nodes (path, title, folder,
+// maturity, canonical, visibility, degrees), edges typed by form (link | anchor | embed),
+// unresolved links, and title/basename collisions. Deterministic: same vault bytes → same
+// graph.json (everything sorted, no timestamps). The graph is a regenerable derivative of the
+// notes — never hand-edited; git records when it was built.
+
+import { readdirSync, readFileSync, mkdirSync, writeFileSync, existsSync } from 'node:fs';
+import { join, relative, sep, basename } from 'node:path';
+
+const vaultRoot = process.cwd();
+if (!existsSync(join(vaultRoot, 'meta'))) {
+    console.error('kb-export: no meta/ found in the current directory — run from the vault root.');
+    process.exit(1);
+}
+
+// Dialect (mirrors meta/contract.md): [[target]], [[target|alias]], [[target#heading]],
+// ![[embed]]. Group 1 = embed marker, 2 = target, 3 = heading anchor, 4 = alias.
+const WIKILINK_RE = /(!?)\[\[([^\]|#]+?)(#[^\]|]+)?(?:\|([^\]]+))?\]\]/g;
+const FRONTMATTER_RE = /^---\r?\n([\s\S]+?)\r?\n---/;
+
+// Skipped at every level: dot-entries (.claude, .obsidian, .vscode, …), node_modules,
+// and meta/ — the control plane is not knowledge (contract: notes are the only canon).
+const SKIP_NAMES = new Set(['node_modules', 'meta']);
+
+function collectNotes(dir, out = []) {
+    for (const entry of readdirSync(dir, { withFileTypes: true })) {
+        if (entry.name.startsWith('.') || SKIP_NAMES.has(entry.name)) continue;
+        const full = join(dir, entry.name);
+        if (entry.isDirectory()) collectNotes(full, out);
+        else if (entry.isFile() && entry.name.endsWith('.md')) out.push(full);
+    }
+    return out;
+}
+
+// Minimal YAML reader for the contract's scalar hints; anything else is ignored.
+function parseFrontmatter(content) {
+    const match = content.match(FRONTMATTER_RE);
+    if (!match) return { fields: {}, body: content };
+    const fields = {};
+    for (const line of match[1].split('\n')) {
+        const kv = line.match(/^([A-Za-z_][\w-]*):\s*(.*?)\s*$/);
+        if (kv) fields[kv[1]] = kv[2].replace(/^["']|["']$/g, '');
+    }
+    return { fields, body: content.slice(match[0].length) };
+}
+
+// Blank out fenced and inline code so documentation examples never become edges,
+// keeping offsets stable.
+function stripCode(body) {
+    return body
+        .replace(/```[\s\S]*?```/g, (m) => ' '.repeat(m.length))
+        .replace(/`[^`\n]+`/g, (m) => ' '.repeat(m.length));
+}
+
+function parseNote(file) {
+    const content = readFileSync(file, 'utf8');
+    const { fields, body } = parseFrontmatter(content);
+    const rel = relative(vaultRoot, file).split(sep).join('/');
+    const id = rel.replace(/\.md$/, '');
+    const h1 = body.match(/^\s*#\s+(.+)$/m);
+    const links = [];
+    const stripped = stripCode(body);
+    let m;
+    WIKILINK_RE.lastIndex = 0;
+    while ((m = WIKILINK_RE.exec(stripped))) {
+        const target = (m[2] || '').trim();
+        if (!target) continue;
+        links.push({
+            target,
+            form: m[1] === '!' ? 'embed' : m[3] ? 'anchor' : 'link',
+            aliased: Boolean(m[4]),
+        });
+    }
+    return {
+        id,
+        title: fields.title || (h1 ? h1[1].trim() : basename(file, '.md')),
+        folder: id.includes('/') ? id.slice(0, id.lastIndexOf('/')) : '',
+        maturity: fields.maturity || 'captured',
+        canonical: fields.canonical !== 'false',
+        visibility: fields.visibility === 'hidden' ? 'hidden' : 'public',
+        links,
+    };
+}
+
+const notes = collectNotes(vaultRoot).map(parseNote).sort((a, b) => a.id.localeCompare(b.id));
+
+// Resolution maps: exact id/path first, then basename (Obsidian-style shortest name),
+// case-insensitively as the last step. A basename shared by several notes is ambiguous.
+const byId = new Map(notes.map((n) => [n.id.toLowerCase(), n.id]));
+const byBase = new Map();
+for (const n of notes) {
+    const base = basename(n.id).toLowerCase();
+    if (!byBase.has(base)) byBase.set(base, []);
+    byBase.get(base).push(n.id);
+}
+
+function resolveTarget(raw) {
+    const clean = raw.replace(/\.md$/, '');
+    const exact = byId.get(clean.toLowerCase());
+    if (exact) return { id: exact };
+    const candidates = byBase.get(basename(clean).toLowerCase()) || [];
+    if (candidates.length === 1) return { id: candidates[0] };
+    return { id: null, reason: candidates.length ? 'ambiguous' : 'missing' };
+}
+
+const edges = [];
+const unresolved = [];
+for (const note of notes) {
+    for (const link of note.links) {
+        const { id, reason } = resolveTarget(link.target);
+        if (id) edges.push({ source: note.id, target: id, form: link.form, aliased: link.aliased });
+        else unresolved.push({ source: note.id, target: link.target, reason });
+    }
+}
+edges.sort((a, b) => a.source.localeCompare(b.source) || a.target.localeCompare(b.target) || a.form.localeCompare(b.form));
+unresolved.sort((a, b) => a.source.localeCompare(b.source) || a.target.localeCompare(b.target));
+
+const inDegree = new Map();
+const outDegree = new Map();
+for (const e of edges) {
+    outDegree.set(e.source, (outDegree.get(e.source) || 0) + 1);
+    inDegree.set(e.target, (inDegree.get(e.target) || 0) + 1);
+}
+
+// Collisions break both wikilink resolution and retrieval — surfaced for the shape goal.
+const collisions = [];
+for (const [base, ids] of [...byBase.entries()].sort()) {
+    if (ids.length > 1) collisions.push({ kind: 'basename', value: base, notes: [...ids].sort() });
+}
+const byTitle = new Map();
+for (const n of notes) {
+    const t = n.title.toLowerCase();
+    if (!byTitle.has(t)) byTitle.set(t, []);
+    byTitle.get(t).push(n.id);
+}
+for (const [title, ids] of [...byTitle.entries()].sort()) {
+    if (ids.length > 1) collisions.push({ kind: 'title', value: title, notes: [...ids].sort() });
+}
+
+const graph = {
+    schema: 'kb-graph/1',
+    nodes: notes.map((n) => ({
+        id: n.id,
+        title: n.title,
+        folder: n.folder,
+        maturity: n.maturity,
+        canonical: n.canonical,
+        visibility: n.visibility,
+        inDegree: inDegree.get(n.id) || 0,
+        outDegree: outDegree.get(n.id) || 0,
+    })),
+    edges,
+    unresolved,
+    collisions,
+};
+
+mkdirSync(join(vaultRoot, 'meta', '_derived'), { recursive: true });
+writeFileSync(join(vaultRoot, 'meta', '_derived', 'graph.json'), JSON.stringify(graph, null, 2) + '\n');
+console.log(
+    `kb-export: ${graph.nodes.length} notes, ${edges.length} edges, ` +
+        `${unresolved.length} unresolved, ${collisions.length} collision(s) → meta/_derived/graph.json`,
+);

package/package.json

@@ -1,6 +1,6 @@
 {
     "name": "@nurix/etna",
-    "version": "0.19.7",
+    "version": "0.19.9",
     "description": "Bootstrap a project with a Nurix harness — copies the harness's CLAUDE.md, skills, agents, rules, and hooks directly into the project from a bundled payload (no marketplace fetch, no network).",
     "type": "module",
     "bin": {

package/data/harnesses/code/rules/nustack.md

@@ -1,150 +0,0 @@
-# Nustack — `@nurix/*` Packages: naming, monorepo layout, and publishing
-
-How a `@nurix/*` multi-package repo is **named**, **structured**, and **shipped**. For consuming an already-published `@nurix/*` package (auth, install, imports), see the Consuming section of [`typescript.md`](typescript.md).
-
----
-
-## 1. Package naming
-
-Every workspace package is scoped to **`@nurix/`**. The segment after the scope encodes **intent** — the dot vs. hyphen is semantic, not cosmetic:
-
-| Form                                            | Meaning                                                                                                                                                                                  | Examples                                                                                                           |
-| ----------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------ |
-| `@nurix/workflows-sdk` (hyphen, single segment) | The **published, externally-destined** surface. A clean `@nurix/*` name is a published _contract_ — changing an export or peer dep is a breaking change for consumers outside this repo. | `@nurix/workflows-sdk`                                                                                             |
-| `@nurix/workflows.<name>` (dot separator)       | **Internal** to the workflows product — `private: true`, refactor freely, no external consumers.                                                                                         | `@nurix/workflows.agent-core`, `.worker`, `.gateway`, `.secrets`, `.connector`, `.playground`, `.playground-tests` |
-| `@nurix/<name>` (plain, no `workflows` prefix)  | Cross-repo **shared libs** owned _elsewhere_ and merely consumed here — never renamed.                                                                                                   | `@nurix/contracts`, `@nurix/components`                                                                            |
-
-- The `<name>` segment is always **kebab-case** (`agent-core`, `playground-tests`).
-- The dot is **not** a path separator, so subpath exports still resolve: `@nurix/workflows.agent-core/nodes`.
-- The dot tracks "internal product package," not the `private` flag exactly — `@nurix/workflows.secrets` is `private: false` because it's extraction-bound (slated to move to a sibling repo/namespace), yet still wears the dotted internal name. Today `-sdk` is the only clean published form.
-
-**Naming a new package:** internal to this repo? → `@nurix/workflows.<thing>`, `private: true`, kebab-case `<thing>` (the default). Externally consumed contract? → clean `@nurix/<thing>` (rare). Shared lib from another repo? → keep its existing `@nurix/<name>`.
-
----
-
-## 2. Monorepo & package boundaries
-
-One `tsconfig.base.json` at the repo root is the **single owner of TS policy** — the strict set (see [`typescript.md`](typescript.md)), `target`, and any option uniform across packages (here, `module`/`moduleResolution`). Each package's `tsconfig.json` is thin: it `extends` the base, then adds only its own *coordinates* (`rootDir`/`outDir`/`include`) and genuine *environment* overrides (`lib`/`types`/`jsx`, plus `module`/`moduleResolution` when a package's module system genuinely differs — a Worker, browser, or NodeNext package). That is environment, not policy. Never re-declare or weaken a *policy* option locally (no per-package `strict: false`, no widening `noUncheckedIndexedAccess`). A framework that owns its own base (e.g. an Astro app on `astro/tsconfigs/strict`) is the one allowed exception.
-
-- **Internal packages are source-first.** A `private: true` workspace package exposes its API through the `exports` field pointing at TypeScript source (`"types"`/`"default"` → `./src/index.ts`) — consumed across the workspace with **no build step**. Prefer the `exports` field; don't add a bare `main`/`module` to new packages. Add one typed subpath per public surface (`"./nodes": { "types": "./src/nodes/index.ts", "default": "./src/nodes/index.ts" }`); consumers import the subpath, **never** a deep relative path into another package's `src/`.
-- **Published packages build to `dist` — never ship raw `src`.** The moment a package crosses a publish boundary (`private: false`), it compiles with `tsc` (`declaration: true`, `declarationMap: true` from the base), ships `files: ["dist"]`, and points `exports`/`types` at `./dist/*` (use `publishConfig.exports` to swap source→dist on publish if the dev entry stays on source). `prepublishOnly` runs the build.
-- **Declare host singletons as `peerDependencies`** on published libraries (`react`, `react-dom`, the framework client) so consumers keep one copy; never bundle them. Apps depend on them directly.
-- **Single-source shared dep versions with pnpm `catalog:`** — `typescript`, `zod`, `vitest`, `react`, type packages. One version per dependency across the workspace so every package's types resolve identically; no per-manifest version drift.
-- **Reach for TS project references only when it hurts** — adopt `references` once the typecheck/build graph is slow enough to feel. Until then, `pnpm -r typecheck` over independent `extends` configs is the correct default.
-
----
-
-## 3. Publishing & the release pipeline
-
-`@nurix/*` packages publish to **npmjs.org with `restricted` access** — only npm users with read rights to the `nurix` org can install them. Reference implementations: `~/dev/components` (`@nurix/components`, library) and `~/dev/etna/packages/cli` (`@nurix/etna`, CLI).
-
-### 3.1 Prerequisites (one-time, org-wide)
-
-1. **npm org `nurix`** exists and you're a member with publish rights — <https://www.npmjs.com/settings/nurix/packages>.
-2. **An npm automation token** with `Read and write` for the `nurix` scope — npm → Generate New Token → Automation.
-3. **The token added as a GitHub Actions secret** named `NPM_PUBLISH_TOKEN` on every publishing repo. `NPM_PUBLISH_TOKEN` is the convention; pick another name only with a strong reason.
-
-### 3.2 `package.json` — required fields
-
-```jsonc
-{
-  "name": "@nurix/<package-name>", // The scope makes it discoverable to org members.
-  "version": "0.1.0",              // Start at 0.1.0; the workflow bumps from here.
-  "private": false,                // MUST be false (or omitted). `npm publish` refuses if true.
-  "publishConfig": { "access": "restricted" }, // Scoped + private: only org members can install.
-  "files": ["dist"]                // Whitelist of what ships. Anything outside is excluded.
-}
-```
-
-- **`publishConfig.access`** — `"restricted"` (recommended): visible only to `nurix`-org readers. `"public"`: world-readable (free, but only if you mean it). Omitting it on a scoped package defaults to `restricted`; be explicit anyway.
-- **`files`** — without it, npm publishes everything not in `.gitignore`, **including source**. Library → `["dist"]`; CLI (etna) → `["bin/", "data/", "README.md"]`. Don't list `package.json`/`README.md` — npm always includes them.
-- **Build hooks** — `prepack` for build steps that must produce files in `files` (also runs on install-as-git-dep); `prepublishOnly` for publish-only steps. Either alone is fine; `@nurix/components` runs both.
-- **Other useful fields** — `type: "module"`, `engines.node`, `bin` (CLIs), `main`/`module`/`types`/`exports` (libraries), `sideEffects: ["**/*.css"]`, `repository` (with `directory` for monorepos), `license: "UNLICENSED"`.
-
-### 3.3 The publish workflow (generic template)
-
-The dual-trigger pattern: a push to the default branch auto-ships a patch; a manual dispatch picks minor/major.
-
-```yaml
-name: Publish to npm
-on:
-  push:
-    branches: [dev]               # your default branch
-    paths:                        # ONLY paths that change what ships — else every README edit publishes
-      - 'src/**'
-      - 'scripts/**'
-      - 'package.json'
-      - 'package-lock.json'
-      - '.github/workflows/publish.yml'
-  workflow_dispatch:
-    inputs:
-      bump: { description: 'Version bump', type: choice, options: [patch, minor, major], default: patch }
-permissions: { contents: write }  # push the version-bump commit + tag
-concurrency: { group: publish, cancel-in-progress: false }  # monorepo: group: publish-<pkg>
-jobs:
-  publish:
-    runs-on: ubuntu-latest
-    steps:
-      - uses: actions/checkout@v5
-        with: { fetch-depth: 0, token: '${{ secrets.GITHUB_TOKEN }}' }
-      - uses: actions/setup-node@v5
-        with: { node-version: 22, registry-url: 'https://registry.npmjs.org' }  # writes .npmrc using $NODE_AUTH_TOKEN
-      - run: npm ci                 # skip ONLY if the build is pure-Node with no deps (e.g. @nurix/etna)
-      - run: |
-          git config user.name "github-actions[bot]"
-          git config user.email "41898282+github-actions[bot]@users.noreply.github.com"
-      - run: npm version ${{ inputs.bump || 'patch' }} -m "chore: release v%s [skip ci]"
-      - run: npm publish            # prepublishOnly / prepack runs the build
-        env: { NODE_AUTH_TOKEN: '${{ secrets.NPM_PUBLISH_TOKEN }}' }
-      - run: git push --follow-tags # pushes the bump commit AND the v<version> tag npm created
-```
-
-**Why dual-trigger is safe** — three safeguards prevent an infinite publish loop: (1) `paths:` scopes the push trigger to artifact-affecting files; (2) `[skip ci]` in the bump commit makes GitHub skip the workflow that bump would otherwise re-trigger; (3) `concurrency: cancel-in-progress: false` queues near-simultaneous merges instead of racing for a version number.
-
-**`registry-url` is load-bearing** — without `registry-url: https://registry.npmjs.org` on `setup-node`, it never writes the `.npmrc` line that uses `$NODE_AUTH_TOKEN`, and the publish falls back to anonymous auth and fails.
-
-### 3.4 The three ways to ship
-
-- **A. Auto on merge (common).** Land on the default branch; if a `paths:`-filtered file changed, the workflow fires and ships a patch.
-- **B. Manual dispatch (minor/major).** **Actions → Publish to npm → Run workflow**, pick `bump = minor|major`.
-- **C. Local (CI down / one-off):** `npm version <patch|minor|major>` → `npm publish` → `git push --follow-tags`.
-
-Local auth uses two tokens, two homes: a **read** token in `~/.npmrc` (`//registry.npmjs.org/:_authToken=…`) for `npm install`, and `NPM_PUBLISH_TOKEN` as an env var (sourced from `~/.zsh_secrets` or equivalent, **not** in `.npmrc` or the repo) for `npm publish`.
-
-> **Agent guard — if `NPM_PUBLISH_TOKEN` isn't in the environment, do not work around it.** No `npm login` to swap the user's auth, no rewriting `~/.npmrc`, no substituting the read token (it lacks publish rights → `403`), no `--registry` overrides, no temp-file token. Instead **stop and report**: "This repo can't publish locally — `NPM_PUBLISH_TOKEN` isn't set. Source `~/.zsh_secrets` (or wherever you keep it) and re-run, or trigger the CI workflow." Some users publish exclusively from CI — that's the default path for a reason.
-
-Verify after any flow: `https://www.npmjs.com/package/@nurix/<name>` and a clean-dir `npx @nurix/<name>@latest`.
-
-### 3.5 Monorepo deviations
-
-When the package lives in `packages/<pkg>/` of a multi-package repo:
-
-- **`working-directory: packages/<pkg>`** on the bump and publish steps so they operate on the right `package.json`.
-- **Scoped concurrency** — `group: publish-<pkg>` lets sibling packages publish in parallel.
-- **Tag prefix — only with multiple tagging packages.** `npm version --tag-version-prefix="<pkg>-v"` (→ `<pkg>-v0.2.0`) is worth it only when more than one package cuts release tags, so they don't collide. A single publishable package (etna's case, even though it's laid out as a monorepo) uses plain `v0.2.0`.
-
-A repo with one publishable package only needs `working-directory`; skip the prefix, and concurrency scoping is optional.
-
-### 3.6 Common pitfalls
-
-- **402 Payment Required** — `access: "public"` on an org without a plan for free public scoped packages. Use `"restricted"` (or upgrade the plan).
-- **403 Forbidden** — `NPM_PUBLISH_TOKEN` missing/wrong, or its user lacks `nurix` write access, or it's a read-only (not Automation) token.
-- **"Cannot publish over previously published version x.y.z"** — a bump ran but publish failed and was re-run without rebasing. `git reset` the bump and let CI re-bump, or `npm version patch && git push --follow-tags && npm publish`.
-- **Publish succeeds but `npx @nurix/foo` is "command not found"** — no `bin` field, or `bin` points outside `files`, or the script is missing its `#!/usr/bin/env node` shebang.
-- **"Git working directory not clean" on `npm version`** — the checkout has untracked/modified files; build only into `.gitignore`d paths (the components repo builds into `dist/`).
-- **Published tarball contains source** — missing `files` in `package.json`. Add `["dist"]` and republish.
-- **Auto-publish fires too often** — no `paths:` filter or one that's too broad. Tighten it to artifact-affecting files, or drop the push trigger for `workflow_dispatch`-only.
-- **Workflow loops forever** — the bump commit lacks `[skip ci]`. Invoke `npm version` with `-m "chore: release v%s [skip ci]"`.
-- **A normal commit silently skips its own push** — the inverse trap. GitHub scans the head commit's **whole message** (subject _and_ body) for skip directives (`[skip ci]`, `[ci skip]`, `[no ci]`, `[skip actions]`, `***NO_CI***`). If any hand-written commit merely _mentions_ the literal token in prose, the entire push is skipped and the publish never fires (symptom: branch moved, paths matched, Actions on — yet zero runs for the SHA). Never write the literal token in a commit message or PR body unless you mean it; to ship a push that carried it by accident, re-trigger via **Run workflow** / `gh workflow run … --ref dev`.
-
----
-
-## 4. Quick checklist for a new `@nurix/*` package
-
-- [ ] `package.json`: `name: "@nurix/X"`, `version: "0.1.0"`, `private: false`, `publishConfig.access: "restricted"`, `files: [...]`
-- [ ] Build step wired into `prepack` (or `prepublishOnly`)
-- [ ] Name follows §1; if it's a workspace member, boundaries follow §2
-- [ ] `.github/workflows/publish.yml` from §3.3
-- [ ] `NPM_PUBLISH_TOKEN` secret added to the repo
-- [ ] First publish from local (`npm publish`) to verify the pipeline, then a no-op commit to verify CI
-- [ ] README notes the `@nurix` scope so consumers know they need org access

package/data/harnesses/kb-agi/agents/kb-agi-init.md

@@ -1,285 +0,0 @@
----
-name: kb-agi-init
-description: Initializes a kb-agi vault by scaffolding the meta/ control plane — the contract (guidance.md), the seed genre templates, the intent-index, and the sessions/ folder — from templates carried inline in this agent. Use on a fresh vault, or when the router reports that meta/guidance.md is missing. Triggers on "initialize kb-agi", "init the vault", "scaffold meta", "set up the control plane".
-tools: Read, Glob, Bash, Write
-model: inherit
----
-
-You are the **kb-agi-init** agent. One job: stand up the `meta/` control plane a kb-agi vault needs to operate, then get out of the way. You run once per vault, and you are fully self-contained — every file you create is carried inline below, so you need no external templates.
-
-You write `meta/` only. **You never write or modify `CLAUDE.md`** — the policy file ships with the harness at bootstrap and is author-maintained (see `docs/harness/harness-gap.md`, Principle 7). If `CLAUDE.md` is absent, stop and tell the user the kb-agi harness wasn't installed.
-
-**You never create `meta/_kg/`.** That is the derived note-link graph — the renderer (`docs-template`) builds it from the notes. It is not part of this scaffold.
-
-**You never create `meta/goals/`.** Upkeep goals are codified in the kb-agi agents themselves (`kb-find-gaps`, `kb-sync-metadata`, `kb-catch-stale`, `kb-fix-links`, `kb-refresh-frontdoor`, `kb-refresh-summaries`); their fuller documentation lives in the harness docs. There is no goals folder in the vault.
-
-## What you create
-
-```
-meta/
-├── guidance.md          # THE CONTRACT
-├── genre/               # seed user-type templates
-│   └── sales.md · pm.md · contributor.md
-├── intent-index.md      # "Read by need" front door (lanes empty until content lands)
-└── sessions/README.md   # query-log format (the one thing the ask path writes)
-```
-
-## Procedure
-
-1. **Check if already initialized.** If `meta/guidance.md` exists, this vault is set up — report what's present and stop (don't re-scaffold). Otherwise continue.
-2. **Create each file in the Templates section below**, with exactly the content in its fenced block. Create parent directories as needed. **Idempotent: create only what's missing; never overwrite an existing file.** Report every file created vs skipped.
-3. **Hand off.** Point the user at the two halves they own and edit: `meta/guidance.md` (the contract — read it) and `meta/genre/*.md` (seed user-types — adapt for your readers). Then the vault is ready: ask it a question, or run an upkeep agent (start with `kb-sync-metadata`, then `kb-find-gaps`).
-
-## Boundaries
-
-- `meta/` only. Never `CLAUDE.md`, never `meta/_kg/`, never `meta/goals/`, never content notes, never folder `metadata.md` (that's authoring / the `kb-find-gaps` agent).
-- Every write is reviewable in git.
-
----
-
-# Templates
-
-Each block below is one file. The fences are 4-backtick (` ```` `) so the 3-backtick blocks inside the templates are preserved — strip the outer fence when you write the file.
-
-## `meta/guidance.md`
-
-````markdown
-# guidance — the contract
-
-This file is the single contract the router (`CLAUDE.md`) and the upkeep agents both read. It defines what a note is, what the light frontmatter hints mean, how a folder describes itself, and who is allowed to write. When any of those agents needs a rule, the rule lives here.
-
-Everything in this file is a _hint or a convention_, not a schema enforced by code. Notes that omit a hint still work; the system degrades gracefully.
-
----
-
-## The note model
-
-The vault is one flat Obsidian vault. Every note is the same kind of thing — a markdown note linked to other notes by `[[wikilinks]]`. There is **no per-document type label** and no altitude. Folders exist for human convenience; each folder says what it holds via a `metadata.md`.
-
-- **One idea per note.** Push deeper material into a _linked_ note rather than bloating one note. The links carry the depth.
-- **Links are the structure.** The note-link graph is the one graph. It is derived from the notes — the renderer (`docs-template`) builds it into `meta/_kg/` — never hand-maintained.
-- **Notes are the only canon.** Everything under `meta/` is control plane, not knowledge. The graph and any index are regenerable derivatives of the notes.
-
----
-
-## Frontmatter hints
-
-A note carries light frontmatter. All fields are optional; treat a missing field as its default.
-
-```yaml
----
-title: Human-readable title # defaults to the H1 / filename
-maturity: synthesized # see ladder below — default: captured
-canonical: true # is this THE note on its topic? default: true
-visibility: public # public | hidden — default: public
----
-```
-
-### maturity ladder
-
-How finished the thinking is. Shapes how the ask path frames an answer, never whether a note is shown.
-
-| value | meaning |
-| --- | --- |
-| `raw` | dumped in, unprocessed — a capture, a transcript, a paste |
-| `captured` | cleaned up, readable, but not yet reconciled with neighbours |
-| `synthesized` | reconciled into the vault's point of view, linked to its neighbours |
-| `published` | load-bearing, citeable as the vault's current position |
-
-### canonical vs historical
-
-`canonical: true` is the current note on its topic. `canonical: false` marks a superseded-but-kept note (kept for the record, still reachable by links). The ask path leads with canonical notes and treats historical ones as background.
-
-### visibility
-
-`public` (default) renders on the static site. `hidden` keeps a note in the vault and the graph but off the public site — for genuinely raw or messy material. Hiding is the exception; default to `public` (doctrine P2 — WYSIWYG).
-
----
-
-## Folder self-description — `metadata.md`
-
-Every content folder carries a `metadata.md` with a fixed shape. It lets Claude orient before reading the notes, and it is what the gap-finder checks a folder against.
-
-```markdown
-# <folder name>
-
-**About.** One or two sentences: what this folder holds and why it exists.
-
-**Should contain.** The kinds of notes that belong here — the checklist the gap-finder reads.
-
-**Entry notes.** The 1–3 notes to start from. (`[[wikilinks]]`)
-
-**Neighbours.** Folders this one links to most. (`[[wikilinks]]` or plain names)
-```
-
-`metadata.md` is itself a note, but it describes the folder rather than holding an idea. It is not content canon — losing one costs orientation, not knowledge.
-
----
-
-## Who may write
-
-This is doctrine P3, restated as the contract:
-
-- **The ask path is read-only.** Its only write is appending a query log under `meta/sessions/`. It never edits a note.
-- **Goal-agents are the only writers of canon.** Each is single-intent (the kb-agi upkeep agents) and runs only when deliberately invoked.
-- **The contribute path is the human steering Claude** to draft and place notes in a normal session — a person is in the loop on every write.
-- **Every write is a git commit.** Nothing is irreversible; anything can be reviewed and rolled back.
-
----
-
-## genre — the reader, not the document
-
-`genre` is the **user-type** of whoever is asking (Sales, PM, Contributor), established by the opening interview in `CLAUDE.md`. It is a label on the _reader_, never on a note. Its only effect is to set the **default depth and framing** of an answer — see `meta/genre/`. It never changes which notes exist or which are reachable.
-
----
-
-## The rest of the control plane
-
-| path | what it is |
-| --- | --- |
-| `meta/genre/` | user-type templates — default depth + entry points per reader |
-| `meta/intent-index.md` | "Read by need" — intent-keyed entry points into the vault |
-| `meta/sessions/` | query logs — every ask, and whether it could be answered |
-| `meta/_kg/` | the derived note-link graph — built by the renderer (`docs-template`), never hand-edited; not part of this scaffold |
-
-Upkeep is run by the kb-agi agents (invoked by name); there is no `meta/goals/` folder in the vault.
-````
-
-## `meta/genre/sales.md`
-
-```markdown
-# genre — Sales
-
-The reader is positioning NuStack to someone else: a prospect, a partner, a teammate who needs the pitch. They want the claim and the proof behind it, not the implementation.
-
-**Default depth.** Start crisp. Lead with the answer in one or two sentences — what we can do, what makes it different — then offer the supporting detail rather than front-loading it. Go deeper only when the question reaches for it ("how exactly…", "what's underneath…").
-
-**Framing.** Outcomes and differentiators over mechanism. Speak in capabilities and claims. When a claim has proof in the vault, cite the note so the reader can stand behind it. Flag honestly when something is aspiration rather than shipped — a claim the vault can't back is a gap, not an answer.
-
-**Start from.**
-
-- `meta/intent-index.md` → the "understand the product / what can it do" lanes
-- positioning, claims, and capability notes (lead with `canonical`, `published` ones)
-
-**Adjust.** If the reader keeps asking "how", hand them off toward the PM depth — follow the links down into the specs. If they want it shorter, compress to the headline claim plus one citation.
-```
-
-## `meta/genre/pm.md`
-
-```markdown
-# genre — PM
-
-The reader is shaping or building the product: a PM, designer, or engineer who needs scope, tradeoffs, and the state of a decision. They want the mechanism and the reasoning, not just the claim.
-
-**Default depth.** Start at working depth — enough to act on. Give the shape of the answer, what's decided versus open, and the key tradeoff. Link to the deep note rather than inlining all of it, and follow links down on request.
-
-**Framing.** Scope, contracts, and decisions. Distinguish what's shipped, what's specced, and what's still open. Surface the tension behind a choice, not just the choice. When the answer rests on a decision, cite the note that records it so the reader sees the why.
-
-**Start from.**
-
-- `meta/intent-index.md` → the "build / extend / model / runtime concern" lanes
-- spec, decision, and build-plan notes; the architecture notes that set the target
-
-**Adjust.** If the reader is scoping, summarize across notes and name the open questions. If they're implementing, go deep into the one note and its neighbours. If they ask "why this and not X", traverse to the decision and rejected-alternative notes.
-```
-
-## `meta/genre/contributor.md`
-
-```markdown
-# genre — Contributor
-
-The reader is here to _add_ knowledge, not consume it. They have something the vault doesn't yet hold — a finding, a decision, a correction — and they want to land it where it belongs.
-
-**Default depth.** Orientation over synthesis. Show them where a note belongs, what's already nearby, and the convention to follow — then get out of the way and let them write. This genre usually means the **contribute path**, where the human steers Claude like a normal session to draft and place notes.
-
-**Framing.** Placement and convention. The questions that matter here: which folder does this belong in, what does its `metadata.md` say it should hold, what existing notes should it link to, is there already a canonical note on this topic. Links form naturally as the note is written.
-
-**Start from.**
-
-- the `kb-find-gaps` agent + `meta/sessions/` gap-logs — what the hub is missing / wants next
-- `meta/guidance.md` — the note model, frontmatter hints, and folder `metadata.md` shape
-- the target folder's `metadata.md` — what belongs there and what's missing
-
-**Adjust.** This path is deliberately thin and grows with use. No sub-agents — it's the human and Claude in a normal session. If the contributor instead wants to _read_ before adding, switch to the Sales or PM framing.
-```
-
-## `meta/intent-index.md`
-
-```markdown
-# intent-index — Read by need
-
-The front door to the vault, keyed on **what you're trying to do**, not who you are (doctrine P4). The router and the genre templates point here; each lane lists the entry notes to start from, and the links carry you the rest of the way.
-
-This is a living index. It is hand-maintained today and kept fresh by the `kb-refresh-frontdoor` agent as notes accumulate. Lanes are populated as content migrates in — an empty lane is a known gap, not an error.
-
----
-
-## "I want to understand the product"
-
-_What NuStack is, what it can do, the claims and their proof._
-
-- _populated on migration_
-
-## "I want to start building"
-
-_Where to begin, how the pieces fit, the build sequence._
-
-- _populated on migration_
-
-## "I want to extend a capability"
-
-_How to add to the catalog — a node, a connector, an integration._
-
-- _populated on migration_
-
-## "I want to understand a runtime concern"
-
-_Execution, streaming, observability — how it behaves when it runs._
-
-- _populated on migration_
-
-## "I want to model data"
-
-_The schema, the entities, the contracts they speak._
-
-- _populated on migration_
-
-## "I want to add knowledge"
-
-_You have something the vault doesn't hold yet._
-
-- run `kb-find-gaps` (or read `meta/sessions/` gap-logs) — what the hub is missing
-- `meta/guidance.md` — the note model and where things belong
-```
-
-## `meta/sessions/README.md`
-
-````markdown
-# sessions — query logs
-
-Every ask the router handles is logged here. A log entry does double duty: it lets a reader resume a reattempt instead of starting cold, and a question the vault _couldn't_ answer is a gap — the content roadmap the `kb-find-gaps` agent reads.
-
-This is the one thing the read-only ask path writes (doctrine P3). It never touches a note.
-
-## Format
-
-One file per session, named `YYYY-MM-DD-short-slug.md`:
-
-```markdown
----
-date: 2026-05-24
-genre: pm
-answered: partial # yes | partial | no
----
-
-## Q: <the question, in the asker's words>
-
-**Answer depth taken.** <crisp | working | deep>
-
-**Notes used.** [[note-a]], [[note-b]]
-
-**Gap.** <what was missing, if answered is partial/no — empty if yes>
-```
-
-The `answered: no | partial` entries plus their `Gap.` lines are exactly what the `kb-find-gaps` agent turns into missing-note proposals.
-````

package/data/harnesses/kb-agi/agents/kb-catch-stale.md

@@ -1,22 +0,0 @@
----
-name: kb-catch-stale
-description: Finds notes that have drifted out of date — a canonical note superseded by a newer one but never demoted, or a summary whose linked-down sources changed after it. Use to audit freshness. Reports by default; demotes/flags only when explicitly asked.
-tools: Read, Grep, Glob, Bash
-model: inherit
----
-
-You are the **kb-catch-stale** goal-agent for the NuStack knowledge hub. One job: surface notes that have drifted out of date.
-
-**Read first:** `meta/guidance.md` (the note model, `maturity` + `canonical` hints) — the contract that governs you. The procedure below is this agent's full, self-contained definition.
-
-## Procedure
-
-1. Group notes by topic (shared `[[wikilinks]]`, near-identical titles). Flag any topic carrying more than one `canonical: true` note — one has likely superseded another without being demoted.
-2. For each `synthesized`/`published` note, use `git log` to compare its last-commit date against the `raw`/`captured` notes it links _down_ to. Flag summaries older than their sources.
-3. Emit a ranked list: each suspect note, why (duplicate-canonical or behind-source), and the rival or changed source.
-
-## Write rules (doctrine P3)
-
-- **Default: write nothing.** Output the stale list.
-- **On request only:** set `canonical: false` on a clearly-superseded note, or hand a behind-source note to the `kb-refresh-summaries` agent. Never rewrite a note's body — that's a refresh, not a staleness call.
-- Every write is a git commit. Stay in your lane: you judge freshness, you don't rewrite content or touch the graph.