@isonimus/stele 0.1.2 → 0.3.0

package/.claude/commands/adr.md

@@ -5,16 +5,17 @@ argument-hint: <short title of the decision>
 
 Create a new ADR recording a decision that later work must obey — a mechanism, data
 format, or boundary. An ADR asserts *"on date X we chose Y because Z"*: a historical
-claim that stays true forever (ADR-0001). If you are recording a **feature work-unit**
+claim that stays true forever (stele:ADR-0001). If you are recording a **feature work-unit**
 rather than a durable decision, use `/slice` instead.
 
 Steps:
 
-1. Compute the next free id: the highest ordinal in `adr/` plus one, zero-padded to four
-   digits. Do not reuse or renumber.
+1. Compute the next free id: the highest ordinal across **both** `adr/` and `slices/` plus
+   one, zero-padded to four digits. ADRs and slices share one id space — rule 2 fails on a
+   duplicate id whichever directory it sits in. Do not reuse or renumber.
 2. Choose the `type`: `architecture` for a durable decision, `slice` for a feature unit,
    `batch` only if it genuinely bundles several unrelated decisions that cannot map 1:1.
-3. Write `adr/NNNN-<kebab-title>.md` opening with the ADR-0002 frontmatter block:
+3. Write `adr/NNNN-<kebab-title>.md` opening with the stele:ADR-0002 frontmatter block:
 
    ```
    ---

package/.claude/commands/init-method.md

@@ -1,9 +1,9 @@
 ---
 description: Install the method kit (CLAUDE.md, LEDGER.md, linter, index, pre-commit hook) into a git repo
-argument-hint: [repo-root] [--check | --update]
+argument-hint: [repo-root] [--check | --update [--force]]
 ---
 
-Install this kit into a repo, or verify an existing install (ADR-0006). The script does
+Install this kit into a repo, or verify an existing install (stele:ADR-0006). The script does
 the mechanical half; you do the two halves that need judgement — filling the scaffolded
 `CLAUDE.md`, and wiring verify scripts.
 
@@ -36,7 +36,7 @@ This scaffolds `adr/`, `CLAUDE.md` and `LEDGER.md` (never overwriting), vendors
 `adr/INDEX.md`, links `~/.claude/CLAUDE.md`, and installs the pre-commit hook **only if
 the corpus lints clean**.
 
-The commands are vendored under softer rules than the machinery (ADR-0007): a repo may
+The commands are vendored under softer rules than the machinery (stele:ADR-0023): a repo may
 edit its own copy of `/slice` or `/wrap-up` to say something repo-specific, and an
 install keeps that edit rather than overwriting it. If you edit one, say so — an edit
 made in an installed repo does not travel back to the toolkit.
@@ -44,7 +44,7 @@ made in an installed repo does not travel back to the toolkit.
 ## 3. If the repo already has a hook framework
 
 A target with a `.pre-commit-config.yaml` gets the doc checks **composed into it** as a
-`repo: local` block rather than a symlink (ADR-0008) — the framework owns
+`repo: local` block rather than a symlink (stele:ADR-0008) — the framework owns
 `.git/hooks/pre-commit`, and a symlink there is silently erased by the next
 `pre-commit install`. The append is idempotent and additive; the existing config is
 never reordered or rewritten, and `--update` leaves it alone.
@@ -99,7 +99,26 @@ rather than summarising it as "installed".
 this repo adapted or declined one. Read them, mention them, do not "fix" them without
 asking; that is somebody's deliberate edit.
 
-`--update` re-copies the vendored scripts, the hook and the commands — for a command it
-discards a local edit, which is exactly what it is for. It is the only way a toolkit fix
-reaches an installed repo: the copies are deliberate (ADR-0006, ADR-0007), and drift is
-the price.
+A `PROBLEM` on a command is different: it means that file is **behind the toolkit and
+unmodified here**, so the repo is simply missing a fix. `--update` takes it.
+
+## 7. Updating an installed repo
+
+```
+node scripts/init-method.mjs <target> --update --apply
+```
+
+`--update` re-copies the vendored scripts and the hook unconditionally — a locally edited
+linter is a defect, not an adaptation (stele:ADR-0006). Commands are gentler
+(stele:ADR-0023): anything this repo has **not** touched takes the toolkit's version,
+anything it **has** touched is kept and reported.
+
+`.claude/.stele-vendored.json` is what makes that distinction possible — it records what
+the toolkit last wrote, so a stale copy and a deliberate edit stop being the same
+observation. **Commit it.** A repo without one (installed before the record existed) has
+every differing command reported as unreconciled and overwrites none of them; reconcile
+those by hand, once.
+
+`--update --force` discards local adaptations. Never reach for it to make output tidy —
+it is for when the operator has decided an adaptation should go. Say what will be lost
+before running it.

package/.claude/commands/remember.md

@@ -3,7 +3,7 @@ description: Route a fact to the destination that governs it — repo CLAUDE.md,
 argument-hint: <the thing to remember>
 ---
 
-Record a durable fact. **This is a router, not a store** (ADR-0005). Your job is to decide
+Record a durable fact. **This is a router, not a store** (stele:ADR-0005). Your job is to decide
 *what the fact governs* and write it where that is enforceable — not to write it wherever
 the operator's phrasing points.
 
@@ -29,7 +29,7 @@ Two tests resolve most cases:
   zod for validation" is a fact. "Migrate the remaining validators to zod" is a task.
 
 Memory is the **residual**, not the default. If you are about to write a rule that
-constrains code into memory, you have misrouted — that is the exact failure ADR-0005
+constrains code into memory, you have misrouted — that is the exact failure stele:ADR-0005
 records, which cost an amend and force-push after the same rule was independently rewritten
 into 12 files across 8 projects.
 
@@ -38,7 +38,7 @@ into 12 files across 8 projects.
 - **Repo `CLAUDE.md`** — add to the section it belongs to. If it is a standing invariant,
   add a row to the §5 invariants table citing the ADR that created it. If this repo has no
   `CLAUDE.md`, scaffold one from `templates/CLAUDE.md` first; without it there is no
-  destination and the fact will silently fall back to memory (ADR-0005).
+  destination and the fact will silently fall back to memory (stele:ADR-0005).
 - **Global `CLAUDE.md`** — edit your global `~/.claude/CLAUDE.md`, wherever your global
   conventions live. Keep it dense: it loads into every session in every repo.
 - **`LEDGER.md`** — one line, `- [type] description (ADR-NNNN)`, citing the source ADR if
@@ -54,7 +54,7 @@ instead of adding a duplicate.
 State which destination it went to and why in one line — e.g. *"→ repo `CLAUDE.md` §3: it
 constrains code, so it needs to be greppable and reviewable."*
 
-This step is not optional. Routing cannot be linted (ADR-0005), so saying the decision out
+This step is not optional. Routing cannot be linted (stele:ADR-0005), so saying the decision out
 loud is the only thing that makes a misroute correctable in the moment rather than
 discoverable in a survey weeks later.
 

package/.claude/commands/slice.md

@@ -4,7 +4,7 @@ argument-hint: <short title of the feature>
 ---
 
 Create a new **slice**: one feature work-unit, written *before* implementation and frozen
-at merge (ADR-0001). A slice is a current-state claim while open, so it goes stale by
+at merge (stele:ADR-0001). A slice is a current-state claim while open, so it goes stale by
 nature — freezing it to past tense at merge ("this is what shipped") converts it into a
 historical claim that never goes stale. If you are recording a durable decision rather
 than a unit of feature work, use `/adr` instead.
@@ -19,7 +19,7 @@ Steps:
    ledger for any item this slice closes** — closing an item means deleting its line (see
    the ledger's own header). If nothing relates, note nothing; this is a read, not a
    requirement to invent links.
-3. Write the file opening with the ADR-0002 frontmatter block, `type: slice`:
+3. Write the file opening with the stele:ADR-0002 frontmatter block, `type: slice`:
 
    ```
    ---
