docs: separate specification contracts from rationale

[atqamz]

Summary

• Reduce SPECS.md to caller-dependable contracts and account for every removed span.
• Move durable rationale into consistently formatted, dated records under docs/adr/ with discoverable Why: links.
• Retire shipped planning material and update references to the new contract and rationale split.
• Preserve the observed herdr pane get transcript in internal/faketool/FIDELITY.md, including the internal seen mechanism.

Verification

• Fresh no-mistakes review completed with zero findings on rebased head 2955f5f43f9d5d585ce1e893f7498a3c5b77e1b9.
• Targeted Nix tests passed, including the real herdr contract lifecycle and a live pane-get probe.
• Lint passed.
• GitHub CI passed on Ubuntu, macOS, Nix, and E2E jobs.
• All six commits are GPG signed and contain no Co-Authored-By trailers.

Sequencing

Issue #163 supersedes the eventual documentation structure and is intentionally sequenced after this migration lands.

Closes #159

[atqamz]

Correction to my own phase-one accounting, since the gate's pr step replaced the body carrying it

Phase one corrected the issue's premise: two thirds of SPECS.md is contract, so the cut ends near 1900 lines and not near 900. That stands. This corrects the accounting in turn, because the file landed at 2588 lines, not 1900, and the gap is the estimate's fault rather than the cut's.

What the estimate got wrong: it classified whole lines, and the rationale was not organized in whole lines. It was welded clause by clause into the same lines as the contract, so a line counted as contract routinely carried two rationale clauses inside it, and removing them shortens that line without deleting it. "26 percent of lines are ADR or retired, so the file drops by a third" is only valid if rationale occupies lines of its own. Here it did not.

Measured in words, the unit that survives reflow, the accounting was accurate. It projected ADR plus retired at 26 percent. The cut removed 27 percent of the words.

	lines	words
before	2831	38,880
after my cut	2579	28,365
net	-252 (-9%)	-10,515 (-27%)

Two sections make it unarguable:

Section	words	lines
## State management	5453 to 3347 (-39%)	163 to 162 (-1)
## CLI specification	21,462 to 15,879 (-26%)	1532 to 1444 (-88)

## State management lost 39 percent of its prose and exactly one line. Deleting rationale lines cannot produce that shape; only shortening lines does.

The added lines are rescued contract, not new contract. The 686 deleted lines carried 21,355 words, 31 words per line against the file's own average of 13.7, so what came out were the longest lines in the file, where contract and rationale were fused. The 434 added lines carry 10,840 words. Roughly half of what I deleted was contract that had to be rewritten to survive its rationale being removed, then set one sentence per line as this repo requires. Genuinely new content is countable: the Why: lines and the ten-line ## What this file is block. So the headline is still a cut, but the line count is not the measure of it and this PR should not be read against one.

What is left, named rather than swept up. 29 because clauses remain in 28,365 words, about one per thousand, each attaching a one-clause why to a rule where a caller has to tell two adjacent conditions apart: why exit 5 differs from 4, why a dead pane differs from a busy composer. Stripping those leaves rules a caller cannot act on. Three places where a further increment does exist, none of them an oversight:

• ## Core principles, 411 words, is the largest remaining block that fails the caller test. It stays by decision: no caller can depend on it and every contributor is bound by it, including by this file's own "per principle 5" citation.
• ## Directory layout gave up only 46 words. Its per-file tree annotations still carry some justification prose.
• ## Error handling and ## Output shape are the densest prose left at about 20 words per line. I read both as contract, the exit-code taxonomy and the TOON surface, but they carry why-clauses a stricter pass would thin.

That increment is a follow-up issue rather than more churn in this diff.

Two things about this PR's body

The gate's pr step overwrote the body. Per standing instruction I have not repaired it: the standalone Closes atqamz/secondhand#159 line is gone, and the body now carries 20 emoji and em dashes. The body I authored, including the correction above, is saved at data/secondhand-specs-contract/pr-162-body.md in the fleet home for restoration before merge.

The Intent section is correct and describes this task. no-mistakes axi run now requires --intent, so I passed this task's intent explicitly instead of letting the step infer it from transcripts.

Three claims the generated body makes are wrong and should not be trusted: it says 30 records (there are 27 plus a README), it says net ~430 lines removed (net is 252), and it says every record is reachable from exactly one section (the firstmate record is cited from two).