@ctxr/skill-llm-wiki 1.0.1 → 1.1.0

package/guide/consumers/recipes/testing.md

@@ -0,0 +1,149 @@
+---
+id: recipe-testing
+type: primary
+depth_role: leaf
+focus: "Use the shipped testkit in consumer test suites"
+parents:
+  - ../index.md
+tags:
+  - testing
+  - testkit
+  - fixtures
+  - consumers
+activation:
+  keyword_matches:
+    - test harness
+    - consumer tests
+    - testkit
+    - stub skill
+    - wiki fixture
+  tag_matches:
+    - testing
+    - testkit
+
+generator: "skill-llm-wiki/v1"
+---
+
+# Recipe: testing with the shipped testkit
+
+## Trigger
+
+Your consumer has tests that interact with `skill-llm-wiki` (e.g. your installer refuses without the skill present, your wiki-write workflow post-heal classifies verdicts). Use the shipped testkit instead of hand-rolling fixtures.
+
+## Commands to locate the testkit
+
+```bash
+skill-llm-wiki where --json | jq -r '.testkit_dir'
+```
+
+The returned absolute path contains:
+
+- `stub-skill.mjs` — seed a presence-only skill under `.claude/skills/` or `.agents/skills/`.
+- `make-wiki-fixture.mjs` — build a minimal hosted-mode wiki at a temp path using the shipped templates.
+- `assert-frontmatter.mjs` — parse a leaf's frontmatter and assert expected fields.
+- `cli-run.mjs` — spawn the CLI, capture stdout/stderr/status, auto-parse the envelope.
+
+> **About `<testkit_dir>` in the code below:** the literal string
+> `<testkit_dir>` is a placeholder. Resolve it at test-load time via
+> the `where` probe, and convert the filesystem path to a `file://`
+> URL before passing it to dynamic `import()` — Node ESM requires
+> this on Windows (where `TESTKIT` looks like `C:\...`) and it is
+> harmless on POSIX. Example:
+>
+> ```js
+> import { spawnSync } from "node:child_process";
+> import { pathToFileURL } from "node:url";
+> const WHERE = JSON.parse(
+>   spawnSync("skill-llm-wiki", ["where", "--json"], { encoding: "utf8" }).stdout,
+> );
+> const TESTKIT = WHERE.testkit_dir;
+> const { stubSkill } = await import(
+>   pathToFileURL(`${TESTKIT}/stub-skill.mjs`).href,
+> );
+> ```
+>
+> Do not copy the `<testkit_dir>/stub-skill.mjs` string verbatim
+> into your imports — it will not resolve.
+
+## Consumer test code
+
+### Presence stub (replaces hand-rolled `wikiSkillStub`)
+
+```js
+import { test } from "node:test";
+import { mkdtempSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import { stubSkill } from "<testkit_dir>/stub-skill.mjs";
+
+test("installer refuses when skill is absent", async () => {
+  const home = mkdtempSync(join(tmpdir(), "test-"));
+  // Do NOT call stubSkill — simulate the absent case.
+  const r = await runInstaller({ env: { HOME: home } });
+  assert.equal(r.status, 1);
+  assert.match(r.stderr, /skill-llm-wiki is not installed/);
+});
+
+test("installer proceeds when stub is present", async () => {
+  const home = mkdtempSync(join(tmpdir(), "test-"));
+  await stubSkill({ home });
+  const r = await runInstaller({ env: { HOME: home } });
+  assert.equal(r.status, 0);
+});
+```
+
+### Fixture wiki (for exercising write workflows)
+
+```js
+import { makeWikiFixture } from "<testkit_dir>/make-wiki-fixture.mjs";
+
+test("my consumer writes a report leaf in the right shape", async () => {
+  const wiki = await makeWikiFixture({
+    path: join(tmpdir(), `reports-${Date.now()}`),
+    kind: "dated",
+    template: "reports",
+    seedLeaves: ["2026/04/18/example.md"],
+  });
+  // Now drive your consumer write code against `wiki.path`.
+  await writeMyLeaf(wiki.path, "2026/04/18/new-report.md", "content");
+  assert.ok(existsSync(join(wiki.path, "2026/04/18/new-report.md")));
+});
+```
+
+### CLI run (for end-to-end verdict-handling tests)
+
+```js
+import { runCli } from "<testkit_dir>/cli-run.mjs";
+
+test("heal on a fresh wiki returns verdict=ok", async () => {
+  const wiki = await makeWikiFixture({ path: tmpWiki(), kind: "dated" });
+  const r = runCli(["heal", wiki.path, "--json"]);
+  assert.equal(r.envelope.verdict, "ok");
+});
+```
+
+### Frontmatter assertions
+
+```js
+import { assertFrontmatterShape } from "<testkit_dir>/assert-frontmatter.mjs";
+
+test("my consumer writes the expected frontmatter", async () => {
+  await writeMyLeaf(wiki.path, "2026/04/18/leaf.md", "content");
+  assertFrontmatterShape(join(wiki.path, "2026/04/18/leaf.md"), {
+    type: "primary",
+    depth_role: "leaf",
+    focus: "leaf",
+  });
+});
+```
+
+## Failure modes
+
+- `testkit_dir` is `null`: you are running against an old skill version without the testkit. Gate on `format_version >= 1` in CI.
+- `stubSkill` fails with "unknown layout": pass one of `"claude-skills"` or `"agents-skills"`.
+- `makeWikiFixture` fails on the template lookup: pass a name matching one of the shipped templates (see [dated-wiki.md](dated-wiki.md) / [subject-wiki.md](subject-wiki.md)).
+
+## Do not
+
+- Import from `scripts/lib/` in your tests. Those are internal; only `scripts/testkit/` is part of the consumer contract.
+- Hand-roll parallel stub helpers once this testkit exists. Drift between your stub and the skill's canonical shape is a real bug source.

