TenantAtlas/specs/153-evidence-domain-foundation/spec.md

Feature Specification: Evidence Domain Foundation

Feature Branch: 153-evidence-domain-foundation
Created: 2026-03-19
Status: Draft
Input: User description: "erstell den spec aus spec candidate der strategisch am besten ist als nächstes"

Spec Scope Fields (mandatory)

• Scope: workspace + tenant + canonical-view
• Primary Routes:
  • /admin/t/{tenant}/evidence as the tenant-scoped evidence inventory and snapshot surface
  • /admin/t/{tenant}/evidence/{snapshot} as the canonical evidence snapshot inspection route
  • Workspace-scoped evidence overview surfaces that summarize snapshot coverage across managed tenants without exposing foreign-tenant detail
  • Existing downstream consumers such as review-pack generation and future readiness/reporting flows that consume evidence snapshots rather than assembling raw artifacts ad hoc
• Data Ownership:
  • Tenant-owned: evidence snapshots, evidence completeness state, artifact references, generation metadata, and immutable historical evidence packages
  • Tenant-owned inputs: findings, stored reports, baseline posture summaries, operational health signals, and related tenant-governance artifacts that are curated into the evidence domain without changing their original systems of record
  • Workspace-owned: aggregate evidence overview filters, rollup summaries, and canonical-view presentation state that never persist foreign-tenant evidence as workspace-owned domain records
  • Downstream exports and stakeholder-facing reports remain separate consumers and are not redefined by this feature
• RBAC:
  • Workspace membership remains the prerequisite for any evidence-domain access
  • Tenant entitlement remains required to inspect tenant-scoped evidence detail
  • evidence.view permits listing and inspecting evidence snapshots within authorized scope
  • evidence.manage permits creating, refreshing, and expiring evidence snapshots
  • Non-members or users outside the relevant tenant scope remain deny-as-not-found; in-scope members lacking the required capability remain forbidden

For canonical-view specs, the spec MUST define:

• Default filter behavior when tenant-context is active: Tenant evidence lists and detail routes default to the routed tenant only. Workspace evidence overview surfaces may carry a tenant prefilter only when the operator explicitly navigates from tenant context, and that prefilter is limited to entitled tenants and remains removable from the shared canonical view.
• Explicit entitlement checks preventing cross-tenant leakage: Evidence queries, completeness summaries, filter options, snapshot labels, and artifact references must always be assembled after workspace and tenant entitlement checks. Unauthorized users must not learn whether another tenant has evidence gaps, artifacts, or snapshots.

User Scenarios & Testing (mandatory)

User Story 1 - Create an immutable evidence snapshot (Priority: P1)

As a governance operator, I want to capture the current evidence state for a tenant into one immutable snapshot, so that later exports, reviews, and audit conversations refer to a stable package instead of a moving collection of live records.

Why this priority: This is the foundation of the entire capability. Without immutable snapshots, every downstream review artifact remains ad hoc and non-reproducible.

Independent Test: Can be fully tested by generating a tenant evidence snapshot from existing findings, stored reports, and governance summaries, then changing the live source records and confirming the captured snapshot remains unchanged.

Acceptance Scenarios:

1. Given a tenant has findings, stored reports, and baseline-related governance signals, When an authorized operator creates an evidence snapshot, Then the system produces one immutable snapshot that records what evidence items were included and their completeness state at capture time.
2. Given a snapshot has already been created, When live findings or stored reports change later, Then the original snapshot remains unchanged and a new snapshot is required to reflect the newer evidence state.
3. Given required evidence inputs are partially missing, When a snapshot is created, Then the snapshot still completes and records explicit completeness gaps rather than pretending the evidence set is complete.

---

User Story 2 - Understand evidence completeness before downstream reporting (Priority: P1)

As a governance operator, I want to see which evidence dimensions are present, stale, or missing before I generate review outputs, so that downstream reports are based on known coverage instead of hidden gaps.

Why this priority: The evidence domain is only valuable if it exposes completeness clearly. Otherwise it becomes another opaque storage layer.

