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
claude/site-changelog-readability-k4p902 View source

Criteria completion

Criteria completion: 4 of 4 (100%) checked; history from Oct 15 to Oct 150%25%50%75%100%Oct 15Oct 15

Relationships

Implements 1
Related 4
Branches 1
claude/site-changelog-readability-k4p902 current done
main done
History 6
  1. 2153967
    Content editedby bjornolofandersson
  2. df590cc
    Content editedby bjornolofandersson
  3. c3a59a7
    • ☑ 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
    by bjornolofandersson
  4. 711f598
    Content editedby bjornolofandersson
  5. 321d355
    Content editedby bjornolofandersson
  6. 4aae7d0
    Created (ready)by bjornolofandersson

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.