@isonimus/stele 0.2.0 → 0.4.1

package/.claude/commands/adr.md

@@ -10,8 +10,9 @@ rather than a durable decision, use `/slice` instead.
 
 Steps:
 
-1. Compute the next free id: the highest ordinal in `adr/` plus one, zero-padded to four
-   digits. Do not reuse or renumber.
+1. Compute the next free id: the highest ordinal across **both** `adr/` and `slices/` plus
+   one, zero-padded to four digits. ADRs and slices share one id space — rule 2 fails on a
+   duplicate id whichever directory it sits in. Do not reuse or renumber.
 2. Choose the `type`: `architecture` for a durable decision, `slice` for a feature unit,
    `batch` only if it genuinely bundles several unrelated decisions that cannot map 1:1.
 3. Write `adr/NNNN-<kebab-title>.md` opening with the stele:ADR-0002 frontmatter block:

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

@@ -1,6 +1,6 @@
 ---
 description: Install the method kit (CLAUDE.md, LEDGER.md, linter, index, pre-commit hook) into a git repo
-argument-hint: [repo-root] [--check | --update]
+argument-hint: [repo-root] [--check | --update [--force]]
 ---
 
 Install this kit into a repo, or verify an existing install (stele:ADR-0006). The script does
@@ -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-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.
+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,14 +98,33 @@ 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
 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 (stele:ADR-0006, stele:ADR-0007), and drift is
-the price.
+A `PROBLEM` on a command is different: it means that file is **behind the toolkit and
+unmodified here**, so the repo is simply missing a fix. `--update` takes it.
+
+## 7. Updating an installed repo
+
+```
+node scripts/init-method.mjs <target> --update --apply
+```
+
+`--update` re-copies the vendored scripts and the hook unconditionally — a locally edited
+linter is a defect, not an adaptation (stele:ADR-0006). Commands are gentler
+(stele:ADR-0023): anything this repo has **not** touched takes the toolkit's version,
+anything it **has** touched is kept and reported.
+
+`.claude/.stele-vendored.json` is what makes that distinction possible — it records what
+the toolkit last wrote, so a stale copy and a deliberate edit stop being the same
+observation. **Commit it.** A repo without one (installed before the record existed) has
+every differing command reported as unreconciled and overwrites none of them; reconcile
+those by hand, once.
+
+`--update --force` discards local adaptations. Never reach for it to make output tidy —
+it is for when the operator has decided an adaptation should go. Say what will be lost
+before running it.

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

@@ -12,7 +12,22 @@ get recorded until they have gone stale (stele:ADR-0003).
      generated index is drift by another name.
    - `npm test` — the test suite must pass; docs changes must not disturb code.
 
-2. **Adversarial pass** (stele:ADR-0017) — run it if this change touched a `CLAUDE.md` §4
+2. **Mutation check** — only if this repo has `scripts/check-mutants.mjs` *and* this change
+   touched a module its list covers. Otherwise skip it and say so; on most changes it has
+   nothing to look at.
+
+   - `npm run mutants`. Every non-exempt mutant must die.
+   - A **survivor is not a bug** — it is correct behaviour that no test is watching, so a
+     later refactor could reverse it in silence. Fix it by writing the missing regression
+     test, never by deleting the mutant.
+   - Mark a mutant `equivalent` only when the mutated code genuinely means the same thing,
+     and say why in the entry. That field is the one way a survivor passes, so it is also
+     the obvious place to bury an inconvenient gap.
+   - It measures whether tests *bite*, not whether code is right: it cannot see a missing
+     input or a rule that was wrong from the start. A green run is not a correctness claim,
+     and step 3 is what covers what it misses.
+
+3. **Adversarial pass** (stele:ADR-0017) — run it if this change touched a `CLAUDE.md` §4
    standing invariant, an exported/public API, a data format or anything persisted, or a
    Definition of Done scenario the slice flagged as risky. Otherwise skip it and say so.
 
@@ -20,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
@@ -34,7 +56,7 @@ get recorded until they have gone stale (stele:ADR-0003).
      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:
+4. Then answer these four out loud, and act on each:
    - **Did this change a user- or dev-facing API or feature?** If so, update `README.md`
      (and any docs) in the same change — it is a live document.
    - **Did this make a decision later work must obey?** If so, write it with `/adr` now,
@@ -48,5 +70,5 @@ get recorded until they have gone stale (stele:ADR-0003).
      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.
 
-4. Report what you found and did for each of the four, so the operator can confirm
+5. Report what you found and did for each of the four, so the operator can confirm
    nothing was silently skipped.

package/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)).
@@ -81,20 +135,55 @@ updated linter calls red. A release that adds a rule can turn a green repo red b
 hook that is already installed, and the failure otherwise shows up as an unexplained
 blocked commit some time later (ADR-0021).
 
+It also **keeps any slash command this repo adapted**. `.claude/.stele-vendored.json`
+records what the toolkit last handed over, which is what lets an update tell a stale copy
+from a deliberate edit — before that record existed the two were the same observation, so
+taking a fix meant discarding every adaptation
+([ADR-0023](adr/0023-vendored-commands-and-what-an-update-may-overwrite.md)).
+Commit that file. `--update --force` discards adaptations, and has to be typed.
+
 From a clone of this repo, the same entry point runs directly:
 
 ```
 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 ([ADR-0007](adr/0007-commands-are-vendored-and-adaptable.md)).
+commands survive re-runs — including across an `--update`
+([ADR-0023](adr/0023-vendored-commands-and-what-an-update-may-overwrite.md), superseding
+[ADR-0007](adr/0007-commands-are-vendored-and-adaptable.md)).
+
+`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.
 
 ---
 
@@ -107,7 +196,7 @@ 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, run the adversarial pass when it triggers, and ask the four questions that get forgotten. |
+| `/wrap-up` | End-of-task gate — run the checks, run the mutation check and adversarial pass when they trigger, and ask the four questions that get forgotten. |
 | `/remember <fact>` | Route a fact to the destination that governs it (see [Where things live](#where-things-live)). |
 | `/init-method` | Install the kit into a git repo. |
 
@@ -117,6 +206,8 @@ 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 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)
 ```
 
@@ -202,7 +293,21 @@ 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**
+   This layer has two instruments, and neither is a linter. The first is the **mutation
+   check** (`npm run mutants`), which answers one narrow question mechanically: *do the
+   tests bite?* It applies a curated list of small behaviour changes to the linter's pure
+   predicates and requires each to break a test. A survivor is not a bug — it is correct
+   behaviour nothing is watching, which a later refactor can reverse in silence. Measured on
+   adoption: 3 of 10 mutants died, and the seven survivors were all correct-but-unpinned
+   behaviour, now covered. It is deliberately not a framework — that would cost the
+   zero-dependency property, and curating the list is the work anyway.
+
+   Its limit is stated rather than discovered: it perturbs code and asks whether tests
+   notice, so it is blind to an input nobody wrote and to a rule that was wrong from the
+   start. **None of the three defects this project has actually suffered would have been
+   caught by it.** It buys regression durability, not correctness.
+
+   The second instrument is the one that covers exactly that gap: the **adversarial pass**
    ([ADR-0017](adr/0017-adversarial-review-is-the-coverage-mechanism.md)). Every coverage
    question has the form "is what you wrote sufficient?" and is addressed to the person who
    just wrote it — who already believes it is, which is why the code looks that way. So
@@ -231,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
@@ -242,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.