WORK-443
ID:WORK-443Status:done

Directional dependency model + cycle-check fix + migration

Implement SPEC-114: give plan work/bug dependencies a direction so the validator's cycle detection stops firing on prose cross-references. Today checkCircularDeps builds its graph from every {% ref %} in an entity (e.refs) with no direction, producing 88 false-positive circular-dependency errors across ~35 mostly-done items.

Priority:mediumComplexity:moderateMilestone:v0.28.0Source:SPEC-114
claude/milestone-v0-28-0-llvtfa View source

Criteria completion

Criteria completion: 8 of 8 (100%) checked; tracking started on Jul 9, no incremental history yet0%25%50%75%100%Jul 9Jul 11

Tracking started Jul 9 — check back for trends.

Relationships

Implements 1
Related 1
Branches 3
claude/milestone-v0-28-0-llvtfa current done
claude/plan-runes-status-vocab-jcq1tx readymain readyclaude/v0.25.0-planning-dipbrf ready
History 3
  1. c731b69
    Created (done)by bjornolofandersson
  2. 9a519fd
    Content editedby Claude
    plan: add v0.28.0 plan-model-hardening milestone and work breakdown
  3. 076b5f6
    Content editedby Claude
    plan: spec the directional dependency model (SPEC-114, WORK-443)

Acceptance Criteria

  • KNOWN_SECTIONS (work + bug) defines directed Blocked by and Blocks sections with aliases; Dependencies retained as a deprecated alias of Blocked by
  • PlanEntity carries typed, directed dependency edges derived only from those sections (not the raw ref set)
  • checkCircularDeps builds its adjacency map from the typed edges; prose / References / source-line refs no longer create edges
  • plan validate on the current corpus reports 0 circular-dependency errors
  • A test fixture with a genuine directed deadlock is still reported as an error
  • refrakt plan migrate dependencies renames legacy ## Dependencies sections (dry-run default, --apply/--git) and reports — without auto-flipping — reverse-direction entries for manual review
  • pipeline.ts dependency rollups consume the same typed edges (single source of truth)
  • Docs updated: CLAUDE.md Plan section + plan-plugin authoring docs describe the directed model and migration command

Approach

The scanner already produces scopedRefs: { id, section }[] and KNOWN_SECTIONS already maps a Dependencies section with a blocked by alias — the plumbing is mostly present. The work:

  1. scanner-core.ts — add Blocked by / Blocks canonical sections + aliases; derive a typed dependencies array (normalised to A → B = "A blocked by B") on PlanEntity from scopedRefs, reversing Blocks entries.
  2. validate.ts — repoint checkCircularDeps from e.refs to the typed edges.
  3. pipeline.ts — switch the existing scopedRefs dependency rollup to the typed edges.
  4. migrate — add a dependencies subcommand alongside migrate filenames.
  5. docs — CLAUDE.md + authoring docs.

References

  • SPEC-114 — the spec
  • WORK-132 — earlier work that added the ## Dependencies sections this supersedes

Resolution

Completed: 2026-07-09

Branch: claude/milestone-v0-28-0-llvtfa PR: refrakt-md/refrakt#565

What was done

  • scanner-core: directed Blocked by / Blocks sections (+ aliases); Dependencies retained as deprecated alias. Typed dependencies edges on PlanEntity; buildBlockedByAdjacency normaliser.
  • validate checkCircularDeps, next, render-pipeline, and pipeline rollups all consume the typed edges. Corpus: 88 → 0 circular errors.
  • refrakt plan migrate dependencies (CLI + MCP) renames legacy headings and flags reverse entries for manual review.
  • Corrected 3 genuinely reverse-modelled items (WORK-007/185/298) → ## Blocks. Versioned the scan cache.

Notes

  • Docs in CLAUDE.md + plan workflow. Did not mass-run the migration on the 324 legacy ## Dependencies headings — the alias keeps them parsing and a bulk rename would be noise; the 3 that formed real cycles were fixed by hand.