@isonimus/stele 0.1.2

package/.claude/commands/adr.md

@@ -0,0 +1,43 @@
+---
+description: Scaffold a new Architecture Decision Record with frontmatter pre-filled
+argument-hint: <short title of the decision>
+---
+
+Create a new ADR recording a decision that later work must obey — a mechanism, data
+format, or boundary. An ADR asserts *"on date X we chose Y because Z"*: a historical
+claim that stays true forever (ADR-0001). If you are recording a **feature work-unit**
+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.
+2. Choose the `type`: `architecture` for a durable decision, `slice` for a feature unit,
+   `batch` only if it genuinely bundles several unrelated decisions that cannot map 1:1.
+3. Write `adr/NNNN-<kebab-title>.md` opening with the ADR-0002 frontmatter block:
+
+   ```
+   ---
+   id: 'NNNN'
+   title: "<title>"
+   type: architecture
+   status: accepted
+   date: <today, YYYY-MM-DD>
+   supersedes: []
+   superseded_by: []
+   ---
+   ```
+
+4. Body sections: `## Context` (the forces and the observed problem — cite data, not
+   estimates), `## Decision`, `## Consequences`.
+5. If this decision **supersedes** an existing ADR: add its id to this ADR's `supersedes`,
+   set the old ADR's `status: superseded` and add this id to its `superseded_by`, and in
+   the body state *why the old reasoning was wrong* — that record is the point. Both
+   directions must match or rule 4 fails. Never edit the old ADR's prose body; only its
+   status/supersession fields may change.
+6. If the decision defers something, record it as one line in `LEDGER.md` citing this ADR.
+   Do not track it anywhere else.
+7. Regenerate the index (`npm run index`) and run the linter (`npm run lint`) — both must
+   be green before you are done.
+
+Title argument: $ARGUMENTS

package/.claude/commands/audit.md

@@ -0,0 +1,25 @@
+---
+description: Full-corpus health check — run every invariant and surface warnings and drift
+argument-hint: [repo-root]
+---
+
+Run a full audit of the ADR corpus and report its health. Unlike `/wrap-up` (a quick gate
+on the current change), this looks at the whole corpus and reports advisory findings the
+build tolerates, so the operator can decide what to promote or clean up.
+
+1. `npm run lint` — report every error (must be zero) and every warning. Rule 9 warnings
+   (bare `ADR NNNN` prose references that do not resolve) are expected on a legacy corpus;
+   list them so a genuine typo can be told from a deliberate cross-repo reference.
+
+2. `npm run index -- --check` — confirm `adr/INDEX.md` is current. If stale, regenerate.
+
+3. `npm test` — the invariant checks are themselves tested; the suite must pass.
+
+4. Cross-check the ledger against reality: for each `LEDGER.md` open item, confirm the ADR
+   it cites still exists (rule 8 covers this) and the deferral is genuinely still open. A
+   closed item that was never deleted is the dual-write failure this method exists to fix.
+
+5. Summarise: error count, warning count, index freshness, and any ledger items that look
+   resolved-but-undeleted. Recommend concrete next actions; do not fix silently.
+
+Repo root argument (default: current repo): $ARGUMENTS

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