@@ -36,7 +36,7 @@ Steps:
 4. Body sections, written before you code:
    - `## Goal` — what ships and why, in one paragraph. Fold in any ledger items from step 2.
    - `## Definition of Done` — **required.** The acceptance criteria as one or more
-     **Given / When / Then** scenarios, written before you code (ADR-0011). This is the
+     **Given / When / Then** scenarios, written before you code (stele:ADR-0011). This is the
      grammar, not a toolchain: plain markdown steps, no Cucumber. State the observable
      outcome — a criterion with no observable "Then" is not done-able. Each scenario's
      proof is named below in `## Verification`; a scenario with no proof is an unmet
@@ -53,7 +53,7 @@ Steps:
    - `## Design` — the approach; cite measured numbers from a probe where a design
      question has a measurable answer, not estimates. State **what existing code was
      considered**: what you searched for, what you reused, and what you deliberately did
-     *not* reuse and why (ADR-0013). This is not a mandate to reuse — the wrong abstraction
+     *not* reuse and why (stele:ADR-0013). This is not a mandate to reuse — the wrong abstraction
      costs more than a duplication (global §3, rule of three); it makes the
      reuse-or-duplicate choice *visible*, so an un-considered duplication is caught at
      review. It is checked by human read-through, not the linter: whether you truly searched
