@ctxr/skill-llm-wiki 1.0.1 → 1.1.0

package/guide/consumers/recipes/dated-wiki.md

@@ -0,0 +1,131 @@
+---
+id: recipe-dated-wiki
+type: primary
+depth_role: leaf
+focus: "Init a dated topic wiki (reports, sessions, regressions) with one command"
+parents:
+  - ../index.md
+tags:
+  - dated
+  - init
+  - hosted
+  - consumers
+activation:
+  keyword_matches:
+    - dated wiki
+    - reports wiki
+    - sessions wiki
+    - regressions wiki
+    - yyyy/mm/dd
+  tag_matches:
+    - dated
+    - init
+
+generator: "skill-llm-wiki/v1"
+---
+
+# Recipe: dated wiki
+
+## Trigger
+
+Your consumer wants to manage a topic whose entries accrete by date (reports, sessions, regression notes, anything with a timestamp). A flat list of date-prefixed siblings will break past a few dozen entries; a nested `{yyyy}/{mm}/{dd}` structure scales indefinitely.
+
+## Commands
+
+```bash
+# Seed the layout contract from a shipped starter template and
+# emit the envelope:
+skill-llm-wiki init .development/shared/reports \
+  --kind dated --template reports --json
+
+# The envelope names the next command to run. Typically:
+skill-llm-wiki build .development/shared/reports \
+  --layout-mode hosted --target .development/shared/reports --json
+```
+
+Available dated templates (from `skill-llm-wiki contract --json` → `layout_tokens`, and `scripts/lib/templates.mjs`):
+
+| Template | Default path template | Best for |
+|---|---|---|
+| `reports` | `{yyyy}/{mm}/{dd}` | review reports, investigations |
+| `sessions` | `{yyyy}/{mm}/{dd}` | daily session logs |
+| `regressions` | `{yyyy}/{mm}` | bug triage, post-mortems |
+| `plans` | `{yyyy}/{mm}/{dd}` | implementation plans + subject families |
+
+If you omit `--template`, `--kind dated` falls back to `reports`.
+
+## Envelope fields
+
+After `init` succeeds, the envelope is:
+
+```json
+{
+  "schema": "skill-llm-wiki/v1",
+  "command": "init",
+  "target": "/abs/path/to/.development/shared/reports",
+  "verdict": "initialised",
+  "exit": 0,
+  "diagnostics": [
+    {
+      "code": "NEXT-01",
+      "severity": "info",
+      "path": "/abs/path/to/.development/shared/reports",
+      "message": "contract seeded; next step: skill-llm-wiki build ..."
+    }
+  ],
+  "artifacts": {
+    "created": ["/abs/.../.llmwiki.layout.yaml"],
+    "modified": [],
+    "deleted": []
+  },
+  "next": {
+    "command": "skill-llm-wiki",
+    "args": ["build", "/abs/.../reports", "--layout-mode", "hosted", "--target", "/abs/.../reports", "--json"]
+  },
+  "timing_ms": 12
+}
+```
+
+Consumers read the structured `next` field to get the exact build command: `env.next.command` + `env.next.args` go directly into `spawnSync`. The `NEXT-01` diagnostic carries the same hint as human-readable prose for operators tailing stdout, but it is not the canonical machine form.
+
+## Minimum consumer code
+
+```js
+import { spawnSync } from "node:child_process";
+
+function initDated(topicPath, template = "reports") {
+  const r = spawnSync(
+    "skill-llm-wiki",
+    ["init", topicPath, "--kind", "dated", "--template", template, "--json"],
+    { encoding: "utf8" },
+  );
+  if (r.status !== 0) throw new Error(`init failed: ${r.stderr}`);
+  const env = JSON.parse(r.stdout);
+  if (env.verdict !== "initialised") throw new Error(env.diagnostics?.[0]?.message ?? "unexpected");
+  // Prefer the structured `next` field over parsing NEXT-01.
+  return {
+    contractPath: env.artifacts.created[0],
+    next: env.next, // { command: "skill-llm-wiki", args: ["build", ...] }
+  };
+}
+
+// Consumers that want to run the build immediately:
+function initAndBuild(topicPath, template = "reports") {
+  const { next } = initDated(topicPath, template);
+  if (!next) throw new Error("init envelope missing `next` field");
+  const r2 = spawnSync(next.command, next.args, { encoding: "utf8", stdio: "inherit" });
+  if (r2.status !== 0) throw new Error(`build exited ${r2.status}`);
+}
+```
+
+## Failure modes
+
+- `verdict: "ambiguous"` with `INIT-02`: you passed neither `--kind` nor `--template`.
+- `verdict: "ambiguous"` with `INIT-05`: `--kind` and `--template` disagree (e.g. `--kind dated --template runbooks`).
+- `verdict: "ambiguous"` with `INIT-07`: a `.llmwiki.layout.yaml` already exists. Pass `--force` only if you are sure the existing contract is wrong; otherwise `skill-llm-wiki rebuild` against the existing contract instead.
+- `verdict: "ambiguous"` with `INIT-08`: the topic path (or the contract path inside it) exists as a symbolic link. `init` refuses to follow symlinks into unknown targets for security. Resolve the symlink explicitly (`realpath <topic>`) and pass the resolved path, or remove the symlink.
+
+## Do not
+
+- Copy the template file by hand. The skill's `init` command reads the same file; there is no reason to duplicate it in your own repo.
+- Pick `{yyyy}-{mm}-{dd}` as a filename prefix. Flat date-prefixed siblings are refused by `validate`.

