TenantAtlas/specs/051-entra-group-directory-cache/checklists/pr-gate.md

# PR Gate Checklist: Entra Group Directory Cache (Groups v1)

**Purpose**: PR review gate to validate that the *requirements* in `spec.md` are complete, clear, consistent, measurable, and cover key scenarios for Groups v1.
**Created**: 2026-01-11
**Feature**: specs/051-entra-group-directory-cache/spec.md

**Note**: This checklist is generated by the `/speckit.checklist` command based on feature context and requirements.

## Requirement Completeness

- [x] CHK001 Are manual and scheduled start modes explicitly specified as in-scope (and not deferred)? [OK, Evidence: Spec §FR-004b, Spec §Pinned Decisions (v1 defaults)]
- [x] CHK002 Are the cached data fields (metadata-only) explicitly enumerated (e.g., displayName, groupTypes, securityEnabled/mailEnabled) rather than described generically? [OK, Evidence: Spec §FR-001a]
- [x] CHK003 Is the full-tenant scope of enumeration explicitly stated as the v1 source of truth (and not “referenced-only”)? [OK, Evidence: Spec §Clarifications, Spec §FR-004a]
- [x] CHK004 Are retention and purge requirements fully specified, including the retention start point and purge trigger? [OK, Evidence: Spec §FR-005a]
- [x] CHK005 Are audit trail requirements defined beyond “auditable” (what is recorded, where it is visible, minimum fields)? [OK, Evidence: Spec §FR-009a]
- [x] CHK006 Are authorization requirements defined for who may (a) browse groups, (b) trigger sync, (c) view run details? [OK, Evidence: Spec §Authorization & Access (Groups v1)]

## Requirement Clarity

