docs: commit trailers close the traceability chain

Commits that implement, change, or withdraw a requirement carry a TRACES
trailer using the same token and syntax as the code tags, so one grep pattern
serves both.

This is the last link. Code tags say where a requirement lives; commit trailers
say when and why it changed, and `git log --grep=AR-012` then reconstructs a
requirement's whole history — which no other artifact provides.

A commit serving no requirement omits the trailer: absence is meaningful, and
inventing a tag to satisfy the form is how orphan tags get created. Withdrawing
a requirement counts as changing it, so the withdrawal stays findable.

Also updates the chain diagram, which still referenced the retired @implements
tag and the thematic A1..E8 IDs.

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
This commit is contained in:
2026-07-30 18:36:16 +02:00
co-authored by Claude Opus 5
parent 041961c8c6
commit fec03099bc
2 changed files with 36 additions and 4 deletions
+26
View File
@@ -94,6 +94,32 @@ is what creates orphan tags.
When adding a requirement, give it a parent and a register row. When adding code,
give it a tag.
### Commits name their requirements too
Every commit that implements, changes, or withdraws a requirement carries a
`TRACES:` trailer — the same token and syntax as the code tags, so one grep
pattern serves both:
```
feat(audio): v1 content-derived audio signature
Implements the §3 construction with the six previously-undefined
parameters pinned, plus a golden fixture the plugin can be written from.
TRACES: IR-004, IR-005, IR-007, IR-008 | SR-003
```
This closes the last link in the chain. Code tags say *where* a requirement
lives; commit trailers say *when and why it changed* — `git log --grep=AR-012`
then reconstructs a requirement's entire history, which no other artifact gives
you.
- Trailer last, after any `Co-Authored-By`.
- A commit serving no requirement (formatting, tooling, a typo) simply omits it —
absence is meaningful, so do not invent a tag to satisfy the form.
- Withdrawing a requirement is a change to it: name it, so the withdrawal is
findable later.
- **Specs are requirements + current-state deltas.** Each requirement carries
`Current:` and `Gap:` so the document doubles as a work list. Keep that shape
when editing.