@isonimus/stele 0.3.0 → 0.4.1

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

@@ -33,13 +33,19 @@ node scripts/init-method.mjs <target> --apply
 
 This scaffolds `adr/`, `CLAUDE.md` and `LEDGER.md` (never overwriting), vendors
 `lint-docs.mjs` / `build-index.mjs` / the hook and the slash commands, generates
-`adr/INDEX.md`, links `~/.claude/CLAUDE.md`, and installs the pre-commit hook **only if
-the corpus lints clean**.
+`adr/INDEX.md`, and installs the pre-commit hook **only if the corpus lints clean**.
 
-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.
+Nothing outside the target repo is written — never `$HOME`, never `~/.claude/CLAUDE.md`
+(stele:ADR-0016). Wiring the operator's machine-level conventions is a personal choice, not
+an install step; do not add it back as a convenience.
+
+The commands and `docs/quality-bar.md` are vendored under softer rules than the machinery
+(stele:ADR-0023): a repo may edit its own copy of `/slice`, `/wrap-up` or the bar 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.
+
+The quality bar is the standard the slice `## Definition of Done` is measured against
+(stele:ADR-0024). Cite it from the scaffolded `CLAUDE.md`; do not restate its rules there.
 
 ## 3. If the repo already has a hook framework
 
@@ -92,8 +98,8 @@ node scripts/init-method.mjs <target> --check
 ```
 
 Writes nothing; fails on a missing or broken hook, a drifted vendored **script**, a stale
-index, a red corpus, or a broken `~/.claude/CLAUDE.md` link. Report its output verbatim
-rather than summarising it as "installed".
+index, or a red corpus. Report its output verbatim rather than summarising it as
+"installed".
 
 `LOCAL` and `MISSING` lines are about commands only and are **not** failures — they say
 this repo adapted or declined one. Read them, mention them, do not "fix" them without

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

@@ -35,6 +35,13 @@ get recorded until they have gone stale (stele:ADR-0003).
      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).
+   - **Tell the reviewer to read the files itself and not to spawn subagents of its own.** A
+     brief that fans out and does not forbid recursion has unbounded cost: a 12-reviewer sweep
+     on 2026-07-30 became an estimated 40–50 agents, exhausted a month's API budget, and lost
+     eight batches mid-run — while the one reviewer that read its own files returned the best
+     report of the twelve. One reviewer deciding to parallelise is enough to reproduce that at
+     smaller scale, so the sentence belongs in every brief, not only the wide ones
+     (stele:ADR-0017).
    - 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

package/CHANGELOG.md

@@ -0,0 +1,86 @@
+# Changelog
+
+Generated by `scripts/build-changelog.mjs` from annotated git tags — never hand-edited
+(ADR-0026). Run `npm run changelog` after tagging a release.
+
+Every entry is a commit subject verbatim. Work committed after the newest tag is absent by
+design and appears when the next release is tagged.
+
+## v0.4.1 — 2026-08-01
+
+- docs(releasing): a change after the tag costs a version, not a moved tag (`5b3c621`)
+- docs(readme): show the formats the linter enforces, and what the kit will not install (`f307d2e`)
+- chore: 0.4.1 — README documents 0.4.0's behaviour, so it ships with it (`23ab57a`)
+- chore: changelog for v0.4.0 (`c9f535e`)
+
+## v0.4.0 — 2026-08-01
+
+- feat: generate the changelog from tags, and stop there (ADR-0026) (`b242d33`)
+- feat: reinvention must name a cost and measure the build (ADR-0025) (`d54711f`)
+- feat: ship the quality bar with the method (ADR-0024) (`7ae3ca8`)
+- fix: ship the changelog to the people it was written for (`6847262`)
+- fix: refuse a managed path that is not a readable file, by name (0.4.0) (`9eed537`)
+- fix: the vendor report says "copied", not "copyd" (`e7af0d5`)
+- docs(adr-0024): the import-the-constant check is worth running after all (`f358cbf`)
+- docs(ledger): a fan-out brief that permits recursion has unbounded cost (`5383f97`)
+- docs(ledger): log the rule that would have caught a ledger losing a section (`5b19a6f`)
+- docs(init-method): stop describing the global link ADR-0016 withdrew (`82d51bd`)
+- chore: stop tracking npm pack output (`7915705`)
+
+## v0.3.0 — 2026-07-28
+
+- feat: an update overwrites only what the repo has not touched (ADR-0023) (`8bcba5d`)
+- feat: make the mutation check standing, wired into /wrap-up (ADR-0022) (`f269c6a`)
+- fix: two defects the adversarial pass found in the published machinery (`97bedd6`)
+- fix: /adr computes the next id across both document directories (`75d36ae`)
+- test: pin six behaviours a mutation probe found unpinned (`19a45f9`)
+- chore: 0.3.0 — an update no longer discards local command adaptations (`bdbaf86`)
+- chore: 0.2.1 — patch the two defects found after publishing 0.2.0 (`7d2086e`)
+
+## v0.2.0 — 2026-07-27
+
+- feat: check citations wherever they are read (ADR-0020) (`68e56ac`)
+- feat: enforce document immutability with a git-aware check (ADR-0019) (`a165fa1`)
+- feat: give the coverage layer an instrument — the adversarial pass (ADR-0017) (`6e2fa6d`)
+- fix: the hook checks every path a rule reads (ADR-0021) (`dec6967`)
+- fix: close the three remaining false greens found by the audit (`b3efdcb`)
+- fix: check the commit rather than the working tree in the pre-commit hook (ADR-0018) (`5144718`)
+- docs: log six enforcement gaps found by auditing the machinery (`562f838`)
+- chore: 0.2.0 — new error-severity rules change installed behaviour (`4fc52f6`)
+- chore: close npm-cleanup ledger item — 0.1.2 published (ADR-0016) (`e8f8812`)
+
+## v0.1.2 — 2026-07-23
+
+- feat: surface the reuse decision (ADR-0013); slice records existing code considered (`c0a9034`)
+- feat: cite the governing ADR at the code site (ADR-0012); /slice folds in ledger (`47a22eb`)
+- feat(lint): rules 12/13 — slices carry Verification and a Gherkin Definition of Done (`8a8a4c0`)
+- feat(init-method): compose with an existing pre-commit framework instead of taking the file (`719178b`)
+- feat(init-method): vendor the slash commands, and let a repo adapt its copy (`c3ae30d`)
+- feat(init): /init-method installs the kit, and refuses to brick the repo (ADR-0006) (`206c629`)
+- feat(lint): rule 11 — verify scripts must be wired (ADR-0004) (`7d81dab`)
+- feat(lint): rule 10 — an empty corpus is not a pass (`3a4c18e`)
+- feat(method): route writes by what they govern, bounding memory (ADR-0005) (`2abf31c`)
+- feat(method): add global CLAUDE.md for cross-repo working conventions (`6575f00`)
+- feat(method): make the architectural type set per-repo (--arch) (`e98a039`)
+- feat(method): enforcement layer — hook, index, commands, CI (Phase 4) (`6a21f42`)
+- feat(method): migrate legacy ADRs to frontmatter (Phase 2) (`b8476de`)
+- feat(method): document invariants, linter, and legacy scanner (`e26d709`)
+- fix: stop the installer touching ~/.claude; drop the global-conventions link (ADR-0016) (`f6199b5`)
+- fix: run the CLI when invoked via a bin symlink (npx no-op) (`53c61c8`)
+- fix(lint): qualify cross-repo citations, unbreaking install into a fresh repo (`04b7afd`)
+- fix(test): read rule codes by pattern, not by fixed width (`f6d709d`)
+- fix(templates): stop the scaffold from duplicating global conventions (`a01c22c`)
+- fix(migrate): don't read a supersession date as the decision date (`35e8792`)
+- refactor: rename to Stele and prepare npm distribution as @isonimus/stele (`ef294ae`)
+- docs: add contributing, security, code of conduct, and PR template (`3ea62f9`)
+- docs: add README — the front door, mental model, and usage scenarios (`108502c`)
+- docs(ledger): close the taxonomy question and the l33t migration (`7c0969d`)
+- docs(adr): name the fourth kind — the live doc — superseding ADR-0001 (`42d7d61`)
+- docs(ledger): record the commands gap and the decision to vendor them (`127dcd8`)
+- docs(ledger): reconcile with boxel, which has now run the whole flow by hand (`78d9baf`)
+- docs(global): expand §3 quality bar with structure, error-handling and test-quality rules (`684954c`)
+- docs(adr): sanction dated corrections on immutable bodies (ADR-0001) (`efc4d29`)
+- docs(ledger): record that an empty corpus lints green (`2902686`)
+- docs(method): record that boxel has no CLAUDE.md (`6fcaa2b`)
+- docs(method): correction covers ADR violations and subpar proposals (`64d0d54`)
+- Add verification harness and standing-invariants conventions (ADR-0004) (`4a995a9`)

package/README.md

@@ -39,7 +39,7 @@ Every document is exactly one kind. There is no fifth. ([ADR-0010](adr/0010-live
 | Kind | Files | Rule |
 |---|---|---|
 | **Immutable** | `adr/*.md`, `slices/*.md` | Written once. Body prose is never edited — only status/supersession fields change. |
-| **Generated** | `adr/INDEX.md` | Built from frontmatter by script. Never hand-edited. |
+| **Generated** | `adr/INDEX.md`, and this repo's `CHANGELOG.md` | Built by script — from frontmatter, or from git tags. Never hand-edited. |
 | **Mutable** | `LEDGER.md` | Exactly one per repo. The only file maintained by hand. |
 | **Live** | `README.md`, `docs/*` | Describes how something behaves *now*; updated in the same change as the code it describes. |
 
@@ -63,6 +63,60 @@ free to change, because status and supersession are how a record announces it wa
 
 ---
 
+## The three formats
+
+Everything the linter enforces is one of these. They are small on purpose: a schema you can
+parse by hand is one you can also fix by hand at 6pm.
+
+**An ADR's frontmatter.** Eight fields, all required, closed vocabularies for `type` and
+`status` (R1–R3):
+
+```markdown
+---
+id: '0007'
+title: "Sessions are signed, not stored"
+type: architecture          # architecture | slice | batch
+status: accepted            # accepted | proposed | superseded | amended
+date: 2026-03-14            # a real calendar date; 2026-02-30 is rejected
+supersedes: []              # [0003] — and 0003 must point back (R4–R7)
+superseded_by: []
+---
+
+# ADR-0007 — Sessions are signed, not stored
+
+## Context
+## Decision
+## Consequences
+```
+
+**A ledger line.** One per item, and closing it means deleting the line (R8 checks the
+citation resolves):
+
+```markdown
+- [bug] Token refresh races when two tabs renew at once; the loser gets a 401 and no retry.
+  Reproduced on staging 2026-03-02 (ADR-0007).
+```
+
+`type` is `bug` | `feature` | `deferred` | `audit`.
+
+**A Definition of Done.** Acceptance criteria as Given/When/Then, written before the code
+(R13 requires a full triad, R12 requires `## Verification` alongside it):
+
+```markdown
+## Definition of Done
+
+- **Given** a session signed 25 hours ago
+  **When** the client calls any authenticated endpoint
+  **Then** the response is 401 and the body names `token_expired`
+
+## Verification
+
+`test/session-expiry.test.mjs`, plus `scripts/session-verify.mjs` for the clock-skew case a
+unit test cannot assert — wired into `package.json`, or R11 fails the commit.
+```
+
+---
+
 ## Quickstart
 
 Install into a git repo — dry-run first, always ([ADR-0006](adr/0006-init-method-bootstrap.md)).
@@ -94,17 +148,43 @@ From a clone of this repo, the same entry point runs directly:
 node scripts/init-method.mjs <repo-root> --apply
 ```
 
-It installs `CLAUDE.md`, `LEDGER.md`, the linter, the index builder, and a pre-commit hook —
+It installs `CLAUDE.md`, `LEDGER.md`, `docs/quality-bar.md`, the linter, the index builder,
+and a pre-commit hook —
 and **refuses to install the hook on a linter-red corpus**, because a hook that blocks every
 commit is the tool bricking the repo it was meant to protect. If a hook framework already
 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)).
 
+It also refuses, by name, when a path it manages is not a file it can read and write — a
+directory where `CLAUDE.md` should be, or a symlink that does not resolve. Nothing is written
+in that state, in any mode: the alternative was an `EISDIR` stack trace naming `readFileSync`,
+or, for an unresolvable link, silently writing through it.
+
 The linter and slash commands are **vendored per repo** and a repo's local edits to the
 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)).
 
+`docs/quality-bar.md` rides the same rules. It is the standard a slice's
+`## Definition of Done` is measured against — no `any`, fail loud, no magic values, the
+testing rule that a test derives from the spec and never from the code
+([ADR-0024](adr/0024-the-quality-bar-ships-with-the-method.md)), and the rule that where a
+well-tested library or standard already covers the need it is proposed **by name** before any
+bespoke design, with a departure argued from a property it would cost *and* a measured build
+cost ([ADR-0025](adr/0025-the-established-solution-is-the-default.md)). Shipping the demand for a
+Definition of Done without the standard it is judged by left every consumer to supply the
+standard themselves. Adapt it freely: a repo whose stack has no `any` should cut that rule,
+and an `--update` keeps the cut.
+
+Almost all of it is **`review-only`** and says so in the file. No linter here can tell
+whether a test was derived from a specification or from the implementation it tests; that is
+what the adversarial pass in `/wrap-up` is for, and claiming otherwise would be the failure
+this kit exists to remove. One subset *is* mechanical and the bar says so: a test asserting a
+constant it imported from the module under test is the assertion `K === K`, it passes whatever
+`K` is, and an AST linter can find it. Catching some instances of a defect beats catching
+none — the original claim that this was not worth checking was withdrawn by amendment after a
+wider count found six sites in one suite.
+
 ---
 
 ## Commands
@@ -127,6 +207,7 @@ 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 run changelog  # regenerate CHANGELOG.md from git tags (this repo only)
 npm test           # the regression suite (every rule has a fixture)
 ```
 
@@ -255,6 +336,31 @@ happened ([ADR-0005](adr/0005-write-routing-and-the-bounds-of-memory.md)):
 A rule that governs a codebase never belongs in assistant memory: memory is invisible to
 every other reader of the repo, unversioned, and lost on a change of machine.
 
+One artifact moved off row two. General *working practice* — the quality bar — now ships
+with the method as `docs/quality-bar.md` rather than living only in a personal global file
+([ADR-0024](adr/0024-the-quality-bar-ships-with-the-method.md)). ADR-0005 rejected
+per-repo copies for having no reconciliation point; the vendoring record built in ADR-0023
+is that point, so the rejection is answered rather than overruled. The table itself still
+governs everything else.
+
+---
+
+## What this kit does *not* install
+
+Stele publishes itself to npm, so it carries release machinery: annotated tags as release
+boundaries, a `CHANGELOG.md` generated from them, and [`docs/releasing.md`](docs/releasing.md)
+for the order of the steps. **None of it is installed into your repo, and no rule requires any
+of it.** Nor are `CONTRIBUTING.md`, `SECURITY.md`, a code of conduct or a PR template
+scaffolded ([ADR-0026](adr/0026-the-changelog-is-generated-and-release-engineering-stops-at-this-repo.md)).
+
+Three reasons, and the third is the one that decides it. Most repos using this kit publish
+nothing, so a release convention there is ceremony against nobody. `CLAUDE.md` and `LEDGER.md`
+*are* scaffolded because the method reads and writes them — community-health files are
+load-bearing for nothing it does, and adding them would make this a repo scaffolder, which
+GitHub already ships and tests better than we would. And `SECURITY.md` is a **promise** — a
+disclosure address, a response window. A missing one says "no stated policy", which is true;
+a templated one says something false to whoever reads it in the moment they rely on it.
+
 ---
 
 ## Design principles
@@ -266,7 +372,10 @@ every other reader of the repo, unversioned, and lost on a change of machine.
 - **Grammar over toolchain.** Given/When/Then is adopted as *writing discipline*, not a test
   framework — the verify scripts are the executable layer.
 - **The diff is the audit trail.** Immutable records, generated indexes, and single-writer
-  ledgers mean the git log *is* the history — no hand-maintained changelog to drift.
+  ledgers mean the git log *is* the history. This repo's own `CHANGELOG.md` follows from that
+  rather than sitting beside it: it is generated from annotated tags, never hand-written, so
+  there is no second copy of the facts to drift
+  ([ADR-0026](adr/0026-the-changelog-is-generated-and-release-engineering-stops-at-this-repo.md)).
 
 For the reasoning behind any of these, read the ADR it links to. That is what the ADRs are
 for.

package/docs/quality-bar.md

@@ -0,0 +1,169 @@
+# Quality bar
+
+The standard a slice's `## Definition of Done` is measured against (stele:ADR-0024). This
+file ships with the method and is vendored into this repo; it is a **live doc**
+(stele:ADR-0010) — update it in the same change as the practice it describes.
+
+It is yours to adapt. An `--update` keeps an edit you made here and reports it, and
+overwrites this file only if the repo never touched it (stele:ADR-0023). A rule that does
+not apply to this stack should be cut rather than ignored.
+
+Each section says how it is **enforced**, in the vocabulary of `CLAUDE.md` §4 —
+`verified_by: <script>`, `pending (LEDGER)`, `review-only`. Most of this is `review-only`:
+it is enforced by `/wrap-up` and by review, not by a script. That is stated rather than
+glossed, because a standard that overstates its own enforcement is the failure
+stele:ADR-0003 exists to prevent, committed one level up.
+
+## 1. Correctness — `review-only`
+
+- **Never use `any`.** No exceptions. `unknown` plus narrowing, generics, or proper types.
+  In a language without `any`, the rule is the same one: no escape hatch that turns off the
+  checker for a value you did not want to describe.
+- **Fail loud.** No swallowed errors — no empty `catch`, no catch-log-and-continue past a
+  broken invariant, no default or fallback that masks a real failure. Validate at boundaries
+  and stop at the first sign something is wrong. A silenced error is a bug debugged twice:
+  once now, blind, and once later for real.
+- **No hacks, no quick fixes, no workarounds.** Find the root cause and fix it for good. A
+  symptom silenced is a bug rescheduled.
+- **No magic values.** A bare `86400` or `0.15` in a branch is a latent bug — name it as a
+  constant whose name explains what it is and why.
+
+## 2. Design — `review-only`
+
+- **Lean, purposeful code — KISS.** The simplest thing that works. Complexity must earn its
+  place, and unexplained complexity is a defect. No speculative generality, no abstraction
+  without a present need. Fight cyclomatic complexity by extracting composable, well-named
+  functions **for readability and reuse — never to hit a number**; decomposition that adds
+  indirection without adding clarity is its own smell.
+- **Cohesion and DRY, by the rule of three.** Modules stay cohesive; a piece of logic lives
+  in one place. Reach for reuse or composition on the **third** instance of the same logic —
+  not the first, which is the speculative generality forbidden above. Apply SOLID only where
+  it earns its keep; misapplied, it produces exactly the over-abstraction this bar exists to
+  prevent.
+- **Names are accurate descriptors.** No `x`, `tmp`, `data2`, `handle2`. A name states the
+  thing's intent and its meaning in the domain. When a good name is hard to find, the design
+  is usually the problem, not the vocabulary.
+- **Comments explain WHY, not WHAT** — the code already shows what. No commented-out code and
+  no unused exports left behind; dead code is deleted, not parked. Version control remembers
+  it.
+- **Never hardcode absolute paths** in config files, scripts, or commands. Always relative.
+- **Prefer the established solution; argue any departure in writing** (stele:ADR-0025). Where a
+  well-tested library, pattern, protocol, or industry standard already covers the need, propose
+  it first and **by name**, before drawing a bespoke design — including when the operator asked
+  for the bespoke build, since asking for one is not evidence that none exists. Hand-rolling is
+  the exception and it is a legitimate one, under two conditions together: it names the property
+  the standard would cost (a hard constraint, a dependency budget, a platform or licence limit)
+  **and** it states the build cost as a measurement, not an estimate. What is not admissible is
+  reinventing by default, or meeting the standard after the code is written — at that point the
+  sunk build argues for itself and the comparison is a design against a rewrite. Both cases are
+  on the record in the repo that ships this file: `stele:ADR-0022` declines a mutation-testing
+  framework, naming the zero-dependency property it would cost and the twenty lines its
+  replacement takes; `stele:ADR-0008` is the bill for the omission — a design that assumed the
+  pre-commit slot was free met the widely-deployed tool that owns it three ADRs later, and pays
+  for a second install shape permanently. Inside a single codebase the same rule is
+  `stele:ADR-0013`.
+
+## 3. Design first — measure twice, cut once — `verified_by: lint-docs.mjs` (partly)
+
+Design before implementation. The decision is written down *before* the code, and the doc
+and the code ship in the same commit. R12 and R13 check that a slice carries its
+`## Verification` and its `## Definition of Done`; they cannot check that a scenario is
+*right*, which is what `/wrap-up` is for.
+
+**Decisions cite measured data, not estimates.** If a design question has a measurable
+answer, measure it — that is what `scripts/<topic>-probe.mjs` is for, and the number goes in
+the ADR.
+
+For anything non-trivial, **present the options and their tradeoffs before building.**
+
+## 4. Tests — `review-only`
+
+- **Every relevant piece of logic gets a regression test — a good one.** No excuses, and no
+  irrelevant, duplicate, or fragile tests either. Test observable behaviour, not
+  implementation internals, and cover the error and edge paths, not just the happy one. Tests
+  are codebase: same standards, same strict typing.
+- **A regression test must fail before the fix and pass after.** One that passes before
+  proves nothing.
+- **Tests assert intended behaviour, not observed behaviour** (stele:ADR-0024). A test
+  derives from the spec — the slice's `## Definition of Done`, the API contract, the
+  reference implementation, the issue — never from reading the code and recording what it
+  currently returns. A test written from the code cannot fail when the code is wrong: it
+  detects change, and it will pin a bug in place and defend it against the fix.
+  - Where there is no prior behaviour to fail against, **write the expected value down before
+    running it**, and treat a first-run pass as unverified rather than as proof.
+  - Where no specification exists, **say so at the test site** and name what the expectation
+    is derived from instead. An invented citation is worse than an admitted gap.
+  - When the spec is ambiguous, **settle the spec.** Never let the implementation cast the
+    deciding vote.
+  - **Citing the source is not the same as opening it.** The finding behind this rule was a
+    test whose comment cited the reference implementation by class name and then stated the
+    wrong arithmetic. Read the source, not the writeup — including your own. An aggregated
+    report of somebody else's findings is a writeup too.
+  - **Never assert a value the test imported from the module under test.** `expect(f(x)).toBe(K)`
+    where `K` comes from the module that produced it is the assertion `K === K`; it passes
+    whatever `K` is, including wrong. Write the number, and put the derivation in a comment.
+    This is the one part of this rule a machine can find, and in the suite that motivated it
+    the form appeared six times — more often than any other test-basis defect
+    (stele:ADR-0024). If this repo has an AST linter, it should carry the rule; scope it to
+    **scalar constants**, since asserting an imported *enum member* (`toBe(ItemId.Apple)`) is
+    correct and was 594 of the hits when the scope was widened.
+
+Neither instrument in the coverage layer detects a test derived from the implementation.
+`npm run mutants` cannot: such a test kills its mutant perfectly well, because mutating the
+constant breaks the test that asserts the constant (stele:ADR-0022). The adversarial pass in
+`/wrap-up` is the enforcement (stele:ADR-0017) — except for the imported-constant form above,
+which is the rule's one mechanically checkable subset, and catching some instances of a defect
+beats catching none.
+
+## 5. Finishing — `review-only`
+
+- **Boyscout rule:** leave every touched file better than found. A noticed bug is ours even
+  if we did not introduce it — fix it, or log it in `LEDGER.md` if deferred.
+- **Verify before declaring done.** Never report a task complete without running this repo's
+  own checks — typecheck, linter, tests. "Done" means the checks ran and passed in this
+  conversation, and that what ran was said out loud — not that the change looks right.
+
+## 6. Commits — `review-only`
+
+- **Explain WHY, not WHAT.** The diff already shows what changed.
+- **Atomic and coherent** — one logical change per commit.
+- **Ship the doc and the code in the same commit.**
+- **Commit only when asked.** Never commit unprompted.
+
+## 7. The operator may be wrong — `review-only`
+
+The operator is not infallible. If a proposal, observation, or assumption is incorrect, say
+so directly, with data or a clear explanation. Deferring to a wrong idea to be agreeable
+builds on a bad premise; being corrected early is cheaper for everyone.
+
+Correction is not only for factual errors. When the operator asks for something that violates
+a recorded decision without justifiable reason, or proposes a subpar fix, feature, or plan,
+push back the same way — with evidence and a concrete better option — and where a standard
+already solves the problem, the better option is that standard, named (§2). An operator can lack
+context a decision record already settled, so citing it *is* the correction. If a violation
+turns out to be justified, that justification is written down as a new or superseding ADR —
+never a silent exception.
+
+This cuts both ways: when the evidence contradicts a convention stated here, report that too.
+
+**Explain the reasoning behind operating choices**, do not just execute. An unexplained
+choice teaches nothing.
+
+## 8. Token economy — `review-only`
+
+- The main model plans, reviews, corrects, and writes tests. Delegate rock-mining
+  (mechanical refactors, boilerplate, broad surveys) to cheaper subagents — a small fast
+  model for mechanical work, a mid-tier one for work needing judgement — instructed to return
+  minimal, structured output so the main context stays clean.
+- **Say what was delegated, to which agent and model, and why** — one line, before the work
+  starts. Delegation is otherwise invisible: a subagent's reasoning never reaches the main
+  conversation, so an unannounced handoff means a result arrives with no way to judge how much
+  to trust it, and no chance to object that the task needed judgement rather than a cheaper
+  model.
+- When context is deep and the task is clearly switching, **say it is a good moment to
+  `/compact`** — it gets forgotten, and it causes context rot.
+
+## 9. Language — `review-only`
+
+**Everything written is in English** — code, comments, commits, docs, and user-facing or
+creative copy alike — regardless of the language of the conversation.

package/docs/releasing.md

@@ -0,0 +1,84 @@
+# Releasing
+
+How a version of `@isonimus/stele` reaches npm. A **live doc** (ADR-0010): update it in the
+same change as the procedure it describes.
+
+It exists because the steps below were previously done from memory, in the repo whose thesis
+is that a rule enforced by memory holds until the first busy afternoon (ADR-0003). Two things
+had already gone wrong by the time it was written: three published versions had **no git tags
+at all**, and a build tarball had been sitting in version control since 2026-07-27.
+
+## The order, and why it is this order
+
+```
+1.  npm run lint && npm test          the corpus is green and the suite passes
+2.  npm run index                     regenerate adr/INDEX.md; commit if it moved
+3.  edit package.json                 bump the version
+4.  commit                            the last commit before the tag
+5.  git tag -a vX.Y.Z -m "…"          on the commit being published (ADR-0026)
+6.  npm run changelog                 regenerate CHANGELOG.md from the new tag
+7.  commit                            "chore: changelog for vX.Y.Z"
+8.  git push && git push --tags       tag and history reach the remote together
+9.  npm publish                       irreversible: a version number is never reusable
+10. /init-method --update             in every installed repo, so the fix actually lands
+```
+
+**Why the tag comes before the changelog.** `scripts/build-changelog.mjs` reads tags and
+nothing else, so a tag that does not exist yet produces a changelog missing its own release.
+Tagging first is not a preference; it is the data dependency.
+
+**Why the changelog is a second commit, and why publish is one commit past the tag.** The
+changelog describes commits up to and including the tagged one, so it cannot live inside the
+object it is naming. `npm publish` therefore packs a tree one commit ahead of `vX.Y.Z` —
+identical to it but for `CHANGELOG.md`, which is the file that could not have been there. That
+skew is deliberate and bounded; anything else in the diff at step 9 means the release is not
+what the tag says it is.
+
+**Step 3 bumps the version, but step 5 tags the commit you are about to publish** — and on
+0.4.0 those were three commits apart, because work continued after the bump. `npm publish`
+packs the working tree, not the version-bump commit, so a tag left behind on the bump would
+name bytes nobody received. Bump last where you can; tag what ships where you cannot.
+
+**Why publish is last and by hand.** `npm publish` cannot be undone: a version number is burned
+even if the release is unpublished within the 72-hour window. Everything reversible happens
+first, so the irreversible step runs against a state already checked.
+
+**Why step 10 is part of the release.** The linter, the hook and the commands are *vendored*
+per repo (ADR-0006, ADR-0023). Publishing changes nothing in boxel or gamatar until
+`/init-method --update` runs there, so a release that stops at step 9 has shipped to the
+registry and to nobody.
+
+## Version numbers
+
+Pre-1.0, so the minor slot carries breaking changes:
+
+- **patch** — a fix that changes no vendored file's behaviour.
+- **minor** — a new linter rule, a change to a vendored command or to `docs/quality-bar.md`,
+  or any change to the installer's behaviour. A new rule makes commits fail that were green in
+  the previous version, which is breaking however small the diff.
+- **major** — reserved for 1.0.
+
+## What the changelog does and does not say
+
+It is generated from commit subjects between tags (ADR-0026). It therefore inherits exactly
+the quality of the commit messages, which is the argument for writing them properly rather
+than an argument for editing the changelog afterwards — **never hand-edit it**; the CI check
+will fail and the edit is lost at the next regeneration.
+
+It cannot say "you must run `--update` for this one". If a release needs that, say so in the
+release commit's subject, where the changelog will pick it up verbatim.
+
+## If something goes wrong
+
+- **Anything changed after tagging, including docs:** do not move the tag. Bump a patch
+  version, tag that, and publish it instead — the working tree is what `npm publish` packs, so
+  a tree that has moved past the tag is no longer the release the tag names. This happened on
+  the first run of this procedure: `v0.4.0` was tagged, a README update followed, and `0.4.1`
+  was published in its place. `v0.4.0` stays in the history as a tagged release that was never
+  published, which the changelog shows and which is the honest record (`0.2.1` is the same).
+- **Tagged the wrong commit, not yet pushed:** `git tag -d vX.Y.Z`, retag, regenerate.
+- **Tagged and pushed the wrong commit:** do not move the tag. Tag the correction as the next
+  patch version — a moved tag means two clones disagree about what a release was.
+- **Published a broken version:** publish the fix as a new version. Unpublishing is available
+  for 72 hours and is worse than a superseding release: it breaks every lockfile that already
+  pinned it.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@isonimus/stele",
-  "version": "0.3.0",
+  "version": "0.4.1",
   "type": "module",
   "description": "A linted, installable ADR workflow for git projects using Claude as an assistant",
   "keywords": [
@@ -29,9 +29,11 @@
   "files": [
     "scripts/",
     "templates/",
+    "docs/",
     ".claude/commands/",
     ".claude/hooks/",
     "README.md",
+    "CHANGELOG.md",
     "LICENSE"
   ],
   "publishConfig": {
@@ -41,6 +43,7 @@
     "test": "node --test test/*.test.mjs",
     "lint": "node scripts/lint-docs.mjs .",
     "index": "node scripts/build-index.mjs .",
+    "changelog": "node scripts/build-changelog.mjs .",
     "immutable": "node scripts/check-immutable.mjs",
     "mutants": "node scripts/check-mutants.mjs",
     "scan": "node scripts/scan-legacy.mjs",

package/scripts/build-changelog.mjs

@@ -0,0 +1,194 @@
+#!/usr/bin/env node
+// Builds CHANGELOG.md from annotated git tags (ADR-0026). Generated, never hand-edited.
+//
+//   node scripts/build-changelog.mjs [repo-root]           write CHANGELOG.md
+//   node scripts/build-changelog.mjs --check [repo-root]   fail if it is stale
+//
+// Tags are the only input, so the file changes when a release is tagged and at no other
+// time — which is what makes --check affordable in CI. Commits made after the newest tag
+// are deliberately absent until the next tag exists (ADR-0026).
+//
+// --check runs in CI only, and cannot move into the pre-commit hook: the hook checks the
+// commit by extracting a `git archive` of the staged tree into a temp directory (ADR-0018),
+// which has no `.git` and therefore no tags. Reading tags from the real repo instead would
+// check the working tree while claiming to check the commit, which is the exact confusion
+// ADR-0018 exists to prevent.
+
+import { writeFileSync, readFileSync, existsSync, realpathSync } from 'node:fs';
+import { execFileSync } from 'node:child_process';
+import { join } from 'node:path';
+import { fileURLToPath } from 'node:url';
+
+const CHANGELOG = 'CHANGELOG.md';
+
+/** Conventional-commit types, in the order a reader cares about them. Anything else sorts
+ *  last under its own literal prefix rather than being dropped: a commit that escaped the
+ *  convention is still a change that shipped, and hiding it would make the file a claim
+ *  about the corpus instead of a rendering of it. */
+const TYPE_ORDER = ['feat', 'fix', 'perf', 'refactor', 'test', 'docs', 'chore'];
+
+const git = (cwd, args) => execFileSync('git', args, { cwd, encoding: 'utf8' }).trim();
+
+/** The type prefix of a conventional subject (`feat(x): …` → `feat`), or null. */
+export function commitType(subject) {
+  const match = /^([a-z]+)(\([^)]*\))?!?:/.exec(subject);
+  return match ? match[1] : null;
+}
+
+const typeRank = (subject) => {
+  const index = TYPE_ORDER.indexOf(commitType(subject));
+  return index === -1 ? TYPE_ORDER.length : index;
+};
+
+/**
+ * The tags, split into releases and everything this tool refuses to call one.
+ *
+ * A release is an **annotated** tag that dereferences to a **commit**, and both halves of
+ * that are load-bearing (ADR-0026, found by the ADR-0017 pass on this file):
+ *
+ * - `refs/tags` holds lightweight tags too — local bookmarks, bisect markers, CI leftovers —
+ *   and counting one as a release publishes a section for something nobody released.
+ * - An annotated tag may point at a blob or a tree. `git rev-list -n 1` then yields the empty
+ *   string, and the next git call inherits it as a ref and dies with a raw `fatal: ambiguous
+ *   argument ''` plus a stack trace.
+ *
+ * Both are read straight off `for-each-ref` rather than probed afterwards: `%(*objecttype)`
+ * and `%(*objectname)` are the peeled object, so one call answers both questions and there is
+ * no window where a tag is assumed to be something it is not.
+ *
+ * Releases come back oldest first, ordered by the tagged **commit's** date rather than the
+ * tag's own — this repo's first three tags were written retroactively in one sitting, so
+ * creation order carries no release information whatever.
+ */
+export function readTags(cwd) {
+  const lines = git(cwd, [
+    'for-each-ref',
+    '--format=%(refname:short)\t%(objecttype)\t%(*objecttype)\t%(*objectname)',
+    'refs/tags',
+  ]);
+  if (lines === '') return { releases: [], skipped: [] };
+
+  const releases = [];
+  const skipped = [];
+
+  for (const line of lines.split('\n')) {
+    const [name, objectType, peeledType, peeledCommit] = line.split('\t');
+    if (objectType !== 'tag') {
+      skipped.push({ name, why: 'lightweight — a release tag is annotated (git tag -a)' });
+      continue;
+    }
+    if (peeledType !== 'commit') {
+      skipped.push({ name, why: `annotated but points at a ${peeledType || 'non-commit object'}` });
+      continue;
+    }
+    // Full timestamp for ordering, short date for display: two releases on one day are
+    // ordinary, and a date-only sort would fall back to alphabetical refname order, which
+    // puts v0.10.0 before v0.9.0.
+    const [orderedBy, date] = git(cwd, ['log', '-1', '--format=%aI\t%ad', '--date=short', peeledCommit]).split('\t');
+    releases.push({ name, commit: peeledCommit, orderedBy, date });
+  }
+
+  releases.sort((a, b) => (a.orderedBy < b.orderedBy ? -1 : a.orderedBy > b.orderedBy ? 1 : 0));
+  return { releases, skipped };
+}
+
+/**
+ * Subject and short SHA of every commit reachable from `to` and from none of `alreadyShipped`,
+ * newest first.
+ *
+ * Excluding *every* earlier release rather than only the previous one is what keeps a commit
+ * in one section. A tagged branch that merges in later is reachable from both its own tag and
+ * the merge's tag, so a plain `previous..this` range reports it twice — once under the release
+ * that shipped it and again under the release that merged it (ADR-0017 pass on this file).
+ *
+ * Merges themselves are excluded: a merge commit's subject records an integration, not a
+ * change, and the commits it brings in are listed individually.
+ */
+export function commitsSince(cwd, alreadyShipped, to) {
+  const lines = git(cwd, ['log', '--no-merges', '--format=%h\t%s', to, '--not', ...alreadyShipped]);
+  if (lines === '') return [];
+
+  return lines.split('\n').map((line) => {
+    const separator = line.indexOf('\t');
+    return { sha: line.slice(0, separator), subject: line.slice(separator + 1) };
+  });
+}
+
+/** The document. Pure, so the shape is testable without a repo. */
+export function renderChangelog(releases) {
+  const head = `# Changelog
+
+Generated by \`scripts/build-changelog.mjs\` from annotated git tags — never hand-edited
+(ADR-0026). Run \`npm run changelog\` after tagging a release.
+
+Every entry is a commit subject verbatim. Work committed after the newest tag is absent by
+design and appears when the next release is tagged.
+`;
+
+  if (releases.length === 0) {
+    return `${head}\nNo tags yet, so no releases to describe.\n`;
+  }
+
+  const sections = [...releases].reverse().map(({ name, date, commits }) => {
+    const body = commits.length === 0
+      ? '\nNo commits between this tag and the previous one.\n'
+      : `\n${[...commits]
+          .sort((a, b) => typeRank(a.subject) - typeRank(b.subject))
+          .map(({ sha, subject }) => `- ${subject} (\`${sha}\`)`)
+          .join('\n')}\n`;
+    return `## ${name} — ${date}\n${body}`;
+  });
+
+  return `${head}\n${sections.join('\n')}`;
+}
+
+/** The document this repo's tags describe, and the tags that were not treated as releases. */
+export function buildChangelog(cwd) {
+  const { releases, skipped } = readTags(cwd);
+  return {
+    text: renderChangelog(
+      releases.map((release, index) => ({
+        ...release,
+        commits: commitsSince(cwd, releases.slice(0, index).map((earlier) => earlier.commit), release.commit),
+      })),
+    ),
+    skipped,
+  };
+}
+
+function main(argv) {
+  const check = argv.includes('--check');
+  const cwd = argv.find((arg) => !arg.startsWith('--')) ?? process.cwd();
+  const path = join(cwd, CHANGELOG);
+  const { text: wanted, skipped } = buildChangelog(cwd);
+
+  // Named rather than dropped in silence: a release tagged with a bare `git tag` produces a
+  // changelog missing that release, and the only symptom is an absence nobody looks for.
+  for (const { name, why } of skipped) {
+    console.error(`note: tag ${name} is not treated as a release — ${why}`);
+  }
+
+  if (!check) {
+    writeFileSync(path, wanted);
+    console.log(`wrote ${CHANGELOG}`);
+    return 0;
+  }
+
+  if (!existsSync(path)) {
+    console.error(`${CHANGELOG} is missing — run \`npm run changelog\`.`);
+    return 1;
+  }
+  if (readFileSync(path, 'utf8') !== wanted) {
+    console.error(`${CHANGELOG} does not match the tags — a release was tagged without regenerating it. Run \`npm run changelog\`.`);
+    return 1;
+  }
+  console.log(`${CHANGELOG} matches the tags`);
+  return 0;
+}
+
+// Resolved on both sides before comparing: a raw `file://${argv[1]}` check is false whenever
+// the script is reached through a symlink, and main() then silently never runs (ADR-0015
+// amendment, where that cost an install that exited 0 and did nothing).
+if (process.argv[1] && realpathSync(process.argv[1]) === fileURLToPath(import.meta.url)) {
+  process.exit(main(process.argv.slice(2)));
+}

