WORK-129
ID:WORK-129Status:done

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.

Priority:mediumComplexity:moderateSource:SPEC-037
changeset-release/main View source

Criteria completion

No incremental history — criteria tracking started on Apr 19.

Relationships

Implements 1
Related 4
Branches 2
changeset-release/main current done
main doneclaude/file-naming-convention-LJdwR done
History 3
  1. f2b3512
    Content editedby Claude
    Add {ID}-{slug}.md filename convention + migrate filenames subcommand
  2. a295513
    Content editedby Claude
    Mark all SPEC-037 work items done with acceptance criteria and resolutio
  3. 1676387
    Created (done)by Claude
    Accept SPEC-037 and break into work items; fix plan validation issues

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

  • WORK-024 — knownSections framework support and plan rune declarations must ship first

References

  • SPEC-037 — Plan Package Hardening (Part 3: scanner integration, dependency resolution)
  • SPEC-003 — Declarative Content Model (knownSections design)

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