WORK-129
ID:WORK-129Status:donePriority:mediumComplexity:moderateSource:SPEC-037

knownSections scanner integration: section-scoped refs and validation

Once knownSections are declared in the plan rune content models (WORK-024), the scanner and validator need to become section-aware. Today, refs are extracted from the entire file without knowing which section they belong to. With knownSections, refs get tagged with their canonical section name, enabling the next command to distinguish blocking dependencies from informational references.

Acceptance Criteria

  • Scanner extracts refs with their canonical section name (e.g., refs in "Dependencies" section tagged as dependency refs)
  • Alias resolution maps "Deps", "Depends On", "Blocked By", "Requires" to the canonical "Dependencies" section
  • Known section presence is reported per entity (which known sections are present/missing, using canonical names)
  • validate warns when a ready+ work item has no Acceptance Criteria section
  • validate warns when a confirmed+ bug has no Steps to Reproduce, Expected, or Actual section
  • validate warns when an accepted decision has no Context or Decision section
  • next command only treats refs in the Dependencies section as blockers (refs in References/Approach/etc. are informational)
  • Backward compatibility: files without known section headings continue working (all refs treated as potential blockers, same as today)
  • Tests for section-scoped ref extraction, alias resolution, and section-aware blocking

Dependencies

References

Resolution

Completed: 2026-04-12

Branch: claude/spec-037-breakdown-docs-Whj40

What was done

  • Added ScopedRef type and extractScopedRefs() to scanner
  • Scanner now reports knownSectionsPresent per entity
  • Validate checks required sections: AC for ready+ work, Steps/Expected/Actual for confirmed+ bugs, Context/Decision for accepted decisions
  • Next command uses section-aware blocking via knownSectionsPresent
  • 13 new tests across scanner, validate, and next test files

Relationships

Depends on

Dependency of

Implements

Related

History

  1. a295513
    statusdraft→done
    • ☑ Scanner extracts refs with their canonical section name (e.g., refs in "Dependencies" section tagged as dependency refs)
    • ☑ Alias resolution maps "Deps", "Depends On", "Blocked By", "Requires" to the canonical "Dependencies" section
    • ☑ Known section presence is reported per entity (which known sections are present/missing, using canonical names)
    • +6 more criteria
  2. 1676387
    Created (draft, medium, moderate, SPEC-037, plan, cli, content-model)