package/guide/index.md

@@ -74,6 +74,13 @@ entries:
     file: "ux/index.md"
     type: index
     focus: User-facing intent resolution and preflight failure messaging.
+  - id: consumers
+    file: "consumers/index.md"
+    type: index
+    focus: "Integrating another skill or agent as a consumer of skill-llm-wiki."
+    tags:
+      - consumers
+      - integration
 children:
   - "basics/index.md"
   - "correctness/index.md"
@@ -83,6 +90,7 @@ children:
   - "operations/index.md"
   - "substrate/index.md"
   - "ux/index.md"
+  - "consumers/index.md"
 ---
 <!-- BEGIN AUTO-GENERATED NAVIGATION -->
 
@@ -110,6 +118,7 @@ children:
 | [operations/index.md](operations/index.md) | 📁 index | per-operation phase pipelines for Build, Extend, Validate, Rebuild, Fix, and Join |
 | [substrate/index.md](substrate/index.md) | 📁 index | Decision machinery — rewrite operators and the tiered AI ladder driving them. |
 | [ux/index.md](ux/index.md) | 📁 index | User-facing intent resolution and preflight failure messaging. |
+| [consumers/index.md](consumers/index.md) | 📁 index | Integrating another skill or agent as a consumer of skill-llm-wiki. |
 
 <!-- END AUTO-GENERATED NAVIGATION -->
 

package/guide/substrate/operators.md

@@ -61,7 +61,7 @@ NEST fires in two modes:
 
 **Cluster-based application.** Each accepted cluster is named via a Tier 2 `cluster_name` request (slug + purpose) — or receives a slug directly from a `propose_structure` Tier 2 response. Names are NEVER shortcut from shared tags; if the sub-agent cannot name a cluster, that cluster does not nest. The NEST applier (`scripts/lib/nest-applier.mjs`) then:
 
