📝 Make the rule/rationale split explicit

AGENTS.md and CONTRIBUTING.md now state that a decision, its rejected
alternatives and its known issues belong in development/<category>.md, that the
actionable rule stays in CONTRIBUTING.md, and that both change in the same
commit. development/README.md names library.md in the category list and spells
out that the sync runs in both directions.

AGENTS.md

@@ -12,6 +12,7 @@ first-action facts. Do not restate evolving prose here — it will drift.
 - **Optional code intelligence:** this repo installs `@spences10/pi-lsp` (pinned in `.pi/settings.json`) as a project-local pi extension. It talks to the repo's own TypeScript 7 via `tsc --lsp --stdio` and exposes **read-only** tools — `lsp_hover`, `lsp_definition`, `lsp_references`, `lsp_find_symbol`, `lsp_document_symbols`, `lsp_diagnostics(_many)`. Prefer `lsp_references` over `grep -w` for widely-colliding identifiers (`matches`, `type`, …); use `lsp_hover` to read inferred types on generic-heavy code. It has no rename / code-action / apply-edit surface — the write side is pi's `edit` tool + `check:tsc`. Treat empty LSP output as _inconclusive_, not success: **`npm run test` / `npm run verify` remain the sole authoritative gate** (see the next bullet). The server keeps running across that gate with a ~5 min idle timeout and registers no file watchers, so if you change `tsconfig.json` / `package.json` mid-session its diagnostics can be stale — when LSP output disagrees with `check:tsc`, trust `check:tsc` and restart pi (or wait out the idle timeout) before concluding the LSP is wrong.
 - **Definition of done — run this before you call the work finished:** `npm run verify`. If all green, commit. If red, look at the output, fix the root cause, and re-run.
 - **On commit:** write a good message (see [CONTRIBUTING.md § Commit messages](./CONTRIBUTING.md#commit-messages)). Lefthook's pre-commit hook already runs the fast, offline, staged-file checks — don't run them by hand. If the hook fails on style, `npm run fix`, restage, recommit.
+- **Document decisions where the next maintainer will look:** rationale, rejected alternatives and known issues go in `development/<category>.md` (see [development/README.md](./development/README.md)); the actionable rule stays in [CONTRIBUTING.md](./CONTRIBUTING.md) and links to it. Change both in the same commit.
 - **`npm run maintain` is NOT part of the feature loop.** Its scans are advisory, never a gate; run them only on an explicit maintenance / update-deps branch.
 
     ```sh

CONTRIBUTING.md

@@ -125,6 +125,11 @@ reaches for by default:
 - **There is no local `npm run publish`, and `publish:publint` / `publish:attw`
   don't go in `check`.** (why:
   [development/publishing.md](./development/publishing.md#ci-only-publishing))
+- **A decision or its rationale belongs in `development/`, not here.** This file
+  holds the actionable rule; `development/<category>.md` holds why, the rejected
+  alternatives and the known issues. When you change a rule, update its category
+  file in the same commit and cross-link the two. (why:
+  [development/README.md](./development/README.md))
 
 ## Branching model
 

development/README.md

@@ -76,10 +76,11 @@ of downloading per job.
 
 ## Adding to these docs
 
-1. Pick the category file for the area you are changing: `workflow`, `tooling`,
-   `testing`, `ci`, or `publishing`.
+1. Pick the category file for the area you are changing: `library`, `workflow`,
+   `tooling`, `testing`, `ci`, or `publishing`.
 2. Add or update a decision block. Keep the existing text unless the decision
    actually changed.
 3. If the change alters an actionable rule, update
    [CONTRIBUTING.md](../CONTRIBUTING.md) in the same commit and cross-link the
-   two.
+   two. The reverse also holds: never change a rule in CONTRIBUTING.md without
+   updating its rationale here.