docs: align housekeeping.md with landed architecture; delete stale plans

[feffef]

Finding

FINDING-05 | WARNING | Style / Documentation
Location: docs/housekeeping.md:27-36 vs src/api-client.ts, src/error-handling.ts

Housekeeping item #3 (marked DONE) described a fetchSafe / fetchProne split with a file-private formatErrorMessage dispatch table. None of those symbols exist in src/. The actual architecture is a single ApiClient.fetchResource that returns a { resource | failure, baseURL } discriminated result, with verbosity-aware formatting inlined per-builder in error-handling.ts and failureToError as the sole boundary converter.

Root cause: item #3 was written against docs/pipeline-refactor-plan.md (superseded by the alt plan, which was then further revised before landing). The planning docs still carry "Proposed — awaiting review" headers and describe designs that either lost or have since been changed.

Concrete impact: any reader (human or AI) searching src/ for fetchSafe, fetchProne, or formatErrorMessage finds nothing. They either spend time hunting for phantom symbols, or they do a git-blame-and-ask and conclude the DONE note is wrong. Either way, trust in the DONE markers in housekeeping.md drops.

Approach chosen: B — rewrite + delete planning docs

The root cause is the stale planning docs. Rewriting item #3 but leaving the planning docs in place guarantees the drift comes back the next time someone reads them.

Alternatives considered

• A — rewrite item docs: fix broken cross-refs and stale names across how-it-works/roadmap/bff/README #3 only: Leaves the misleading planning docs in place. Rejected because they are the source of the drift.
• C — delete item docs: fix broken cross-refs and stale names across how-it-works/roadmap/bff/README #3 entirely (housekeeping is for open work): The project convention keeps DONE items as a historical record, so deletion would be a style break. Rejected.

Bundled quick fixes

• Quick Fix 3: drop dangling references to missing docs/integration-test-split.md from housekeeping items feat: NavigationError class + public-export tidy #5 and #7.
• Quick Fix 13: same as FINDING-05 Approach A minimal patch — covered by the main rewrite.
• Quick Fix 14: reorder housekeeping items into numerical sequence (no content changes).

Test plan

• npx jest — all tests pass (doc-only change).
• git grep "pipeline-refactor-plan" after delete → no references remain.
• git grep "integration-test-split" after edit → no references remain.
• Housekeeping items read in numerical order 1..15.

Review checklist

• Dedicated opus peer review: approved

[feffef]

Opus Reviewer (on behalf of @feffef): LGTM — verified against source of truth.

Accuracy of rewritten item #3: Every function named in the new text exists in the code. Confirmed in src/api-client.ts:141-147 that ApiClient.fetchResource returns the { resource | failure, baseURL } shape as described. Confirmed in src/error-handling.ts that all six builders (uriExpansionFailure, networkFailure, unmappedStatusFailure, invalidJsonFailure, invalidStructureFailure, responseFailure) and failureToError are exported with verbosity-aware formatting inlined per builder. The new blurb matches the landed architecture exactly.

Planning-doc deletion safety: ls-tree confirms docs/pipeline-refactor-plan.md and docs/pipeline-refactor-plan-alt.md are gone. git grep across the whole tree at the PR ref shows zero residual references to either file (AGENTS.md, README.md, how-it-works.md — all clean).

Dangling integration-test-split refs: git grep returns zero matches on the PR branch. The reference was correctly removed from item #5 ("following docs/integration-test-split.md" clause dropped) and item #7 (**Source**: docs/integration-test-split.md consolidation review line removed, body trivially reworded to drop "The plan flagged…" framing). Substance preserved.

Item ordering: Now strictly 1–15. Main had items at 3, 5, 4, 6, 7, 8, 10, 11, 13, 14, 9, 15, 12 — a mess. PR branch is 1, 2, 3, 4, 5, 6, 7, 8, 9, 10, 11, 12, 13, 14, 15. Spot-checked items #4, #9, #12, #15 after the move — content identical to pre-reorder. Item #7's minor rewording is a necessary consequence of removing the deleted-doc reference, not gratuitous editing.

Scope: --stat shows exactly three files changed: docs/housekeeping.md modified, docs/pipeline-refactor-plan.md deleted, docs/pipeline-refactor-plan-alt.md deleted. No scope creep.

Minor nit (not blocking): item #12 bottom of file on main had no trailing newline; PR now has one. Net improvement.