Skip to content

fix(workbench): reconcile traceability for implementing-domain-driven-design and refactoring-guru #4

Description

@rxavier1979

Refs #1. Blocks #6 — rule IDs cannot be surfaced from a mapping that does not reconcile.

Status: diagnosed 2026-08-20, not started.

Verified: 12 of 14 books reconcile exactly. Two do not, and the mismatch is bidirectional in both.

Not verified: which specific bullets lack IDs and which IDs are orphaned. The sweep counted; it did not diff line-by-line. The first task on this issue is that diff.

The central fact

Book Section Traceability IDs Released bullets Delta
implementing-domain-driven-design Decision rules 18 19 1 bullet has no ID
implementing-domain-driven-design Trigger rules 12 10 2 IDs are orphaned
refactoring-guru Decision rules 24 24 OK
refactoring-guru Trigger rules 20 14 6 IDs are orphaned

Orphaned IDs mean rules were removed from mini.md without updating traceability.md — exactly the drift PROCESS.md "Traceability Rules" exists to prevent.

These are the only content-level defects found anywhere in the corpus. Everything else that failed a check is mechanical (line endings, symlinks) or absent (NOTICE, self-governance files).

Goal

Every released mini rule maps to exactly one M* id, and every M* id maps to exactly one released rule, in all 14 books.

Decisions (settled 2026-08-20)

# Decision Rationale
1 Diff before editing — enumerate the unmapped bullets and orphaned IDs explicitly, and post them as a comment on this issue before any file changes The counts say that it is broken, not what is broken. Editing on a count is guessing.
2 An orphaned ID is retired, never renumbered PROCESS.md treats IDs as stable references. Renumbering silently invalidates every external citation. Record as retired (rule removed <date>).
3 An unmapped bullet gets the next unused id, not a gap-filling one Same reason. implementing-domain-driven-design currently tops out at M28, so the new one is M29.
4 This is a book-specific miss, not a process bug PROCESS.md already required reconciliation; the process is correct and was not followed. Per its own "Process vs Book Diagnosis" section, that means fix the books and do not amend PROCESS.md.

Acceptance

  • the specific unmapped bullets and orphaned IDs are enumerated in a comment before any edit
  • 14/14 books reconcile: decision-IDs == decision-bullets, trigger-IDs == trigger-bullets
  • retired IDs are recorded as retired, not reused
  • rules_lint.py checks 1 and 2 catch a reintroduced mismatch
  • decision-log 0004 — Rule IDs are stable references: orphans retire, they never renumber

Reproduction

# per book: count unique `M\d+` in _rule-workbench/<book>/traceability.md,
# split by the "Decision rules:" / "Trigger rules:" subsections,
# and compare against "- " bullets under the matching H2 in <book>/<book>.mini.md

The sweep script that produced the table above is attached to #5.

Metadata

Metadata

Assignees

Labels

bugSomething isn't workingcorpusRule content, traceability, IDswave:1Wave 1 — foundations

Type

No type

Projects

No projects

Milestone

No milestone

Relationships

None yet

Development

No branches or pull requests

Issue actions