@isonimus/stele 0.1.2 → 0.2.0

package/.claude/commands/adr.md

@@ -5,7 +5,7 @@ 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:
@@ -14,7 +14,7 @@ Steps:
    digits. 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

@@ -3,7 +3,7 @@ description: Install the method kit (CLAUDE.md, LEDGER.md, linter, index, pre-co
 argument-hint: [repo-root] [--check | --update]
 ---
 
-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-0007): 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.
@@ -101,5 +101,5 @@ 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
+reaches an installed repo: the copies are deliberate (stele:ADR-0006, stele:ADR-0007), and drift is
 the price.

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,29 @@ 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. **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.
+
+3. 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 +45,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
+4. 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,11 @@ 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).
+
 From a clone of this repo, the same entry point runs directly:
 
 ```
@@ -96,16 +107,17 @@ 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 adversarial pass when it triggers, 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 test           # the regression suite (every rule has a fixture)
 ```
 
 ---
@@ -139,6 +151,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 +174,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 +202,15 @@ 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 one instrument, and it is not a linter: 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.2.0",
   "type": "module",
   "description": "A linted, installable ADR workflow for git projects using Claude as an assistant",
   "keywords": [
@@ -41,6 +41,7 @@
     "test": "node --test test/*.test.mjs",
     "lint": "node scripts/lint-docs.mjs .",
     "index": "node scripts/build-index.mjs .",
+    "immutable": "node scripts/check-immutable.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)));
+}

package/scripts/init-method.mjs

@@ -28,6 +28,7 @@ const TOOLKIT = dirname(dirname(fileURLToPath(import.meta.url)));
 const VENDORED = [
   ['scripts/lint-docs.mjs', 'scripts/lint-docs.mjs'],
   ['scripts/build-index.mjs', 'scripts/build-index.mjs'],
+  ['scripts/check-immutable.mjs', 'scripts/check-immutable.mjs'],
   ['.claude/hooks/pre-commit', '.claude/hooks/pre-commit'],
 ];
 
@@ -61,7 +62,16 @@ const FRAMEWORK_CONFIG = '.pre-commit-config.yaml';
 /** Identifies our block on re-runs, so composing is idempotent. */
 const FRAMEWORK_HOOK_ID = 'stele-docs';
 
-/** Appended verbatim. Mirrors .claude/hooks/pre-commit — the same two commands. */
+/**
+ * Appended verbatim. Mirrors .claude/hooks/pre-commit — the same two checks.
+ *
+ * These deliberately run against the working tree (`.`), where the hook materialises the
+ * staged tree first (ADR-0018). It is not an oversight and must not be "fixed" into a
+ * copy of that machinery: the framework stashes unstaged changes before dispatching, so
+ * by the time these entries run the working tree already *is* the index. Reproducing the
+ * archive dance here would duplicate what the framework provides — which is the whole
+ * reason ADR-0008 chose to compose with it rather than fight it for the file.
+ */
 const FRAMEWORK_BLOCK = `
   # Doc invariants (stele:ADR-0003, composed by /init-method per stele:ADR-0008).
   # Zero-dependency and language: system, so there is nothing to install but node.
@@ -79,6 +89,12 @@ const FRAMEWORK_BLOCK = `
         language: system
         pass_filenames: false
         always_run: true