@@ -61,7 +61,7 @@ Steps:
    - `## Verification` — **required.** Name the unit tests, and if the behaviour cannot be
      asserted in a unit test (rendering, worldgen, physics, timing), name the
      `scripts/<slice>-verify.mjs` script and confirm it is wired into `package.json`
-     (ADR-0004). A slice with no `## Verification` section is incomplete. The linter
+     (stele:ADR-0004). A slice with no `## Verification` section is incomplete. The linter
      enforces both required sections (R12/R13): a `type: slice` must carry `## Verification`
      and a `## Definition of Done` holding at least one full Given/When/Then triad.
    - `## As built` — filled in at merge: what actually shipped, in past tense, confirming

package/.claude/commands/wrap-up.md

@@ -4,7 +4,7 @@ description: End-of-task gate — run the checks and ask the four questions that
 
 Run before finishing a task. The point is to make mechanical what memory keeps dropping:
 the linter catches structural drift, and four questions catch the follow-ups that never
-get recorded until they have gone stale (ADR-0003).
+get recorded until they have gone stale (stele:ADR-0003).
 
 1. Run the linter and the index check:
    - `npm run lint` — must be green (rule 9 warnings are acceptable on a legacy corpus).
@@ -12,7 +12,44 @@ get recorded until they have gone stale (ADR-0003).
      generated index is drift by another name.
    - `npm test` — the test suite must pass; docs changes must not disturb code.
 
-2. Then answer these four out loud, and act on each:
+2. **Mutation check** — only if this repo has `scripts/check-mutants.mjs` *and* this change
+   touched a module its list covers. Otherwise skip it and say so; on most changes it has
+   nothing to look at.
+
+   - `npm run mutants`. Every non-exempt mutant must die.
+   - A **survivor is not a bug** — it is correct behaviour that no test is watching, so a
+     later refactor could reverse it in silence. Fix it by writing the missing regression
+     test, never by deleting the mutant.
+   - Mark a mutant `equivalent` only when the mutated code genuinely means the same thing,
+     and say why in the entry. That field is the one way a survivor passes, so it is also
+     the obvious place to bury an inconvenient gap.
+   - It measures whether tests *bite*, not whether code is right: it cannot see a missing
+     input or a rule that was wrong from the start. A green run is not a correctness claim,
+     and step 3 is what covers what it misses.
+
+3. **Adversarial pass** (stele:ADR-0017) — run it if this change touched a `CLAUDE.md` §4
+   standing invariant, an exported/public API, a data format or anything persisted, or a
+   Definition of Done scenario the slice flagged as risky. Otherwise skip it and say so.
+
+   - Spawn one subagent (two only if the second gets a *different* brief: **correctness** —
+     edge cases, error paths, boundaries, ordering and partial-failure hazards; **cost** —
+     complexity class, allocation, IO in loops). Sonnet 5 for correctness; announce the
+     delegation before it starts (`~/.claude/CLAUDE.md` §6).
+   - Brief it **blind to intent, aware of law**: give it the diff, this repo's `CLAUDE.md`,
+     and `adr/INDEX.md`. Do *not* give it the conversation, your rationale, or the slice's
+     claims about itself. A reviewer handed the reasoning returns the reasoning; one handed
+     nothing flags every deliberate deviation as a bug.
+   - Require a concrete failure scenario per finding — input or state → wrong output,
+     crash, or a counted cost. Reject "consider validating this" at intake, uninvestigated.
+   - **Reproduce before acting.** An accepted correctness finding becomes a test that fails
+     before the fix and passes after; one you cannot reproduce is rejected. The reviewer had
+     no intent context and is confidently wrong a predictable share of the time.
+   - Route what survives through the four questions below — fix, `LEDGER.md`, `/adr`, or
+     `/slice`. **And record the rejections**: a finding you correctly dismissed will be
+     raised again by every future fresh reader until the reason is written at the site
+     (stele:ADR-0012) or in the §4 table. That is what makes the next pass cheaper than this one.
+
+4. Then answer these four out loud, and act on each:
    - **Did this change a user- or dev-facing API or feature?** If so, update `README.md`
      (and any docs) in the same change — it is a live document.
    - **Did this make a decision later work must obey?** If so, write it with `/adr` now,