Independent Test: Can be fully tested by preparing tenants with complete, partial, and stale evidence inputs and confirming that the evidence surface reports the correct completeness and freshness state for each dimension.

Acceptance Scenarios:

1. Given a tenant has current findings and stored reports for all in-scope evidence dimensions, When the operator inspects evidence status, Then the tenant shows a complete evidence state for those dimensions.
2. Given one or more evidence dimensions are missing or stale, When the operator inspects evidence status or a snapshot detail view, Then the missing or stale dimensions are clearly identified with no false claim of readiness.
3. Given an operator opens a specific snapshot, When they inspect it, Then they can see which evidence dimensions were included, omitted, or incomplete at the time of capture.

---

User Story 3 - Reuse one evidence package across downstream consumers (Priority: P2)

As a product owner, I want review packs and future readiness/reporting surfaces to consume curated evidence snapshots instead of reassembling raw artifacts independently, so that evidence logic stays consistent across the product.

Why this priority: The strategic value is architectural reuse. If every downstream feature keeps rebuilding its own evidence assembly logic, the foundation does not actually exist.

Independent Test: Can be fully tested by generating a snapshot and verifying that downstream consumers resolve included evidence artifacts through the snapshot contract rather than directly reading live source artifacts for the same workflow.

Acceptance Scenarios:

1. Given a downstream export or readiness flow requests tenant evidence, When an eligible snapshot already exists, Then the downstream flow resolves evidence through the snapshot contract instead of rebuilding the same evidence set from scratch.
2. Given the operator needs refreshed evidence, When they explicitly request a new snapshot, Then the newer snapshot becomes available alongside older snapshots rather than mutating them in place.
3. Given two downstream consumers use the same snapshot, When they inspect included evidence dimensions, Then both consumers see the same inclusion and completeness truth.

Edge Cases

• A tenant has some evidence dimensions available and others never generated; the snapshot must be captured as partial rather than blocked indefinitely.
• A stored report or findings source is stale but still readable; the foundation must preserve freshness metadata instead of silently treating stale evidence as current.
• A source artifact referenced by an older snapshot is later deleted or superseded; the older snapshot must remain intelligible from stored snapshot metadata.
• An operator triggers snapshot creation twice in quick succession with unchanged inputs; the system must avoid creating duplicate immutable artifacts when the evidence state is unchanged.
• A workspace operator can view workspace-level evidence summaries but is not entitled to inspect every tenant represented in the workspace; unauthorized tenant detail must remain hidden.
• A downstream consumer requests evidence for a tenant with no snapshot yet; the system must fail with a clear absence state rather than silently falling back to untracked live assembly.

Requirements (mandatory)

Constitution alignment (required): This feature introduces a new evidence-domain data model, write behavior for immutable snapshot capture, and queued generation work that assembles evidence from existing internal artifacts only. It does not introduce new Microsoft Graph calls. The feature must define tenant isolation, completeness semantics, snapshot immutability, and run observability for snapshot generation. Because evidence capture is a high-value governance mutation, every snapshot creation and expiration path must be auditable and test-covered.

Constitution alignment (OPS-UX): This feature creates a new OperationRun family for evidence snapshot generation and must comply with the Ops-UX 3-surface feedback contract. Start actions may show intent-only feedback. Progress belongs only in the active-ops widget and Monitoring run detail. Evidence snapshot detail surfaces may link to the canonical run detail but must not render a parallel progress surface. Terminal notification behavior remains service-owned through OperationRunService. Any summary counts recorded for evidence snapshot generation must use allowed operation summary keys and numeric-only values. Scheduled or system-initiated snapshot generation must not create initiator-only terminal database notifications.

Constitution alignment (RBAC-UX): This feature operates in the tenant/admin plane for tenant-scoped evidence surfaces and in workspace-admin canonical views for cross-tenant evidence overview. Cross-plane access remains deny-as-not-found. Non-members or users outside workspace or tenant scope receive 404. In-scope users lacking evidence.view or evidence.manage receive 403 according to the action attempted. Authorization must be enforced server-side for snapshot generation, inspection, expiration, and any downstream evidence resolution entry point. The canonical capability registry remains the only capability source. Any destructive-like expiration action requires confirmation.