-1. **Atomic slug resolution.** Before touching the filesystem, `resolveNestSlug(slug, proposal)` checks whether the proposed slug collides with (a) any member leaf's id, (b) any non-member sibling leaf's id in the same parent, or (c) an existing sibling subdirectory name. On collision the slug is auto-suffixed deterministically (`<slug>-group`, then `<slug>-group-2`, `-group-3`, …) until it's non-colliding. The rename is audited in `decisions.yaml` as `decision: slug-renamed`. This pre-empts the DUP-ID class of validation failure that would otherwise rollback the entire NEST after apply.
+1. **Atomic slug resolution.** Before touching the filesystem, `resolveNestSlug(slug, proposal, wikiRoot, opts)` checks whether the proposed slug collides with (a) any member leaf's id, (b) any non-member sibling leaf's id in the same parent, (c) an existing sibling subdirectory name, or (d) any live leaf id or subdirectory basename elsewhere in the tree (full-tree walk, activated whenever `wikiRoot` is provided). On collision the slug is auto-suffixed deterministically (`<slug>-group`, then `<slug>-group-2`, `-group-3`, …) until it's non-colliding. The rename is audited in `decisions.yaml` as `decision: slug-renamed`. This pre-empts the DUP-ID class of validation failure that would otherwise rollback the entire NEST after apply — including cross-depth collisions (e.g. a cluster slug `event-patterns` proposed under `design-patterns-group/` that would collide with an existing `arch/event-patterns/` in a different branch of the tree). The optional `opts.wikiIndex` argument accepts a precomputed `Set` from `buildWikiForbiddenIndex(wikiRoot)` — the convergence loop builds it once per iteration and mutates it with `wikiIndex.add(resolvedSlug)` after each successful apply, dropping per-proposal cost from O(full-tree) to O(parent-dir). `wikiRoot` is itself optional: legacy callers that omit it get the parent-dir-only walk preserved from v1.0.0 (modulo the dot-skip rule described in the module source).
 2. Creates `<parent>/<slug>/` (using the resolved slug).
 3. Moves each cluster member into the new directory and rewrites its `parents[]` to `["index.md"]`.
 4. Writes a minimal `index.md` stub carrying `id` (= resolved slug), `type: index`, `depth_role: subcategory`, a `focus:` line from the cluster purpose, and — when the members share them — `shared_covers[]` (intersection of member covers) and `tags[]` (intersection of member tags). The stub does NOT carry aggregated `activation_defaults`: routing is semantic, and descent decisions are made against the stub's `focus` + `shared_covers`, not against a literal keyword union.

package/guide/substrate/tiered-ai.md

@@ -9,7 +9,7 @@ covers:
   - "Tier 0 is TF-IDF over frontmatter (focus + covers + tags) with fixed thresholds"
   - "Tier 1 is local embeddings via @xenova/transformers (MiniLM, REQUIRED dep)"
   - "Tier 2 is a sub-agent, executed via the CLI exit-7 handshake (never inline)"
-  - default quality mode is tiered-fast; claude-first and tier0-only are opt-in
+  - default quality mode is tiered-fast; claude-first and deterministic are opt-in
   - "similarity-cache at <wiki>/.llmwiki/similarity-cache/ memoises pairwise results"
   - "decision-log at <wiki>/.llmwiki/decisions.yaml records every non-trivial decision"
   - operator-convergence routes every MERGE similarity check through tiered.decide
@@ -85,8 +85,9 @@ well-structured corpora — pairs of near-duplicate entries
 should collapse as SAME, obviously unrelated pairs as DIFFERENT
 — leaving only genuinely ambiguous pairs to escalate. The actual
 Tier 0 hit rate on a given wiki depends on how informative the
-frontmatter is; run with `--quality-mode tier0-only` and inspect
-`decisions.yaml` to measure the tier distribution for your corpus.
+frontmatter is; inspect `decisions.yaml` after a build to measure
+the tier distribution for your corpus (grep the `tier:` field on
+every decision entry).
 
 ## Tier 1 — local embeddings (scripts/lib/embeddings.mjs)
 
@@ -275,13 +276,13 @@ all of its Tier 2 cost on subsequent rebuilds.
 
 ## Quality modes
 
-Choose via `--quality-mode` or the `LLM_WIKI_QUALITY_MODE` env var.
+Choose via `--quality-mode` (flag) or `LLM_WIKI_QUALITY_MODE` (env var). The flag wins when both are set. Invalid values on EITHER path raise `INT-13` at the intent layer with the same valid-values suggestions — a stale env value from an obsolete shell profile fails loud on the next `skill-llm-wiki` invocation rather than silently falling through to a plain throw at convergence time. Env-var validation is gated to subcommands that consume quality mode (build / extend / rebuild / fix / join); recovery paths like `rollback` are unaffected.
 
 | Mode | Behaviour | Use when |
 |------|-----------|----------|
 | **`tiered-fast`** (default) | Full ladder. Tier 0 → Tier 1 → Tier 2 on mid-band escalations. | General-purpose builds. |
 | `claude-first` | Tier 0 is still consulted for decisive cases. Mid-band Tier 0 skips Tier 1 and goes directly to Tier 2. | When the user values Claude's judgment over speed/cost. |
