Epic 004 — Behavior-preserving refactoring backlog

This epic records repository-specific refactoring work discovered by the 2026-10-12 repository review. All tasks in this epic have been implemented; the status index and task descriptions record their completion.

Execution contract

Every task inherits these constraints:

Re-read the affected code, current canonical guide, docs/current-state.md, and docs/ai-handover.md; do not assume this snapshot is still current.
Preserve all externally visible behavior, HTTP contracts, specification text, ADR history, traceability IDs, and scenario IDs. Do not edit existing files under docs/specs/ or docs/decisions/; a new ADR may be added only when a task explicitly calls for one.
Prefer a mechanical move with unchanged tests first, validate it, then perform any semantic cleanup and validate again. Do not combine a substantial production refactor with a substantial test refactor.
Centralize only a demonstrated shared concept or invariant. Similar-looking provider, transport, domain, and presentation code may intentionally remain separate.
Use the lowest appropriate focused tests after each meaningful step. Run pnpm quality before completing every task, plus the task-specific validation below. The full existing CI gate is still required for a delivered revision.
Update the affected canonical guide, docs/current-state.md, and docs/ai-handover.md. Keep the latter two as concise continuation aids rather than adding another historical narrative.
If inspection no longer supports a proposed boundary, stop and record the evidence instead of forcing the planned shape. Tasks marked Decision require the stated answer before dependent implementation begins.

Ordered backlog

Task	Kind	Outcome	Depends on	Status
REF-TASK-001	Documentation	Reduce current-state and handover to current facts	None	Implemented
REF-TASK-002	Documentation	Reorganize the canonical project guides	001	Implemented
REF-TASK-003	Documentation/tooling	Make documentation navigation declarative and complete	002	Implemented
REF-TASK-004	Test only	Establish narrow frontend HTTP test helpers	None	Implemented
REF-TASK-005	Test only	Split the KDS component test by behavior	004	Implemented
REF-TASK-006	Test only	Split authentication HTTP tests by route family	None	Implemented
REF-TASK-007	Test only	Split KDS browser scenarios without changing evidence	None	Implemented
REF-TASK-008	Production, mechanical	Decompose the KDS page into cohesive feature modules	005	Implemented
REF-TASK-009	Production, mechanical	Split authentication HTTP registration by concern	006	Implemented
REF-TASK-010	Production, mechanical	Split order HTTP registration and client API modules	005	Implemented
REF-TASK-011	Production, mechanical	Split locale resources by locale and namespace	008	Implemented
REF-TASK-012	Naming, mechanical	Align product form files and internal names with contents	None	Implemented
REF-TASK-013	Production, semantic	Consolidate named order-transition plumbing	010	Implemented
REF-TASK-014	Production/tooling, semantic	Consolidate user-provisioning command composition	009	Implemented
REF-TASK-015	Decision	Decide ownership of duplicated order contracts and limits	008, 010	Implemented
REF-TASK-016	Decision	Decide safe decomposition of order persistence	013, 015	Implemented
REF-TASK-017	Production/API hygiene	Remove accidental exports and reviewed compatibility aliases	008–16	Implemented
REF-TASK-018	Guidance/ADR	Codify the patterns established by completed refactors	002–17	Implemented
REF-TASK-019	Validation	Run final consistency and regression review	001–18	Implemented

Tasks 001–007 are deliberately safe preparation. Tasks 008–12 are mechanical restructuring and must not contain semantic cleanup. Tasks 13–17 may proceed only after their prerequisite structure is stable. Tasks 15 and 16 are decision gates: repository evidence does not currently justify a shared cross-workspace contract package or a particular persistence split.

Review exclusions and non-findings

Generated Drizzle snapshots are large but are migration artifacts, not refactoring candidates.
docs/api/openapi.yaml is large because it is the complete public contract; split-source OpenAPI would add a build mechanism and is not justified by current evidence.
docs/specs/ and docs/decisions/ are historical records. Existing files are inputs to the review, never cleanup targets.
No catch-all production utils or common module and no demonstrated circular source dependency was found. Do not create a generic helper bucket during this epic.
Frontend wire types resembling backend domain types are not automatically duplicates: they have different date representations and deployment boundaries. REF-TASK-015 owns that decision.
Provider-specific checkout types and mappings must remain inside backend/src/integrations/; superficial similarity to neutral checkout/domain types is intentional boundary translation.

Cross-check result

The backlog was checked for overlap and behavior risk. Test restructuring precedes the matching production splits; naming is isolated from component and service decomposition; order-contract and persistence changes are decision-gated; documentation cleanup does not rewrite specifications or ADRs; and every implementation task names focused validation plus the repository-wide quality gate.