@@ -23,8 +60,8 @@ get recorded until they have gone stale (ADR-0003).
      deferrals live; a TODO in code or a note in your head is not tracked.
    - **Did this write code a later operator would plausibly try to "fix"?** — a deliberate
      deviation, a non-obvious constraint, a hard-won exception. If so, cite the governing
-     ADR at that site in a comment (ADR-0012), so the choice announces it is on purpose
+     ADR at that site in a comment (stele:ADR-0012), so the choice announces it is on purpose
      where the edit happens, not only in the §4 table nobody thinks to open.
 
-3. Report what you found and did for each of the four, so the operator can confirm
+5. Report what you found and did for each of the four, so the operator can confirm
    nothing was silently skipped.

package/.claude/hooks/pre-commit

@@ -21,9 +21,59 @@ if ! command -v node >/dev/null 2>&1; then
   exit 1
 fi
 
+# The checks run against the COMMIT, not the working tree (ADR-0018). Reading the working
+# tree passes on a state no commit will ever contain: stage a broken ADR, fix it without
+# staging the fix, and the hook is green while HEAD lands red. `git write-tree` is used
+# rather than `git stash --keep-index` because it touches nothing the operator owns.
+tree=$(git write-tree)
+
+staged=$(mktemp -d)
+trap 'rm -rf "$staged"' EXIT
+
+# Only what the two checks actually read. The full tree costs ~1.1ms per tracked file —
+# ~11s on a 10k-file repo, which is a hook people delete (ADR-0018 has the numbers).
+# ADR-0018: a rule that starts reading a file outside this list must extend it here, or
+# the hook checks a file it never extracted. That obligation was missed exactly once, by
+# the very next feature: rules 14 and 15 read the prose files and ran nowhere in the hook
+# for a whole release. `test/read-set.test.mjs` now compares this list against the scope
+# the linter exports, so the next omission fails a test instead of going quiet. Paths
+# absent from the tree are dropped, because `git archive` fails on a pathspec that matches
+# nothing.
+paths=''
+for candidate in adr slices LEDGER.md CLAUDE.md README.md docs .claude/commands scripts package.json; do
+  if git cat-file -e "$tree:$candidate" 2>/dev/null; then
+    paths="$paths $candidate"
+  fi
+done
+
+# No doc path in the tree at all is not a reason to skip: the checks then run against an
+# empty directory and rule 10 reports "no adr/ or slices/ directory here", which is the
+# right diagnosis rather than a silent pass.
+if [ -n "$paths" ]; then
+  # shellcheck disable=SC2086  # word splitting is the point: $paths is a pathspec list.
+  git archive "$tree" -- $paths | tar -x -C "$staged"
+fi
+
+# The commit's own checkers, not the working tree's (ADR-0018) — grading a commit with a
+# linter it does not contain is the same defect one turn removed. No fallback to the
+# working copy: a silent fallback is the thing this hook exists to remove.
+for checker in lint-docs.mjs build-index.mjs check-immutable.mjs; do
+  if [ ! -f "$staged/scripts/$checker" ]; then
+    echo "pre-commit: scripts/$checker is not in the commit — cannot check it against itself." >&2
+    echo "            Stage the vendored checker, or run /init-method --update." >&2
+    exit 1
+  fi
+done
+
 # 1. Invariants must hold (rules 1–8 block; rule 9 warns). Zero-dependency, so no install.
