spec-kitty / spec-kitty/spec-kitty
Doctrine canonical-structure remediation, mission B2: DRG edge migration + extractor retirement
- Dominant language
- Python
- Stars
- 1.6k
- Forks
- 165
- Avg merge
- 14h 52m
- Merged PRs (30d)
- 303
Description
## Programme context
Part of a five-mission programme that closes one root cause behind four symptoms found while
fixing P0 #2934 and researching #2935: **the doctrine layer predates its own canonical model, and
nothing enforces the model that replaced it.** The programme was originally specced as a single
mission, [`doctrine-canonical-structure-remediation-01KYEYSD`](https://github.com/Priivacy-ai/spec-kitty/blob/main/kitty-specs/doctrine-canonical-structure-remediation-01KYEYSD/spec.md)
(`spec.md` is the requirements authority and carries the full FR→mission routing table; `plan.md`
carries the cost, the Phase 0 findings, and the ordering rationale in detail). At an estimated
28–43 agent-days and ~555–665 file touches, the operator ruled it too large for one pull request
and split it into five sequenced missions (A, B1, B2, C, D). This is mission **B2** — the largest
of the five.
Programme record: `docs/plans/3-2-x-milestone-roadmap.md`, section "Doctrine canonical-structure
remediation programme".
## Scope — mission `drg-edge-migration-extractor-retirement-01KYFV8C`
Moves all 774 doctrine relationships ("edges" in the doctrine relationship graph, or DRG) from
being computed by a Python script every time the doctrine graph is regenerated, to being written
down directly in checked-in YAML files (one authored file per doctrine kind, plus a generated
cache file rebuilt from those). Concretely:
- Migrates 559 relationship entries currently living as inline `references:` blocks (and four
sibling fields) inside 169 doctrine artefact files, into the new authored-edge format.
- Authors the remaining 215 relationships that today are computed rather than written down — the
`scope` relation (the seed of every governance-context resolution) plus mission-type, template,
curated, and calibrated relationships.
- Deletes both Python modules that currently compute relationships by hand
(`hand_authored_overlay.py` and the `_CURATED_ARTIFACT_EDGES` registry) and retires every
relationship-producing pass in `extractor.py` — node discovery (finding which doctrine files
exist) stays automatic; only relationship computation stops.
- Preserves the 68 hand-written rationale notes and 219 reference labels that exist today so they
are not silently lost in the move (labels become an `aliases` field on the 102 artefacts they
name).
- Carries a human review of 55 relationships that were inferred by a heuristic, so they are not
silently promoted into "this was always intentional."
- Proves the migration lost nothing: a committed before/after snapshot, a "does deleting this code
actually change anything" test for each computed pass, and a check that the doctrine content
used to build agent prompts is byte-for-byte identical before and after.
This mission is a same-surface bulk edit and carries its own `occurrence_map.yaml` guardrail
(required by DIRECTIVE_035) — the only one of the five missions that does.
## Requirement IDs owned (from the programme spec's routing table)
- **Functional**: FR-013, FR-014, FR-015, FR-016, FR-017, FR-018, FR-019, FR-024, FR-025, FR-026,
FR-027, FR-028
- **Non-functional**: NFR-002, NFR-005, NFR-006 (shared with B1), NFR-007, NFR-008, NFR-009,
NFR-010, NFR-011, NFR-013
- **Success criteria**: SC-006, SC-009, SC-010, SC-011, SC-012, SC-013, SC-014
## Cost estimate
11–14 agent-days, ~365–390 files touched — roughly two-thirds of the whole programme's file
count.
## Why the ordering matters
- **Depends on mission B1 landing first (blocked by #2949).** Two of the 774 relationships being
migrated here are the existing tension claims that B1 retires in favor of the new `impacts`
field. If this mission ran first, those two relationships would be migrated once under the
scheme B1 is about to replace, then migrated again — the same relationship touched twice for no
reason.
- **Also depends transitively on mission A** (A blocks B1 blocks B2) for the same silent-drop
guard rails B1 needs.
- **Must land before mission C.** Mission C authors brand-new doctrine content. The whole point of
this mission is that doctrine content is now supposed to declare its relationships directly in
checked-in files instead of relying on a script to infer them. C's new content needs to be
written the new way from the start, which only works once this mission's format exists.
## Cross-links
- Blocked by #2949 (mission B1)
- Blocks #2951 (mission C, test-quality doctrine series)
- Sub-issue of #2466 (Doctrine/Charter extensibility & pack ecosystem)
/cc @stijn-dejongh (charter tracker-ticket assignment rule)
Contributor guide
Assessment
This issue has not been assessed yet.