# Naming Rule

---
rule_id: R-NAME-01
category: Process
status: locked
owner: Project Manager / Architect
scope: docs, branches, contracts, tasks, APIs, events, code names
---

## 1. Rule

One concept has one name across requirements, design, contracts, code, tests, and reports.

Names must make traceability obvious.

## 2. Document Names

| Type | Format | Example |
|:---|:---|:---|
| requirement | `REQ-{NNN}.md` | `REQ-001.md` |
| ADR | `ADR-{NNN}.md` | `ADR-001.md` |
| design foundation | `docs/design/DESIGN.md` | `docs/design/DESIGN.md` |
| design grammar | `docs/design/design-language.md` | `docs/design/design-language.md` |
| surface profile | `docs/design/surface-profiles/{surface}.md` | `docs/design/surface-profiles/consumer.md` |
| design derivation | `docs/design/derivation/REQ-{id}.md` | `docs/design/derivation/REQ-014.md` |
| design exception | `docs/design/decisions/EX-{id}.md` (legacy `docs/design/exceptions/EX-{id}.md` still recognized) | `docs/design/decisions/EX-001.md` |
| design tokens | `docs/design/tokens/tokens.json` (+ generated `tokens.css`) | `docs/design/tokens/tokens.json` |
| portable DESIGN snapshot | `docs/design/proof/portable/DESIGN.md` (derived, not authority) | `docs/design/proof/portable/DESIGN.md` |
| component proposal | `docs/design/decisions/CP-{id}.md` (legacy `docs/design/components/CP-{id}.md` still recognized) | `docs/design/decisions/CP-001.md` |
| foundation replay record | `docs/reports/design-foundation/` | `docs/reports/design-foundation/FOUNDATION-REPLAY-template.md` |
| UI design package directory | `docs/design/prototypes/{module}/` | `docs/design/prototypes/fund/` |
| UI prototype HTML | `<feature>.html` (one per page/dialog/wizard) | `fund-list.html`, `wizard.html` |
| UI module entry hub | `index.html` (card-grid linking to every page HTML file) | `docs/design/prototypes/fund/index.html` |
| UI stories (per-module current truth) | `stories.md` (one complete module set; source REQs appear only in `source_refs`) | `docs/design/prototypes/investor/stories.md` |
| UI flows (per-module current truth) | `flows.md` (one complete module set; `F-NNN` + `PATH-*` steps) | `docs/design/prototypes/investor/flows.md` |
| Scenario model | `scenario-model.json` (module rules and branch witnesses) | `docs/design/prototypes/investor/scenario-model.json` |
| Generated cases | `cases.json` (current generated output) | `docs/design/prototypes/investor/cases.json` |
| Scenario coverage | `scenario-coverage.json` (current generated output) | `docs/design/prototypes/investor/scenario-coverage.json` |
| Fixture contract | `fixture-contract.json` (synthetic setup and cleanup) | `docs/design/prototypes/investor/fixture-contract.json` |
| UI user story template | `USER-STORY-template.md` (canonical structure; output lives in module `stories.md`) | `docs/design/prototypes/USER-STORY-template.md` |
| UI user flow template | `USER-FLOW-template.md` (canonical structure; output lives in module `flows.md`) | `docs/design/prototypes/USER-FLOW-template.md` |
| contract overview | `CONTRACTS-{NNN}.md` | `CONTRACTS-001.md` |
| frontend contract | `FE-{NNN}.md` | `FE-001.md` |
| backend contract | `BE-{NNN}.md` | `BE-001.md` |
| sync contract | `SYNC-{NNN}.md` | `SYNC-001.md` |
| task | `TASK-{NNN}.md` | `TASK-001.md` |
| bug | `BUG-{NNN}.md` | `BUG-001.md` |
| review | `REV-{NNN}.md` | `REV-001.md` |
| acceptance | `ACC-{NNN}.md` | `ACC-001.md` |
| QA report | `QA-{NNN}.md` | `QA-001.md` |

## 3. Branch Names

| Type | Format | Example |
|:---|:---|:---|
| docs | `docs/<topic>` | `docs/req-001-onboarding` |
| feature | `feature/<task-id>-<topic>` | `feature/TASK-001-login` |
| bugfix | `bugfix/<bug-id>-<topic>` | `bugfix/BUG-007-retry` |
| tech debt | `td/<id>-<topic>` | `td/TD-003-repository-cleanup` |
| release | `release/<version-or-date>` | `release/2026-05-20` |
| hotfix | `hotfix/<bug-id>-<topic>` | `hotfix/BUG-009-payment-timeout` |

## 4. Code And API Names

| Object | Rule |
|:---|:---|
| directories | follow project ecosystem; keep cross-doc paths stable |
| types/classes | use domain names; avoid vague `Manager` or `Helper` |
| API fields | match `SYNC-*` exactly |
| states | match `docs/architecture/state/*.md` exactly |
| events | `{domain}.{entity}.{action}`, e.g. `order.payment.succeeded` |
| errors | stable short code, e.g. `E1001`; never reuse meaning |

## 5. Forbidden

- core domain names like `data`, `info`, `tmp`
- multiple names for the same concept
- API field rename without contract approval
- default values that hide unknown business identity
- legacy `proto/` paths for the UI design package directory; the canonical name is `prototypes/` (per `docs/rules/ui-prototype.md` §4). Existing `proto/` paths must be migrated before the next UI-impacting REQ locks
- per-REQ, per-round, `v1/v2`, addendum, or generation copies of module stories, flows, cases, prototypes, fixtures, or Playwright specs