TenantAtlas/specs/422-exchange-teams-comparable-renderable-pack/spec.md

Feature Specification: Spec 422 - Exchange & Teams Comparable / Renderable Pack

Feature Branch: 422-exchange-teams-comparable-renderable-pack Created: 2026-06-28 Status: Draft Input: User-provided draft "Spec 422 - Exchange & Teams Comparable / Renderable Pack", prepared through spec-kit-next-best-prep.

Preparation Selection Summary

• Selected candidate: Spec 422 - Exchange & Teams Comparable / Renderable Pack.
• Source location: User-provided attachment /Users/ahmeddarrazi/.codex/attachments/664830db-b955-4f77-9a26-ef75ccc067d7/pasted-text.txt.
• Why selected: Specs 419, 420, and 421 establish the M365 Coverage v2 sequence: workload registry, generic evidence/blocker semantics, and Entra comparable/renderable precedent. The user-provided Spec 422 draft is the next explicit Exchange/Teams pack in that sequence.
• Roadmap relationship: Extends the Coverage v2 / M365 path after Specs 414, 415, 417, 418, 419, 420, and 421; aligns with the roadmap's anti-drift, Microsoft governance expansion, and operator-safe evidence interpretation direction.
• Close alternatives deferred: Security/Compliance readiness, certified packs, restore/apply, customer reports, Review Pack/PDF output, M365 dashboards, and source-contract/capture expansion are deferred because they require different claims, contracts, product surfaces, or risk controls.
• Completed-spec guardrail result: Specs 414, 415, 417, 418, 419, 420, and 421 are completed dependency context only. This package must not patch, normalize, reopen, or strip their implementation reports, completed tasks, validation results, or browser proof.
• Smallest viable implementation slice: Add evidence-gated typed compare/render support for selected Exchange and Teams Coverage v2 evidence rows, with transportRule, acceptedDomain, appPermissionPolicy, and meetingPolicy as the required first typed support set when content-backed evidence exists. Do not add capture/source contracts, restore, certification, customer output, or workload mini-platforms.
• Candidate Selection Gate: PASS for a directly provided candidate, with repo-truth scope reduction documented below.

Draft-To-Repo Deviations

The attached draft assumes Exchange and Teams generic content-backed evidence may already exist for selected types. Current repo evidence shows:

• Specs 419 and 420 intentionally registered Exchange/Teams representative resource types and missing-contract blockers.
• CoverageSourceContractResolver currently maps explicit capture contracts for selected Intune/Entra-adjacent types and explicitly blocks at least acceptedDomain and appPermissionPolicy as missing source contracts from Spec 420.
• The current repo does not prove live content-backed capture for transportRule, acceptedDomain, appPermissionPolicy, or meetingPolicy.
• The draft also says not to fake typed support and not to implement Graph/TCM capture when missing from Spec 420.

Therefore this spec keeps the draft intent but narrows implementation truth:

• Implement typed compare/render semantics only for existing or test-seeded content-backed evidence rows.
• Do not add or guess Exchange/Teams capture contracts, remote calls, TCM fetches, Graph endpoints, or source mappings in this spec.
• Do not promote registry defaults or customer claims when live content-backed evidence is absent.
• The implementation report must include an Exchange/Teams evidence matrix that names promoted evidence-backed rows and deferred live-capture blockers.

Spec Candidate Check (mandatory - SPEC-GATE-001)

• Problem: TenantPilot can recognize Exchange and Teams Coverage v2 resource types, but operators cannot safely understand or compare selected Exchange/Teams configuration evidence without raw payload reading when content-backed evidence is present.
• Today's failure: Exchange and Teams resource entries can exist as registry or blocked evidence context, but TenantPilot must not imply mail-flow, Teams policy, restore, certification, or customer-ready coverage before typed compare/render support and no-overclaim guardrails exist.
• User-visible improvement: Operators reviewing the existing Coverage v2 surface can understand selected Exchange/Teams configuration evidence through typed summaries and deterministic compare outcomes while broad Exchange, Teams, M365, restore, certification, and customer-ready claims remain blocked.
• Smallest enterprise-capable version: Support typed compare/render for transportRule, acceptedDomain, appPermissionPolicy, and meetingPolicy only when content-backed evidence rows exist; preflight the wider listed Exchange/Teams types and defer any missing-evidence or missing-contract type. No capture expansion, restore, certification, customer output, or new dashboard.
• Explicit non-goals: No Exchange restore/apply, no Teams restore/apply, no certification, no full Exchange/Teams catalog, no new Exchange/Teams-specific table family, no broad M365 coverage claims, no customer-facing report/review pack/PDF output, no new capture start action, no direct Graph/TCM calls during render/compare, no tenant_id, no v1 compatibility.
• Permanent complexity imported: Bounded typed normalization/compare/render helpers for selected Exchange/Teams resource types, derived compare importance labels, Claim Guard tests, redaction tests, and focused browser proof if rendered output changes. No new persisted entity, status family, runtime Product Surface framework, or mini-platform by default.
• Why now: Spec 421 proved the comparable/renderable pattern for selected Entra evidence. Exchange and Teams are the next high-value M365 governance domains, but they need strict no-overclaim boundaries before any future capture, certification, or customer-facing claim work.
• Why not local: A one-off Exchange/Teams UI parser would bypass Coverage v2 registry/evidence/identity/redaction/Claim Guard truth. The existing Coverage v2 path is the correct shared path.
• Approval class: Core Enterprise.
• Red flags triggered: New typed compare/render helpers and derived importance labels. Defense: the helpers are bounded to selected evidence-backed resource types, use existing Coverage v2 truth, and directly prevent unsafe operator interpretation and overclaiming.
• Score: Nutzen: 2 | Dringlichkeit: 2 | Scope: 2 | Komplexitaet: 1 | Produktnaehe: 2 | Wiederverwendung: 2 | Gesamt: 11/12
• Decision: approve as a narrowed, evidence-gated comparable/renderable pack.

