ss-tools/specs/041-dataset-lineage-blast-radius/checklists/requirements.md

Requirements Checklist: Dataset Lineage & Blast-Radius

Purpose: Validate spec.md completeness, clarity, and testability before /speckit.plan. Created: 2026-07-22 Feature: spec.md

Content Quality

• CHK001 Spec is user/operator-focused; storage/index implementation deferred to plan
• CHK002 All five stories independently testable with stated Independent Tests
• CHK003 Priorities assigned (US1–US3 P1, US4–US5 P2) with justification
• CHK004 Key entities defined without schema detail

Gap Coverage (BR-1..BR-5 from 036–039 analysis)

• CHK005 BR-1 (reverse index dataset→dashboards) → US1, LIN-FR-001..003, SC-001
• CHK006 BR-2 (cross-dashboard StructureDiff / schema-change classification) → US2, LIN-FR-004..006, SC-002
• CHK007 BR-3 (baseline invalidation single-release scoped) → US3, LIN-FR-007..008, SC-003/004
• CHK008 BR-4 (no fleet-wide trigger) → US5, LIN-FR-010..011, SC-005
• CHK009 BR-5 (C07 too narrow / dataset deprecation absent) → US4, LIN-FR-009, SC-006

Requirement Quality

• CHK010 Every FR testable (deterministic fingerprints, zero catalog writes, severity ordering, typed errors)
• CHK011 FR IDs hierarchical and stable (LIN-FR-001..015)
• CHK012 No [NEEDS CLARIFICATION] markers remain
• CHK013 Rejected paths recorded in header @REJECTED (QueryModel extension, query-time derivation, auto-invalidation)

Dependency Traceability

• CHK014 037 dependencies explicit: StructureDiff orthogonality (LIN-FR-006), immutability rules (LIN-FR-007), release pinning (LIN-FR-008)
• CHK015 036 dependencies explicit: approval-gate semantics for PROD fan-out (LIN-FR-014), permission_denied UX
• CHK016 040 integration explicit: blast-radius read model served from pinned index snapshot (LIN-FR-013)
• CHK017 039 integration explicit: FleetReport consumable without AgentRun (LIN-FR-011)
• CHK018 Trigger enum extension dataset_updated declared (LIN-FR-011) — requires amendment note to 036/037 at plan time

Safety & Risk

• CHK019 No silent mutation: propagation marks/reports only; catalog hash invariant verified (SC-003)
• CHK020 Stale-index handling: last-good retained, typed provenance, never empty-as-current (LIN-FR-003, SC-007)
• CHK021 Cycle safety: topological fan-out, typed lineage_cycle finding, zero hangs (LIN-FR-015, SC-005)
• CHK022 Environment scoping: cross-env propagation warns env_mismatch, never assumes (LIN-FR-012)

Success Criteria

• CHK023 All SC measurable (100% dependents, 100% classification agreement, zero writes, ordering, zero hangs)

Clarifications Integrated (2026-07-22)

• CHK028 Graph model corrected: two-level dataset←chart←dashboard, no SQL-source lineage, cycles removed (LIN-FR-015 rewritten)
• CHK029 Usage extraction = C+2 hybrid: structured params exact per viz_type + sqlglot SQL-expression analysis with unresolved_refs findings and per-expression conservative fallback (LIN-FR-016/017, SC-008)
• CHK030 Severity Matrix v1 accepted as defaults (11 rules incl. widening=info, rename=warning+hint) — LIN-FR-004 amended
• CHK031 Refresh rides existing IdMappingService.sync_environment cycle (migration_sync_cron + sync-now); no dedicated scheduler; post-sync hook bounded to changed uuids; opt-in lineage_index_enabled default false (LIN-FR-002/018/019)

Open Items (deferred to /speckit.plan)

• CHK024 Index storage model (edges table alongside ResourceMapping vs derived cache) — plan-time research; cadence CLOSED via CHK031 (rides sync_environment cycle)
• CHK025 Classification rules versioning scheme — CLOSED: Severity Matrix v1 accepted; rule changes require version bump + new golden fixtures (clarification Q3)
• CHK026 Amendment mechanics for 036/037 trigger enum + 040 read-model contract — plan-time coordination
• CHK027 Derived-dataset (SQL-query datasets) lineage source — CLOSED: out of scope, graph is two-level binding graph (clarification Q1)