Update Plan Documents to Use Xref Syntax

changeset-release/main View source

Criteria completion

No incremental history — criteria tracking started on Apr 19.

Relationships

ID:SPEC-008Status:review

Unbuilt Runes — High-Level Spec

ID:WORK-020Status:done

Add Entity Registration to @refrakt-md/plan

Priority:medium

ID:WORK-026Status:done

Add ref as Alias for xref

Priority:mediumComplexity:trivial

ID:WORK-028Status:done

Plan File Scanner Library

Priority:highComplexity:moderate

changeset-release/main current done

main done claude/file-naming-convention-LJdwR done

Apr 21, 01:17 PMf2b3512
Content editedby Claude
Add {ID}-{slug}.md filename convention + migrate filenames subcommand
Apr 10, 06:58 PMf262d7b
Content editedby Claude
Backfill source attributes on all 123 work items
Mar 29, 07:56 PMcf0cfc0
Content editedby Claude
Revert "Fix plan site truncation by escaping Markdoc tags in code fences
Mar 29, 05:15 PM703b85a
Content editedby Claude
Fix plan site truncation by escaping Markdoc tags in code fences
Mar 23, 07:20 AMebe0c64
Content editedby Claude
Migrate plan files to {% ref %} xref syntax (WORK-021)
Mar 23, 07:12 AM38e7523
Content editedby Claude
Resequence xref work items before CLI scanner
Mar 22, 06:42 PM6424098
Created (done)by Claude
Add work items for plan xref integration

Summary

Plan documents currently use plain-text references like Ref: SPEC-008 (Unbuilt Runes) and Dependencies: WORK-015. Replace these with {% ref %} tags so cross-references are machine-readable and will resolve to links once WORK-020 (entity registration) is complete.

Scope

All files under plan/work/, plan/spec/, and plan/decision/ that contain cross-references to other plan documents.

Examples

Before:

> Ref: SPEC-008 (Unbuilt Runes) — Package: `@refrakt-md/media`

After:

> Ref: {% xref "SPEC-008" /%} — Package: `@refrakt-md/media`

Before:

- Requires track and playlist runes (WORK-015) to exist as child content

After:

- Requires track and playlist runes ({% xref "WORK-015" /%}) to exist as child content

Acceptance Criteria

All SPEC-###, WORK-###, ADR-### references in plan documents use {% xref %} syntax
Blockquote Ref: lines use xref for each referenced ID
Dependency mentions in prose and lists use xref
No plain-text ID references remain (except inside attribute values like id="WORK-004")

Dependencies

WORK-026 (ref alias — so migrated files can use the shorter {% ref %} syntax)