Spec Scope Fields (mandatory)

• Scope: Workspace + managed-environment scoped Coverage v2 evidence and read-model behavior for selected Exchange and Teams resource types.
• Primary Routes: Existing internal/operator Coverage v2 readiness route workspaces/{workspace}/environments/{environment}/tenant-configuration/coverage-v2; no new route, navigation entry, customer route, report, download, or dashboard.
• Data Ownership: Existing TenantConfigurationResourceType, TenantConfigurationResource, and TenantConfigurationResourceEvidence records. Environment-owned rows remain scoped by workspace_id, managed_environment_id, and same-scope provider_connection_id where provider-sourced.
• RBAC: Existing Coverage v2 read authorization applies. Non-member workspace or missing managed-environment entitlement returns 404. Established member without evidence view capability returns 403. No mutating action is introduced.

For canonical-view specs:

• Default filter behavior when tenant-context is active: N/A - no new canonical route or route filter.
• Explicit entitlement checks preventing cross-tenant leakage: Existing page, widgets, read model, and any new compare/render service must resolve records through workspace + managed environment scope and must not use provider-native tenant IDs as ownership.

No Legacy / No Backward Compatibility Constraint (mandatory)

TenantPilot is pre-production unless this spec explicitly records a compatibility exception.

• Compatibility posture: canonical Coverage v2 extension; no compatibility exception.
• Legacy aliases, fallback readers, hidden routes, duplicate UI, old labels, or historical fixtures kept?: no.
• Why clean replacement is safe now: This is a new internal Coverage v2 compare/render slice over existing evidence. No production data or external contract requires legacy Coverage v1 adapters, fallback readers, dual writes, or old customer-facing coverage vocabulary.

UI Surface Impact (mandatory - UI-COV-001)

Does this spec add, remove, rename, or materially change any reachable UI surface?

• No UI surface impact
• Existing page changed
• New page/route added
• Navigation changed
• Filament panel/provider surface changed
• New modal/drawer/wizard/action added
• New table/form/state added
• Customer-facing surface changed
• Dangerous action changed
• Status/evidence/review presentation changed
• Workspace/environment context presentation changed

Impact is limited to data/rendering on the existing Coverage v2 internal/operator surface if implementation exposes comparable/renderable Exchange/Teams summaries or coverage-level rows. No new route, navigation, action, dashboard, customer output, report, download, restore, certify, or capture UI is allowed.

If implementation requires runtime UI edits beyond existing surface rendering, the implementation must keep this spec/plan/tasks aligned before editing runtime UI files.

UI/Productization Coverage (mandatory when UI Surface Impact is not "No UI surface impact"; otherwise write N/A - no reachable UI surface impact plus rationale)