package/guide/consumers/recipes/format-gate.md

@@ -0,0 +1,126 @@
+---
+id: recipe-format-gate
+type: primary
+depth_role: leaf
+focus: "Gate consumer CI on skill-llm-wiki contract --json format_version"
+parents:
+  - ../index.md
+tags:
+  - contract
+  - format-version
+  - compatibility
+  - consumers
+activation:
+  keyword_matches:
+    - format version
+    - contract gate
+    - compatibility check
+    - version gate
+    - drift detection
+  tag_matches:
+    - contract
+    - format-version
+
+generator: "skill-llm-wiki/v1"
+---
+
+# Recipe: format_version gate
+
+## Trigger
+
+Your consumer's tests used to drift-test against SKILL.md prose. Replace that with a single integer comparison against `format_version`.
+
+## Commands
+
+```bash
+skill-llm-wiki contract --json
+```
+
+Parse the contract JSON; assert `format_version >= <your required>`. Note that `contract --json` emits the contract shape (schema `skill-llm-wiki/contract/v1`), NOT the operational envelope (`skill-llm-wiki/v1`). It carries no `verdict` or `diagnostics` fields.
+
+## Contract JSON fields
+
+```json
+{
+  "schema": "skill-llm-wiki/contract/v1",
+  "format_version": 1,
+  "min_consumer_format_version": 1,
+  "package_version": "1.0.1",
+  "frontmatter_schema": { "leaf": { "required": [...], "fields": {...} } },
+  "layout_tokens": [{ "token": "{yyyy}", "description": "..." }, ...],
+  "subcommands": { "build": { "positionals": ["source"], "flags": [...] }, ... },
+  "envelope_schema": { "schema": "skill-llm-wiki/v1", "fields": {...} },
+  "exit_codes": { "0": "ok", "1": "usage error", ... }
+}
+```
+
+Fields consumers care about:
+
+- `format_version`: integer. Bumps on breaking changes.
+- `min_consumer_format_version`: integer. The oldest consumer format_version the current skill still speaks to. A consumer whose required version is below this refuses to run; between this and `format_version` runs unchanged.
+- `package_version`: semver string. For display only; gate on `format_version`, not on semver.
+
+## Minimum consumer code
+
+```js
+import { spawnSync } from "node:child_process";
+
+export const REQUIRED_WIKI_FORMAT_VERSION = 1;
+
+export function enforceContract(required = REQUIRED_WIKI_FORMAT_VERSION) {
+  const r = spawnSync("skill-llm-wiki", ["contract", "--json"], {
+    encoding: "utf8",
+  });
+  if (r.status !== 0) {
+    throw new Error(
+      `skill-llm-wiki contract failed (${r.status}): ${r.stderr}`,
+    );
+  }
+  const env = JSON.parse(r.stdout);
+  if (env.format_version < required) {
+    throw new Error(
+      `skill-llm-wiki format_version=${env.format_version} is below the required ${required}. ` +
+        `Upgrade: npm i -g @ctxr/skill-llm-wiki@latest`,
+    );
+  }
+  if (env.min_consumer_format_version > required) {
+    throw new Error(
+      `skill-llm-wiki dropped support for format_version=${required}; ` +
+        `current min_consumer_format_version=${env.min_consumer_format_version}. ` +
+        `Your consumer must upgrade its integration to format_version >= ${env.min_consumer_format_version}.`,
+    );
+  }
+  return env;
+}
+```
+
+## CI one-liner
+
+```bash
+# Fail CI if the installed skill is below the required format_version.
+FV=$(skill-llm-wiki contract --json | jq -r '.format_version')
+if [ "$FV" -lt 1 ]; then echo "skill format_version=$FV below required 1" >&2; exit 1; fi
+```
+
+## When to bump your required version
+
+Bump `REQUIRED_WIKI_FORMAT_VERSION` when:
+
+- The skill bumps `format_version` and your consumer depends on the new behaviour.
+- A leaf frontmatter field your consumer reads is added or removed.
+- A CLI flag your consumer passes becomes mandatory or is removed.
+- The operational envelope shape (schema `skill-llm-wiki/v1`) changes a field your consumer parses from validate/init/heal/rollback output.
+
+Do NOT bump when the skill ships a `package_version` patch or minor release that doesn't touch the contract.
+
+## Failure modes
+
+- `format_version` missing from the contract JSON: the skill is too old to declare a format version (pre-1). Treat as `< 1` and fail with an upgrade message.
+- Contract JSON is unparseable: the skill's `contract` subcommand is broken. Open an issue upstream.
+- `min_consumer_format_version` exceeds your required version: the skill intentionally dropped support for your version. You must upgrade your consumer.
+
+## Do not
+
+- Drift-test against SKILL.md prose. The contract subcommand exists specifically so consumers do not need to read SKILL.md programmatically.
+- Gate on `package_version` semver. A patch release can ship bug fixes without bumping `format_version`; a `format_version` bump is the only breaking-change signal.
+- Cache the contract across PR runs. It's a ~100ms probe; run it every time.