- [x] CHK007 Is “periodic schedule” quantified with an explicit default cadence and configuration surface (per-tenant vs global)? [OK, Evidence: Spec §FR-004b (configurable per environment), Spec §Pinned Decisions (v1 defaults)]
- [x] CHK008 Is “deterministic selection identifier” defined with an unambiguous string/format and stability rules (per tenant + scope versioning)? [OK, Evidence: Spec §FR-004]
- [x] CHK009 Is “deduplicated” behavior specified (e.g., reject/skip when an active run exists; idempotency window), rather than implied? [OK, Evidence: Spec §User Story 1 Acceptance #6, Plan §Idempotency & Concurrency]
- [x] CHK010 Is “stale” defined with a specific comparison rule (e.g., $lastSeenAt < now - N days) and timezone/clock assumptions? [OK, Evidence: Spec §Clarifications (UTC everywhere), Spec §FR-005]
- [x] CHK011 Is the “unresolved fallback” label format and truncation rule specified consistently (e.g., last 8 chars, ellipsis placement)? [OK, Evidence: Spec §User Story 3 Acceptance #1–#2]
- [x] CHK012 Is “no live directory calls during render” defined operationally (what counts as render-time, allowed background refresh vs forbidden UI-triggered calls)? [OK, Evidence: Spec §FR-006a]

## Requirement Consistency

- [x] CHK013 Do the Clarifications (app-only auth, metadata-only, full scope) align with the Functional Requirements without contradiction? [OK, Evidence: Spec §Clarifications, Spec §FR-001a, Spec §FR-004a, Spec §FR-011a]
- [x] CHK014 Are the acceptance scenarios for US1 aligned with FR-003 (async only) and FR-002 (run record), without missing a required attribute? [OK, Evidence: Spec §User Story 1 Acceptance, Spec §FR-002, Spec §FR-003]
- [x] CHK015 Do US2 filters (stale) align with FR-005 and FR-007 (what filters are mandatory vs optional)? [OK, Evidence: Spec §User Story 2 Acceptance, Spec §FR-005, Spec §FR-007]
- [x] CHK016 Is the “read-only to Entra” rule consistent across spec (no implied writes or membership reads)? [OK, Evidence: Spec §FR-001, Spec §FR-001a]
- [ ] CHK017 Are success criteria thresholds consistent with scope and constraints (e.g., SC-003 95% resolution vs metadata-only cache + tenant scope)? [Consistency, Spec §SC-003, Spec §FR-001a, Spec §FR-004a]

## Acceptance Criteria Quality

- [ ] CHK018 Are acceptance scenarios written with objective outcomes (observable run record fields, counts, timestamps), not subjective terms? [Measurability, Spec §User Story 1 Acceptance]
- [x] CHK019 Do acceptance scenarios specify what constitutes “partial” completion vs “failed” (and expected operator-visible fields)? [OK, Evidence: Spec §FR-002a, Spec §FR-011]
- [x] CHK020 Are the success criteria (SC-001..SC-004) measurable with defined measurement method and scope (which pages, which tenants, sampling window)? [OK, Evidence: Spec §Success Criteria → Measurable Outcomes (SC-001..SC-004)]
- [ ] CHK021 Is the staleness default (N=30) defined as a requirement and stated as configurable (including configuration boundary: env/tenant)? [Measurability, Spec §FR-005]

## Scenario Coverage

- [x] CHK022 Are the primary flows covered end-to-end: start sync → run record → cache updated → browse/search → resolve label? [OK, Evidence: Spec §User Story 1–3 Acceptance]
- [x] CHK023 Are scheduled-run scenarios fully defined beyond cadence (initiator identity, operator visibility, and dedupe rules), rather than only mentioned? [OK, Evidence: Spec §Scheduled Sync Semantics (SS-001..SS-003), Spec §User Story 1 Acceptance #5–#7]
- [x] CHK024 Are multi-tenant isolation scenarios explicitly addressed (prevent cross-tenant reads in browse and label resolution)? [OK, Evidence: Spec §FR-010, Spec §Authorization & Access (Groups v1)]
- [x] CHK025 Are “no prior sync” scenarios specified (empty cache UI/labels, guidance to run sync)? [OK, Evidence: Spec §User Story 2 Acceptance #3, Spec §User Story 3 Acceptance #4]

## Edge Case Coverage

- [x] CHK026 Are throttling/partial results requirements specified with concrete behavior (retry/backoff, max duration, run status outcome)? [OK, Evidence: Spec §FR-011b, Spec §Edge Cases, Spec §CR-002a, Spec §FR-002a]
- [x] CHK027 Are permission-missing scenarios specified with operator-facing guidance (what the UI shows, what operators should do) beyond a stable error categorization? [OK, Evidence: Spec §FR-011c, Spec §Edge Cases]
- [x] CHK028 Is the behavior specified when a group disappears and later reappears within the 90-day window (last_seen update vs new record)? [OK, Evidence: Spec §FR-005b, Spec §FR-005a]
- [x] CHK029 Is paging/large-tenant behavior specified with bounding rules (max pages, safety stop, counters semantics)? [OK, Evidence: Spec §CR-002a, Spec §FR-002b]

## Non-Functional Requirements

- [ ] CHK030 Are performance requirements quantified for large tenants (sync duration, DB query latency, UI list responsiveness)? [Gap, Spec §Edge Cases, Spec §Technical Context]
- [ ] CHK031 Are logging/observability requirements defined (what to log, redaction rules, correlation IDs) for sync runs? [Gap, Spec §FR-009, Spec §FR-011]
- [x] CHK032 Are data minimization and privacy constraints explicitly stated for cached group metadata (e.g., no PII beyond displayName)? [OK, Evidence: Spec §FR-001a, Spec §Pinned Decisions (v1 defaults) Scope boundary]
- [ ] CHK033 Are accessibility requirements specified for the “Directory → Groups” UI (keyboard, table filtering, screen reader labels) if UI is in scope? [Gap, Spec §US2]

## Dependencies & Assumptions

- [x] CHK034 Are external dependencies explicitly pinned: required Graph permissions (e.g., Group.Read.All), endpoint family, and version (v1.0/beta)? [OK, Evidence: Spec §Pinned Decisions (v1 defaults), Spec §FR-011a, Spec §Contract Requirements]
- [ ] CHK035 Are Graph contract registry requirements sufficiently specific (contract key/name, allowed selects, expected fields) to be implementable without guesswork? [Completeness, Spec §Contract Requirements]
- [ ] CHK036 Are operational prerequisites specified (queue worker, scheduler/cron, retention job timing) including what happens if they’re missing? [Gap, Spec §Assumptions, Spec §US1 Acceptance]

## Ambiguities & Conflicts

- [ ] CHK037 Is the scope of “name resolution across the suite” explicitly bounded (which modules/pages are in v1 vs future)? [Completeness, Spec §Out of Scope (Groups v1)]
- [ ] CHK038 Is the relationship between cached group data and the existing live Graph-based resolution behavior explicitly defined (migration/transition expectations)? [Gap, Spec §FR-006, Spec §FR-008]
- [x] CHK039 Are error categories defined as an explicit controlled vocabulary (permission/throttling/transient/unknown) with mapping criteria? [OK, Evidence: Spec §FR-011]

## Notes

- Mark items as complete: `[x]`
- Use inline notes to capture identified gaps and propose spec edits
- This PR gate validates requirements quality (not implementation)