Rule: Frontmatter is the canonical place to encode cross-document discipline (forward-traceability, supersession chains, companion-file relationships, pin-kind semantics, honesty caveats, kill-condition outcomes, target Phase Qs, gold value). Treat frontmatter expansion as a high-leverage activity worth investing in, not as bureaucratic overhead.
Why (Rich-confirmation 2026-05-03T~21:45 BST): “I love frontmatter — it is a fantastic way to improve the way we use files.” Said unprompted after the cumulative landing of:
- §3.5 snapshot-pin vs floor-pin distinction (locked 2026-04-29)
- §3.6 forward-traceability —
phase_q_relevance:+ structuredcompanion_files:(locked 2026-05-03 morning) - §3.7 placeholder cascade-Q-file convention with state lifecycle (locked 2026-05-03 with frontmatter-conventions v1.4)
- T-file frontmatter contract per ν.α plan §1.1 (12+ honesty_caveats; bidirectional cite-back with placeholder cascade-Q files)
- Pre-commit pin-drift hook enforcement of
version_pinned:floor-pins - Z1.5 supersedes / superseded_by chain just authored today
- Plan-file frontmatter
companion_files:blocks driving the pin-drift hook
The compound effect across these: a researcher arriving 6 months from now can reconstruct the entire spike-suite reasoning chain (T-file → cascade-Q file → arch-state row → plan §0 checkbox → CHANGELOG → memory file → MEMORY.md index) from frontmatter alone, without reading a single body section. That’s the load-bearing payoff.
How to apply:
- When authoring any new TT artefact: invest the time to write the FULL recommended frontmatter, not the minimum. Prior incidents (e.g. forward-traceability gap surfaced by 22-spike audit 2026-05-03) showed that minimum-frontmatter creates findability debt that costs hours to repay later.
- When proposing a new convention that adds frontmatter fields: don’t apologise for it as overhead. The Rich-confirmation establishes that frontmatter-richness is the desired direction.
- When touching an old file with thin frontmatter: bring it up to current convention if the touch is substantive (don’t bulk-migrate; opportunistically improve).
- When designing new conventions (e.g. for a future spike-skill): default to frontmatter as the canonical place to encode the contract, with body content for human prose.
- This rule applies retroactively: if a new field would make a class of files more discoverable or auditable, propose it confidently rather than hedging.
Cross-references:
- Frontmatter conventions doc:
~/testatetech/docs-strategy/frontmatter-conventions.mdv1.4+ (§§3.5/3.6/3.7 are recent peaks) - Pre-commit enforcement:
~/testatetech/docs-strategy/scripts/check-frontmatter-pins.py - Sister memory:
feedback_research_artefact_forward_traceability(locked 2026-05-03) — the WRITE-time discipline this confirmation reinforces - Companion:
feedback_check_t_files_first_for_any_inherit_v2_work— the READ-time companion to forward-traceability frontmatter