Skip to content
sdlc

T-SJH1-capability-drop-contains

Status: closed/done · Impact: medium · Complexity: small

Goal

Section titled “Goal”

Capability stores containment in both directions — parent_key up and contains down — with no consistency check between them; that is the same drift class as DarkFactory’s hand-maintained blocks inverse. Make parent_key the only stored direction and derive children (D-3PDM-cross-project-data-model-adoption P2, finding F5; D-7F2M-why-what-verify-chain “references point up”).

Proposed

Section titled “Proposed”

Capability schema v2 removes contains; a v1→v2 migration drops the key after verifying it matches the children’s parent_key inverses (MigrationError on mismatch); index/site/definition projections derive children by scanning parent_key. milestone.tasks stays a stored down-pointing member list — the documented exception recorded in D-3PDM-cross-project-data-model-adoption.

Downstream consumer note (2026-07-17): the SDF capability graph (Tier B, apps/sdlc/desktop/docs/ui-consolidation-plan.md) renders containment the same way — children derived by parent_key inversion; a parent_key referencing no existing instance renders as a ghost node, so dangling parents are a display state, not an error.

Acceptance criteria

Section titled “Acceptance criteria”
  • AC-1: capability schema v2 has no contains; SCHEMA_VERSION is “2”; HISTORICAL_KEY_ORDER matches.
  • AC-2: the v1→v2 migration drops contains only when consistent with the children’s parent_key; inconsistency raises MigrationError.
  • AC-3: all existing capability instances migrate clean and entities audit is green.
  • AC-4: generated docs/site still render capability children (derived from parent_key).
  • AC-5: capability/definition.md reflects the change; check_entities passes.

Out of scope

Section titled “Out of scope”
  • milestone.tasks (documented exception; revisiting it is an open question in D-3PDM-cross-project-data-model-adoption).
  • Task parent_key semantics (unchanged).

Dependencies

Section titled “Dependencies”
  • Shares capability/schema.ts with T-2KK8 — resolved 2026-07-17: one combined v2 bump; T-2KK8 hosts the migration, this task contributes the contains-consistency verification rule to it.

Discovery context

Section titled “Discovery context”
  • D-3PDM-cross-project-data-model-adoption P2 / finding F5: ontological authors containment on one side and derives the other (0/76 files carry the derived pointer); DarkFactory’s unchecked blocks inverse shows the failure mode.

← Back to Tasks