Constitution alignment (OPS-EX-AUTH-001): Not applicable. No authentication handshake behavior is changed.

Constitution alignment (BADGE-001): Evidence completeness, freshness, and snapshot status are status-like values and must use centralized badge semantics rather than local page-level color mapping. Tests must cover all newly introduced status values.

Constitution alignment (UI-NAMING-001): The target object is the evidence snapshot. Operator-facing verbs are Create snapshot, View snapshot, Refresh evidence, and Expire snapshot. Source/domain disambiguation is needed only where a snapshot references specific evidence dimensions such as findings, permission posture, or baseline posture. The same evidence vocabulary must be preserved across action labels, modal titles, run titles, notifications, and audit prose. Implementation-first terms such as materialize, denormalize, or projection rebuild must not become primary operator-facing labels.

Constitution alignment (Filament Action Surfaces): This feature adds a Filament evidence resource or page family for list and detail inspection plus snapshot-generation actions. The Action Surface Contract is satisfied if creation remains an explicit header action, list inspection uses a canonical inspect affordance, destructive expiration requires confirmation, and all mutations are authorization-gated and auditable.

Constitution alignment (UX-001 — Layout & Information Architecture): Evidence list screens must provide search, sort, and filters for core dimensions such as tenant, snapshot status, completeness state, and capture date. Snapshot detail must use an Infolist-style inspection surface rather than a disabled edit form. Empty states must include a specific title, explanation, and exactly one CTA. If snapshot creation uses a modal instead of a dedicated create page, that is an explicit exemption because snapshot creation is an operation trigger, not freeform data entry.

Functional Requirements

• FR-153-001: The system MUST provide a first-class evidence domain that curates existing governance artifacts into immutable evidence snapshots.
• FR-153-002: Each evidence snapshot MUST record the workspace, tenant, creation time, initiating actor class, included evidence dimensions, completeness state, and freshness metadata for each included dimension.
• FR-153-003: The first implementation slice MUST support at least findings summaries, permission posture evidence, Entra admin-role evidence, baseline or drift posture summaries, and one explicit operations_summary dimension composed from recent tenant-scoped OperationRun rollups relevant to downstream review-pack and readiness evidence.
• FR-153-004: Evidence snapshots MUST be immutable after successful creation. Refreshing evidence MUST create a new snapshot rather than mutating an existing one.
• FR-153-005: The system MUST capture evidence completeness explicitly, including complete, partial, missing, and stale states for each evidence dimension.
• FR-153-006: The system MUST allow snapshot creation to succeed when evidence is partial, provided the missing or stale dimensions are recorded clearly in snapshot metadata.
• FR-153-007: Evidence snapshot generation MUST use existing internal evidence sources and MUST NOT trigger live Microsoft Graph collection during snapshot creation.
• FR-153-008: The system MUST provide one canonical tenant-scoped evidence inventory surface where authorized operators can list snapshots and inspect their completeness and freshness state.
• FR-153-009: The system MUST provide a canonical snapshot inspection surface that shows included evidence dimensions, completeness state, freshness metadata, source references, and downstream readiness suitability.
• FR-153-010: Workspace-scoped evidence overview surfaces MUST summarize evidence availability and completeness across authorized tenants without revealing unauthorized tenant detail.
• FR-153-011: The system MUST define a deduplication rule for unchanged evidence state so that repeated snapshot requests with identical included evidence do not create unnecessary duplicate immutable artifacts.
• FR-153-012: The system MUST expose whether a downstream consumer is using a specific snapshot or whether no eligible snapshot exists for the requested evidence scope.
• FR-153-013: Downstream consumers in scope for this foundation MUST be able to resolve evidence through the snapshot contract instead of rebuilding the same evidence set directly from live source records.
• FR-153-014: The system MUST preserve enough snapshot metadata that an older snapshot remains intelligible even if one or more underlying source artifacts are later superseded, expired, or removed from active views.
• FR-153-015: The feature MUST define retention and lifecycle semantics for evidence snapshots, including active, superseded, and expired states.
• FR-153-016: Expiring an evidence snapshot MUST be an explicit, confirmed, auditable action and MUST NOT retroactively change what the snapshot contained.
• FR-153-017: Evidence snapshot generation and expiration MUST be recorded in audit history with workspace scope, tenant scope, actor, action, and outcome.
• FR-153-018: The feature MUST introduce at least one positive and one negative authorization test for evidence snapshot viewing and management.
• FR-153-019: The feature MUST introduce regression tests proving snapshot immutability, completeness-state accuracy, downstream consumer reuse, and cross-tenant isolation.

