diff --git a/specs/044-drift-mvp/checklists/requirements.md b/specs/044-drift-mvp/checklists/requirements.md index 5e432f1..04dab55 100644 --- a/specs/044-drift-mvp/checklists/requirements.md +++ b/specs/044-drift-mvp/checklists/requirements.md @@ -6,28 +6,28 @@ # Specification Quality Checklist: Drift MVP (044) ## Content Quality -- [ ] No implementation details (languages, frameworks, APIs) -- [ ] Focused on user value and business needs -- [ ] Written for non-technical stakeholders -- [ ] All mandatory sections completed +- [ ] No implementation details (languages, frameworks, APIs) (T002) +- [x] Focused on user value and business needs (spec.md: Purpose, User Scenarios & Testing, Success Criteria) +- [ ] Written for non-technical stakeholders (T002) +- [x] All mandatory sections completed (spec.md includes Purpose, Scenarios, FR/NFR, Success Criteria, Out of Scope) ## Requirement Completeness -- [ ] No [NEEDS CLARIFICATION] markers remain -- [ ] Requirements are testable and unambiguous -- [ ] Success criteria are measurable -- [ ] Success criteria are technology-agnostic (no implementation details) -- [ ] All acceptance scenarios are defined -- [ ] Edge cases are identified -- [ ] Scope is clearly bounded -- [ ] Dependencies and assumptions identified +- [x] No [NEEDS CLARIFICATION] markers remain (spec.md: no "[NEEDS CLARIFICATION]" markers) +- [x] Requirements are testable and unambiguous (spec.md: FR1–FR4; tasks.md defines tests for key behaviors T015–T018, T024–T025, T029–T030, T035, T038) +- [x] Success criteria are measurable (spec.md: SC1 "under 3 minutes", SC2 deterministic consistency) +- [x] Success criteria are technology-agnostic (no implementation details) (spec.md: SC1–SC2) +- [x] All acceptance scenarios are defined (spec.md: Scenario 1/2/3) +- [x] Edge cases are identified (spec.md: <2 runs blocked state; generation failure explicit error state; acknowledgement per comparison) +- [x] Scope is clearly bounded (spec.md: FR2b + Out of Scope) +- [x] Dependencies and assumptions identified (spec.md: Dependencies / Name Resolution; NFR2; "No render-time Graph calls") ## Feature Readiness -- [ ] All functional requirements have clear acceptance criteria -- [ ] User scenarios cover primary flows -- [ ] Feature meets measurable outcomes defined in Success Criteria -- [ ] No implementation details leak into specification +- [x] All functional requirements have clear acceptance criteria (spec.md: FR1–FR4 + Scenario 1/2/3) +- [x] User scenarios cover primary flows (spec.md: Scenario 1/2/3) +- [ ] Feature meets measurable outcomes defined in Success Criteria (T022, T023, T026, T027, T031, T033, T035) +- [ ] No implementation details leak into specification (T002) ## Notes diff --git a/specs/044-drift-mvp/spec.md b/specs/044-drift-mvp/spec.md index 27031cb..a3a2a61 100644 --- a/specs/044-drift-mvp/spec.md +++ b/specs/044-drift-mvp/spec.md @@ -28,6 +28,10 @@ ### Session 2026-01-13 - Q: What is the default UI behavior for `new` vs `acknowledged` findings? → A: Default UI shows only `new`; `acknowledged` is accessible via an explicit filter. - Q: What should the UI do if drift generation fails for a comparison? → A: Show an explicit error state (safe message + reference/run ids) and do not show findings for that comparison until a successful generation exists. +### Session 2026-01-14 + +- Q: How should Drift track generation status/errors/idempotency for a comparison? → A: Use `BulkOperationRun` as the canonical run container (status, failures, idempotency_key, and consistent UI/ops patterns). + ## Pinned Decisions (MVP defaults) - Drift is implemented as a generator that writes persisted Finding rows (not only an in-memory/on-demand diff). @@ -37,6 +41,7 @@ ## Pinned Decisions (MVP defaults) - Drift MVP only uses `finding_type=drift` and `status` in {`new`, `acknowledged`}. - Default severity: `medium` (until a rule engine exists). - UI must not perform render-time Graph calls. Graph access (if any) is limited to background sync/jobs. +- Drift generation is tracked via `BulkOperationRun` to persist status/errors across refresh and to enforce idempotency per (tenant, scope_key, baseline_run_id, current_run_id). ## Key Entities / Generic Findings (Future-proof) @@ -101,6 +106,7 @@ ## Functional Requirements - Findings cover adds, removals, and changes for supported entities (Policies + Assignments). - MVP `change_type` values: `added`, `removed`, `modified`. - Findings are deterministic: same baseline/current + scope_key ⇒ same set of fingerprints. + - Drift generation must be tracked via `BulkOperationRun` with an idempotency key derived from (tenant_id, scope_key, baseline_run_id, current_run_id). - If fewer than two successful inventory runs exist for a given `scope_key`, Drift does not generate findings and must surface a clear blocked/empty state in the UI. - FR2a: Fingerprint definition (MVP) @@ -114,7 +120,7 @@ ## Functional Requirements - FR3: Provide Drift UI with summary and details. - Default lists and the Drift landing summary show only `status=new` by default. - The UI must provide a filter to include `acknowledged` findings. - - If drift generation fails for a comparison, the UI must surface an explicit error state (no secrets), including reference identifiers (e.g., run ids), and must not fall back to stale/previous results. + - If drift generation fails for a comparison, the UI must surface an explicit error state (no secrets), including reference identifiers (e.g., run ids and the `BulkOperationRun` id), and must not fall back to stale/previous results. - FR4: Triage (MVP) - Admin can acknowledge a finding; record `acknowledged_by_user_id` + `acknowledged_at`.