@@ -0,0 +1,105 @@
+---
+description: Install the method kit (CLAUDE.md, LEDGER.md, linter, index, pre-commit hook) into a git repo
+argument-hint: [repo-root] [--check | --update]
+---
+
+Install this kit into a repo, or verify an existing install (ADR-0006). The script does
+the mechanical half; you do the two halves that need judgement — filling the scaffolded
+`CLAUDE.md`, and wiring verify scripts.
+
+Target repo: `$ARGUMENTS` (default: the current repo root).
+
+## 1. Look before writing
+
+Run the dry run first and read what it plans:
+
+```
+node scripts/init-method.mjs <target>
+```
+
+It writes nothing. `WOULD` lines are the plan, `KEEP` means a file already exists and
+will be left alone, `PROBLEM` means something needs a decision. Report the plan to the
+operator before applying it if anything is being scaffolded over a repo that already has
+conventions of its own.
+
+If the target is not a git repository the run refuses. Offer `git init`; do not work
+around it — the hook has nowhere to live.
+
+## 2. Apply
+
+```
+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**.
+
+The commands are vendored under softer rules than the machinery (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.
+
+## 3. If the repo already has a hook framework
+
+A target with a `.pre-commit-config.yaml` gets the doc checks **composed into it** as a
+`repo: local` block rather than a symlink (ADR-0008) — the framework owns
+`.git/hooks/pre-commit`, and a symlink there is silently erased by the next
+`pre-commit install`. The append is idempotent and additive; the existing config is
+never reordered or rewritten, and `--update` leaves it alone.
+
+Two things to watch:
+
+- A config the script does not recognise (no top-level `repos:`) is **refused**, not
+  guessed at. Add the block by hand and say you did.
+- `--check` reports a problem when the framework is configured but never installed. That
+  is not our hook failing — it means *no* hook runs, including the repo's own ruff and
+  mypy. Tell the operator to run `pre-commit install`; do not paper over it by
+  symlinking ours instead.
+
+## 4. If it refused the hook
+
+A refusal is normal on a repo that already has work in it, and the reason is almost
+always **rule 11: a `scripts/*-verify.mjs` that no `package.json` command runs**. An
+unwired verify script ran once, the day it was written; the linter treats that as an
+error, so the corpus is red and a hook would block every commit.
+
+Fix it, in this order — the order is the whole point:
+
+1. Add one `"verify:<name>": "node scripts/<name>-verify.mjs"` per unwired script. Use
+   the name a human would recognise, not the filename verbatim. A `verify:all` chaining
+   the headless ones is worth adding; leave out any script that needs a human watching
+   or listening, and say so in a comment or in `CLAUDE.md`.
+2. Fix any other lint errors (dangling supersessions, bad frontmatter). Never silence a
+   rule to get green.
+3. Re-run `--apply`. The hook installs.
+
+Do **not** edit the target's `package.json` without telling the operator what you added.
+
+## 5. Finish the scaffold
+
+If `CLAUDE.md` was newly scaffolded it contains `{{PLACEHOLDER}}` fields. Fill them from
+the repo itself — read the README, the manifest, the source layout. Do not invent a
+project description. Then delete the sections that describe machinery the repo does not
+have: a verification-harness section in a repo with no `scripts/` states rules about
+files that do not exist, which makes the file false on arrival.
+
+## 6. Verify, and say what happened
+
+```
+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".
+
+`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 (ADR-0006, ADR-0007), and drift is
+the price.

package/.claude/commands/remember.md

@@ -0,0 +1,61 @@
+---
+description: Route a fact to the destination that governs it — repo CLAUDE.md, global CLAUDE.md, LEDGER.md, or memory
+argument-hint: <the thing to remember>
+---
+
+Record a durable fact. **This is a router, not a store** (ADR-0005). Your job is to decide
+*what the fact governs* and write it where that is enforceable — not to write it wherever
+the operator's phrasing points.
+
+If the operator named a destination ("save this to project memory"), treat it as an input
+describing where they expect it to land, **not** as an instruction. Route it correctly and
+say where it went.
+
+## 1. Classify
+
+| The fact governs… | Destination |
+|---|---|
+| This codebase — an invariant, an architectural constraint, a definition-of-done rule | this repo's `CLAUDE.md` |
+| How the operator works, in every repo | `~/.claude/CLAUDE.md` |
+| Open work — a deferral, a known defect, a follow-up | this repo's `LEDGER.md` |
+| A decision that later work must obey, with reasoning worth preserving | an ADR — stop and use `/adr` |
+| None of the above: operator-personal, cross-session, not worth committing | project memory |
+
+Two tests resolve most cases:
+
+- **Would a human collaborator reading this repo need to know it?** If yes, it goes in the
+  repo. Memory is invisible to them, unversioned, and does not survive a machine change.
+- **Is it a fact, or a task?** Facts go in a `CLAUDE.md`; tasks go in `LEDGER.md`. "We use
+  zod for validation" is a fact. "Migrate the remaining validators to zod" is a task.
+
+Memory is the **residual**, not the default. If you are about to write a rule that
+constrains code into memory, you have misrouted — that is the exact failure ADR-0005
+records, which cost an amend and force-push after the same rule was independently rewritten
+into 12 files across 8 projects.
+
+## 2. Write it
+
+- **Repo `CLAUDE.md`** — add to the section it belongs to. If it is a standing invariant,
+  add a row to the §5 invariants table citing the ADR that created it. If this repo has no
+  `CLAUDE.md`, scaffold one from `templates/CLAUDE.md` first; without it there is no
+  destination and the fact will silently fall back to memory (ADR-0005).
+- **Global `CLAUDE.md`** — edit your global `~/.claude/CLAUDE.md`, wherever your global
+  conventions live. Keep it dense: it loads into every session in every repo.
+- **`LEDGER.md`** — one line, `- [type] description (ADR-NNNN)`, citing the source ADR if
+  one exists.
+- **Memory** — one fact per file, with the frontmatter schema, plus a one-line pointer in
+  `MEMORY.md`.
+
+Before writing anywhere, check whether an existing entry already covers it and update that
+instead of adding a duplicate.
+
+## 3. Report
+
+State which destination it went to and why in one line — e.g. *"→ repo `CLAUDE.md` §3: it
+constrains code, so it needs to be greppable and reviewable."*
+
+This step is not optional. Routing cannot be linted (ADR-0005), so saying the decision out
+loud is the only thing that makes a misroute correctable in the moment rather than
+discoverable in a survey weeks later.
+
+Fact to record: $ARGUMENTS

package/.claude/commands/slice.md

@@ -0,0 +1,72 @@
+---
+description: Scaffold a new slice (one feature work-unit) with frontmatter pre-filled
+argument-hint: <short title of the feature>
+---
+
+Create a new **slice**: one feature work-unit, written *before* implementation and frozen
+at merge (ADR-0001). A slice is a current-state claim while open, so it goes stale by
+nature — freezing it to past tense at merge ("this is what shipped") converts it into a
+historical claim that never goes stale. If you are recording a durable decision rather
+than a unit of feature work, use `/adr` instead.
+
+Steps:
+
+1. Compute the next free id: highest ordinal in `adr/` (and `slices/` if present) plus
+   one, zero-padded to four digits.
+2. Scan `LEDGER.md` for open items this slice touches — a `[feature]` it delivers, a
+   `[bug]` it fixes, a `[deferred]` it finally picks up. Fold each relevant one into
+   `## Goal` so the slice knows the history it is answering, and **delete the line from the
+   ledger for any item this slice closes** — closing an item means deleting its line (see
+   the ledger's own header). If nothing relates, note nothing; this is a read, not a
+   requirement to invent links.
+3. Write the file opening with the ADR-0002 frontmatter block, `type: slice`:
+
+   ```
+   ---
+   id: 'NNNN'
+   title: "<title>"
+   type: slice
+   status: accepted
+   date: <today, YYYY-MM-DD>
+   supersedes: []
+   superseded_by: []
+   ---
+   ```
+
+4. Body sections, written before you code:
+   - `## Goal` — what ships and why, in one paragraph. Fold in any ledger items from step 2.
+   - `## Definition of Done` — **required.** The acceptance criteria as one or more
+     **Given / When / Then** scenarios, written before you code (ADR-0011). This is the
+     grammar, not a toolchain: plain markdown steps, no Cucumber. State the observable
+     outcome — a criterion with no observable "Then" is not done-able. Each scenario's
+     proof is named below in `## Verification`; a scenario with no proof is an unmet
+     criterion, not a finished one. Example:
+
+     ```
+     ## Definition of Done
+
+     - **Given** a fresh world
+     - **When** the player places the block
+     - **Then** it renders with its mesher shape, a hotbar icon, and a hand-held model
+     ```
+
+   - `## Design` — the approach; cite measured numbers from a probe where a design
+     question has a measurable answer, not estimates. State **what existing code was
+     considered**: what you searched for, what you reused, and what you deliberately did
+     *not* reuse and why (ADR-0013). This is not a mandate to reuse — the wrong abstraction
+     costs more than a duplication (global §3, rule of three); it makes the
+     reuse-or-duplicate choice *visible*, so an un-considered duplication is caught at
+     review. It is checked by human read-through, not the linter: whether you truly searched
+     is the coverage question no machine decides.
+   - `## Verification` — **required.** Name the unit tests, and if the behaviour cannot be
+     asserted in a unit test (rendering, worldgen, physics, timing), name the
+     `scripts/<slice>-verify.mjs` script and confirm it is wired into `package.json`
+     (ADR-0004). A slice with no `## Verification` section is incomplete. The linter
+     enforces both required sections (R12/R13): a `type: slice` must carry `## Verification`
+     and a `## Definition of Done` holding at least one full Given/When/Then triad.
+   - `## As built` — filled in at merge: what actually shipped, in past tense, confirming
+     each Definition-of-Done scenario was met or recording the deviation. This is the
+     freeze step.
+5. Regenerate the index and run the linter; both green before done.
+
+Title argument: $ARGUMENTS

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

@@ -0,0 +1,30 @@
+---
+description: End-of-task gate — run the checks and ask the four questions that get forgotten
+---
+
+Run before finishing a task. The point is to make mechanical what memory keeps dropping:
+the linter catches structural drift, and four questions catch the follow-ups that never
+get recorded until they have gone stale (ADR-0003).
+
+1. Run the linter and the index check:
+   - `npm run lint` — must be green (rule 9 warnings are acceptable on a legacy corpus).
+   - `npm run index` — regenerate `adr/INDEX.md` and stage it if it changed. A stale
+     generated index is drift by another name.
+   - `npm test` — the test suite must pass; docs changes must not disturb code.
+
+2. Then answer these four out loud, and act on each:
+   - **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,
+     while the reasoning is fresh. An unrecorded decision is re-litigated later from
+     nobody's memory.
+   - **Did this defer something** — a follow-up, a known-but-unfixed bug, a TODO? If so,
+     add one line to `LEDGER.md` citing the relevant ADR. The ledger is the only place
+     deferrals live; a TODO in code or a note in your head is not tracked.
+   - **Did this write code a later operator would plausibly try to "fix"?** — a deliberate
+     deviation, a non-obvious constraint, a hard-won exception. If so, cite the governing
+     ADR at that site in a comment (ADR-0012), so the choice announces it is on purpose
+     where the edit happens, not only in the §4 table nobody thinks to open.
+
+3. Report what you found and did for each of the four, so the operator can confirm
+   nothing was silently skipped.

package/.claude/hooks/pre-commit

@@ -0,0 +1,29 @@
+#!/bin/sh
+# Stele pre-commit hook — the load-bearing enforcement decision (ADR-0003).
+#
+# A linter nobody runs is another convention resting on memory, which is the failure this
+# project exists to fix. This hook makes the checks mechanical: no green corpus, no commit.
+# CI (.github/workflows/docs.yml) is the backstop for clones without the hook installed.
+#
+# Install: ln -sf ../../.claude/hooks/pre-commit .git/hooks/pre-commit
+# (/init-method does this; see ADR-0003. Do NOT install on a linter-red corpus — fix the
+#  reds first, or every commit is blocked. See LEDGER.)
+#
+# Bypass in a genuine emergency with `git commit --no-verify`; CI still catches it.
+
+set -e
+
+root=$(git rev-parse --show-toplevel)
+cd "$root"
+
+if ! command -v node >/dev/null 2>&1; then
+  echo "pre-commit: node not found on PATH — cannot run doc checks." >&2
+  exit 1
+fi
+
+# 1. Invariants must hold (rules 1–8 block; rule 9 warns). Zero-dependency, so no install.
+node scripts/lint-docs.mjs .
+
+# 2. The generated index must match the corpus. A stale INDEX.md is drift by another name;
+#    regenerate and stage it rather than letting it fall behind.
+node scripts/build-index.mjs --check .

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Isonimus
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,206 @@
+# Stele
+
+A zero-dependency workflow that keeps a codebase's **decisions, work, and definition of
+done** honest — enforced by a git hook and CI, not by anyone remembering to.
+
+It is meant to be **vendored into any git repo**: one command drops in a decision-record
+tree, a worklist, a linter, and a pre-commit hook, and from then on the repo refuses commits
+that let its own records rot.
+
+> This README is a **live doc** — the *how-to* and the vision. The *why* behind every rule
+> lives in [`adr/`](adr/), and each section below links to the decision that governs it.
+> Where the two ever disagree, the ADR wins; tell us so we can fix the README.
+
+---
+
+## The problem
+
+Conventions kept in a model's memory, a wiki, or someone's head hold until the first busy
+afternoon. They are invisible in review, unversioned, and gone on a change of machine. Three
+failures recur:
+
+- **Decisions drift.** A choice recorded as prose gets quietly edited until the record no
+  longer says what was actually decided, and the reasoning that made it right is lost.
+- **Work-in-progress lies.** A doc written in the present tense ("the system does X") is
+  true the day it is written and slowly false forever after.
+- **"Done" is assumed, not defined.** A feature with three required outputs and no written
+  acceptance criteria ships with two of them, because the intent was never in a form that
+  made the omission visible.
+
+Stele's answer is a single principle: **if a convention matters, it is executable;
+if it genuinely cannot be checked, that limit is stated out loud rather than trusted.**
+
+---
+
+## The mental model — four kinds of document
+
+Every document is exactly one kind. There is no fifth. ([ADR-0010](adr/0010-live-docs-are-the-fourth-kind.md), superseding [ADR-0001](adr/0001-immutable-or-generated.md))
+
+| 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. |
+| **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. |
+
+- An **ADR** records a decision later work must obey: *"on date X we chose Y because Z"* — a
+  historical claim, true forever.
+- A **slice** is one feature work-unit, written *before* implementation and **frozen to past
+  tense at merge** ("this is what shipped") — which converts a going-stale claim into a
+  never-stale one.
+
+**Single writer, one direction.** An ADR records a deferral once, as a fact. `LEDGER.md`
+cites the ADR. You never reach back into an ADR to close a ledger item — **closing an item
+means deleting its line from the ledger.** Changing your mind means a **new** ADR that
+supersedes the old one and says *why the old reasoning was wrong* — that record is the most
+valuable thing this workflow produces, and an in-place edit destroys it.
+
+---
+
+## Quickstart
+
+Install into a git repo — dry-run first, always ([ADR-0006](adr/0006-init-method-bootstrap.md)).
+Stele is delivered by `npx`, then **vendored** into the repo; it is never a runtime
+dependency ([ADR-0015](adr/0015-distribution-by-npx-delivered-vendoring.md)):
+
+```
+npx @isonimus/stele <repo-root>            # dry run: shows what it would do
+npx @isonimus/stele <repo-root> --apply    # install the kit
+npx @isonimus/stele <repo-root> --check    # verify an install is intact
+npx @isonimus/stele <repo-root> --update   # re-sync vendored machinery
+```
+
+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 —
+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)).
+
+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
+
+Run in Claude Code as `/<name>`.
+
+| Command | What it does |
+|---|---|
+| `/adr <title>` | Scaffold a new Architecture Decision Record, frontmatter pre-filled. |
+| `/slice <title>` | Scaffold a new slice (one feature work-unit). |
+| `/audit` | Full-corpus health check — run every invariant, surface warnings and drift. |
+| `/wrap-up` | End-of-task gate — run the checks and ask the four questions that get forgotten. |
+| `/remember <fact>` | Route a fact to the destination that governs it (see [Where things live](#where-things-live)). |
+| `/init-method` | Install the kit into a git repo. |
+
+Under the hood, the npm scripts are the enforcement surface:
+
+```
+npm run lint     # node scripts/lint-docs.mjs .   — the invariant checker
+npm run index    # regenerate adr/INDEX.md
+npm test         # the regression suite (every rule has a fixture)
+```
+
+---
+
+## Scenarios
+
+**Record a decision.** `/adr "Use a hand-rolled frontmatter parser"`. Fill Context /
+Decision / Consequences, cite measured numbers where a question has a measurable answer, and
+commit. Never edit it afterward.
+
+**A decision changed.** Do *not* edit the old ADR. `/adr` a new one, set `supersedes: [NNNN]`
+on it and `superseded_by` on the old, and spend a paragraph on *why the old reasoning was
+wrong*. The linter enforces that the supersession is bidirectional and that a superseded ADR
+no longer reads as "accepted" (rules R4–R7).
+
+**Start a feature.** `/slice "CSV export"`. Before you write code, fill:
+- `## Goal` — what ships and why;
+- `## Definition of Done` — the acceptance criteria as **Given / When / Then** scenarios
+  ([ADR-0011](adr/0011-slices-carry-a-definition-of-done.md));
+- `## Design` — the approach, citing probe numbers not estimates;
+- `## Verification` — the unit tests, or a `scripts/<slice>-verify.mjs` for behaviour a unit
+  test can't assert.
+
+At merge, freeze `## As built` in past tense, confirming each Definition-of-Done scenario was
+met. The linter requires both `## Verification` (R12) and a `## Definition of Done` holding a
+real Given/When/Then triad (R13).
+
+**Behaviour a unit test can't assert** (rendering, worldgen, physics, timing). Write
+`scripts/<slice>-verify.mjs` that drives the real system headlessly, **fails on any console
+error**, and writes artifacts (screenshots, numbers) for human review. Name it in
+`## Verification` and **wire it into `package.json`** — an unwired verify script runs once and
+is dead thereafter, so the linter fails if any is unwired (R11). ([ADR-0004](adr/0004-verification-harness-and-in-repo-invariants.md))
+
+**Adopt into an existing repo.** `/init-method <repo> --apply`. Migrate the corpus and hand-
+fix any red supersession pairs *before* the hook goes on. Legacy documents that predate a
+rule warn rather than error, so adoption is never blocked by history.
+
+**A rule you must break, with reason.** Don't take a silent exception. Record the
+justification as a new or superseding ADR — in this workflow, a justified violation *is* a
+decision, and decisions are immutable records.
+
+---
+
+## Enforcement, in three honest layers
+
+The linter ([`scripts/lint-docs.mjs`](scripts/lint-docs.mjs)) runs from the pre-commit hook
+and in CI. Its rules are graded by what can actually be mechanised
+([ADR-0003](adr/0003-enforcement-by-hook.md)):
+
+1. **Machine-checked (error — blocks the commit).** Frontmatter shape and completeness
+   (R1), id/filename agreement and uniqueness (R2), closed status/type vocabulary (R3), the
+   supersession graph (R4–R7), ledger citations resolve (R8), the linter isn't pointed at an
+   empty corpus (R10), verify scripts are wired (R11), and slices carry their required
+   sections (R12/R13).
+2. **Legacy-aware (warning, not error).** Bare prose cross-references (R9) and slice-section
+   rules on documents that predate them warn instead of failing, so a repo's history never
+   blocks its next commit — while *new* work is held to the full bar.
+3. **Coverage — unenforceable, and said so.** Whether a verify script tests something *true*,
+   whether a §4 invariant actually holds, whether the acceptance scenarios are *complete* —
+   none can be decided by reading one version of a file. These are surfaced by `/wrap-up` for
+   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.
+
+The dividing line is the whole point: **a rule is enforced, legacy-tolerated, or explicitly
+declared uncheckable — never silently trusted.**
+
+---
+
+## Where things live
+
+`/remember` routes a fact to whatever *governs* it, never to wherever the conversation
+happened ([ADR-0005](adr/0005-write-routing-and-the-bounds-of-memory.md)):
+
+| The fact governs… | Goes in |
+|---|---|
+| A codebase — invariants, architecture, definition-of-done | that repo's `CLAUDE.md` |
+| How you work, everywhere | global `~/.claude/CLAUDE.md` |
+| Open work — deferrals, defects, follow-ups | that repo's `LEDGER.md` |
+| Operator-personal, cross-session facts (e.g. git identity) | assistant memory |
+
+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.
+
+---
+
+## Design principles
+
+- **Zero dependencies.** The whole kit is Node's standard library. It drops into any repo
+  regardless of package manager, and the frontmatter schema is small enough to parse by hand.
+- **Enforce with a hook, remember nothing.** A convention that matters becomes a rule; one
+  that can't be checked is stated as such, out loud.
+- **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.
+
+For the reasoning behind any of these, read the ADR it links to. That is what the ADRs are
+for.

package/package.json

@@ -0,0 +1,48 @@
+{
+  "name": "@isonimus/stele",
+  "version": "0.1.2",
+  "type": "module",
+  "description": "A linted, installable ADR workflow for git projects using Claude as an assistant",
+  "keywords": [
+    "adr",
+    "architecture-decision-record",
+    "claude",
+    "pre-commit",
+    "documentation",
+    "workflow",
+    "linter"
+  ],
+  "author": "Iker Laforga",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "git+ssh://git@github.com/Isonimus/stele.git"
+  },
+  "homepage": "https://github.com/Isonimus/stele#readme",
+  "bugs": "https://github.com/Isonimus/stele/issues",
+  "engines": {
+    "node": ">=20"
+  },
+  "bin": {
+    "stele": "scripts/init-method.mjs"
+  },
+  "files": [
+    "scripts/",
+    "templates/",
+    ".claude/commands/",
+    ".claude/hooks/",
+    "README.md",
+    "LICENSE"
+  ],
+  "publishConfig": {
+    "access": "public"
+  },
+  "scripts": {
+    "test": "node --test test/*.test.mjs",
+    "lint": "node scripts/lint-docs.mjs .",
+    "index": "node scripts/build-index.mjs .",
+    "scan": "node scripts/scan-legacy.mjs",
+    "migrate": "node scripts/migrate-adrs.mjs",
+    "init": "node scripts/init-method.mjs"
+  }
+}