# REF-TASK-002 — Reorganize the canonical project guides around their declared purposes

**Status:** Implemented  
**Kind:** Documentation cleanup  
**Depends on:** REF-TASK-001

## Problem and evidence

Several root guides grew by prepending feature details. `docs/architecture.md` begins with roughly
500 lines of product/order implementation detail before its purpose and high-level architecture, and
contains an empty `Fulfillment transition boundary` heading. `docs/development.md` begins with
email/password-recovery operations before its purpose and setup, and duplicates section number 14.
`docs/test-strategy.md` starts with unnumbered detail, then jumps from section 3 to section 38.
`docs/ci.md` repeats much of the Definition of Done as an 800-line requirement-by-requirement map.
`docs/developer-log.md` is a personal chronological note rather than a maintained project guide;
`docs/accessibility-review.md` mixes a reusable release protocol with a dated evidence record.

## Proposed change

Reorder and edit only living documents directly under `docs/`: lead with purpose and a short map,
group details beneath stable concepts, remove true duplication by linking to the owning guide, fix
heading numbering, and merge contradictory wording after checking implementation. Decide explicitly
whether `developer-log.md` should be removed from maintained docs and whether dated accessibility
evidence belongs in the current-state checkpoint or an evidence artifact; preserve useful product
ideas in an appropriate backlog only if they remain intentional. Keep architecture rationale in
architecture, commands in development, test selection in test strategy, pipeline mechanics in CI,
and completion requirements in Definition of Done.

## Constraints and sequence

Create a source-of-truth matrix before editing. Make one guide coherent at a time and update all
internal links after each move. Do not rewrite `docs/specs/**` or `docs/decisions/**`, change stable
IDs, or alter policy merely to shorten prose. Keep provider/security limitations and historical ADR
links intact. If two guides conflict on policy, ask the user which policy is intended rather than
selecting silently.

## Validation

Run Markdown formatting/link/spelling checks after each guide, `pnpm docs:build` and
`pnpm docs:site:check` after navigation-affecting changes, then `pnpm quality`. Inspect the
generated project pages for heading hierarchy and rewritten links. No application tests.

## Guidance / ADR

The resulting `docs/documentation.md` must state document ownership and placement rationale. No ADR
unless the task changes an architectural decision rather than its presentation.

## Implementation record

The living architecture, development, testing, CI, and Docker guides now open with purpose and
navigation context before accumulated feature/security detail. Feature boundaries and operational
notes have explicit parent sections; the empty fulfillment heading and duplicate development section
number were removed; testing coverage/command sections now follow sections 1–3 as sections 4–5, with
internal references updated.

`docs/documentation.md` now contains an explicit source-of-truth matrix and placement rationale. The
informal `docs/developer-log.md` was removed because intentional product requirements already belong
in specifications/backlogs and Git retains the note history. `docs/accessibility-review.md` now owns
only the reusable manual protocol; its dated execution record remains in Git, while the current
unresolved manual limitation stays in `docs/current-state.md`. No policy, specification, ADR, public
contract, or application behavior changed.