package/guide/consumers/recipes/post-write-heal.md

@@ -0,0 +1,125 @@
+---
+id: recipe-post-write-heal
+type: primary
+depth_role: leaf
+focus: "The canonical after-every-leaf-write heal invocation"
+parents:
+  - ../index.md
+tags:
+  - heal
+  - envelope
+  - post-write
+  - consumers
+activation:
+  keyword_matches:
+    - post write
+    - after write
+    - heal
+    - validate after write
+    - next command
+  tag_matches:
+    - heal
+    - post-write
+
+generator: "skill-llm-wiki/v1"
+---
+
+# Recipe: post-write heal
+
+## Trigger
+
+Your consumer just wrote a leaf into a hosted wiki. Before moving on, call `heal` to classify the wiki's state and let it name the next command.
+
+## Commands
+
+```bash
+skill-llm-wiki heal .development/shared/reports --json
+```
+
+That is the entire step. Do not invoke `validate`, `fix`, or `rebuild` directly; `heal` is the router.
+
+## Envelope fields
+
+```json
+{
+  "schema": "skill-llm-wiki/v1",
+  "command": "heal",
+  "target": "/abs/.../reports",
+  "verdict": "ok" | "fixable" | "needs-rebuild" | "broken" | "ambiguous",
+  "exit": 0,
+  "diagnostics": [
+    { "code": "IDX-01", "severity": "warning", "path": "...", "message": "..." },
+    { "code": "NEXT-01", "severity": "info",    "path": "...", "message": "next: skill-llm-wiki fix ... --json" }
+  ],
+  "next": { "command": "skill-llm-wiki", "args": ["fix", "/abs/.../reports", "--json"] },
+  "timing_ms": 23
+}
+```
+
+> The `next` field is the canonical machine-readable form. The `NEXT-01`
+> info diagnostic carries the same hint as a human-readable string for
+> operators tailing stdout; consumers should prefer `env.next` and only
+> fall back to parsing the diagnostic when running against a pre-v1
+> skill that does not emit it.
+
+| Verdict | What the consumer does |
+|---|---|
+| `ok` | Nothing. Move on. |
+| `fixable` | Invoke `env.next.command` with `env.next.args` (typically `skill-llm-wiki fix <wiki> --json`). |
+| `needs-rebuild` | Invoke `env.next.command` with `env.next.args` (typically `skill-llm-wiki rebuild <wiki> --json`). |
+| `broken` | Surface every `severity: "error"` diagnostic to the user. Do not auto-mutate. |
+| `ambiguous` | `validate` itself failed; inspect `HEAL-00` diagnostic for the error. |
+
+## Minimum consumer code
+
+```js
+import { spawnSync } from "node:child_process";
+
+function healAfterWrite(wikiPath) {
+  const r = spawnSync(
+    "skill-llm-wiki",
+    ["heal", wikiPath, "--json"],
+    { encoding: "utf8" },
+  );
+  const env = JSON.parse(r.stdout);
+  switch (env.verdict) {
+    case "ok":
+      return;
+    case "fixable":
+    case "needs-rebuild": {
+      if (!env.next) throw new Error("heal returned fixable/needs-rebuild without a `next` field");
+      const result = spawnSync(env.next.command, env.next.args, { stdio: "inherit" });
+      if (result.status !== 0) {
+        throw new Error(`follow-up ${env.next.command} exited ${result.status}`);
+      }
+      return;
+    }
+    case "broken":
+      reportDiagnosticsToUser(env.diagnostics);
+      throw new Error(`heal: wiki is broken at ${wikiPath}`);
+    default:
+      throw new Error(`heal: unexpected verdict ${env.verdict}`);
+  }
+}
+```
+
+## Failure modes
+
+- `verdict: "ambiguous"` with a `HEAL-00` diagnostic: validate threw. The wiki substrate itself may be broken (e.g. missing `.llmwiki/git/`).
+- A `fixable` run whose follow-up `fix` invocation fails: re-run `heal`; it should now report `needs-rebuild` or `broken`.
+- `heal` on a path that does not exist or is not a wiki returns `verdict: "broken"` with `WIKI-01` in diagnostics.
+
+## Why not `fix` / `rebuild` / `validate` directly?
+
+Consumers that pick one of the three without checking the validate output end up:
+
+- Running `fix` on a structurally-broken wiki that only `rebuild` can resolve.
+- Running `rebuild` on a wiki with trivial index drift, triggering unnecessary Tier 2 sub-agent work.
+- Running `validate` and then duplicating the action table consumers always get wrong.
+
+`heal` centralises the classification so every consumer uses the same rules.
+
+## Do not
+
+- Call `heal` on hot paths (per-keystroke). It runs full validate; budget for one invocation per logical leaf-write batch.
+- Ignore `broken` verdicts silently. The wiki is corrupt and further writes will compound the problem.

