[mzored]

Why

docs/ had grown to 205 KB, about forty times the shipped kernel. Every release added a narrative paragraph to evidence.md, a version log to the decisions.md cells, and a reading-notes section to prior-art.md. One release story was told in four places, so every release meant four places to update.

What changes

The docs now describe only the current state. Per-release motivation goes in CHANGELOG.md, and git history keeps the earlier text. This follows Diátaxis (reference describes what is, not its history), Keep a Changelog (one curated history file), and lightweight ADR practice (a short record with a status, amended in place).

File	Before	After
docs/decisions.md	46.3 KB	31.5 KB, one short section per live decision: decision, why, status, reopens when
docs/evidence.md	44.3 KB	24.1 KB: labels, per-claim rules, observed table, host facts, open questions
docs/prior-art.md	51.1 KB	11.8 KB: borrowed and refused ideas, without per-release reading notes
docs/guide.md + docs/faq.md	35.1 KB	14.1 KB: the FAQ merged in as a Questions section
docs/outcome-contract.md	14.4 KB	9.3 KB: duties stated once, linking the shipped files
docs/design.md, docs/README.md	14.4 KB	deleted: live content moved, docs index moved to the README
AGENTS.md	15.5 KB	14.5 KB: same rules, plainer prose, a repository map, and the new docs-maintenance rule

docs/ total: 205 KB → 91 KB. All rewritten files follow the unslop style: no em dashes, sentence-case headings, short active sentences.

The new rule in AGENTS.md: a release edits docs/decisions.md only when a decision, premise, or reopen condition changes, and docs/evidence.md only when a claim's status changes or a receipt lands. Neither file carries per-release narrative or a version log.

The links that pointed at deleted files or anchors in README.md, SECURITY.md, CHANGELOG.md, .github/CONTRIBUTING.md, evals/, and site/ were repointed. The archive links go to the pinned commits 2f72c7f and 72aef45.

plugins/skiphow/ is untouched, so there is no VERSION bump and no release.

Verification

• python scripts/check.py: local deterministic checks passed. git diff --check is clean.
• Every #anchor link into docs/ resolves; check.py ignores anchors, so this was checked separately.
• Isolated read-only Codex review over 11 rounds. It looked for any lost live decision, premise, reopen condition, open UNVERIFIED question, Observed or FAIL row, or AGENTS.md rule, and for any contradiction with the shipped package.
  • Rounds 1–10 found 13, 6, 2, 4, 4, 8, 5, 4, 5 and 9 dropped or wrong clauses. Each one was confirmed and fixed.
  • A clause-by-clause pass over every old decision row and evidence item then restored the rest.
  • Round 11 returned no qualifying findings.
  • One finding was refused: the old question about where the setup record goes, because the package no longer has a setup record.

🤖 Generated with Claude Code