UI Action Matrix (mandatory when Filament is changed)

Surface	Location	Header Actions	Inspect Affordance (List/Table)	Row Actions (max 2 visible)	Bulk Actions (grouped)	Empty-State CTA(s)	View Header Actions	Create/Edit Save+Cancel	Audit log?	Notes / Exemptions
Evidence Snapshot List	Tenant-context evidence page or resource under /admin/t/{tenant}/evidence	Create snapshot (evidence.manage)	Clickable row to snapshot detail	View snapshot, Expire snapshot (evidence.manage, destructive)	None in v1	Create first snapshot	None	N/A	Yes	Create uses an action modal as an operation trigger, not a CRUD create page
Evidence Snapshot Detail	Canonical detail route under /admin/t/{tenant}/evidence/{snapshot}	Refresh evidence (evidence.manage)	N/A	None	None	N/A	Refresh evidence, Expire snapshot	N/A	Yes	Detail is an inspection surface and must use Infolist-style composition
Workspace Evidence Overview	Workspace-admin canonical evidence overview	Contextual filter actions only	Row or linked-card drill-down to authorized tenant evidence view	View tenant evidence	None	Clear filters	None	N/A	No direct mutation	Must suppress unauthorized tenant rows and filter options

Key Entities (include if feature involves data)

• Evidence Snapshot: An immutable, timestamped evidence package for one tenant within one workspace, capturing which evidence dimensions were included and how complete they were at a specific point in time.
• Evidence Dimension: A named evidence category such as findings summary, permission posture, baseline posture, or operational health summary that can be included, missing, stale, or partial in a snapshot.
• Evidence Source Reference: A structured reference to the underlying artifact or summary that supplied a given evidence dimension at snapshot time.
• Evidence Completeness State: The normalized assessment of whether the snapshot is complete, partial, missing required dimensions, or stale for downstream governance use.

Success Criteria (mandatory)

Measurable Outcomes

• SC-001: An authorized operator can create a tenant evidence snapshot and inspect its completeness state in under 2 minutes without leaving the product.
• SC-002: 100% of evidence snapshots created in automated tests remain unchanged after their underlying live source artifacts are modified.
• SC-003: Operators can identify missing or stale evidence dimensions for a tenant from the evidence surface in one inspection step, without manually cross-checking multiple source pages.
• SC-004: Repeated snapshot requests with unchanged evidence state do not create duplicate artifacts in automated deduplication tests.
• SC-005: Downstream consumers covered by the first rollout resolve evidence from the snapshot contract instead of rebuilding equivalent live evidence sets in automated integration tests.
• SC-006: Negative authorization tests prove that non-members receive deny-as-not-found behavior and in-scope users without the proper capability cannot create or expire evidence snapshots.

Assumptions

• Review pack export, permission posture, Entra admin-role evidence, findings workflow, and baseline or drift posture outputs are sufficiently mature to act as the first evidence-domain inputs.
• The first rollout focuses on internal evidence curation and inspection, not on stakeholder-facing readiness presentation.
• Evidence snapshot generation is DB-backed and can rely on existing stored or summarized artifacts rather than live recollection.
• The downstream consumer contract begins with one or more existing export or reporting flows and expands later.

Non-Goals

• Building executive, customer-facing, or framework-oriented readiness presentations
• Replacing review-pack export with a new export format
• Acting as a generic BI warehouse or arbitrary reporting engine
• Triggering new Microsoft Graph scans during snapshot creation
• Defining formal compliance certification claims or legal attestations