• Route/page/surface: Existing Coverage v2 readiness page and inspect slide-over under apps/platform/app/Filament/Pages/TenantConfiguration/CoverageV2Readiness.php and apps/platform/app/Filament/Widgets/TenantConfiguration/*.
• Current or new page archetype: Technical Annex / internal operator registry and evidence inspection surface.
• Design depth: Internal/Hidden with Product Surface evidence/status guardrails.
• Repo-truth level: repo-verified existing surface.
• Existing pattern reused: Existing read-only Coverage v2 page, widgets, badge catalog, inspect slide-over, and read model.
• New pattern required: none by default.
• Screenshot required: focused browser proof required if rendered output changes.
• Page audit required: no new page audit unless a new route/navigation/surface is introduced, which is out of scope.
• Customer-safe review required: no customer-facing surface; customer-output gate must remain N/A/no output.
• Dangerous-action review required: no dangerous action.
• Coverage files updated or explicitly not needed:
  • docs/ui-ux-enterprise-audit/route-inventory.md
  • docs/ui-ux-enterprise-audit/design-coverage-matrix.md
  • docs/ui-ux-enterprise-audit/page-reports/...
  • docs/ui-ux-enterprise-audit/strategic-surfaces.md
  • docs/ui-ux-enterprise-audit/grouped-follow-up-candidates.md
  • docs/ui-ux-enterprise-audit/unresolved-pages.md
  • Existing internal page only; no new coverage artifact unless runtime UI scope expands.
• No-impact rationale when applicable: N/A.

Product Surface Impact (mandatory for UI-affecting specs; otherwise write N/A - no rendered product surface changed plus rationale)

Reference: docs/product/standards/product-surface-contract.md.

• Product Surface Contract applies?: yes, because evidence/status presentation may change on an existing rendered operator surface.
• Page archetype: Technical Annex / internal operator evidence inspection surface.
• Primary user question: Which selected Exchange/Teams resources are safely comparable/renderable, and what material changes or blockers require operator attention?
• Primary action: Inspect selected existing Coverage v2 evidence rows. No start, restore, certify, publish, export, or customer-output action.
• Surface budget result: pass by reusing the existing internal surface and not adding new page/action families.
• Technical Annex / deep-link demotion: OperationRun links, raw evidence IDs, source keys, payloads, provider IDs, identity diagnostics, permission context, and unsupported fields remain hidden, diagnostic, or secondary.
• Canonical status vocabulary: Product-facing labels must map to existing canonical wording or internal Coverage v2 labels. Do not display "Exchange covered", "Teams covered", "certified", "restore-ready", "customer-ready", "100% Exchange coverage", "100% Teams coverage", or "full M365 coverage".
• Visible complexity impact: neutral or decreased. Typed summaries should reduce raw-payload interpretation burden without adding a new surface.
• Product Surface exceptions: none.

Browser Verification Plan (mandatory)

• Browser proof required?: yes if rendered Coverage v2 output changes.
• No-browser rationale: N/A - no rendered UI surface changed is allowed only if implementation proves no rendered output changes.
• Focused path when required: Existing Coverage v2 readiness route for a seeded workspace/managed environment with selected content-backed Exchange/Teams evidence rows.
• Primary interaction to execute: Load the page, inspect selected Exchange/Teams rows, verify comparable/renderable state and operator summary, and verify no raw payload, secrets, restore/certify/customer-ready claim, or console/Livewire error.
• Console, Livewire, Filament, network, and 500-error checks: required for focused path when rendered data changes.
• Full-suite failure triage: unrelated failures may be documented only after focused proof is green.

Human Product Sanity Check (mandatory)

• Required?: yes if rendered output changes.
• No-human-sanity rationale: N/A only when no rendered product surface changes.
• Reviewer questions: Is the summary understandable without raw payload? Is it clear this is selected Exchange/Teams comparable/renderable support, not certification or restore readiness? Are diagnostics demoted? Is there one obvious inspect path and no high-impact action?
• Planned result location: specs/422-exchange-teams-comparable-renderable-pack/implementation-report.md.

Product Surface Merge Gate Checklist (mandatory)

• No-legacy posture or approved exception recorded.
• Product Surface Impact is completed for existing-surface evidence/status rendering.
• Browser proof is required if rendered output changes, or N/A - no rendered UI surface changed must be justified.
• Human Product Sanity is required if rendered output changes, or N/A must be justified.
• Product Surface exceptions are documented as none.
• Implementation report will state Livewire v4 compliance, provider registration location, global search posture, destructive/high-impact action posture, asset strategy, tests/browser result, deployment impact, visible complexity outcome, and completed-spec rewrite assertion.

Cross-Cutting / Shared Pattern Reuse (mandatory when the feature touches notifications, status messaging, action links, header actions, dashboard signals/cards, alerts, navigation entry points, evidence/report viewers, or any other existing shared operator interaction family; otherwise write N/A - no shared interaction family touched)

• Cross-cutting feature?: yes, evidence/status/rendering and Claim Guard behavior.
• Interaction class(es): evidence inspection, coverage-level/status display, compare summaries, diagnostic detail demotion.
• Systems touched: Existing Coverage v2 registry/resource/evidence models, generic normalizer/redactor, identity resolver, Claim Guard, badge catalog/read model if rendered, and focused tests.
• Existing pattern(s) to extend: Coverage v2 resource/evidence/read model, BadgeCatalog/BadgeRenderer, ClaimGuard, and existing read-only Filament surface.
• Shared contract / presenter / builder / renderer to reuse: Existing Coverage v2 paths. Any Exchange/Teams typed helpers must remain bounded adapters under the existing Tenant Configuration service boundary.
• Why the existing shared path is sufficient or insufficient: It already owns evidence, source metadata, identity, claim state, redaction, read authorization, and the existing operator surface. It lacks typed compare/render behavior for selected Exchange/Teams payloads.
• Allowed deviation and why: Bounded Exchange/Teams typed helpers are allowed because raw generic payloads cannot safely support operator comparison. They must not become a generic provider framework or separate Exchange/Teams engine.
• Consistency impact: Compare/render state must align with existing coverage levels, evidence states, identity states, claim states, badge labels, RBAC behavior, and Product Surface demotion.
• Review focus: No raw-payload default display, no customer claims, no restore/certify action, no mini-platform, no new tables, no tenant_id, no endpoint guessing.

OperationRun UX Impact (mandatory when the feature creates, queues, deduplicates, resumes, blocks, completes, or deep-links to an OperationRun; otherwise write N/A - no OperationRun start or link semantics touched)

• Touches OperationRun start/completion/link UX?: no new start/completion/link UX.
• Shared OperationRun UX contract/layer reused: N/A by default. Existing evidence rows may retain existing OperationRun references as diagnostics only.
• Delegated start/completion UX behaviors: N/A - no queued operation is introduced.
• Local surface-owned behavior that remains: inspect existing evidence only.
• Queued DB-notification policy: N/A - no new queued notification.
• Terminal notification path: N/A - no new OperationRun lifecycle.
• Exception required?: none. If compare/render becomes long-running or persisted as an operation, stop and amend this spec first.

Provider Boundary / Platform Core Check (mandatory when the feature changes shared provider/platform seams, identity scope, governed-subject taxonomy, compare strategy selection, provider connection descriptors, or operator vocabulary that may leak provider-specific semantics into platform-core truth; otherwise write N/A - no shared provider/platform boundary touched)

• Shared provider/platform boundary touched?: yes.
• Boundary classification: mixed. Coverage v2 evidence/resource/claim/read-model truth is platform-core; Exchange/Teams resource semantics and Microsoft 365 field names are provider-owned typed adapters.
• Seams affected: compare strategy selection, typed normalization/render fields, redaction rules, coverage-level promotion, Claim Guard wording, and existing operator surface rendering.
• Neutral platform terms preserved or introduced: workspace, managed environment, provider connection, resource type, evidence state, coverage level, identity state, claim state, compare result, render summary.
• Provider-specific semantics retained and why: Exchange/Teams resource names and fields are necessary for current operator meaning, but must stay inside bounded typed mapping/helpers and source metadata.
• Why this does not deepen provider coupling accidentally: No provider-native tenant ID ownership, no Exchange/Teams table family, no Exchange/Teams dashboard, no provider framework, no customer claim activation, and no restore/certify support.
• Follow-up path: source-contract/capture enablement, additional resource types, Security/Compliance comparable packs, certification, restore, and customer reporting remain later specs.

UI / Surface Guardrail Impact (mandatory when operator-facing surfaces are changed; otherwise write N/A)

Surface / Change	Operator-facing surface change?	Native vs Custom	Shared-Family Relevance	State Layers Touched	Exception Needed?	Low-Impact / N/A Note
Existing Coverage v2 readiness / inspect surface	yes, if rendered summaries or coverage levels change	Native Filament + existing widgets/read model	evidence/status/read-only registry	page/detail	no	Existing internal surface only; no new navigation/action.

Decision-First Surface Role (mandatory when operator-facing surfaces are changed)

Surface	Decision Role	Human-in-the-loop Moment	Immediately Visible for First Decision	On-Demand Detail / Evidence	Why This Is Primary or Why Not	Workflow Alignment	Attention-load Reduction
Existing Coverage v2 readiness / inspect surface	Tertiary Evidence / Diagnostics Surface	Verify selected Exchange/Teams evidence can be interpreted safely	Resource name, coverage level, evidence/identity/claim state, typed summary if rendered	raw/normalized payload, source metadata, unsupported fields, evidence hash, OperationRun link	Not primary; it supports evidence inspection and release review	Follows existing Coverage v2 internal review flow	Reduces raw-payload reading for selected Exchange/Teams evidence.

Audience-Aware Disclosure (mandatory when operator-facing surfaces are changed)

Surface	Audience Modes In Scope	Decision-First Default-Visible Content	Operator Diagnostics	Support / Raw Evidence	One Dominant Next Action	Hidden / Gated By Default	Duplicate-Truth Prevention
Existing Coverage v2 readiness / inspect surface	operator-MSP, support-platform	selected resource summary, material changes, blockers, claim state	unsupported fields, source metadata, identity diagnostics	raw payload stays hidden or secondary/internal; secrets never shown	Inspect	raw payload, provider IDs, OperationRun details, source keys	Coverage level and summary state appear once and do not duplicate as broad Exchange/Teams readiness.

UI/UX Surface Classification (mandatory when operator-facing surfaces are changed)

Surface	Action Surface Class	Surface Type	Likely Next Operator Action	Primary Inspect/Open Model	Row Click	Secondary Actions Placement	Destructive Actions Placement	Canonical Collection Route	Canonical Detail Route	Scope Signals	Canonical Noun	Critical Truth Visible by Default	Exception Type / Justification
Coverage v2 readiness	List / Table / Report	Read-only registry/evidence inspection	Inspect selected evidence	Primary link column	not required	none	none	existing route	inspect slide-over	workspace + managed environment	Coverage v2 resources	coverage level, evidence state, identity state, claim state	none

Operator Surface Contract (mandatory when operator-facing surfaces are changed)

Surface	Primary Persona	Decision / Operator Action Supported	Surface Type	Primary Operator Question	Default-visible Information	Diagnostics-only Information	Status Dimensions Used	Mutation Scope	Primary Actions	Dangerous Actions
Coverage v2 readiness / inspect	Tenant operator / release reviewer	Verify selected Exchange/Teams evidence interpretation without unsafe claims	Technical Annex / read-only evidence inspection	What selected Exchange/Teams evidence is comparable/renderable, and what changed materially?	typed summary, coverage/evidence/identity/claim state, last captured	raw payload, unsupported fields, source metadata, evidence hash, OperationRun	coverage level, evidence state, identity state, claim state, compare importance	read-only	Inspect	none

Proportionality Review (mandatory when structural complexity is introduced)

• New source of truth?: no. Existing Coverage v2 resource/evidence rows remain truth.
• New persisted entity/table/artifact?: no new table by default. Compare/render should derive from existing evidence unless implementation proves persistence is required and this spec is amended.
• New abstraction?: yes, bounded typed compare/render helpers may be introduced or existing services extended.
• New enum/state/reason family?: no persisted enum/status family. Derived importance labels (critical, important, informational) may exist only inside compare output/tests.
• New cross-domain UI framework/taxonomy?: no.
• Current operator problem: Operators cannot safely understand material Exchange/Teams configuration changes from generic payloads and can over-read evidence as certification, restore readiness, or broad M365 coverage.
• Existing structure is insufficient because: Generic normalization sorts/redacts payloads but does not express Exchange mail-flow/domain semantics, Teams app/meeting policy semantics, volatile-field exclusions, or safe render summaries.
• Narrowest correct implementation: Bounded typed helpers for content-backed Exchange/Teams evidence rows, mandatory first support for transportRule, acceptedDomain, appPermissionPolicy, and meetingPolicy, with other listed types evidence-gated.
• Ownership cost: Focused tests for each supported type, maintenance of field mappings as Microsoft payloads evolve, and Product Surface/browser proof if rendered output changes.
• Alternative intentionally rejected: Raw-payload display, source-contract guessing, and separate Exchange/Teams policy engines/dashboards were rejected because they increase operator risk and provider coupling.
• Release truth: Current-release truth over existing Coverage v2 evidence, not future capture, certification, restore, or customer reporting preparation.

Compatibility posture

This feature assumes a pre-production environment. Backward compatibility, legacy aliases, migration shims, historical fixtures, and compatibility-specific tests are out of scope.

Testing / Lane / Runtime Impact (mandatory for runtime behavior changes)

• Test purpose / classification: Unit for typed normalization/compare/render/redaction/Claim Guard; Feature for evidence-gated promotion, RBAC/scope, no overclaim/no restore/no certification/no tenant_id; Browser if rendered Coverage v2 output changes.
• Validation lane(s): fast-feedback, confidence, browser if rendered UI changes.
• Why this classification and these lanes are sufficient: The core behavior is deterministic pure transformation over existing evidence plus internal read-model rendering. No schema or remote provider path is added by default.
• New or expanded test families: Spec 422 focused unit/feature tests; one focused browser smoke only if rendered output changes.
• Fixture / helper cost impact: Use minimal workspace/managed-environment/provider/evidence factories and fake content-backed evidence payloads. No live Graph/TCM calls.
• Heavy-family visibility / justification: none by default.
• Special surface test profile: shared-detail-family / standard-native-filament if existing inspect slide-over changes.
• Standard-native relief or required special coverage: focused browser proof validates the existing read-only page and inspect summary when rendered.
• Reviewer handoff: Confirm lane fit, no hidden capture/OperationRun/customer-output scope, and no new heavy fixtures.
• Budget / baseline / trend impact: none expected.
• Escalation needed: document-in-feature if optional Exchange/Teams types remain blocked; follow-up-spec if source contracts/capture are needed.
• Active feature PR close-out entry: Guardrail / Exception / Smoke Coverage.
• Planned validation commands:
  • cd apps/platform && ./vendor/bin/sail bin pint --dirty --format agent
  • cd apps/platform && ./vendor/bin/sail artisan test --compact tests/Unit/Support/TenantConfiguration/Spec422ExchangeTransportRuleNormalizerTest.php tests/Unit/Support/TenantConfiguration/Spec422ExchangeAcceptedDomainNormalizerTest.php tests/Unit/Support/TenantConfiguration/Spec422TeamsAppPermissionPolicyNormalizerTest.php tests/Unit/Support/TenantConfiguration/Spec422TeamsMeetingPolicyNormalizerTest.php tests/Unit/Support/TenantConfiguration/Spec422ExchangeTeamsComparableDiffTest.php tests/Unit/Support/TenantConfiguration/Spec422ExchangeTeamsRenderableSummaryTest.php tests/Unit/Support/TenantConfiguration/Spec422ExchangeTeamsRedactionTest.php tests/Unit/Support/TenantConfiguration/Spec422ExchangeTeamsClaimGuardTest.php
  • cd apps/platform && ./vendor/bin/sail artisan test --compact tests/Feature/TenantConfiguration/Spec422ExchangeTeamsComparableRenderableTest.php tests/Feature/TenantConfiguration/Spec422ExchangeTeamsCoverageLevelPromotionTest.php tests/Feature/TenantConfiguration/Spec422ExchangeTeamsNoRestoreNoCertificationTest.php tests/Feature/TenantConfiguration/Spec422ExchangeTeamsNoTenantIdTest.php tests/Feature/TenantConfiguration/Spec422ExchangeTeamsNoMiniPlatformTest.php
  • cd apps/platform && ./vendor/bin/sail artisan test --compact tests/Browser/Spec422ExchangeTeamsComparableRenderableOperatorSurfaceSmokeTest.php if rendered output changes
  • git diff --check

User Scenarios & Testing (mandatory)

User Story 1 - Understand Exchange mail-flow evidence safely (Priority: P1)

As a tenant operator or release reviewer, I need captured Exchange transport rule and accepted domain evidence to render as concise operator summaries and deterministic compare results so I can understand material mail-flow/domain changes without reading raw payloads.

Independent Test: Given content-backed Exchange evidence payloads, compare output identifies transport rule state/condition/action/priority changes and accepted domain name/type/default changes; render output summarizes the current resources without raw payload or secrets.

Acceptance Scenarios:

1. Given content-backed transportRule evidence, When the resource is rendered, Then the operator sees display name, enabled/state, priority/order, condition/action summaries, claim/identity state, and last captured time.
2. Given two transportRule payloads that differ only in volatile fields, When they are compared, Then the result is unchanged or marks volatile fields as ignored.
3. Given an accepted domain type or default-domain flag changes, When the payloads are compared, Then the result marks the change as material with bounded importance.

User Story 2 - Understand Teams policy evidence safely (Priority: P1)

As a tenant operator or release reviewer, I need captured Teams app permission and meeting policy evidence to render as concise operator summaries and deterministic compare results so I can understand app allow/block and meeting behavior changes without reading raw payloads.

Independent Test: Given content-backed Teams evidence payloads, compare output identifies app permission allow/block changes and meeting policy external/recording/lobby/content-sharing changes; render output hides raw payloads and unsafe message/content data.

Acceptance Scenarios:

1. Given content-backed appPermissionPolicy evidence, When the resource is rendered, Then the operator sees display name, policy mode, allowed/blocked app summary, claim/identity state, and last captured time.
2. Given content-backed meetingPolicy evidence, When meeting access, recording, lobby, or sharing settings change, Then compare output identifies the material change with bounded importance.
3. Given payload fields that could contain chat, message, file, recording, transcript, token, or credential content, When render/compare output is produced, Then sensitive content is redacted or excluded.

User Story 3 - Keep non-evidence-backed Exchange/Teams types honest (Priority: P1)

As a release reviewer, I need all selected Exchange/Teams types to remain unpromoted unless content-backed evidence exists so TenantPilot does not claim typed support for data it cannot prove.

Independent Test: Given registered Exchange/Teams resource types without content-backed evidence, the promotion path leaves them detected/content-backed-only as appropriate and records a blocker/deferred reason rather than comparable/renderable support.

Acceptance Scenarios:

1. Given a selected Exchange/Teams type has no content-backed evidence, When Spec 422 promotion is evaluated, Then it remains unpromoted and the implementation report records the blocker.
2. Given an optional listed type has content-backed evidence and typed tests, When it is promoted, Then it receives comparable/renderable support without restore/certification/customer claims.

User Story 4 - Prevent Exchange/Teams overclaiming (Priority: P1)

As a product/release owner, I need Claim Guard and Product Surface output to block certification, restore readiness, full Exchange/Teams coverage, and customer-ready claims so internal compare/render support cannot become unsafe customer proof.

Independent Test: Claim Guard tests block forbidden wording while allowing scoped internal comparable/renderable wording, and rendered surfaces contain no restore/certified/customer-ready claims.

Acceptance Scenarios:

1. Given a claim says "Exchange certified" or "Teams restore-ready", When Claim Guard evaluates it, Then it is blocked.
2. Given a claim says selected Exchange or Teams resources are comparable/renderable for internal review, When Claim Guard evaluates it, Then it remains scoped/internal and does not become customer-facing proof.

Functional Requirements

• FR-422-001: The implementation MUST use existing Coverage v2 resource type, resource, evidence, identity, redaction, read-model, and Claim Guard boundaries.
• FR-422-002: A resource type MUST be promoted to comparable/renderable only when content-backed evidence exists and typed normalization, compare, render, redaction, and tests exist.
• FR-422-003: transportRule, acceptedDomain, appPermissionPolicy, and meetingPolicy MUST have typed compare/render support for content-backed evidence rows.
• FR-422-004: remoteDomain, organizationConfig, sharedMailbox, mailboxPlan, appSetupPolicy, messagingPolicy, teamsUpdateManagementPolicy, and voiceRoute MAY be promoted only if implementation preflight proves content-backed evidence and scope stays bounded.
• FR-422-005: Missing source contracts or missing content-backed evidence MUST remain explicit blockers/deferred reasons and MUST NOT be papered over by default registry promotion.
• FR-422-006: Compare output MUST classify changes as added, removed, changed, unchanged, ignored_volatile, redacted, or unsupported_field.
• FR-422-007: Compare importance labels MUST remain derived compare-output labels only: critical, important, or informational.
• FR-422-008: Compare MUST ignore or label volatile fields including Graph/TCM context, etags, created/modified timestamps, and source metadata that is not business-relevant.
• FR-422-009: Compare MUST be deterministic, including stable array ordering where order is not semantically meaningful and explicit null/empty handling.
• FR-422-010: Render output MUST answer what the resource is, enabled/active state, behavior controlled, targets/scope where available, material change summary, blockers, redaction, unsupported fields, claim state, identity state, and capture time.
• FR-422-011: Render output MUST NOT show raw payloads, raw provider responses, tokens, secrets, credential values, private keys, certificate material, authorization headers, cookies, mail/message content, Teams chat content, Teams file content, meeting recordings, transcripts, or unneeded PII by default.
• FR-422-012: Claim Guard MUST allow only scoped internal comparable/renderable wording and MUST block certified, restore-ready, customer-ready, full, all-resource, 100 percent, or broad Exchange/Teams/M365 coverage claims.
• FR-422-013: No restore/apply action, certified state, customer-facing route, customer report, Review Pack output, management PDF output, export, or download is in scope.
• FR-422-014: Render/compare MUST be DB-only from existing evidence at render time and MUST NOT call Graph, TCM, provider clients, HTTP, remote APIs, or Microsoft documentation.
• FR-422-015: No new Exchange-specific or Teams-specific table family, persisted compare result table, provider mini-platform, or tenant_id ownership path may be introduced.
• FR-422-016: Existing Coverage v2 read authorization MUST apply: non-member/wrong scope deny as not found, established member missing capability forbidden, and provider connection scope must match workspace/managed environment.
• FR-422-017: Existing Coverage v2 operator surface MAY show comparable/renderable Exchange/Teams summaries; any rendered change requires focused browser proof and Human Product Sanity.
• FR-422-018: If implementation requires capture expansion, a new source contract, a new OperationRun type, new persisted truth, a new UI action, or customer output, it MUST stop and amend/split the spec first.

Non-Functional Requirements

• NFR-422-001: Compare/render behavior must be deterministic across repeated runs for the same normalized evidence.
• NFR-422-002: Redaction must be applied before any operator render or compare summary can expose sensitive values.
• NFR-422-003: Existing read-only Coverage v2 surface performance must remain DB-only: no render-time remote/provider/HTTP calls and no new per-row query or service loop outside the existing read model for typed summaries.
• NFR-422-004: Tests must prove business truth rather than thin presentation internals: material change detection, redaction, claims, scope, and no overclaim.
• NFR-422-005: No UI label may imply restore, certification, full coverage, customer proof, or production readiness.

Key Entities / Data

• TenantConfigurationResourceType: Existing Coverage v2 registry definition for selected Exchange/Teams resource types.
• TenantConfigurationResource: Existing scoped observed resource row tied to workspace, managed environment, provider connection, identity, and latest evidence.
• TenantConfigurationResourceEvidence: Existing append-only evidence row with raw payload boundary, normalized payload, coverage level, evidence state, capture outcome, permission context, and optional OperationRun link.
• Compare result: Derived in-memory output for selected evidence comparisons; not persisted by default.
• Render summary: Derived operator-safe view model; not persisted by default.

Out Of Scope

• Exchange or Teams restore/apply.
• Exchange or Teams certification or certified compare.
• Full Exchange, Teams, or M365 catalog support.
• New source capture contracts, TCM fetchers, Graph endpoint mappings, or Microsoft documentation fetches.
• Customer-facing Exchange/Teams reports, Review Pack output, management PDF output, or public export.
• New Coverage v2 start/capture action, route, navigation item, dashboard, wizard, or customer workspace surface.
• New Exchange/Teams tables, mini-platform services, provider framework, or persisted compare history.
• Coverage v1 compatibility, fallback readers, dual writes, old gap taxonomy adapters, or tenant_id.

Acceptance Criteria

• AC-422-001: Transport Rule, Accepted Domain, App Permission Policy, and Meeting Policy evidence can be normalized, compared, and rendered deterministically when content-backed evidence rows exist.
• AC-422-002: Optional Exchange/Teams types are either promoted with repo-real evidence and focused tests or remain explicitly blocked/deferred.
• AC-422-003: Compare output detects material Exchange mail-flow/domain and Teams app/meeting policy changes while ignoring volatile fields.
• AC-422-004: Render output hides secrets, raw payloads, mail/message/chat/file/recording/transcript content, and unsupported/redacted fields are diagnostics only.
• AC-422-005: Claim Guard blocks certified, restore-ready, full/100 percent Exchange/Teams or M365, customer-ready, and broad coverage claims.
• AC-422-006: No restore/apply/customer-output UI, action, route, report, download, capture contract, or certification state is introduced.
• AC-422-007: No tenant_id, Exchange/Teams-specific table family, persisted compare result table, or mini-platform appears.
• AC-422-008: Focused unit and feature tests pass; focused browser proof passes if rendered output changes.

Success Criteria

• SC-422-001: A reviewer can inspect the implementation report and see an Exchange/Teams evidence matrix naming promoted and deferred types.
• SC-422-002: For each mandatory first support type, focused tests prove at least one volatile-only no-change comparison and at least one material-change comparison.
• SC-422-003: Redaction tests prove no secret/credential/token/raw payload or content-bearing mail/Teams value appears in render summaries, compare summaries, OperationRun context, audit metadata, or default UI.
• SC-422-004: Product Surface close-out confirms existing-surface impact only, Product Surface exceptions none, and no broad Exchange/Teams/M365 claims.

Risks

Risk	Severity	Mitigation
Compare/render is mistaken for certification	High	Claim Guard, Product Surface wording, no certified coverage level.
Missing Exchange/Teams source contracts are silently treated as support	High	Evidence-gated requirement and blocker task.
Raw payload, mail content, Teams content, or secrets render by default	High	Redaction tests, browser proof, diagnostics demotion.
Exchange/Teams-specific mini-platform appears	High	Reuse existing Coverage v2 services; no new tables/dashboard.
Remote calls happen during render	High	DB-only requirement and fail-hard tests.
Scope leaks across workspace/environment/provider connection	High	Existing authorization plus feature tests.
Optional resource types expand scope too far	Medium	Conditional promotion only with evidence and tests; otherwise defer.

Assumptions

• Specs 419, 420, and 421 are complete enough to serve as read-only implementation precedent.
• Current Exchange/Teams live capture contracts may be missing; missing capture remains out of scope and is documented as a blocker/deferred result.
• Existing Coverage v2 surface is internal/operator only and read-only.
• Existing Coverage v2 models and coverage-level enum can represent comparable/renderable without schema changes.
• Any implementation report will be created during the later implementation loop, not during preparation.

Open Questions

None blocking for the narrowed implementation-ready slice. Live Exchange/Teams capture/source-contract availability is an implementation preflight fact; missing evidence is an expected blocker/deferred result, not an open product decision for this pack.

Follow-Up Spec Candidates

• Exchange/Teams source-contract and content-backed capture enablement.
• Exchange remote domain, organization config, shared mailbox, and mailbox plan comparable/renderable expansion.
• Teams app setup, messaging, update management, and voice route comparable/renderable expansion.
• Security and Compliance readiness/comparable pack.
• Exchange/Teams certified compare pack.
• M365 customer reporting Claim Guard pack.
• Exchange/Teams restore/apply feasibility and safety review.