-| `tier0-only` | Tier 0 only. Mid-band decisions become "undecidable" and the caller must resolve manually. | Air-gapped, hermetic CI, and smoke tests that must not reach out to Claude. |
+| `deterministic` | Tier 0 → Tier 1 ladder with a static threshold resolving mid-band Tier 1 pairs. No LLM/sub-agent is ever consulted. Cluster naming comes from `generateDeterministicSlug` + `deterministicPurpose`; Tier 2 escalations are skipped entirely. Repeated runs on the same inputs produce byte-reproducible output. | Hermetic CI; large deterministic corpus builds where reproducibility matters more than Tier 2's naming nuance. For air-gapped use, pre-warm the Tier 1 MiniLM model cache on a networked host — `@xenova/transformers` downloads the model on first use otherwise. |
 
 ## Similarity cache
 

package/guide/ux/user-intent.md

@@ -9,7 +9,7 @@ covers:
   - the CLI refuses every ambiguous invocation with a structured INT-NN code
   - Claude MUST ask the user before running the skill when intent is unclear
   - ambiguity scenarios each have a fixed resolving flag the user can pick
-  - "--json-errors makes the ambiguity body machine-parseable for Claude to read"
+  - "--json (canonical) or --json-errors (legacy alias) makes the ambiguity body machine-parseable for Claude to read"
   - "--no-prompt / LLM_WIKI_NO_PROMPT=1 disables interactive fallback; failures become hard errors"
   - never silently default — the cost of a wrong guess is always higher than a clarifying question
 tags:
@@ -80,13 +80,14 @@ in the wrong place) is always higher than a one-sentence clarifying question.
 | INT-10 | Unknown `--layout-mode` value | use `sibling` / `in-place` / `hosted` |
 | INT-11 | Unknown flag / malformed flag value | correct the flag |
 | INT-12 | Prompt required in non-interactive mode | supply the flag the prompt was asking for, or re-run in a TTY |
-| INT-13 | Unknown `--quality-mode` value | use `tiered-fast` / `claude-first` / `tier0-only` |
+| INT-13 | Unknown `--quality-mode` value | use `tiered-fast` / `claude-first` / `deterministic` |
 
-## `--json-errors` for programmatic consumption
+## `--json` for programmatic consumption
 
 When the skill is called from a script or from another Claude session, pass
-`--json-errors` on every invocation. The ambiguity body becomes a single JSON
-object on stderr:
+`--json` (canonical) on every invocation; `--json-errors` is the legacy alias
+and continues to work. The ambiguity body becomes a single JSON object on
+stderr:
 
 ```json
 {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ctxr/skill-llm-wiki",
-  "version": "1.0.1",
+  "version": "1.1.0",
   "description": "Claude Code skill — build, extend, validate, rebuild, fix, and join LLM wikis from any knowledge corpus. Token-efficient retrieval via hierarchical indices, DAG parents, and deterministic rewrite operators.",
   "type": "module",
   "license": "MIT",
@@ -31,12 +31,16 @@
     "LICENSE",
     "CHANGELOG.md",
     "scripts/",
-    "guide/"
+    "guide/",
+    "templates/"
   ],
   "ctxr": {
     "type": "skill",
     "target": "folder"
   },
+  "bin": {
+    "skill-llm-wiki": "scripts/cli.mjs"
+  },
   "scripts": {
     "test": "node --test",
     "validate": "node scripts/cli.mjs --version",
@@ -50,6 +54,8 @@
   },
   "dependencies": {
     "@xenova/transformers": "2.17.2",
-    "gray-matter": "^4.0.3"
+    "gray-matter": "^4.0.3",
+    "p-retry": "^6.2.0",
+    "p-timeout": "^6.1.3"
   }
 }