-node scripts/lint-docs.mjs .
+node "$staged/scripts/lint-docs.mjs" "$staged"
 
 # 2. The generated index must match the corpus. A stale INDEX.md is drift by another name;
 #    regenerate and stage it rather than letting it fall behind.
-node scripts/build-index.mjs --check .
+node "$staged/scripts/build-index.mjs" --check "$staged"
+
+# 3. Immutable documents may only grow (ADR-0019). Skipped on an unborn branch, where the
+#    first commit has nothing to have edited.
+if git rev-parse --verify --quiet HEAD >/dev/null; then
+  node "$staged/scripts/check-immutable.mjs" HEAD "$tree"
+fi

package/README.md

@@ -55,6 +55,12 @@ means deleting its line from the ledger.** Changing your mind means a **new** AD
 supersedes the old one and says *why the old reasoning was wrong* — that record is the most
 valuable thing this workflow produces, and an in-place edit destroys it.
 
+This one is enforced, not merely stated: a committed immutable document's body may **gain**
+lines — an appended `## Amendment`, a correction marker placed at the claim it corrects — and
+may never lose or rewrite one
+([ADR-0019](adr/0019-immutable-bodies-may-gain-lines-never-lose-them.md)). Frontmatter stays
+free to change, because status and supersession are how a record announces it was superseded.
+
 ---
 
 ## Quickstart
@@ -70,6 +76,18 @@ npx @isonimus/stele <repo-root> --check    # verify an install is intact
 npx @isonimus/stele <repo-root> --update   # re-sync vendored machinery
 ```
 
+`--update` lints the corpus once the new machinery is in place and reports anything the
+updated linter calls red. A release that adds a rule can turn a green repo red behind a
+hook that is already installed, and the failure otherwise shows up as an unexplained
+blocked commit some time later (ADR-0021).
+
+It also **keeps any slash command this repo adapted**. `.claude/.stele-vendored.json`
+records what the toolkit last handed over, which is what lets an update tell a stale copy
+from a deliberate edit — before that record existed the two were the same observation, so
+taking a fix meant discarding every adaptation
+([ADR-0023](adr/0023-vendored-commands-and-what-an-update-may-overwrite.md)).
+Commit that file. `--update --force` discards adaptations, and has to be typed.
+
 From a clone of this repo, the same entry point runs directly:
 
 ```
@@ -83,7 +101,9 @@ owns the pre-commit slot, the doc checks join it rather than fight for the file
 ([ADR-0008](adr/0008-compose-with-an-existing-hook-framework.md)).
 
 The linter and slash commands are **vendored per repo** and a repo's local edits to the
-commands survive re-runs ([ADR-0007](adr/0007-commands-are-vendored-and-adaptable.md)).
+commands survive re-runs — including across an `--update`
+([ADR-0023](adr/0023-vendored-commands-and-what-an-update-may-overwrite.md), superseding
+[ADR-0007](adr/0007-commands-are-vendored-and-adaptable.md)).
 
 ---
 
@@ -96,16 +116,18 @@ Run in Claude Code as `/<name>`.
 | `/adr <title>` | Scaffold a new Architecture Decision Record, frontmatter pre-filled. |
 | `/slice <title>` | Scaffold a new slice (one feature work-unit). |
 | `/audit` | Full-corpus health check — run every invariant, surface warnings and drift. |