package/guide/consumers/recipes/skill-absent.md

@@ -0,0 +1,111 @@
+---
+id: recipe-skill-absent
+type: primary
+depth_role: leaf
+focus: "Detect the skill is missing and surface an upgrade path without silently degrading"
+parents:
+  - ../index.md
+tags:
+  - skill-absent
+  - preflight
+  - install-hint
+  - consumers
+activation:
+  keyword_matches:
+    - skill missing
+    - skill not installed
+    - install hint
+    - preflight skill
+    - hard dependency
+  tag_matches:
+    - skill-absent
+    - preflight
+
+generator: "skill-llm-wiki/v1"
+---
+
+# Recipe: skill-absent detection
+
+## Trigger
+
+Your consumer treats `@ctxr/skill-llm-wiki` as a hard dependency and must refuse to run when the skill is missing, rather than silently degrading to raw-markdown writes.
+
+## Commands
+
+```bash
+skill-llm-wiki contract --json
+```
+
+This is the canonical probe. It is exempt from the runtime-dep preflight inside the skill itself, so even a partially-broken install still answers the probe as long as the binary is on PATH.
+
+## Decision tree
+
+`skill-llm-wiki contract --json` emits the **contract JSON** (schema `skill-llm-wiki/contract/v1`), not the operational envelope (`skill-llm-wiki/v1`). It has no `verdict` or `diagnostics` fields; gate on `format_version` directly.
+
+1. `skill-llm-wiki contract --json` exits `0` with a parseable contract JSON containing `format_version >= <your required>`: proceed.
+2. `skill-llm-wiki contract --json` exits `0` with `format_version` below your required value: the skill is present but too old. Surface an upgrade message.
+3. `skill-llm-wiki contract --json` exits non-zero: the skill is installed but broken (e.g. runtime deps corrupted). Surface a reinstall message.
+4. The binary is not on PATH (spawnSync returns ENOENT or no output): the skill is not installed. Surface an install message.
+
+## Minimum consumer code
+
+```js
+import { spawnSync } from "node:child_process";
+
+const REQUIRED_FORMAT_VERSION = 1;
+
+export function probeSkill() {
+  const r = spawnSync("skill-llm-wiki", ["contract", "--json"], {
+    encoding: "utf8",
+  });
+  if (r.error && r.error.code === "ENOENT") {
+    return { ok: false, state: "absent" };
+  }
+  if (r.status !== 0) {
+    return { ok: false, state: "broken", stderr: r.stderr };
+  }
+  try {
+    const env = JSON.parse(r.stdout);
+    if ((env.format_version ?? 0) < REQUIRED_FORMAT_VERSION) {
+      return { ok: false, state: "too-old", current: env.format_version };
+    }
+    return { ok: true, ...env };
+  } catch {
+    return { ok: false, state: "unparseable" };
+  }
+}
+
+export function enforceSkillPresent() {
+  const p = probeSkill();
+  if (p.ok) return p;
+  const hint =
+    p.state === "absent"
+      ? "@ctxr/skill-llm-wiki is not installed.\n" +
+        "Install with: npx @ctxr/kit install @ctxr/skill-llm-wiki"
+      : p.state === "too-old"
+        ? `@ctxr/skill-llm-wiki format_version ${p.current} is below the required ${REQUIRED_FORMAT_VERSION}.\n` +
+          "Upgrade with: npm i -g @ctxr/skill-llm-wiki@latest"
+        : `@ctxr/skill-llm-wiki is installed but not answering the contract probe.\n${p.stderr ?? ""}`;
+  throw new Error(hint);
+}
+```
+
+## Do not
+
+- Silently fall back to raw markdown writes when the skill is missing. Every downstream tool that expects the wiki format will break.
+- Inline the install command guess. Read the contract JSON's `package_version` and compare to your own requirement; publish your install hint alongside your agent.
+- Cache the probe result across sessions. A user can uninstall the skill at any time; the probe is cheap (~100ms) and should run once per invocation.
+
+## Recovery
+
+Once the consumer reports the skill is missing, recovery for the user is:
+
+```bash
+# Via @ctxr/kit (preferred, manages SKILL.md path + update flow):
+npx @ctxr/kit install @ctxr/skill-llm-wiki
+
+# Or plain npm for CI / scripted environments:
+npm i -g @ctxr/skill-llm-wiki
+```
+
+The consumer's preflight should re-run `probeSkill()` after the install.

