init

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>

.claude/commands/adr.md

@@ -0,0 +1,21 @@
+---
+description: Record an architectural decision in six lines
+---
+
+Append an ADR to `docs/decisions.md` using the exact format at the top of that file.
+
+First, before writing anything: find the doc that owns this topic via the ownership table in
+`docs/README.md` and read it. If it already carries the rule, do not write an ADR — amend that doc
+and say that is what you did. An ADR that restates an existing doc is a duplicate, not a decision.
+
+Rules:
+- Next sequential number. Never renumber, never rewrite an existing entry.
+- To reverse a decision, add a new ADR and mark the old one `superseded by ADR-NNNN`.
+- Six lines. If the reasoning needs more, the decision is not yet made.
+- `Revisit if:` must name a specific observable event, not "if requirements change".
+- If the decision adds a dependency, update `scripts/allowed-deps.txt` in the same change.
+- If the decision raises a budget, update `scripts/budgets.env` in the same change and state
+  the old and new values in the ADR.
+
+If the argument for `$ARGUMENTS` is thin — no forcing reason, or no consequence you can name —
+say so and ask one question rather than writing a hollow entry.

.claude/commands/audit.md

@@ -0,0 +1,26 @@
+---
+description: Hunt speculative complexity and propose deletions
+---
+
+Read the code and find what has not earned its place. Propose removals; change nothing yet.
+
+Look for:
+- Interfaces with one implementation. Type parameters with one instantiation.
+- Function parameters, struct fields, config knobs, or frontmatter keys with no real caller
+  or no real author using them.
+- Two implementations of the same idea (parsing, path joining, slugging, date handling).
+- Abstractions built ahead of their counter: a pipeline at two transforms, a resolver at one
+  route, an extension registry before its counter is due.
+- Files and functions over the advisory sizes in `scripts/budgets.env`; nesting past 4.
+- Error handling that logs and returns, or wraps without adding information.
+- Tests that assert on private helpers, or that need a mock to exist.
+- Dead code, commented-out code, `TODO`s older than the feature that introduced them.
+- Comments that narrate control flow.
+- Anything in `docs/` describing code that no longer exists — excluding `ideas/` and
+  `reference/`, which are never audited against the code and must not be opened here.
+
+Report as a table: item, location, why it has not earned its place, LOC recovered if deleted,
+and risk of deleting. Order by LOC recovered, descending. Recommend a top three.
+
+Then stop. Deletions happen as their own small changes, with a go-ahead each, and each one runs
+`./scripts/verify.sh`.

.claude/commands/invariants.md

@@ -0,0 +1,33 @@
+---
+description: Check the architecture invariants against the code, not against the docs
+---
+
+`verify.sh` checks what a grep can check. This pass checks the nine invariants in
+`docs/architecture.md`, which need reading the code. Run at arc boundaries, before a freeze, and
+before the first deploy.
+
+For each invariant, answer **held / violated / not yet applicable**, with a file and line when
+violated. Do not fix anything in this pass.
+
+1. **Open page object** — are all fields optional in practice? Find any place a missing field causes
+   a nil deref, an error return, or a template failure that reaches the response.
+2. **Trusted / untrusted modes** — trace every path by which non-repo bytes could reach shortcode or
+   template evaluation. This is the one invariant where "probably fine" is not an answer: name the
+   check that stops it, or report it violated.
+3. **Identity is not language** — is the bundle key free of language? Any place a language suffix
+   leaks into a cache key, a URL, or a dependency key is a violation.
+4. **Request-time render behind a cache** — does export walk the same code path as the server, or has
+   a second path appeared?
+5. **Permalinks permanent** — does any code derive a URL by a rule other than the one in
+   `content-model.md`? Does every rename path emit an alias plus a permanent redirect?
+6. **Interactions off the content graph** — can an interaction invalidate more than its own fragment?
+7. **Every feature is a leaf** — is each `internal/ext/*` package deletable without touching the
+   core? Try naming the diff that removes one.
+8. **Degrades with external services off** — for each external client, is there a path that still
+   serves correctly, slowly, when it is unreachable?
+9. **Core stops growing after Arc 2** — compare the `core` figure `verify.sh` prints against the one
+   recorded at the freeze in `state.md`. Post-freeze growth is the finding, not the number.
+
+Then: report held/violated per invariant, and for anything violated, whether it is a bug to fix now
+or a latent item with a trigger. A violated invariant is a stop condition (`CLAUDE.md §6`) — say so
+plainly rather than documenting it as the new normal.