-| `/wrap-up` | End-of-task gate — run the checks and ask the four questions that get forgotten. |
+| `/wrap-up` | End-of-task gate — run the checks, run the mutation check and adversarial pass when they trigger, and ask the four questions that get forgotten. |
 | `/remember <fact>` | Route a fact to the destination that governs it (see [Where things live](#where-things-live)). |
 | `/init-method` | Install the kit into a git repo. |
 
 Under the hood, the npm scripts are the enforcement surface:
 
 ```
-npm run lint     # node scripts/lint-docs.mjs .   — the invariant checker
-npm run index    # regenerate adr/INDEX.md
-npm test         # the regression suite (every rule has a fixture)
+npm run lint       # node scripts/lint-docs.mjs .   — the invariant checker
+npm run index      # regenerate adr/INDEX.md
+npm run immutable  # immutable bodies only gained lines since HEAD
+npm run mutants    # do the tests actually bite? (mutation check)
+npm test           # the regression suite (every rule has a fixture)
 ```
 
 ---
@@ -139,6 +161,16 @@ error**, and writes artifacts (screenshots, numbers) for human review. Name it i
 `## Verification` and **wire it into `package.json`** — an unwired verify script runs once and
 is dead thereafter, so the linter fails if any is unwired (R11). ([ADR-0004](adr/0004-verification-harness-and-in-repo-invariants.md))
 
+**Cite a decision.** Write `ADR-NNNN` for one in *this* repo and `<repo>:ADR-NNNN` for one
+in another — a bare citation always means "here", which is what lets the linter treat a
+citation that doesn't resolve as a real defect rather than a maybe
+([ADR-0009](adr/0009-cross-repo-citations-are-qualified.md)). Text you expect to be copied
+into another repo — a template, a slash command — must use the qualified form even for your
+own decisions, or the copy silently names the *other* repo's decision of that number. Naming
+your own repo costs nothing: the linter resolves `<this-repo>:ADR-NNNN` locally, so those
+citations stay checked here and stay skipped downstream
+([ADR-0020](adr/0020-citations-are-checked-wherever-they-are-read.md)).
+
 **Adopt into an existing repo.** `/init-method <repo> --apply`. Migrate the corpus and hand-
 fix any red supersession pairs *before* the hook goes on. Legacy documents that predate a
 rule warn rather than error, so adoption is never blocked by history.
@@ -152,14 +184,25 @@ decision, and decisions are immutable records.
 ## Enforcement, in three honest layers
 
 The linter ([`scripts/lint-docs.mjs`](scripts/lint-docs.mjs)) runs from the pre-commit hook
-and in CI. Its rules are graded by what can actually be mechanised
+and in CI. The hook checks the **commit**, not the files on disk — it materialises the staged
+tree and runs the checks against that, so a fix you forgot to `git add` cannot green a commit
+that lands red ([ADR-0018](adr/0018-the-hook-checks-the-commit-not-the-working-tree.md)). Rules
+are graded by what can actually be mechanised
 ([ADR-0003](adr/0003-enforcement-by-hook.md)):
 
-1. **Machine-checked (error — blocks the commit).** Frontmatter shape and completeness
-   (R1), id/filename agreement and uniqueness (R2), closed status/type vocabulary (R3), the
-   supersession graph (R4–R7), ledger citations resolve (R8), the linter isn't pointed at an
-   empty corpus (R10), verify scripts are wired (R11), and slices carry their required
-   sections (R12/R13).
+1. **Machine-checked (error — blocks the commit).** Frontmatter shape, completeness and a
+   real ISO date (R1), id/filename agreement and uniqueness (R2), closed status/type
+   vocabulary (R3), the supersession graph (R4–R7), ledger citations resolve (R8), the
+   linter isn't pointed at an empty corpus (R10), verify scripts are wired (R11), slices
+   carry their required sections in their own prose — a heading quoted inside a code fence
+   is not compliance (R12/R13) — and citations and links resolve in the prose read as
+   *instruction*: `CLAUDE.md`, `README.md`, `docs/`, the slash commands (R14/R15,
+   [ADR-0020](adr/0020-citations-are-checked-wherever-they-are-read.md)).
+
+   Every rule reads inside one declared scope, which is exactly what the hook copies out of
+   the staged tree — so a rule cannot pass in CI and do nothing in the hook, and a link
+   check cannot depend on where it ran
+   ([ADR-0021](adr/0021-the-checked-scope-is-one-list-and-no-rule-reads-outside-it.md)).
 2. **Legacy-aware (warning, not error).** Bare prose cross-references (R9) and slice-section
    rules on documents that predate them warn instead of failing, so a repo's history never
    blocks its next commit — while *new* work is held to the full bar.
@@ -169,6 +212,29 @@ and in CI. Its rules are graded by what can actually be mechanised
    a human read-through, never claimed as guaranteed. A linter that pretended to check them
    would be a false green, the exact failure this project exists to prevent.
 
+   This layer has two instruments, and neither is a linter. The first is the **mutation
+   check** (`npm run mutants`), which answers one narrow question mechanically: *do the
+   tests bite?* It applies a curated list of small behaviour changes to the linter's pure
+   predicates and requires each to break a test. A survivor is not a bug — it is correct
+   behaviour nothing is watching, which a later refactor can reverse in silence. Measured on
+   adoption: 3 of 10 mutants died, and the seven survivors were all correct-but-unpinned
+   behaviour, now covered. It is deliberately not a framework — that would cost the
+   zero-dependency property, and curating the list is the work anyway.
+
+   Its limit is stated rather than discovered: it perturbs code and asks whether tests
+   notice, so it is blind to an input nobody wrote and to a rule that was wrong from the
+   start. **None of the three defects this project has actually suffered would have been
+   caught by it.** It buys regression durability, not correctness.
+
+   The second instrument is the one that covers exactly that gap: the **adversarial pass**
+   ([ADR-0017](adr/0017-adversarial-review-is-the-coverage-mechanism.md)). Every coverage
+   question has the form "is what you wrote sufficient?" and is addressed to the person who
+   just wrote it — who already believes it is, which is why the code looks that way. So
+   `/wrap-up` spawns a reviewer that is **blind to intent but aware of law**: it gets the
+   diff, `CLAUDE.md` and the ADR index, never the rationale. Findings must state a concrete
+   failure, get reproduced before they are acted on, and — when correctly *rejected* — get
+   written at the code site (ADR-0012) so the next fresh reader does not raise them again.
+
 The dividing line is the whole point: **a rule is enforced, legacy-tolerated, or explicitly
 declared uncheckable — never silently trusted.**
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@isonimus/stele",
-  "version": "0.1.2",
+  "version": "0.3.0",
   "type": "module",
   "description": "A linted, installable ADR workflow for git projects using Claude as an assistant",
   "keywords": [
@@ -41,6 +41,8 @@
     "test": "node --test test/*.test.mjs",
     "lint": "node scripts/lint-docs.mjs .",
     "index": "node scripts/build-index.mjs .",
+    "immutable": "node scripts/check-immutable.mjs",
+    "mutants": "node scripts/check-mutants.mjs",
     "scan": "node scripts/scan-legacy.mjs",
     "migrate": "node scripts/migrate-adrs.mjs",
     "init": "node scripts/init-method.mjs"

package/scripts/check-immutable.mjs

@@ -0,0 +1,145 @@
+#!/usr/bin/env node
+// Checks that immutable documents stayed immutable (ADR-0019).
+//
+//   node scripts/check-immutable.mjs <base> <head>
+//
+// Compares two tree-ish revisions. Fails when a document under adr/ or slices/ that exists
+// in <base> has had its body changed other than by appending, or has been removed.
+//
+// This is a sibling of `build-index --check`, not a lint rule, because it needs git — and
+// lint(root) is a pure function over one directory, which is what makes it testable and
+// reusable from init-method (ADR-0019). Frontmatter is deliberately out of scope: status
+// and supersession fields are the mutable surface by design (ADR-0002).
+
+import { execFileSync } from 'node:child_process';
+import { realpathSync } from 'node:fs';
+import { fileURLToPath } from 'node:url';
+import { parseFrontmatter } from './lint-docs.mjs';
+
+const DOC_DIRS = ['adr', 'slices'];
+
+/** The generated index lives among the documents but is not one (ADR-0010). */
+const GENERATED = 'INDEX.md';
+
+const git = (...args) => execFileSync('git', args, { encoding: 'utf8', maxBuffer: 64 * 1024 * 1024 });
+
+/** Immutable documents in a tree. A pathspec matching nothing is not an error for
+ *  ls-tree, so a repo without slices/ needs no special case. */
+function docsIn(rev) {
+  const out = git('ls-tree', '-r', '--name-only', rev, '--', ...DOC_DIRS);
+  return out.split('\n').filter((p) => p.endsWith('.md') && !p.endsWith(`/${GENERATED}`));
+}
+
+/**
+ * The document's body as lines, with trailing blanks dropped so that a file gaining or
+ * losing a final newline does not read as an edit.
+ *
+ * Returns null when the frontmatter does not parse: the body boundary is then unknown, and
+ * comparing whole files instead would silently change what this check means. Rule 1 already
+ * errors on those files, so nothing escapes between the two (ADR-0019).
+ */
+function bodyLines(text) {
+  const parsed = parseFrontmatter(text);
+  if (!parsed.ok) return null;
+  const lines = parsed.body.split('\n');
+  while (lines.length && lines[lines.length - 1].trim() === '') lines.pop();
+  return lines;
+}
+
+const show = (rev, path) => git('show', `${rev}:${path}`);
+
+/**
+ * Index of the first line of `was` that is not still present, in order, in `now` — or -1
+ * when the older body survives intact.
+ *
+ * A subsequence test rather than a prefix test: insertions anywhere are legitimate here,
+ * because this repo's sanctioned way to correct a wrong claim is a marker placed *at* the
+ * claim (ADR-0001's 2026-07-21 amendment, used in ADR-0003), not a note at the end. What
+ * it forbids is a line disappearing or changing, which is what "immutable" means.
+ *
+ * The known limit: deleting a line that recurs verbatim later in the same body reads as
+ * intact. Blank lines and bare headings are the realistic instances, and both are prose
+ * scaffolding rather than claims (ADR-0019).
+ */
+function firstLostLine(was, now) {
+  let cursor = 0;
+  for (let i = 0; i < was.length; i++) {
+    while (cursor < now.length && now[cursor] !== was[i]) cursor++;
+    if (cursor === now.length) return i;
+    cursor++;
+  }
+  return -1;
+}
+
+/** Whether a revision resolves. Used only to tell an unborn branch from a real base —
+ *  every other git failure here is a genuine fault and is left to throw. */
+function revExists(rev) {
+  try {
+    git('rev-parse', '--verify', '--quiet', `${rev}^{commit}`);
+    return true;
+  } catch {
+    return false;
+  }
+}
+
+/**
+ * @returns {string[]} one message per violation; empty means the bodies only grew.
+ */
+export function checkImmutable(base, head) {
+  const problems = [];
+  const present = new Set(docsIn(head));
+
+  for (const path of docsIn(base)) {
+    if (!present.has(path)) {
+      problems.push(`${path}: removed. Immutable documents are never deleted — supersede it instead (ADR-0010).`);
+      continue;
+    }
+
+    const was = bodyLines(show(base, path));
+    const now = bodyLines(show(head, path));
+    if (was === null || now === null) continue; // rule 1 owns unparseable frontmatter
+
+    const lost = firstLostLine(was, now);
+    if (lost !== -1) {
+      problems.push(
+        `${path}: body line ${lost + 1} was deleted or rewritten. Immutable prose may gain lines,\n` +
+        `             never lose or change them (ADR-0019).\n` +
+        `    was: ${was[lost]}`,
+      );
+    }
+  }
+  return problems;
+}
+
+/**
+ * Defaults are what let the pre-commit *framework* call this with no arguments: its `entry`
+ * is argv, never a shell, so `$(git write-tree)` in a config would be passed literally. The
+ * hook still names both revisions explicitly, having already computed the tree (ADR-0018).
+ */
+function main(argv) {
+  const [base = 'HEAD', head] = argv;
+
+  if (base === 'HEAD' && !revExists('HEAD')) {
+    console.log('check-immutable: no commits yet — nothing to have edited.');
+    return 0;
+  }
+
+  const problems = checkImmutable(base, head ?? git('write-tree').trim());
+  for (const problem of problems) console.error(`  IMMUTABLE  ${problem}`);
+  if (problems.length) {
+    console.error(
+      `\n${problems.length} immutable document(s) changed below the frontmatter.\n` +
+      'Record the change as an appended `## Amendment — <date>: …` block, or as a new ADR that\n' +
+      'supersedes this one and says why the old reasoning was wrong (ADR-0010).',
+    );
+    return 1;
+  }
+  return 0;
+}
+
+// Resolved on both sides before comparing: the hook invokes this through the vendored copy
+// and a raw `file://${argv[1]}` compare is false whenever a symlink is in the path, which
+// silently no-ops main() (ADR-0015 amendment).
+if (process.argv[1] && realpathSync(process.argv[1]) === fileURLToPath(import.meta.url)) {
+  process.exit(main(process.argv.slice(2)));
+}