package/guide/consumers/recipes/subject-wiki.md

@@ -0,0 +1,110 @@
+---
+id: recipe-subject-wiki
+type: primary
+depth_role: leaf
+focus: "Init a subject topic wiki (runbooks, adrs) with nested categories"
+parents:
+  - ../index.md
+tags:
+  - subject
+  - init
+  - hosted
+  - consumers
+activation:
+  keyword_matches:
+    - subject wiki
+    - runbooks wiki
+    - adr wiki
+    - nested categories
+  tag_matches:
+    - subject
+    - init
+
+generator: "skill-llm-wiki/v1"
+---
+
+# Recipe: subject wiki
+
+## Trigger
+
+Your consumer wants to manage a topic whose entries group by subject (runbooks, architecture decisions, playbooks). The wiki grows by adding subcategories, not dates.
+
+## Commands
+
+```bash
+skill-llm-wiki init .development/shared/runbooks \
+  --kind subject --template runbooks --json
+
+# After init, build (one-time):
+skill-llm-wiki build .development/shared/runbooks \
+  --layout-mode hosted --target .development/shared/runbooks --json
+```
+
+Available subject templates:
+
+| Template | Best for |
+|---|---|
+| `runbooks` | operational runbooks, playbooks, incident response |
+| `adrs` | architecture decision records (zero-padded sequential prefix) |
+
+If you omit `--template`, `--kind subject` falls back to `runbooks`.
+
+## Category promotion rule
+
+Both shipped templates encode the same invariant in their `global_invariants`: create a subject subfolder on the first write, and grow the hierarchy whenever two or more leaves share a defensible grouping. Never pile leaves at the topic root after a threshold — do it on write.
+
+Your consumer should:
+
+1. Pick the subject subfolder before writing the leaf.
+2. Write the leaf at the deepest valid category path.
+3. Run `heal` (see [post-write-heal.md](post-write-heal.md)) so `validate` catches drift from the invariant.
+
+## Envelope fields
+
+Same `init` envelope as the dated recipe:
+
+```json
+{
+  "schema": "skill-llm-wiki/v1",
+  "command": "init",
+  "verdict": "initialised",
+  "target": "/abs/.../runbooks",
+  "artifacts": { "created": ["/abs/.../.llmwiki.layout.yaml"] },
+  "diagnostics": [{ "code": "NEXT-01", "severity": "info", "message": "..." }],
+  "next": {
+    "command": "skill-llm-wiki",
+    "args": ["build", "/abs/.../runbooks", "--layout-mode", "hosted", "--target", "/abs/.../runbooks", "--json"]
+  }
+}
+```
+
+Consumers read `env.next.command` + `env.next.args` to get the build invocation; the `NEXT-01` diagnostic carries the same hint as prose for humans tailing stdout.
+
+## Minimum consumer code
+
+```js
+import { spawnSync } from "node:child_process";
+
+function initSubject(topicPath, template = "runbooks") {
+  const r = spawnSync(
+    "skill-llm-wiki",
+    ["init", topicPath, "--kind", "subject", "--template", template, "--json"],
+    { encoding: "utf8" },
+  );
+  if (r.status !== 0) throw new Error(`init failed: ${r.stderr}`);
+  const env = JSON.parse(r.stdout);
+  // Prefer the structured `next` field over parsing NEXT-01.
+  return { contractPath: env.artifacts.created[0], next: env.next };
+}
+```
+
+## Failure modes
+
+- `verdict: "ambiguous"` with `INIT-05`: `--kind subject` does not match a dated template (`reports`, `sessions`, `regressions`, `plans`).
+- `verdict: "ambiguous"` with `INIT-07`: contract already exists; use `--force` or `rebuild`.
+- `verdict: "ambiguous"` with `INIT-08`: the topic path (or the contract path inside it) is a symbolic link. `init` refuses to follow symlinks for security. Resolve it explicitly or remove it before retrying.
+
+## Do not
+
+- Put runbooks in a flat list at the topic root. After three siblings, every new leaf should land under a named subcategory.
+- Use a date prefix or date subfolder. Subject wikis are explicitly not dated; that is why they use this template.