WORK-024
ID:WORK-024Status:done

Add knownSections to Plan Rune Content Models

Priority:mediumComplexity:moderateSource:SPEC-003,SPEC-021,SPEC-037
main View source

Criteria completion

Criteria completion: 8 of 8 (100%) checked; history from Mar 22 to Apr 120%25%50%75%100%Mar 22Apr 12

Relationships

Implements 3
Related 6
Branches 3
main current done
claude/file-naming-convention-LJdwR donechangeset-release/main doneclaude/align-sidenav-styling-4MuxV blocked
History 5
  1. e900a90
    Created (done)by bjornolofandersson
  2. a295513
    • ☑ `knownSections` supported 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 `sectionModel` fallback
    • ☑ Validation warns on missing required sections (if any declared as required)
    • ☑ Tests for alias resolution and fallback behaviour
    by Claude
  3. 1676387
    Content editedby Claude
  4. f262d7b
    Content editedby Claude
  5. 3fc7634
    Created (blocked)by Claude
    Add work items for remaining SPEC-021 plan runes gaps

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

  • knownSections supported 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 sectionModel fallback
  • 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)