WS-005: Why documentation ships with implementation

Status	Accepted
Date	2026-08
Sources	workspace CLAUDE.md §5a–§5d; route-inventory / contract reminder patterns

Context

ER has many doc surfaces: hub CLAUDE.md, child README, MkDocs sites, OpenAPI, portal HTML. Agents can ship code and leave docs for “later.”

Problem

“Docs to follow” is how customer docs, developer day-one, and contracts drift from the binary. The next human or AI then trusts stale pages.

Decision

An implementation is not done until:

1. Owning hub CLAUDE.md (architecture + change log) is updated
2. Every stale doc inside that hub is updated — including published website content
3. Tests were run and the behaviour exercised (§5b)
4. An Implementation record is written into the proposal (§5c)
5. If it deploys, the live URL is verified (§5d)

Same-effort hooks in the product hub remind; some contracts fail CI (check-route-inventory.sh).

Alternatives considered

Alternative	Why not
Separate docs tickets	Chronically slip; knowledge stays in heads
Docs-only follow-up PRs	Split review; easy to skip under pressure
Generate all docs from code	Incomplete for “why”; ADRs still need humans

Consequences

• Proposal checklist blocks implemented without the record
• Developer portal day-one must describe this full loop, not a shorter ancestor