package/scripts/check-mutants.mjs

@@ -31,11 +31,15 @@ const LINTER = 'scripts/lint-docs.mjs';
 const IMMUTABLE = 'scripts/check-immutable.mjs';
 
 /** ADR-0022 excluded init-method.mjs wholesale, reasoning that a mutant there mostly proves
- *  the filesystem still works. `classifyCommand` (ADR-0023) is the first total, IO-free
+ *  the filesystem still works. `classifyVendored` (ADR-0023) is the first total, IO-free
  *  predicate in that file, so it falls inside the scope ADR-0022 actually described rather
  *  than the file it named. Recorded as a refinement, never a silent exception. */
 const INIT = 'scripts/init-method.mjs';
 
+/** The changelog's type classifier and its ordering are total and IO-free, so they fall in
+ *  the same scope as the linter's predicates — the git-reading half does not (ADR-0026). */
+const CHANGELOG = 'scripts/build-changelog.mjs';
+
 /**
  * The curated mutant list. Each entry names one behaviour and the smallest edit that
  * reverses it.
@@ -98,13 +102,13 @@ export const MUTANTS = [
     replace: 'if (!isSuperseded && supersededBy.length > 1) {',
   },
   {
-    label: 'classifyCommand: treat an unrecorded command as stale rather than unknown',
+    label: 'classifyVendored: treat an unrecorded command as stale rather than unknown',
     file: INIT,
     find: "if (recordedDigest === undefined) return 'unknown';",
     replace: "if (recordedDigest === undefined) return 'stale';",
   },
   {
-    label: 'classifyCommand: swap the stale/adapted verdict',
+    label: 'classifyVendored: swap the stale/adapted verdict',
     file: INIT,
     find: "return digest(targetText) === recordedDigest ? 'stale' : 'adapted';",
     replace: "return digest(targetText) === recordedDigest ? 'adapted' : 'stale';",
@@ -115,6 +119,18 @@ export const MUTANTS = [
     find: 'if (cursor === now.length) return i;',
     replace: 'if (cursor > now.length) return i;',
   },
+  {
+    label: 'commitType: accept a subject with no colon as conventional',
+    file: CHANGELOG,
+    find: "/^([a-z]+)(\\([^)]*\\))?!?:/",
+    replace: "/^([a-z]+)(\\([^)]*\\))?!?:?/",
+  },
+  {
+    label: 'typeRank: sort an unrecognised type first rather than last',
+    file: CHANGELOG,
+    find: 'return index === -1 ? TYPE_ORDER.length : index;',
+    replace: 'return index === -1 ? 0 : index;',
+  },
   {
     label: 'firstLostLine: compare body lines loosely',
     file: IMMUTABLE,

package/scripts/init-method.mjs

@@ -12,7 +12,7 @@
 // documents it would report "0 document(s) — ok" (the reason rule 10 exists), certifying
 // an install that checks nothing.
 
-import { existsSync, readFileSync, writeFileSync, mkdirSync, copyFileSync, lstatSync, readlinkSync, symlinkSync, unlinkSync, readdirSync, realpathSync } from 'node:fs';
+import { existsSync, readFileSync, writeFileSync, mkdirSync, copyFileSync, lstatSync, statSync, accessSync, constants as fsConstants, readlinkSync, symlinkSync, unlinkSync, readdirSync, realpathSync } from 'node:fs';
 import { createHash } from 'node:crypto';
 import { join, dirname, relative } from 'node:path';
 import { fileURLToPath } from 'node:url';
@@ -35,21 +35,36 @@ const VENDORED = [
 
 const COMMANDS_DIR = '.claude/commands';
 
+/** Prose vendored alongside the commands and under the same rules: adaptable, kept on
+ *  update unless untouched. The quality bar is the standard a slice's Definition of Done
+ *  is measured against, so it has to reach the repo the Definition of Done lives in
+ *  (ADR-0024). A Python repo cutting the rule about `any` is use, not drift. */
+export const ADAPTABLE_DOCS = ['docs/quality-bar.md'];
+
 /**
- * The slash commands, vendored too (ADR-0023) — same target path as toolkit path.
+ * Everything vendored under the adaptable rules (ADR-0023) — same target path as toolkit
+ * path, which is what lets one classification serve both `--update` and `--check`.
  *
- * Read from disk rather than listed, so a new command reaches installed repos without
- * anyone remembering to extend an array here.
+ * Commands are read from disk rather than listed, so a new command reaches installed repos
+ * without anyone remembering to extend an array here.
  */
