ID:WORK-024Status:done
Add knownSections to Plan Rune Content Models
Priority:mediumComplexity:moderateSource:SPEC-003,SPEC-021,SPEC-037
Add
Criteria completion
No incremental history — criteria tracking started on Apr 21.
Relationships
Implements 3
Related 6
ID:SPEC-037Status:accepted
Plan Package Hardening
Version:1.0
ID:SPEC-035Status:draft
Multi-Language Support
Version:1.0
ID:WORK-129Status:done
knownSections scanner integration: section-scoped refs and validation
Priority:mediumComplexity:moderate
ID:WORK-131Status:done
Update site docs and plan CLAUDE.md for plan package hardening changes
Priority:mediumComplexity:simple
ID:WORK-132Status:done
Convert plan content to machine-readable refs and adopt knownSections conventions
Priority:mediumComplexity:complex
ID:WORK-133Status:done
Mobile plan section navigation and desktop TOC filtering
Priority:mediumComplexity:moderate
Branches 3
claude/file-naming-convention-LJdwR current done
main donechangeset-release/main doneclaude/align-sidenav-styling-4MuxV blocked Summary
SPEC-021 defines named sections with aliases for work, bug, and decision runes. The current implementation uses a generic sections content model — any H2 heading creates a section, but headings aren't validated or aliased.
The knownSections feature would let content models declare expected section names and aliases, enabling:
- Validation: warn if a required section is missing (e.g., work item without "Acceptance Criteria")
- Aliases: "AC", "Criteria", "Done When" all map to "Acceptance Criteria"
- Templates: editor can suggest section names when authoring
Proposed Known Sections
work:
- Acceptance Criteria (aliases: Criteria, AC, Done When)
- Edge Cases (aliases: Exceptions, Corner Cases)
- Approach (aliases: Technical Notes, Implementation Notes, How)
- References (aliases: Refs, Related, Context)
- Verification (aliases: Test Cases, Tests)
bug:
- Steps to Reproduce (aliases: Reproduction, Steps, Repro)
- Expected (aliases: Expected Behaviour)
- Actual (aliases: Actual Behaviour)
- Environment (aliases: Env)
decision:
- Context
- Options Considered (aliases: Options, Alternatives)
- Decision
- Rationale (aliases: Reasoning, Why)
- Consequences (aliases: Impact, Trade-offs)
Acceptance Criteria
knownSectionssupported in the content model framework (packages/runes/src/content-model/)- Work rune declares known sections with aliases
- Bug rune declares known sections with aliases
- Decision rune declares known sections with aliases
- Alias matching is case-insensitive
- Unknown sections still pass through via
sectionModelfallback - Validation warns on missing required sections (if any declared as required)
- Tests for alias resolution and fallback behaviour
Dependencies
- SPEC-037 — accepted spec that defines the full knownSections design for plan runes
References
- SPEC-003 (Declarative Content Model — framework-level knownSections design)
- SPEC-021 (Plan Runes — section definitions for work/bug/decision)
- SPEC-037 (Plan Package Hardening — unblocks this work item)
Resolution
Completed: 2026-04-12
Branch: claude/spec-037-breakdown-docs-Whj40
What was done
- Added KnownSectionDefinition type to packages/types/src/content-model.ts
- Added knownSections field to SectionsModel interface
- Implemented matchKnownSection() in packages/runes/src/lib/resolver.ts
- Resolver adds $canonicalName to resolved sections when matched
- Declared knownSections for work (6 sections), bug (4 sections), decision (5 sections)