.claude/commands/leaf.md

@@ -0,0 +1,24 @@
+---
+description: Decide whether a catalog item is a leaf worth building, or a trunk that waits
+---
+
+Evaluate `$ARGUMENTS` against the leaf/trunk test in `docs/exploration.md`.
+
+Research it only as far as needed to answer accurately — what it actually requires, not what its
+homepage claims. If it is a protocol or spec, state which parts are mandatory versus optional.
+
+Answer these, briefly:
+
+1. **Leaf or trunk?** Per `architecture.md` invariant 7.
+2. **Reduces to:** which primitive, concretely, with the shape of the implementation in two lines.
+3. **Prerequisites:** which arc or primitive must exist first. Is that gate open today?
+4. **Cost:** estimated LOC, new dependencies, new disk fields, ongoing maintenance burden,
+   and anything it makes permanent (URLs, identifiers, published data).
+5. **Sovereignty test:** apply the one in `roadmap.md` Governors.
+6. **Fit:** does it serve fiction, webcomics, essays, Bengali-language work, or the
+   low-bandwidth ethos — or is it interesting for its own sake? Interesting-for-its-own-sake is
+   a legitimate answer for a cheap leaf and a disqualifying one for anything expensive.
+7. **Verdict:** build now / build when gate X opens / trunk, needs an ADR / no.
+
+Write the verdict as one row in the Verdicts table in `docs/exploration.md`. Do not implement
+anything in this pass.

.claude/commands/refresh-docs.md

@@ -0,0 +1,33 @@
+---
+description: Reconcile the docs against the actual code and report drift
+---
+
+Reconcile documentation with reality. The code is the truth; the docs are the suspects.
+
+1. Inventory the actual Go files, their line counts, and the non-stdlib dependencies in `go.mod`.
+2. Compare against `docs/state.md`: inventory rows, counters, latent items, `verified against`.
+   Recount the counters **from the code** — number of render transforms, routing cases, views,
+   output formats, extensions — rather than trusting the recorded numbers.
+3. Check `docs/architecture.md` STATUS lines: has a primitive become real, or is one described
+   as live when it is not built?
+4. Check `docs/content-model.md` `[spec]` versus `[live]` markers against what the parser
+   actually accepts. Frontmatter fields the code reads but the doc omits are drift; fields the
+   doc promises but the code ignores are worse drift.
+5. Check `scripts/allowed-deps.txt` against `go.mod`.
+6. Look for facts stated in two docs. Delete one, link to the other.
+7. Run `./scripts/verify.sh --list` and check every doc sentence claiming a gate against it. A doc that
+   says "`verify.sh` fails on X" where no such gate exists is the most damaging drift there is: it reads
+   as enforcement and is decoration.
+8. Check the reverse too — a gate in the list that no doc explains. Either document it or delete it.
+9. Follow every cross-doc citation of a *section* ("see `roadmap.md` Governors", "`CLAUDE.md` §6") and
+   confirm the heading exists. Whole sections have gone missing while another doc still cited them.
+
+Scope: the docs listed above and nothing else. **Do not open `ideas/` or `reference/`** —
+they describe proposals and facts, never the state of the code, so they cannot be drifted against
+it. `verify.sh` already checks their indexes mechanically.
+
+Then:
+- Fix the docs. Doc-only diff; no code changes in this pass, no matter what you find.
+- Anything in the code that contradicts an ADR: report it, do not silently document it as
+  correct. A drifted invariant is a bug, not a new decision.
+- Report drift found, drift fixed, and anything that needs a human decision.

.claude/commands/verify.md

@@ -0,0 +1,18 @@
+---
+description: Run the objective gates and report evidence, not opinions
+---
+
+Run `./scripts/verify.sh` and report the result.
+
+Then, if the working tree has uncommitted changes, produce feature-specific evidence for what
+changed: start the server and `curl` the affected URL, run the relevant test by name, or diff
+the golden file. Show real output.
+
+If anything fails:
+1. Report the failure verbatim before interpreting it.
+2. Diagnose in one paragraph.
+3. Propose the smallest fix. Do not apply it without a go-ahead unless it is a formatting fix.
+
+If a budget in `scripts/budgets.env` is exceeded, do not raise the budget. Report which budget,
+by how much, and which files are responsible. Offer the two options: shrink the code, or an ADR
+raising the ceiling deliberately.