-const commandFiles = (toolkit) =>
-  readdirSync(join(toolkit, COMMANDS_DIR))
+const adaptableFiles = (toolkit) => [
+  ...readdirSync(join(toolkit, COMMANDS_DIR))
     .filter((name) => name.endsWith('.md'))
     .sort()
-    .map((name) => `${COMMANDS_DIR}/${name}`);
+    .map((name) => `${COMMANDS_DIR}/${name}`),
+  ...ADAPTABLE_DOCS,
+];
 
 /**
- * What the toolkit last handed this repo: command path → SHA-256 of the content written
- * there (ADR-0023).
+ * What the toolkit last handed this repo: vendored adaptable path → SHA-256 of the content
+ * written there (ADR-0023).
+ *
+ * The JSON key is still `commands`, though the set now includes `docs/quality-bar.md`
+ * (ADR-0024). Renaming it would mean bumping PROVENANCE_VERSION, and an unrecognised
+ * version is deliberately read as *no record at all* — so a cosmetic rename would
+ * reclassify every command in every installed repo as `unknown` on the next run. The
+ * inaccuracy is cheaper than that, and this comment is the fix.
  *
  * Without it an update sees two states where three are needed — a stale copy of an older
  * release and a deliberate local adaptation are the same observation, "differs from the
@@ -127,6 +142,76 @@ function isSymlink(path) {
   }
 }
 
+/**
+ * Managed paths in the target that exist but are not a file this tool can read and write.
+ *
+ * `existsSync` answers the wrong question twice, and every managed path lives in a repo we
+ * do not control. It is **true** for a directory, so the read crashes with an `EISDIR` that
+ * names `readFileSync` rather than the offending path; it is **false** for a symlink that
+ * does not resolve, so the path reads as *absent* — `--check` calls it missing and `--apply`
+ * writes straight through the link. Refusing by name is the fix, for the reason the hook
+ * install refuses rather than warns (ADR-0006): a stack trace tells the operator nothing
+ * about which file is wrong.
+ *
+ * `.git/hooks/pre-commit` is deliberately a symlink and is judged by installHook(), not here.
+ */
+function unusablePaths({ target, toolkit }) {
+  const managed = [
+    ...SCAFFOLD.map(([dest]) => dest),
+    ...VENDORED.map(([dest]) => dest),
+    ...adaptableFiles(toolkit),
+    join('adr', 'INDEX.md'),
+    PROVENANCE,
+    FRAMEWORK_CONFIG,
+  ];
+
+  return managed.flatMap((dest) => {
+    const path = join(target, dest);
+    let link;
+    try {
+      link = lstatSync(path, { throwIfNoEntry: false });
+    } catch (error) {
+      // throwIfNoEntry suppresses ENOENT and nothing else. ENOTDIR here means an ancestor
+      // exists as a file, so nothing at this path can be read, written or created — and
+      // pointing at the leaf would send the operator to the wrong file.
+      return [{ path, kind: error.code === 'ENOTDIR'
+        ? 'unreachable — a parent of it exists as a file rather than a directory'
+        : `cannot be inspected (${error.code})` }];
+    }
+    if (link === undefined) return []; // absent: the ordinary case
+    if (link.isFile()) return whenUnreadable(path);
+    if (!link.isSymbolicLink()) {
+      return [{ path, kind: link.isDirectory() ? 'a directory' : 'not a regular file' }];
+    }
+    // A symlink to a real file reads and writes fine, so it stays supported. statSync
+    // throws ELOOP on a cycle, which throwIfNoEntry does not suppress — the code it
+    // carries goes into the report rather than being discarded.
+    try {
+      if (statSync(path).isFile()) return whenUnreadable(path);
+      return [{ path, kind: `a symlink to ${readlinkSync(path)}, which is not a file` }];
+    } catch (error) {
+      return [{ path, kind: `a symlink to ${readlinkSync(path)} that cannot be resolved (${error.code})` }];
+    }
+  });
+}
+
+/**
+ * A file whose type is fine but whose permissions are not: `lstat` succeeds on a `chmod 000`
+ * file, and the read that follows throws a bare EACCES.
+ *
+ * Only readability is checked. Every managed path that exists is read unconditionally, while
+ * writes are conditional — so refusing on write permission too would reject a read-only
+ * vendored file that already matches the toolkit and needs no write at all.
+ */
+function whenUnreadable(path) {
+  try {
+    accessSync(path, fsConstants.R_OK);
+    return [];
+  } catch (error) {
+    return [{ path, kind: `unreadable (${error.code})` }];
+  }
+}
+
 /** The linter's error findings for a repo.
  *  Always the repo ROOT: pointed at a subdirectory holding no documents the linter
  *  reports "0 document(s) — ok", certifying an install that checks nothing (rule 10). */
