spec(044): record BulkOperationRun decision

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
 

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`.