docs: align README, CHANGELOG and CONTRIBUTING with actual state

[skateddu]

What

A coherence pass over the documentation: each file checked against the filesystem, against the CI definition, and against its own stated scope — the README describing current state, the CHANGELOG recording change.

Already coherent, for the record: the agent (13), command (10), rule (10), skill (22) and hook (6) tables match the files on disk exactly — no orphans, no omissions.

A. Claims that no longer matched the repo

Where	Was	Is
Optional dependencies	jq required by "enforce-uv, protect-main, auto-lint"	All six hooks parse their payload with it — a partial install silently breaks session-start, guard-secrets and verify
Project tree	ci.yml = "Lint + configuration validation"	Also shellcheck and the hook tests
CI section intro	"lints with ruff and validates configuration"	The table below it already listed pytest
CI ruff row	scope .claude/statusline.py and scripts/	pyproject.toml also includes tests/**/*.py

CONTRIBUTING.md was the one that could actually cost someone a red build. Its verification command ran the linter alone, while CI runs four checks — a contributor could pass locally and fail in CI. Both the Submitting Changes step and the Development Setup block now run the same four, with a note that CI also runs shellcheck and that the hook tests need bash and jq (they skip without them, rather than fail).

Deliberately not changed: CLAUDE.md's verification command still omits scripts/validate_config.py. CLAUDE.md is copied into downstream projects where that script does not exist, so its generic command is correct as-is.

B. README passages that narrated change instead of state

Five places read as release notes rather than documentation:

• "Fullscreen rendering … is now the default"
• "Since Claude Code v2.1.200 … stays canonical and needs no migration"
• "subagents now run in the background"
• "every past bug in them has been a logic error — a condition that silently disabled a hook, a regex boundary that let rm -rf / through" — that is this repo's history (fix(hooks): correct PreToolUse if-condition syntax and add explicit settings defaults #10, fix(hooks): fix rm -rf boundary matching in protect-main.sh #11)
• "That wiring has broken before"

Rewritten to state the current situation. The rationale for the hook tests survives intact without the history: a script can be syntactically clean, correctly wired, and still reach the wrong decision — shellcheck sees none of that.

C. CHANGELOG

• Internal inconsistency fixed: the CI entry described a workflow of linting + shellcheck + validator, but the test step was added to that same workflow later in this unreleased cycle. Unreleased entries should describe where the cycle landed.
• Section order: was Added, Removed, Fixed, Changed — matching neither Keep a Changelog nor this file's own released sections. Now Added, Changed, Removed, Fixed.
• Bullet spacing normalised to match the released sections (contiguous, not blank-separated).
• State duplication removed. Several entries restated README content rather than recording the change: the sandbox entry summarised the whole section including its footguns, the tuning-variables entry repeated semantics already in the README table, the /code-review entry described what the built-in command does. A changelog is frozen; the README evolves — that prose was guaranteed to drift into being wrong with nobody noticing. Each now records what changed and why, and points at the README for what it is. Net −2,261 characters with no factual loss.
• One genuinely missing entry added: the linter's include/known-first-party extension, which happened in ci: add lint and configuration validation workflow #16 and test: cover hook decisions with 65 behavioural tests #17 but was never recorded.

Verification

All four checks and the 65 hook tests pass. The README's JSON block still parses and its internal anchor still resolves.

Side note found while opening this PR

The enforce-uv hook denied the gh pr create call that carried this description, because the text contained a verification command after && and the hook's pattern reads the whole command string. A false positive on quoted text rather than an executed command — worth a look separately.

🤖 Generated with Claude Code