# REF-TASK-018 — Codify patterns established by completed refactors

**Status:** Implemented  
**Kind:** Development guidance and ADR follow-up  
**Depends on:** REF-TASK-002 through REF-TASK-017

## Problem and evidence

The current development guide is strong on commands and quality gates but does not give concise
placement rules for feature modules, route registrars, intentional exports, test file organization,
or when repeated-looking code crosses a boundary and should remain duplicated. Without recording the
rationale, the repository can regress to large coordinator files or swing too far into generic
helpers. Guidance must describe conventions actually established by completed work, not prescribe
unimplemented architecture.

## Proposed change

Add a compact maintainability section to `docs/development.md`, linking to architecture/testing/
documentation guides rather than duplicating them. Cover:

- route pages as composition roots and feature-local files by responsibility;
- backend HTTP registrar composition and dependency direction;
- capability-based API modules and intentional public exports;
- dominant naming: domain terms and externally meaningful identifiers stay stable, filenames match
  their primary responsibility, and local versus exported constants follow existing TypeScript
  conventions;
- shared abstractions only for the same invariant, with provider/domain/wire/presentation mappings
  allowed to remain separate;
- unit/component/integration/E2E file organization and fixture ownership;
- user-facing role/name selectors first, stable explicit selectors only when semantics cannot
  identify the element, and no selector changes solely for tests;
- documentation placement, concise current-state/handover roles, and immutable spec/ADR history;
- when dependency-boundary changes require an ADR and how superseding preserves old ADRs.

## Constraints and sequence

Draft only after implementation tasks reveal the actual pattern. Cross-check every rule against at
least two repository examples or state that it is a deliberate new convention. Do not add an ADR for
file moves, test helpers, or naming. If REF-TASK-015 or 016 changed architecture, add a new ADR and
mark an older decision superseded only through a new record/cross-link—never rewrite its history.

## Validation

Peer-review examples against the tree; run documentation link/spelling/format checks,
`pnpm docs:build`, `pnpm docs:site:check`, inspect the development page, and run `pnpm quality`. No
application tests.

## Guidance / ADR

This task is the guidance update. ADR applicability is determined by REF-TASK-015/016 outcomes.