+      - id: stele-immutable
+        name: immutable documents only grow
+        entry: node scripts/check-immutable.mjs
+        language: system
+        pass_filenames: false
+        always_run: true
 `;
 
 const read = (path) => readFileSync(path, 'utf8');
@@ -256,6 +272,28 @@ function frameworkInstalled({ target, report }) {
   else report('problem', hook, 'the pre-commit framework is configured but never installed — no hook runs at all, including its own. Run `pre-commit install`.');
 }
 
+/**
+ * Reports a corpus the freshly vendored linter calls red.
+ *
+ * `--apply` refuses to *install* a hook on a red corpus, because a hook that blocks every
+ * commit is the tool bricking the repo it protects. `--update` reaches the same state by
+ * the other door and had no equivalent guard: a release that adds an error-severity rule
+ * lands a stricter linter behind a hook that is already live, and the next commit fails
+ * with no hint that an update caused it.
+ *
+ * It reports rather than refuses. By the time the copy is written the old linter is gone,
+ * so there is nothing to decline into — and rolling back would leave the repo on machinery
+ * the operator explicitly asked to replace. Loud and accurate beats a silent half-update.
+ */
+function lintAfterUpdate({ target, report }) {
+  const errors = lintErrors(target);
+  if (errors.length === 0) {
+    return report('ok', target, 'corpus still clean under the updated linter');
+  }
+  for (const f of errors) report('problem', f.path, f.message);
+  report('problem', target, `${errors.length} lint error(s) under the updated linter — the hook is live, so every commit is blocked until these are fixed. \`git commit --no-verify\` is the escape hatch while you do.`);
+}
+
 function check({ target, toolkit, report }) {
   for (const [dest, src] of VENDORED) {
     const to = join(target, dest);
@@ -318,6 +356,7 @@ export function initMethod({ target, toolkit = TOOLKIT, mode = 'install', apply
   } else if (mode === 'update') {
     vendor({ target, toolkit, apply, report });
     vendorCommands({ target, toolkit, apply, force: true, report });
+    if (apply) lintAfterUpdate({ target, report });
   } else {
     scaffold({ target, toolkit, apply, report });
     vendor({ target, toolkit, apply, report });

package/scripts/lint-docs.mjs

@@ -10,14 +10,44 @@
 //
 // Exit 1 if any error-severity rule fails. Warnings never fail the build.
 
-import { readFileSync, readdirSync, existsSync } from 'node:fs';
-import { join, basename } from 'node:path';
+import { readFileSync, readdirSync, existsSync, realpathSync } from 'node:fs';
+import { fileURLToPath } from 'node:url';
+import { join, basename, dirname, relative } from 'node:path';
 
 const STATUSES = ['accepted', 'proposed', 'superseded', 'amended'];
 const TYPES = ['architecture', 'slice', 'batch'];
 const REQUIRED = ['id', 'title', 'type', 'status', 'date'];
 const DOC_DIRS = ['adr', 'slices'];
 
+// Prose that is read as instruction rather than as a record (ADR-0020). `CLAUDE.md` is
+// loaded at the start of every session and the command files are the assistant's own
+// procedures, so a citation rotting in either misroutes work silently — the corpus itself
+// stays green because rules 8 and 9 never open these files. Directories are scanned one
+// level deep; anything else here is a plain file path.
+const PROSE_FILES = ['CLAUDE.md', 'README.md'];
+const PROSE_DIRS = ['docs', '.claude/commands'];
+
+/**
+ * Every path this linter reads, relative to the repo root — the hook's archive list
+ * (ADR-0018) in machine-readable form.
+ *
+ * The hook materialises the staged tree and copies only what the checks read, so a rule
+ * reading outside this set runs against a file that was never extracted. That happened:
+ * rules 14 and 15 shipped reading four paths the hook did not copy, and were dead there
+ * for a release while passing in CI. `test/read-set.test.mjs` holds the two lists equal.
+ */
+export const READ_SCOPE = [
+  ...DOC_DIRS, 'LEDGER.md', ...PROSE_FILES, ...PROSE_DIRS, 'scripts', 'package.json',
+];
+
+/** Whether a root-relative path lies inside the checked scope. Outside it, the hook and a
+ *  working-tree run would disagree, and a check that depends on where it runs is worse
+ *  than no check. */
+function inReadScope(rootRelative) {
+  if (rootRelative.startsWith('..')) return false;
+  return READ_SCOPE.some((entry) => rootRelative === entry || rootRelative.startsWith(`${entry}/`));
+}
+
 // The date the required-slice-section rules (R12/R13) shipped (ADR-0004, ADR-0011). A
 // slice dated before this predates the rules and only warns; one dated on or after must
 // comply. Without the split, a repo adopting this linter would go red on its whole legacy
@@ -34,16 +64,70 @@ const normId = (v) => String(v).trim().padStart(4, '0');
 
 const isId = (v) => /^\d{1,4}$/.test(String(v).trim());
 
+/**
+ * ISO 8601 `YYYY-MM-DD`, and a day that exists — `2026-02-31` parses but round-trips wrong.
+ *
+ * `date` is not decoration: R12/R13 pick their severity by string-comparing it against
+ * SLICE_SECTIONS_SINCE, so anything sorting above `2026-07-22` grades as current and
+ * anything below grades as legacy. Unvalidated, `date: sometime last tuesday` graded as
+ * *current* purely because 's' > '2', and a copy-pasted earlier date graded as legacy —
+ * shipping a slice with no Definition of Done on a green build. ADR-0002 already specifies
+ * ISO 8601; this is that specification made executable.
+ */
+function isCalendarDate(v) {
+  const text = String(v).trim();
+  if (!/^\d{4}-\d{2}-\d{2}$/.test(text)) return false;
+  return new Date(`${text}T00:00:00Z`).toISOString().startsWith(text);
+}
+
 // Citations, bare or qualified (ADR-0009). A leading `<repo>:` says the decision lives in
 // another repo's corpus, which this linter cannot open and so must skip. The colon has to
 // be adjacent, leaving an ordinary sentence ending in a colon ("see also: ADR-0004")
 // resolving locally as before.
 const CITATION = /(?:([A-Za-z][\w.-]*):)?ADR[-\s](\d{1,4})/g;
 
-/** Ids cited in `text` that this repo is expected to own — cross-repo refs skipped. */
-function* localCitations(text) {
+/**
+ * Ids cited in `text` that this repo is expected to own — cross-repo refs skipped.
+ *
+ * A qualifier naming *this* repo resolves locally (ADR-0020). Text that is vendored into
+ * other repos must qualify its citations, or a bare `ADR-0005` copied into gamatar reads
+ * as gamatar's ADR-0005; but qualifying it would also put it permanently beyond checking,
+ * since ADR-0009 skips every qualified reference. Recognising our own name is what keeps
+ * `stele:ADR-0005` verified in the one corpus that can verify it.
+ */
+function* localCitations(text, selfRepo = null) {
   for (const [, repo, id] of text.matchAll(CITATION)) {
-    if (repo === undefined) yield normId(id);
+    if (repo === undefined || (selfRepo !== null && repo === selfRepo)) yield normId(id);
+  }
+}
+
+/** This repo's own name for citation purposes: the unscoped half of package.json `name`.
+ *  Null when there is no readable name — rule 11 owns malformed package.json, and without
+ *  a name there is simply no self-qualifier to recognise. */
+function repoName(root) {
+  const path = join(root, 'package.json');
+  if (!existsSync(path)) return null;
+  let pkg;
+  try {
+    pkg = JSON.parse(readFileSync(path, 'utf8'));
+  } catch {
+    return null;
+  }
+  const name = typeof pkg.name === 'string' ? pkg.name : '';
+  const unscoped = name.startsWith('@') ? name.slice(name.indexOf('/') + 1) : name;
+  return unscoped === '' ? null : unscoped;
+}
+
+// Inline markdown links, with the optional title form `[x](path "title")`.
+const LINK = /\]\(\s*([^)\s]+)(?:\s+"[^"]*")?\s*\)/g;
+
+/** Link targets in `line` that name a file in this repo. External URLs, mail links,
+ *  in-page anchors and absolute paths are all outside what a file check can decide. */
+function* relativeLinks(line) {
+  for (const [, target] of line.matchAll(LINK)) {
+    if (/^(?:[a-z][a-z0-9+.-]*:|\/\/|\/|#)/i.test(target)) continue;
+    const path = target.split('#')[0].split('?')[0];
+    if (path !== '') yield path;
   }
 }
 
@@ -127,16 +211,53 @@ export function loadDocs(root) {
   return docs;
 }
 
+/** The prose files present under `root`, as { path, text }. Missing ones are simply
+ *  absent — not every repo has docs/ or slash commands. */
+function loadProse(root) {
+  const paths = PROSE_FILES.map((f) => join(root, f));
+  for (const dir of PROSE_DIRS) {
+    const full = join(root, dir);
+    if (!existsSync(full)) continue;
+    paths.push(...readdirSync(full).sort().filter((f) => f.endsWith('.md')).map((f) => join(full, f)));
+  }
+  return paths.filter(existsSync).map((path) => ({ path, text: readFileSync(path, 'utf8') }));
+}
+
 // --- section helpers --------------------------------------------------------
 // Slice rules (R12/R13) assert the presence and shape of `## Sections` in the body prose.
 // This is the only place the linter reads body text structurally; ADR-0002 keeps
 // frontmatter the machine-readable surface, and a markdown heading is not frontmatter.
 
+/**
+ * Body lines with fenced code blocks blanked out, positions preserved.
+ *
+ * A `## Verification` inside a fence is a *quotation* of the rule, not compliance with it.
+ * Reproduced 2026-07-27: a slice whose only two required sections sat in a ```markdown
+ * sample — exactly what a document explaining the slice template contains — lints clean,
+ * which is a false green on the two rules that define "done".
+ */
+function withoutFences(body) {
+  const fence = /^\s*(```|~~~)/;
+  let open = null;
+  return (body ?? '').split('\n').map((line) => {
+    const marker = line.match(fence);
+    if (marker && open === null) {
+      open = marker[1];
+      return '';
+    }
+    if (marker && line.trim().startsWith(open)) {
+      open = null;
+      return '';
+    }
+    return open === null ? line : '';
+  });
+}
+
 /** The text under a `## Heading`, up to the next `#`/`##` heading or end of body.
  *  Returns null when the heading is absent — distinct from a present-but-empty section. */
 function sectionText(body, name) {
   const heading = new RegExp(`^##\\s+${name}\\s*$`, 'i');
-  const lines = (body ?? '').split('\n');
+  const lines = withoutFences(body);
   const start = lines.findIndex((l) => heading.test(l.trim()));
   if (start === -1) return null;
   const rest = lines.slice(start + 1);
@@ -201,6 +322,9 @@ const rules = {
           report('error', d.path, `R1 missing required field "${field}"`);
         }
       }
+      if (d.data.date !== undefined && !isCalendarDate(d.data.date)) {
+        report('error', d.path, `R1 date "${d.data.date}" is not a calendar date in YYYY-MM-DD form`);
+      }
     }
   },
 
@@ -261,6 +385,14 @@ const rules = {
       const supersededBy = listOf(d, 'superseded_by');
       const supersedes = listOf(d, 'supersedes');
 
+      // R4 — a document cannot supersede itself. Self-reference satisfies every other
+      // check in this rule vacuously: the bidirectionality test finds the id in its own
+      // list, R6 sees a superseded status with a non-empty superseded_by, and R7 sees a
+      // target that is not "accepted". The whole graph agrees, about nothing.
+      if (supersedes.includes(id) || supersededBy.includes(id)) {
+        report('error', d.path, `R4 ADR ${id} supersedes itself — a decision is replaced by a later one, never by itself`);
+      }
+
       // R5 — dangling references. Legacy 0051 and 0061 claimed supersession with no
       // resolvable target at all.
       for (const key of ['supersedes', 'superseded_by']) {
@@ -315,8 +447,9 @@ const rules = {
     const ids = new Set(docs.filter((d) => d.ok && d.data.id !== undefined).map((d) => normId(d.data.id)));
 
     const text = readFileSync(path, 'utf8');
+    const self = repoName(root);
     text.split('\n').forEach((line, i) => {
-      for (const id of localCitations(line)) {
+      for (const id of localCitations(line, self)) {
         if (!ids.has(id)) {
           report('error', path, `R8 line ${i + 1} cites ADR ${id}, which does not exist. Another repo's decision is cited as \`<repo>:ADR-${id}\` (ADR-0009).`);
         }
@@ -324,6 +457,41 @@ const rules = {
     });
   },
 
+  // R14/R15 — the prose that is read as instruction (ADR-0020). Rules 8 and 9 open
+  // `LEDGER.md` and the corpus and nothing else, so `CLAUDE.md`, `README.md`, `docs/` and
+  // the slash commands were never checked at all. That is not hypothetical: gamatar's
+  // vendored `/remember` said "the exact failure ADR-0005 exists to prevent", and
+  // gamatar's ADR-0005 is a superseded decision about canvas face textures.
+  //
+  // Error, not a warning like R9: measured across boxel's prose (43 bare references) and
+  // gamatar's, every reference that is meant to be local resolves, so the severity that
+  // forced R9 to warn — legacy volume — is absent here.
+  //
+  // The two run together because they share the file set. R15 checks relative link
+  // targets, and only here: a broken link inside an immutable document cannot be fixed
+  // without the rewrite ADR-0019 forbids, so it is not something to fail a build on.
+  prose(docs, root, report) {
+    const ids = new Set(docs.filter((d) => d.ok && d.data.id !== undefined).map((d) => normId(d.data.id)));
+    const self = repoName(root);
+
+    for (const { path, text } of loadProse(root)) {
+      text.split('\n').forEach((line, i) => {
+        for (const id of localCitations(line, self)) {
+          if (!ids.has(id)) {
+            report('error', path, `R14 line ${i + 1} cites ADR ${id}, which does not exist. Another repo's decision is cited as \`<repo>:ADR-${id}\` (ADR-0009).`);
+          }
+        }
+        for (const target of relativeLinks(line)) {
+          const resolved = relative(root, join(dirname(path), target));
+          if (!inReadScope(resolved)) continue;
+          if (!existsSync(join(root, resolved))) {
+            report('error', path, `R15 line ${i + 1} links to ${target}, which does not exist`);
+          }
+        }
+      });
+    }
+  },
+
   // R11 — every verify script is wired into package.json (ADR-0004). The harness's
   // load-bearing half: an unwired `*-verify.mjs` ran once on the day it was written and
   // never again — ADR-0004 Finding 2 found eleven of twelve boxel scripts in exactly that
@@ -400,12 +568,13 @@ const rules = {
   // Since ADR-0009 a bare reference means unambiguously "in this repo" — the other-repo
   // case has its own syntax — so the remaining obstacle to erroring here is boxel's
   // legacy volume alone, not the mechanism.
-  proseRefs(docs, _root, report) {
+  proseRefs(docs, root, report) {
     const ids = new Set(docs.filter((d) => d.ok && d.data.id !== undefined).map((d) => normId(d.data.id)));
+    const self = repoName(root);
     for (const d of docs) {
       if (!d.ok || !d.body) continue;
       const unresolved = new Set();
-      for (const id of localCitations(d.body)) {
+      for (const id of localCitations(d.body, self)) {
         if (!ids.has(id)) unresolved.add(id);
       }
       for (const ref of [...unresolved].sort()) {
@@ -458,6 +627,8 @@ function main(argv) {
   return errors > 0 ? 1 : 0;
 }
 
-if (import.meta.url === `file://${process.argv[1]}`) {
+// realpath, not a string compare on argv[1]: invoked through a bin symlink the naive form
+// silently does nothing, which is how `npx stele` shipped as a no-op (ADR-0015).
+if (realpathSync(process.argv[1]) === fileURLToPath(import.meta.url)) {
   process.exit(main(process.argv.slice(2)));
 }

package/templates/CLAUDE.md

@@ -36,13 +36,27 @@ Changing our minds means writing a **new** ADR that supersedes the old one, neve
 it. The superseding note must say *why the old reasoning was wrong* — that record is the
 most valuable thing this workflow produces, and an in-place edit destroys it.
 
+A committed document's body may **gain** lines — an appended `## Amendment — <date>: …`, or a
+correction marker placed at the claim it corrects — and may never lose or rewrite one. The
+hook enforces this (stele:ADR-0019); frontmatter is exempt, because status and supersession
+fields are how a record announces it was superseded.
+
 This is also how a justified rule-violation gets recorded. `~/.claude/CLAUDE.md` §2 says a
 justified violation is written down as a decision rather than taken as a silent exception;
 in this repo, that decision is a new or superseding ADR.
 
 ## 2. Enforcement — invariants are executable
 
-`node scripts/lint-docs.mjs` runs from a pre-commit hook and in CI.
+`node scripts/lint-docs.mjs` runs from a pre-commit hook and in CI. The hook checks the
+**commit**, not the working tree, so a fix you forgot to stage cannot green a red commit
+(stele:ADR-0018); alongside the linter it verifies that `adr/INDEX.md` matches the corpus and
+that immutable bodies have only gained lines (stele:ADR-0019).
+
+A citation is bare (`ADR-NNNN`) only when it means *this* repo, and qualified
+(`<repo>:ADR-NNNN`) otherwise (stele:ADR-0009). The linter resolves citations in `LEDGER.md`,
+in the corpus, and in the prose that is read as instruction — this file, `README.md`,
+`docs/`, `.claude/commands/` — so a citation that rots there fails the build rather than
+quietly misrouting the next session (stele:ADR-0020).
 
 A rule enforced by memory is a rule that holds until the first busy afternoon. If a
 convention matters, it gets a rule; if it genuinely can't be checked, say so out loud
@@ -76,7 +90,7 @@ are exempt: a probe answers its question once and the number lands in an ADR.
 
 Every slice carries two required sections, both rule-checked: `## Verification` names the
 proof (R12), and `## Definition of Done` states the acceptance criteria as Given/When/Then
-scenarios written before the code (R13, ADR-0011). Each scenario names its proof in
+scenarios written before the code (R13, stele:ADR-0011). Each scenario names its proof in
 `## Verification`; the linter checks the sections exist and that the Definition of Done
 holds a full triad — it cannot check that a scenario is *right*, which is what `/wrap-up`
 is for.