feedback_frontmatter_modernisation_pattern

The modern frontmatter pattern (introduced 2026-04-28 in arch-state v3.5 + master-plan v1.6, propagated to risk-register v1.1 + repo-topology v1.2 in v3.8 batch) replaces the legacy related: [path1, path2] list-of-paths style with a structured companion_files: block:

doc_type: "<descriptive type>"  # e.g. "phase-1-orchestration-plan", "risk-register", "repository-topology"
companion_files:
  <key_name>:
    path: "<relative-or-absolute-path>"
    role: "<one-sentence description of what this file is>"
    relationship: "<paragraph describing how this file relates to the doc enclosing this block>"
    version_pinned: "v<X.Y>+ (<lastmod-timestamp>)"  # where appropriate

Why: Three concrete benefits validated 2026-04-28: (1) drift detection — version_pinned per companion entry surfaces stale references at-a-glance (e.g., the v3.8 batch caught risk-register pinned at v1.1 while the file was actually at v1.0); (2) bidirectional readability — every cross-cutting doc has explicit role: + relationship: so a Day-1 reader understands what each companion is for without reading the whole companion file; (3) automation surface — structured fields can be machine-validated by extending validate-build-plan-sync.sh. Legacy related: [path1, path2] provides none of these — just unstructured path strings prone to silent staleness (e.g., repo-topology’s related: had a stale inherit-v2-phase-1-development-plan.md for ~12 hours after the file was renamed via git mv).

How to apply:

When touching any spec/state file with legacy related: frontmatter:

1. Add doc_type: field (descriptive label per file’s role)
2. Replace related: block with structured companion_files: per pattern above
3. Add version_pinned: to each entry where the companion has a frontmatter version
4. Bump file version (minor for frontmatter-only changes; major for restructuring)
5. Add CHANGELOG row documenting the migration
6. Cross-validation script catches BUILD-PLAN.md ↔ pointer drift today; extending to companion_files.X.version_pinned ↔ file-X-actual-version is a forward action

Pattern reference files (canonical examples 2026-04-28):

• ~/testatetech/docs-strategy/docs/superpowers/specs/inherit-v2-architecture-state.md v3.8 — most-comprehensive companion_files block (8 entries: index + tier_1 + tier_2 + tier_3 + master_plan + risk_register + repo_topology + standards_engagement_state + critique_ready_spec_superseded)
• ~/testatetech/docs-strategy/docs/superpowers/specs/inherit-v2-phase-1-master-plan.md v1.8 — companion_files + per_repo_build_plans (with canonical_version_pinned per entry)
• ~/testatetech/docs-strategy/docs/superpowers/specs/inherit-v2-risk-register.md v1.1 + inherit-v2-repository-topology.md v1.2 — modernisation examples for short-form companion files

Forward candidates not yet migrated: inherit-v2-standards-engagement-state.md (still at v1.0 with legacy frontmatter; not investigated 2026-04-28).