@ctxr/skill-llm-wiki 1.0.1 → 1.0.2

package/SKILL.md

@@ -1,6 +1,7 @@
 ---
 name: skill-llm-wiki
 description: Use when the user explicitly asks to build, extend, validate, repair, rebuild, or merge an LLM-optimized knowledge wiki from markdown notes, documentation, source code, or mixed folders. Default output is a single stable sibling `<source>.wiki/` with full history in a private git repo under `.llmwiki/git/`; `--layout-mode in-place` transforms the source folder itself, and `--layout-mode hosted --target <path>` honours a user-provided `.llmwiki.layout.yaml` contract. SKILL.md is the entry point; detailed operation instructions are loaded on demand from `guide/` per the routing procedure below.
+format_version: 1
 ---
 
 # skill-llm-wiki
@@ -41,6 +42,12 @@ Every operation is a git sequence: `preflight → pre-op snapshot → phase comm
 
 **Ambiguous invocations refuse and prompt.** If the user's request could mean two things (a default sibling would stomp on a foreign directory, a hosted target has no contract, `--layout-mode in-place` is combined with `--target`, …), the CLI exits with code 2 and a structured `INT-NN` error rather than guessing. See `guide/ux/user-intent.md` for the full list.
 
+## Integrating another skill or agent as a consumer
+
+If the user is building a skill, agent, or CI job that calls this skill programmatically (rather than asking you to build a wiki for them in this session), route them to `guide/consumers/index.md`. That subtree answers: how to gate on `format_version`, how to `init` a topic wiki in one command, how to `heal` after every leaf write, how to detect the skill-absent case, how to write consumer tests against the shipped `scripts/testkit/` helpers. Every consumer recipe is dispatched from `guide/consumers/index.md`; do not re-derive the integration path from SKILL.md alone.
+
+Quick probe summary: `skill-llm-wiki contract --json` returns `format_version` + the full CLI + frontmatter schema, and `skill-llm-wiki where --json` returns absolute install paths. Both are exempt from the runtime-dep preflight so consumers can probe before the skill is fully set up.
+
 ## Non-automation contract
 
 This skill has **no hooks, no filesystem watchers, no PostToolUse listeners, no install-time wiring, no background processes**. Every action happens only in direct response to an explicit user request against an explicit target directory. If the user did not ask, do nothing. Do not propose automation. Do not create hooks. Do not schedule anything.

package/guide/cli.md

@@ -12,7 +12,7 @@ covers:
   - "remote mirroring: remote add/list/remove, sync with tag-only default refspec"
   - "layout mode flags (--layout-mode sibling|in-place|hosted, --target)"
   - "tiered-AI flags (--quality-mode tiered-fast|claude-first|tier0-only)"
-  - "UX flags (--no-prompt, --json-errors, --accept-dirty, --accept-foreign-target, --review)"
+  - "UX flags (--no-prompt, --json, --json-errors (legacy alias), --accept-dirty, --accept-foreign-target, --review)"
   - "internal helpers: ingest, draft-leaf, draft-category, index-rebuild, index-rebuild-one, shape-check"
   - "exit code summary (0 ok, 1 usage, 2 validation/ambiguity/review-abort, 3 resolve miss, 4 node too old, 5 git missing/too old, 6 wiki corrupt, 7 NEEDS_TIER2 suspend-and-resume, 8 DEPS_MISSING runtime dependency missing)"
 tags:
@@ -235,7 +235,8 @@ All top-level operations accept:
 ## UX flags
 
 - `--no-prompt` / env `LLM_WIKI_NO_PROMPT=1` — fail loudly on any ambiguity instead of prompting; emits `INT-12` if the skill would otherwise ask a TTY question.
-- `--json-errors` — emit `INT-NN` ambiguity errors as JSON on stderr instead of numbered-options text.
+- `--json` — canonical machine-output flag. Enables the `skill-llm-wiki/v1` envelope on subcommands that emit one (validate, init, heal, rollback) and switches `INT-NN` ambiguity errors to JSON on stderr. The consumer-facing probe subcommands `contract` and `where` always emit JSON when this flag is present.
+- `--json-errors` — legacy alias for `--json`, kept for consumers that adopted the flag before the envelope shipped. Triggers identical behaviour. New code should pass `--json`.
 - `--accept-dirty` — operate on a source inside a dirty user git repo (escape hatch for `INT-08`).
 - `--review` — enable the `rebuild` interactive review cycle. See `guide/operations/rebuild.md`.
 

package/guide/consumers/index.md

@@ -0,0 +1,106 @@
+---
+id: consumers
+type: index
+depth_role: subcategory
+depth: 1
+focus: "Integrating another skill or agent as a consumer of skill-llm-wiki"
+parents:
+  - ../index.md
+tags:
+  - consumers
+  - integration
+  - agent
+  - skill
+  - recipes
+activation:
+  keyword_matches:
+    - consumer
+    - consume
+    - integrate
+    - integration
+    - my skill uses
+    - my agent uses
+    - wrap
+    - depend on
+    - hard dependency
+  tag_matches:
+    - consumers
+    - integration
+  escalation_from:
+    - build
+    - init
+    - heal
+    - contract
+    - where
+orientation: |
+  Route here when a user is building another skill, agent, or CI job
+  that calls skill-llm-wiki programmatically. The recipes under
+  recipes/ cover the canonical patterns: seed a dated or subject
+  wiki, run heal after every leaf write, gate CI on validate, handle
+  the skill-absent case, and wire up a consumer test suite. Each
+  recipe names the exact commands and the envelope fields consumers
+  read.
+
+  Not for: end users who are building a wiki for themselves (see
+  SKILL.md + guide/operations/ instead).
+
+entries:
+  - id: consumers-quickstart
+    file: quickstart.md
+    type: primary
+    focus: "Ten-minute integration path: detect the skill, init a topic, heal after writes"
+    tags: [quickstart, integration]
+  - id: recipe-dated-wiki
+    file: recipes/dated-wiki.md
+    type: primary
+    focus: "Init a dated topic (reports, sessions, regressions) with one command"
+    tags: [dated, init, hosted]
+  - id: recipe-subject-wiki
+    file: recipes/subject-wiki.md
+    type: primary
+    focus: "Init a subject topic (runbooks, adrs) with nested categories"
+    tags: [subject, init, hosted]
+  - id: recipe-post-write-heal
+    file: recipes/post-write-heal.md
+    type: primary
+    focus: "The canonical after-every-leaf-write heal invocation"
+    tags: [heal, envelope, post-write]
+  - id: recipe-ci-gate
+    file: recipes/ci-gate.md
+    type: primary
+    focus: "Gate CI on skill-llm-wiki validate --json"
+    tags: [ci, validate, gate]
+  - id: recipe-skill-absent
+    file: recipes/skill-absent.md
+    type: primary
+    focus: "Detect the skill is missing and surface an upgrade path without silently degrading"
+    tags: [skill-absent, preflight, install-hint]
+  - id: recipe-testing
+    file: recipes/testing.md
+    type: primary
+    focus: "Use the shipped testkit in consumer test suites"
+    tags: [testing, testkit, fixtures]
+  - id: recipe-format-gate
+    file: recipes/format-gate.md
+    type: primary
+    focus: "Gate consumer CI on skill-llm-wiki contract --json format_version"
+    tags: [contract, format-version, compatibility]
+
+generator: "skill-llm-wiki/v1"
+---
+
+# Consumers
+
+Every consumer recipe in this subtree follows the same shape:
+
+1. **Trigger** — when a consumer should activate this recipe.
+2. **Commands** — the exact CLI invocations with every flag.
+3. **Envelope fields** — which fields the consumer reads from the
+   `--json` envelope to decide what to do next.
+4. **Minimum checked-in code** — the consumer-side shell or script
+   that the recipe maps to, kept to the smallest honest example.
+5. **Failure modes** — what happens when each step goes wrong and
+   how the recipe tells the consumer to react.
+
+Consumers should read [quickstart.md](quickstart.md) first, then
+pick the recipes matching their integration shape.

package/guide/consumers/quickstart.md

@@ -0,0 +1,96 @@
+---
+id: consumers-quickstart
+type: primary
+depth_role: leaf
+focus: "Ten-minute integration path for any consumer that shells out to skill-llm-wiki"
+parents:
+  - index.md
+tags:
+  - quickstart
+  - integration
+  - consumers
+activation:
+  keyword_matches:
+    - quickstart
+    - getting started
+    - first integration
+    - how do i call
+    - new consumer
+  tag_matches:
+    - quickstart
+
+generator: "skill-llm-wiki/v1"
+---
+
+# Quickstart
+
+You are building a skill, agent, or CI job that wants to manage docs via `skill-llm-wiki`. Here is the shortest path that gets you working without reinventing the common scaffolding.
+
+## 1. Declare the dependency and gate on format_version
+
+`skill-llm-wiki` ships a machine-readable version contract. Read it in your preflight:
+
+```bash
+skill-llm-wiki contract --json | jq -r '.format_version'
+```
+
+Fail fast if that number is below your required minimum. See [recipes/format-gate.md](recipes/format-gate.md) for the canonical gate.
+
+## 2. Locate the install path once
+
+Every other consumer concern (templates, testkit, SKILL.md) hangs off one canonical probe:
+
+```bash
+skill-llm-wiki where --json
+```
+
+Fields you will actually use: `skill_root`, `skill_md`, `templates_dir`, `testkit_dir`. Stop hard-coding `~/.claude/skills/ctxr-skill-llm-wiki/...`; read it from the probe.
+
+## 3. Init a topic wiki with one command
+
+Instead of copying a layout contract and then running build with the right flags, use:
+
+```bash
+skill-llm-wiki init .development/shared/reports --kind dated --template reports --json
+```
+
+The skill seeds the contract from its own shipped templates and prints the exact `build` command to run next. See [recipes/dated-wiki.md](recipes/dated-wiki.md) and [recipes/subject-wiki.md](recipes/subject-wiki.md).
+
+## 4. After every leaf write, run heal
+
+Your consumer writes a leaf. Immediately call:
+
+```bash
+skill-llm-wiki heal .development/shared/reports --json
+```
+
+Parse the envelope. Switch on `verdict`:
+
+- `ok`: nothing to do.
+- `fixable`: run `skill-llm-wiki fix <wiki>`.
+- `needs-rebuild`: run `skill-llm-wiki rebuild <wiki>`.
+- `broken`: surface the diagnostics to the user; do not auto-mutate.
+
+See [recipes/post-write-heal.md](recipes/post-write-heal.md) for the full envelope handling.
+
+## 5. Gate CI on validate
+
+Your CI job runs `skill-llm-wiki validate <wiki> --json` against every wiki the project ships. See [recipes/ci-gate.md](recipes/ci-gate.md).
+
+## 6. Handle the skill-absent case explicitly
+
+If your consumer is a hard dependency on `skill-llm-wiki`, refuse to run when the skill is missing and point the user at the install command. See [recipes/skill-absent.md](recipes/skill-absent.md) for the canonical message and exit shape.
+
+## 7. Use the shipped testkit in your test suite
+
+Hand-rolled stubs and fixtures drift over time. Import from `scripts/testkit/` (path discoverable via `where --json`). See [recipes/testing.md](recipes/testing.md).
+
+## What this replaces
+
+- Hand-written layout YAML files duplicated across every consumer.
+- `validate → fix → rebuild` ladders reimplemented per consumer.
+- Three-step path discovery for SKILL.md.
+- Drift-detection tests against SKILL.md prose.
+- Hand-rolled presence stubs.
+
+The envelope schema is stable across `format_version` 1; consumers gate on that integer and bump when the skill does.

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

@@ -0,0 +1,125 @@
+---
+id: recipe-ci-gate
+type: primary
+depth_role: leaf
+focus: "Gate CI on skill-llm-wiki validate --json"
+parents:
+  - ../index.md
+tags:
+  - ci
+  - validate
+  - gate
+  - consumers
+activation:
+  keyword_matches:
+    - ci gate
+    - ci validation
+    - github actions
+    - gitlab pipeline
+    - pre-commit wiki
+  tag_matches:
+    - ci
+    - gate
+
+generator: "skill-llm-wiki/v1"
+---
+
+# Recipe: CI gate
+
+## Trigger
+
+Your consumer wants CI to reject PRs that break wikis shipped in the repository.
+
+## Commands
+
+```bash
+skill-llm-wiki validate .development/shared/reports --json
+```
+
+Exit code `0` → clean. Exit code `2` → errors found; CI should fail.
+
+## Envelope fields
+
+```json
+{
+  "schema": "skill-llm-wiki/v1",
+  "command": "validate",
+  "target": "/abs/.../reports",
+  "verdict": "ok" | "broken",
+  "exit": 0 | 2,
+  "diagnostics": [
+    { "code": "IDX-01", "severity": "warning", "path": "...", "message": "..." },
+    { "code": "PARSE",  "severity": "error",   "path": "...", "message": "..." }
+  ],
+  "timing_ms": 412
+}
+```
+
+CI should fail when `exit !== 0` AND any diagnostic with `severity: "error"` is present. A warning-only run exits 0.
+
+## GitHub Actions example
+
+```yaml
+# .github/workflows/wiki-validate.yml
+name: wiki-validate
+on: [pull_request]
+jobs:
+  validate:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-node@v4
+        with: { node-version: "20" }
+      - run: npm i -g @ctxr/skill-llm-wiki
+      - name: contract gate
+        run: |
+          FV=$(skill-llm-wiki contract --json | jq -r '.format_version')
+          if [ "$FV" -lt 1 ]; then
+            echo "skill-llm-wiki format_version=$FV is below required 1" >&2
+            exit 1
+          fi
+      - name: validate reports
+        run: skill-llm-wiki validate .development/shared/reports --json | tee validate.json
+      - name: fail on error diagnostics
+        run: |
+          errs=$(jq '[.diagnostics[] | select(.severity == "error")] | length' validate.json)
+          if [ "$errs" -gt 0 ]; then
+            jq '.diagnostics[] | select(.severity == "error")' validate.json
+            exit 1
+          fi
+```
+
+## Pre-commit / husky example
+
+```json
+// package.json
+"scripts": {
+  "wiki:validate": "skill-llm-wiki validate .development/shared/reports --json | node scripts/wiki-validate-check.mjs"
+}
+```
+
+```js
+// scripts/wiki-validate-check.mjs
+import { readFileSync } from "node:fs";
+const env = JSON.parse(readFileSync(0, "utf8"));
+const errors = env.diagnostics.filter((d) => d.severity === "error");
+if (errors.length > 0) {
+  for (const e of errors) console.error(`[${e.code}] ${e.path}: ${e.message}`);
+  process.exit(1);
+}
+```
+
+## Failure modes
+
+- Validate exits `2`: error-severity findings present in the wiki; `.diagnostics` contains one entry per finding with its code, severity, path, and message.
+- Validate exits `4`: Node.js too old on the CI runner. Upgrade to Node 20 or the version pinned in the skill's `.nvmrc`.
+- Validate exits `5`: git missing or too old on the runner.
+- Validate exits `7`: impossible for `validate` alone; only reachable from build/extend/rebuild (Tier 2 suspend-and-resume).
+- Validate exits `8`: runtime deps missing on CI runner. Install `@ctxr/skill-llm-wiki` (and its transitive deps) in the CI image.
+- For wiki-substrate corruption (missing `.llmwiki/git/`, divergent refs), run `skill-llm-wiki heal <wiki> --json` instead — `heal` is the subcommand that classifies substrate state and surfaces verdict `broken` with exit 6.
+
+## Do not
+
+- Parse `stderr` for errors. The envelope on stdout is the contract; stderr is free-form logging.
+- Silence errors with `|| true`. Validate failures are real; a broken wiki in `main` propagates to every downstream consumer.
+- Rerun validate in a loop until it passes. If it fails once, it fails deterministically.

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.