@@ -151,7 +236,7 @@ function vendor({ target, toolkit, apply, report }) {
     }
     mkdirSync(dirname(to), { recursive: true });
     copyFileSync(from, to);
-    report('wrote', to, `${verb}d from toolkit`);
+    report('wrote', to, `${verb === 'copy' ? 'copied' : 'updated'} from toolkit`);
   }
 }
 
@@ -199,7 +284,7 @@ function writeProvenance(target, commands) {
  *
  * @returns {'absent'|'current'|'stale'|'adapted'|'unknown'}
  */
-export function classifyCommand({ targetText, toolkitText, recordedDigest }) {
+export function classifyVendored({ targetText, toolkitText, recordedDigest }) {
   if (targetText === null) return 'absent';
   if (targetText === toolkitText) return 'current';
   if (recordedDigest === undefined) return 'unknown';
@@ -213,21 +298,21 @@ const KEPT_REASON = {
 };
 
 /**
- * Slash commands, which are prose and therefore adaptable (ADR-0023).
+ * Slash commands and the quality bar — prose, and therefore adaptable (ADR-0023, ADR-0024).
  *
  * Copy-if-absent, unlike vendor(): a repo that has tailored `/slice` to its own workflow
  * must not have that overwritten. `--update` additionally refreshes anything the repo has
  * not touched, and only `--force` discards an adaptation (ADR-0023).
  */
-function vendorCommands({ target, toolkit, apply, update, force, report }) {
+function vendorAdaptable({ target, toolkit, apply, update, force, report }) {
   const recorded = readProvenance(target, report);
   const learned = { ...recorded };
   let changed = false;
 
-  for (const path of commandFiles(toolkit)) {
+  for (const path of adaptableFiles(toolkit)) {
     const to = join(target, path);
     const toolkitText = read(join(toolkit, path));
-    const state = classifyCommand({
+    const state = classifyVendored({
       targetText: existsSync(to) ? read(to) : null,
       toolkitText,
       recordedDigest: recorded[path],
@@ -411,9 +496,9 @@ function check({ target, toolkit, report }) {
   // under which no command difference could be counted and so a shipped defect in one was
   // invisible in every installed repo).
   const recorded = readProvenance(target, report);
-  for (const path of commandFiles(toolkit)) {
+  for (const path of adaptableFiles(toolkit)) {
     const to = join(target, path);
-    const state = classifyCommand({
+    const state = classifyVendored({
       targetText: existsSync(to) ? read(to) : null,
       toolkitText: read(join(toolkit, path)),
       recordedDigest: recorded[path],
@@ -465,16 +550,27 @@ export function initMethod({ target, toolkit = TOOLKIT, mode = 'install', apply
     return { actions, problems: 1 };
   }
 
+  // Before anything reads or writes, and in every mode: a partial install is worse than no
+  // install, and --check cannot judge a state it would crash on. Every offending path is
+  // named, not just the first, so one re-run is enough to clear them.
+  const unusable = unusablePaths({ target, toolkit });
+  if (unusable.length > 0) {
+    for (const { path, kind } of unusable) {
+      report('problem', path, `${kind} — this tool reads and writes it as a file. Move or remove it, then re-run.`);
+    }
+    return { actions, problems: unusable.length };
+  }
+
   if (mode === 'check') {
     check({ target, toolkit, report });
   } else if (mode === 'update') {
     vendor({ target, toolkit, apply, report });
-    vendorCommands({ target, toolkit, apply, update: true, force, report });
+    vendorAdaptable({ target, toolkit, apply, update: true, force, report });
     if (apply) lintAfterUpdate({ target, report });
   } else {
     scaffold({ target, toolkit, apply, report });
     vendor({ target, toolkit, apply, report });
-    vendorCommands({ target, toolkit, apply, update: false, force: false, report });
+    vendorAdaptable({ target, toolkit, apply, update: false, force: false, report });
     buildIndex({ target, apply, report });
     installHook({ target, apply, report });
   }

package/templates/CLAUDE.md

@@ -4,10 +4,14 @@
 
 Stack: {{STACK}}
 
-General working practices — quality bar, commit hygiene, delegation, correction, language
-— live in `~/.claude/CLAUDE.md` and apply here without being restated. This file carries
-only what is specific to **this** repo. Restating a global rule here would create a second
-copy with no sync path, which is the failure stele:ADR-0005 exists to prevent.
+General working practices — quality bar, testing standard, commit hygiene, delegation,
+correction, language — live in [`docs/quality-bar.md`](docs/quality-bar.md) and apply here
+without being restated. It ships with the method and is vendored into this repo, so it is
+yours to adapt; an update keeps what you changed (stele:ADR-0024).
+
+This file carries only what is specific to **this** repo. Restating a rule from the bar here
+would create a second copy with no sync path, which is the failure stele:ADR-0005 exists to
+prevent.
 
 ## 1. Document taxonomy — four kinds