GitHub round trip
Branches, commits, and PRs carry feature IDs; merges flip status, stamp the manifest, and write the changelog. Drift is caught at the moment of change.
Branch names (feat/FEAT-0012-usage-billing) and commit trailers
(Refs: FEAT-0012) tie every change to the graph. CI checks that each PR
references a valid ID; a trace comment posts the PR’s slice of the graph —
claim, doc, screens, decisions, tests — beside the diff.
A drift check runs as a PR status in both directions: code deviating
from spec, and vision pages deviating from what building taught us. On
merge, frontmatter flips to built, the PR number lands in the manifest,
and the public changelog entry is generated — grouped by feature, never
hand-written.
Features are not mirrored into GitHub Issues — dual-write drifts. If a board is ever wanted, it’s a generated read-only view of frontmatter.
Years later, the archaeology still works: grep an ID, walk the log, find the PRs, the linked decisions, and the checkpoint of the vision site as it looked when the feature was specced — what was imagined, not just what was built.