WORK-642
ID:WORK-642Status:done

Every ref in a release note resolves to a plan entity

refrakt validate --deep passes a page containing {% ref "SPEC-99999" /%}. Only the site build reports it, as one "entity not found" warning among hundreds. A mistyped ID in a release note would therefore ship as a dead drawer.

Priority:mediumComplexity:simpleMilestone:v0.41.1Source:SPEC-176
main View source

Criteria completion

Criteria completion: 4 of 4 (100%) checked; tracking started on Oct 16, no incremental history yet0%25%50%75%100%Oct 16Oct 28

Tracking started Oct 16 — check back for trends.

Relationships

Implements 1
Related 4
Branches 2
main current done
claude/site-changelog-readability-k4p902 donemain done

Acceptance Criteria

  • A test fails when a file in releases/notes/ contains a {% ref %} or {% xref %} whose target is not an ID or milestone name declared in the plan
  • The failure names the note file, the line and the unknown ID
  • Declarations inside code fences in plan/ do not count as declared
  • The milestone openings WORK-641 uses as a fallback are checked the same way

Approach

Collect declared IDs from the id attribute of spec, work, bug and decision tags and the name attribute of milestone tags across the plan directory, skipping fenced blocks. Then scan the notes for ref targets. This is a string check, so it needs no build and runs with the rest of scripts/*.test.mjs.

Blocked by

  • WORK-641

References

  • SPEC-176 D6.

Resolution

Completed: 2026-10-15

Branch: claude/site-changelog-readability-k4p902 PR: refrakt-md/refrakt#704

What was done

  • scripts/generate-changelog.mjs: declaredPlanIds (spec/work/bug/decision ids and milestone names, fenced examples excluded), unresolvedRefs, and releaseRefFindings, which checks every note and every milestone opening used as a fallback.
  • Tests on fixtures plus one over this repository's real notes and milestones.

Notes

  • Findings name the file, line and target. A string check, so it runs with npm test and needs no build.