# Traceability contract — REBNO

[doc->REQ-HYG-02]

> How REBNO uses [`traceable-reqs`](https://github.com/BigscreenVR/traceable-reqs) to
> keep requirements traced from doc through implementation to tests.
> The manifest is `traceable-reqs.toml` (seeded from `.planning/REQUIREMENTS.md`).
> This contract makes the trace pay off instead of rotting.

## Why

traceable-reqs measures **active-milestone delivery**, not archived history.
Requirements that are not part of the current active milestone are inactive
(`required_stages = []`) so `check` stays green before their phase starts.
A requirement that is activated but has no evidence (doc, impl, test) is a
requirement you are *hoping* is met. This contract converts hope into a build
step that fails when evidence is missing.

See CLAUDE.md §Requirements Traceability for tag forms and per-stage placement rules.

## The contract (rules)

1. **The manifest is the authoritative requirement registry.** Every requirement
   in `.planning/REQUIREMENTS.md` exists in `traceable-reqs.toml` with a canonical
   `REQ-<PREFIX>-<NUM>` id. No work without a REQ; no REQ without intent to satisfy.
   The manifest holds the id and `required_stages`; REQUIREMENTS.md holds the prose.

2. **Tag in the same change as the evidence.** When you write the function, test, or
   doc section that satisfies a stage, add its `[<stage>->REQ-ID]` tag in *that same
   commit*. Never "tag later" — this single rule is what prevents trace drift.

3. **Evidence-proximate tags, not file-tops.** A tag sits on or immediately above the
   real function, test, doc section, or workflow step that proves the stage.
   One tag = one piece of real evidence. Tags at file tops are noise and usually wrong.

4. **Activation, not premature failure.** Every requirement starts `required_stages = []`
   (inactive) so `check` stays green before the phase that delivers it begins.
   A phase activates the requirements it delivers by setting their real `required_stages`
   at plan time. Closed-milestone requirements and future-phase requirements stay `[]`
   until promoted. `check` must be green on the active milestone's requirements — not
   on all requirements ever defined.

   Rationale: closed-phase requirements were gated by their phase's functional milestone
   gate; retro-tagging archived work is busywork with no forward value. Future-phase
   requirements cannot have evidence yet — activating them early just fails the build
   for no reason.

5. **Illustrative tags in documentation use angle-bracket stage.** When documentation
   (including planning docs, ADRs, and runbooks) needs to *show* tag syntax as an
   example or grammar description, wrap the stage word in angle brackets:
   `[<stage>->REQ-ID]`. The scanner (traceable-reqs v0.1.1+) treats these as
   illustrations and emits no finding. Real evidence tags use the bare stage word
   (e.g. the `[doc->REQ-HYG-02]` tag at the top of this file).

   This rule exists because planning documents frequently describe the tagging
   contract itself and would otherwise accumulate false parse_error / undeclared_id
   findings from their own illustrative examples.

## Lifecycle

- **Manifest seeded:** all requirements inactive (`required_stages = []`).
  `pnpm trace:check` is green (nothing required yet).
- **Each phase:** activates the requirements it delivers by setting `required_stages`
  at plan time. A phase is not done until `pnpm trace:check` is green for its
  activated requirements.
- **Closed phases:** remain in the manifest with `required_stages = []` (deactivated,
  not removed). This preserves the registry so a future milestone can re-activate
  a requirement or promote it to a tighter stage set.

## Verification

```bash
# Hard gate on active requirements — must be zero findings before a phase is complete
pnpm trace:check

# Inspect all requirements and their current stage coverage
pnpm trace:list

# Drill into one requirement
traceable-reqs trace REQ-HYG-02
```

`pnpm trace:check` is wired into `pnpm preflight` (Plan 07-06). Run it locally
before claiming any plan complete.