spec 013: design APPROVED — four pages, five phases, API repairs first

[iancooper]

Spec 013's design phase, approved 2026-09-06. Three files were sitting uncommitted in the working tree; this is all of them, plus the approval marker the tooling actually reads.

What lands

• spec/013-howto_guides/design.md (941 lines) — the authority for the rest of 013. Four new pages, six edited, four nested SUMMARY.md entries, no new section. Five phases, one PR each: 1 P0-2 + P0-4, 2 P0-1, 3 P0-3, 4 P1-1 + P1-2, 5 the acceptance pass with AC9 walked backwards.
• .design-approved — 009's form, an empty marker. /spec:design, /spec:review and /spec:status read this file, not the Status line inside the document. 492b1ea is the commit that edited the second and said it added the first, which is why this is a separate bullet rather than an assumption.
• README.md — the outline box ticked.
• CLAUDE.md — Q7's ruling: ## Step N: headings now cover how-tos as well as tutorials. The reason was never about tutorials specifically; it is about a page a reader executes. It binds pages written from here on and does not reach the 53 pages already typed How-to, whose published anchors would move for no reader benefit.

The rulings, so none is re-opened

Q3	Answered by measurement, not by a ruling — its premise was stale. 012's phase 10 repaired HandlerFailure.md's nack table at 05ab80c, three days before the requirements described the defects as open. P0-3 links the table; it repairs nothing.
Q5	P0-2 widens from ten dead call sites to seventeen — twenty defects, eight code blocks, six pages. The blocks holding the ten are V9 throughout.
Q6	P0-4 added — ten dead type names across six pages, all in prose four lines above code blocks that get it right. The V9 .UseXxxOutbox( family stays recorded, not scheduled.
Q7	## Step N: extended to how-tos.
Q4	Deferred, not open. A write to ../Brighter/samples/ is authorised per PR, so it is asked when phase 2's PR exists.

Why P0-2 goes first, ahead of the public commitment

P0-1 is what #67 is owed, and it still ships in phase 2. But .ResiliencePipelines( and .ConfigureResiliencePipelines( are declared nowhere at 10.7.0 or on origin/master, .Policies( is V9's dead form, and the real API — .Resilience(registry, policyRegistry) and .DefaultResilience() — is on zero pages. Nothing new should be written on top of a surface the corpus spells wrongly.

Every API name in the design was verified at both refs with a control, because a zero is also what a broken grep returns.

Gates

All seven, unmoved before and after — this touches no file under contents/:

linkcheck.py                 No broken internal links (160 files checked).
pagelint.py                  0 errors, 779 warnings, 158 pages
urlmap.py --check-shape      0 — 157 pages, 12 sections, deepest 4 of 4, widest 12 of 20
urlmap.py --check-redirects  0 — 77 entries, 7858 bytes, printable ASCII
versioncheck.py              0 stale pins of 18 examined across 5 page(s).
optioncheck                  0 mismatches across 59 tables and 519 rows
urlmap.py --verify           predicted 157, published 157, 157 agree

pagelint.py --changed origin/master reports 0 code block(s) strict — vacuous by construction, and the scope line says so rather than the verdict being read as evidence.

🤖 Generated with Claude Code

https://claude.ai/code/session_0146UueHL6H3zGBGTYwz7GtL