Linear-aligned 3-tier audit architecture (locked 2026-05-26)
Rule
TT abandons per-repo CHANGELOG.md auto-regeneration in favour of a 3-tier audit architecture aligned with Linear’s native model:
| Tier | Layer | Storage | Captures | Cadence |
|---|---|---|---|---|
| 1 Operational | Linear issues + linked PRs | linear.app/mediahq2 | Per-task work units; PR titles <type>(scope): ENG-NNN <desc> auto-link via magic words; PR review state surfaces in Linear UI | Per-commit / per-PR |
| 2 Strategic | wave-execution-records | docs-strategy/docs/superpowers/specs/2026-MM-DD-wave-X-execution-record.md with linear_project_id: frontmatter | Per-wave audit: honesty caveats §3, velocity, substrate-correcting findings, deferred items §6 | Per-wave-closure |
| 3 Public | GitHub Releases auto-gen | github.com/testatetech/ | Release notes from PR titles + labels; “Full Changelog” diff links | Per-tag (Phase-2+ only) |
Why: Wave C record §3.5 documented git-cliff CHANGELOG.md auto-regen rebase tax (~17-28 cycles cumulative across Waves A+B+C; ~5-15s friction per push). Empirical Spike A (post-commit hook, VALIDATED-WITH-CAVEATS — SHA cascade) + Spike C v2 (release-please, EMPIRICAL REJECT — ~35-50% audit-trail loss) + SOTA research (Vercel/Linear/Stripe/Anthropic all dropped CHANGELOG.md years ago in favour of release-driven changelog websites) + Linear-fit research (Linear has no CHANGELOG feature; “changelog equivalent” is Project completion view) all converge: drop CHANGELOG.md + use Linear Projects + wave-records as audit substrate.
How to apply:
- New v2 build repos (post-2026-05-26): do NOT add CHANGELOG.md or
.github/workflows/changelog.yml. Wirelinear_project_id:field in any wave-record or BUILD-PLAN frontmatter going forward. - Existing 5 v2 build repos (Wave A.2 cascade): freeze CHANGELOG.md with header pointing to wave-records + Linear; delete
.github/workflows/changelog.yml. Wave C.1 Del 3 ships this. - docs-strategy + docs-admin: no CHANGELOG.md or workflow to begin with; no action needed.
- Wave-execution-record authoring (going forward): include
linear_project_id: ENG-PROJ-NNNin frontmatter. Mark corresponding Linear Project as Complete after pushing the record. - PR title convention (Steven Day-1 substrate):
<type>(<scope>): ENG-NNN <description>— CC-compliant AND Linear-magic-word-compatible. - GitHub Releases at v1.0+ (Phase-2+): single config flag (
generate_release_notes: true) when first tag cut; zero migration overhead.
Why each rejected option failed empirically
| Option | Verdict | Evidence |
|---|---|---|
| A (post-commit hook + amend) | VALIDATED-WITH-CAVEATS | SHA cascade on rebases breaks PR review tracking + Linear PR commit-tracking; DIY hook script outside pre-commit framework pattern |
| B (tag-only trigger) | weak fit | TT has 0 tags → CHANGELOG freezes anyway; doesn’t leverage Linear at all |
| C (release-please) | EMPIRICAL REJECT | Spike C v2 sandbox proved ~35-50% audit-trail loss on TT-shaped commits; CHANGELOG format conflict with git-cliff; v1.0 default mismatches TT phase numbering |
| D (check-only CI) | redundant | Same as O’ but adds Rich cognitive load (regen-before-push); doesn’t leverage Linear |
| E (KEEP v1.2 actor-guard) | wasted effort | Actor-guard redundant per GitHub’s GITHUB_TOKEN loop protection; doesn’t fix rebase tax |
| F (DROP Del 3 entirely) | abdication | No fix; tax remains |
| G (changesets) | poor fit | Designed for npm monorepos; TT’s 7-sibling pattern misfits; Linear unaware of .changeset/*.md files |
| H (GitHub auto-gen release notes) | partial | Good for v1.0+; native to GitHub but not Linear-surfaced |
| I (release-drafter) | redundant vs H | Now native via GitHub; draft state not in Linear |
| J (Spec-Kit changelog) | NON-INSTALLABLE | S5 spike + 2026-05-26 re-check: still stale at commit 2026-04-11; manifest defect unfixed |
| L (wave-closure script) | good but redundant with O’ | Preserves CHANGELOG.md but doesn’t leverage Linear; O’ is cleaner |
Why O’ is the strongest fit
- Linear has no native changelog feature but its Project completion view IS the per-wave audit (maps 1:1 onto TT wave-closure rhythm)
- PR↔Issue magic words (
Fixes ENG-123) make Linear the operational tier; PR titles auto-attach to issues linear_project_id:field already in TT frontmatter v1.4+ per Spec-Kit alignment work (Stage 7); just promote to canonical use- GitHub Releases native auto-gen ready at v1.0+; one config flag flip
- Wave-execution-records already richer than CHANGELOG.md (honesty caveats, velocity, substrate-corrections per
feedback_research_artefact_forward_traceability) - Stealth-discipline preserved (per
project_openinherit_release_discipline): no public marketing-grade changelog until TT-ready - Steven Day-1 substrate simpler: single PR title convention + reference to wave-records dir; no CHANGELOG.md to explain or maintain
Research substrate (empirical evidence)
- Wave C record §3.5: rebase tax confirmed across 3 waves (~17-28 cycles cumulative)
- Spike A (~/testatetech/docs-strategy commit log Spike A): post-commit + amend works but SHA cascade
- Spike C v2 (throwaway repo
davieshq/spike-rp-2026-05-26, since deleted): release-please ~50% commit visibility on TT-shaped sandbox - SOTA scan: Vercel/Linear/Stripe/Anthropic all use release websites, not CHANGELOG.md
- keepachangelog.com 1.1 FAQ: acknowledges GitHub Releases as alternative; objections (portability + discoverability) largely obsolete in 2026
- Linear docs research: no native CHANGELOG/release feature; Project completion = changelog equivalent; GitHub PR↔Issue linking is bidirectional via magic words
- Spec-Kit changelog extension: NON-INSTALLABLE 2026-04-11 → 2026-05-26 (unchanged; manifest defect)
Related memories
- feedback-pilot-belongs-in-spike-phase-not-execution — discipline applied to Spike A + Spike C v2 (empirical pilots before commit)
- feedback-research-artefact-forward-traceability — wave-records are the richer substrate that absorbs CHANGELOG.md’s purpose
- feedback-recursive-review-and-revise-pattern-2026-05-25 — second-pass /review-plan caught v1.1 RP2-H1/H2 + this Spike-A/C/SOTA round revealed Del 3 was solving wrong problem entirely
- project-tt-core-tool-stack-2026-05-22 — Linear locked as core infra
- project-wave-c-closed-2026-05-26 — Wave C closure substrate
Phase-2+ activation triggers
When TT cuts first v1.0 release (Phase-2+):
- Tag
v1.0.0on the repo being released - In
.github/workflows/release.yml(new file): useactions/create-releaseORsoftprops/action-gh-releasewithgenerate_release_notes: true - GitHub auto-gen reads PR titles + labels from the diff range
- Release notes appear on github.com/testatetech/
/releases/tag/v1.0.0 - Future releases (v1.0.1, v1.1.0, etc.) follow same pattern
No CHANGELOG.md needed at any layer. Linear remains operational truth; wave-records remain strategic truth; GitHub Releases is the public-facing trail.