# Feature Specification: Spec 428 - Exchange/Teams Content-Backed Evidence Promotion **Feature Branch**: `428-exchange-teams-content-backed-evidence-promotion` **Created**: 2026-07-04 **Status**: Draft - fail-safe/no-op preparation **Input**: User-provided draft `Spec 428 - Exchange/Teams Content-Backed Evidence Promotion` ## Preparation Selection Summary - **Selected candidate**: Spec 428 - Exchange/Teams Content-Backed Evidence Promotion. - **Source location**: User-provided attachment `/Users/ahmeddarrazi/.codex/attachments/2717e3cd-a286-48f2-984e-785578d4a6ee/pasted-text.txt`. - **Why selected**: The user directly provided a P0 draft for the next Exchange/Teams Coverage v2 step after Spec 427. The draft itself includes a fail-safe path when Spec 427 leaves all targets blocked. - **Roadmap relationship**: This belongs to the Coverage v2 / M365 evidence sequence after Specs 414, 415, 417, 419, 420, 426, and 427. It is not sourced from the automatic candidate queue, which currently has no safe auto-prep target. - **Close alternatives deferred**: Management-report runtime validation, governance-artifact lifecycle, provider-readiness productization, cross-domain indicator follow-through, and AI runtime consumer candidates remain manual-promotion/backlog items. They do not supersede this direct P0 Coverage v2 continuation. - **Completed-spec guardrail result**: Specs 414, 415, 417, 419, 420, 422, 426, and 427 are completed historical context only. Their close-out notes, completed task checklists, validation results, browser proof, and implementation reports must not be edited by this spec. - **Smallest viable implementation slice**: Close Spec 428 as a fail-safe/no-op because Spec 427 final state leaves all four target resource types blocked as `contract_blocked_repo_adapter_missing`. No application runtime code, migrations, UI, capture path, provider calls, evidence rows, compare/render promotion, certification, restore, or customer output may be added. - **Candidate Selection Gate**: PASS WITH CONDITIONS. The candidate is valid only as the draft's own fail-safe/no-op path; it is not ready for content-backed evidence capture. ## Draft-To-Repo Deviations The provided draft assumes at least one target type from Spec 427 reached: ```text contract_verified_pending_capture ``` Current repo truth says otherwise. `specs/427-exchange-teams-verified-source-contract-enablement/implementation-report.md` records: | Draft resource type | Repo canonical type | Spec 427 final state | Spec 427 capture outcome | | --- | --- | --- | --- | | `exchange.transportRule` | `transportRule` | `contract_blocked_repo_adapter_missing` | `capture_blocked_missing_contract` | | `exchange.acceptedDomain` | `acceptedDomain` | `contract_blocked_repo_adapter_missing` | `capture_blocked_missing_contract` | | `teams.appPermissionPolicy` | `appPermissionPolicy` | `contract_blocked_repo_adapter_missing` | `capture_blocked_missing_contract` | | `teams.meetingPolicy` | `meetingPolicy` | `contract_blocked_repo_adapter_missing` | `capture_blocked_missing_contract` | Therefore this spec preserves the draft intent but changes the implementation outcome: - no eligible resource type exists for Spec 428; - content-backed evidence promotion must not run; - no provider call may be attempted; - no fake empty capture may be treated as evidence; - no `TenantConfigurationResource` or `TenantConfigurationResourceEvidence` rows may be created by this spec; - later content-backed evidence promotion requires a new or refreshed source-adapter/source-contract spec that first changes the Spec 427 blocker truth. This deviation follows the draft's hard-stop rule: ```text If all four target types remain blocked after 427, this spec should close as FAIL-safe / no-op: no eligible verified contracts for evidence promotion. ``` ## Spec Candidate Check *(mandatory - SPEC-GATE-001)* - **Problem**: The next Coverage v2 sequence step could be misread as permission to create Exchange/Teams content-backed evidence even though the current repo has no verified provider adapter/source contract for the four target types. - **Today's failure**: Without an explicit Spec 428 fail-safe package, a later implementation pass could fake evidence, reinterpret blocked contracts as empty collections, or overclaim Exchange/Teams/M365 readiness from helper-only or render-only code. - **User-visible improvement**: Operators and reviewers get a clear product-truth boundary: Exchange/Teams content-backed evidence is not available yet, and the system must remain blocked instead of producing false calm. - **Smallest enterprise-capable version**: A no-runtime-change closure that verifies the Spec 427 blocker matrix, records zero eligible types, and blocks content-backed evidence promotion until a future source-adapter/source-contract spec changes repo truth. - **Explicit non-goals**: No source-contract verification, no endpoint guessing, no Graph or provider calls, no evidence capture, no new OperationRun type, no migrations, no UI, no compare/render expansion, no certification, no restore, no customer output, no `tenant_id`, no Exchange/Teams mini-platform. - **Permanent complexity imported**: None in runtime. This spec adds only preparation artifacts and a later implementation-report expectation. - **Why now**: The draft was directly provided as the next sequence step after Spec 427, and Spec 427 completed with all targets blocked. Recording the fail-safe now prevents unsafe evidence promotion. - **Why not local**: This is not a local code issue. It is a sequence/product-truth gate over completed Spec 427 evidence and must live in the active Spec Kit package. - **Approval class**: Core Enterprise. - **Red flags triggered**: None for runtime complexity. The content-backed evidence concept is already part of Coverage v2; this package adds no new status family or runtime layer. - **Score**: Nutzen: 2 | Dringlichkeit: 2 | Scope: 2 | Komplexitaet: 2 | Produktnaehe: 1 | Wiederverwendung: 2 | **Gesamt: 11/12** - **Decision**: approve as fail-safe/no-op only; reject any runtime evidence promotion under current repo truth. ## Spec Scope Fields *(mandatory)* - **Scope**: Workspace + managed-environment scoped Coverage v2 evidence gate, no runtime mutation. - **Primary Routes**: N/A - no route, page, navigation, panel, action, report, download, or customer surface changes. - **Data Ownership**: Existing Coverage v2 ownership remains `workspace_id`, `managed_environment_id`, and `provider_connection_id` where provider provenance exists. This spec creates no rows and no schema. - **RBAC**: Existing RBAC remains unchanged. No new action, policy, gate, capability, global search behavior, or UI affordance is introduced. For canonical-view specs: - **Default filter behavior when tenant-context is active**: N/A - no canonical route or rendered query change. - **Explicit entitlement checks preventing cross-tenant leakage**: N/A for runtime; later source-adapter work must enforce workspace + managed-environment + provider-connection same-scope checks before any capture. ## No Legacy / No Backward Compatibility Constraint *(mandatory)* TenantPilot is pre-production unless this spec explicitly records a compatibility exception. - **Compatibility posture**: canonical no-op closure; no compatibility exception. - **Legacy aliases, fallback readers, hidden routes, duplicate UI, old labels, or historical fixtures kept?**: no. - **Why clean replacement is safe now**: No runtime behavior changes. The spec explicitly forbids legacy adapters, fallback readers, dual writes, Coverage v1 bridges, fake evidence, and `tenant_id` ownership truth. ## UI Surface Impact *(mandatory - UI-COV-001)* Does this spec add, remove, rename, or materially change any reachable UI surface? - [x] 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 No-impact rationale: Spec 428 is a fail-safe/no-op closure over completed Spec 427 blocker truth. It must not edit runtime UI files, route files, Filament resources/pages/widgets, navigation, reports, downloads, customer outputs, or browser-rendered diagnostics. ## 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)* N/A - no reachable UI surface impact. Any future work that changes existing Coverage v2 rendering or exposes Exchange/Teams evidence status must amend the active spec/plan/tasks first and satisfy the Product Surface Contract. ## 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?**: no - no rendered product surface changes. - **Page archetype**: N/A. - **Primary user question**: N/A. - **Primary action**: N/A. - **Surface budget result**: N/A. - **Technical Annex / deep-link demotion**: N/A for runtime. The spec requires raw evidence, source keys, OperationRun internals, and provider diagnostics to remain absent from UI because no evidence is created. - **Canonical status vocabulary**: N/A for UI. Internal blocker vocabulary remains `contract_blocked_repo_adapter_missing` and `capture_blocked_missing_contract`. - **Visible complexity impact**: neutral. - **Product Surface exceptions**: none. ## Browser Verification Plan *(mandatory)* - **Browser proof required?**: no. - **No-browser rationale**: `N/A - no rendered UI surface changed`. - **Focused path when required**: N/A. - **Primary interaction to execute**: N/A. - **Console, Livewire, Filament, network, and 500-error checks**: N/A. - **Full-suite failure triage**: N/A. ## Human Product Sanity Check *(mandatory)* - **Required?**: no. - **No-human-sanity rationale**: N/A - no product surface changed. - **Reviewer questions**: N/A. - **Planned result location**: N/A. ## Product Surface Merge Gate Checklist *(mandatory)* - [x] No-legacy posture or approved exception recorded. - [x] Product Surface Impact is completed or `N/A` is justified. - [x] Browser proof is completed or `N/A - no rendered UI surface changed` is justified. - [x] Human Product Sanity is completed or not applicable with rationale. - [x] Product Surface exceptions are documented or `none`. - [x] 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, no completed-spec rewrite assertion, and no application implementation. ## 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?**: no runtime touch. - **Interaction class(es)**: N/A. - **Systems touched**: Completed Spec 427 implementation report and Coverage v2 source-contract terminology as read-only evidence. - **Existing pattern(s) to extend**: none in this spec. - **Shared contract / presenter / builder / renderer to reuse**: N/A. - **Why the existing shared path is sufficient or insufficient**: Existing Coverage v2 source-contract gate is sufficient to block promotion. - **Allowed deviation and why**: none. - **Consistency impact**: Later runtime work must reuse `CoverageSourceContractResolver`, `GenericContentEvidenceCaptureService`, `GraphClientInterface` or repo-existing provider abstraction, `CanonicalIdentityResolver`, `OperationRunService`, and `ClaimGuard`. - **Review focus**: Confirm the no-op does not create a parallel Exchange/Teams evidence path. ## 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. - **Shared OperationRun UX contract/layer reused**: N/A. - **Delegated start/completion UX behaviors**: N/A. - **Local surface-owned behavior that remains**: none. - **Queued DB-notification policy**: N/A. - **Terminal notification path**: N/A. - **Exception required?**: none. If this spec is later amended to create remote/provider capture, it must create/reuse an OperationRun-backed service path and satisfy the central OperationRun Start UX Contract before any runtime implementation. ## 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?**: no runtime boundary change; provider boundary is reviewed as a prep gate. - **Boundary classification**: Coverage v2 source-contract/evidence truth is platform-core; Exchange/Teams source details are provider-owned and currently blocked. - **Seams affected**: none at runtime. - **Neutral platform terms preserved or introduced**: workspace, managed environment, provider connection, resource type, source contract, capture outcome, evidence state, identity state, claim state. - **Provider-specific semantics retained and why**: Exchange/Teams names are retained only to identify blocked target types inherited from Spec 427. - **Why this does not deepen provider coupling accidentally**: No provider-specific table, adapter, endpoint, permission, route, UI, or customer claim is added. - **Follow-up path**: follow-up spec only after real source adapter/source contract evidence exists. ## UI / Surface Guardrail Impact *(mandatory when operator-facing surfaces are changed; otherwise write `N/A`)* N/A - no operator-facing surface change. ## Decision-First Surface Role *(mandatory when operator-facing surfaces are changed)* N/A - no operator-facing surface change. ## Audience-Aware Disclosure *(mandatory when operator-facing surfaces are changed)* N/A - no operator-facing surface change. ## UI/UX Surface Classification *(mandatory when operator-facing surfaces are changed)* N/A - no operator-facing surface change. ## Operator Surface Contract *(mandatory when operator-facing surfaces are changed)* N/A - no operator-facing surface change. ## Proportionality Review *(mandatory when structural complexity is introduced)* - **New source of truth?**: no. - **New persisted entity/table/artifact?**: no runtime artifact. Spec Kit artifacts only. - **New abstraction?**: no. - **New enum/state/reason family?**: no. - **New cross-domain UI framework/taxonomy?**: no. - **Current operator problem**: Preventing false Exchange/Teams/M365 evidence readiness claims when all target source contracts remain blocked. - **Existing structure is insufficient because**: Existing runtime correctly blocks capture, but the next sequence spec needs an explicit fail-safe close-out so a later implementation loop does not reinterpret the draft as capture permission. - **Narrowest correct implementation**: No-op implementation report and validation only. - **Ownership cost**: Minimal Spec Kit maintenance; no runtime ownership cost. - **Alternative intentionally rejected**: Creating fake evidence, guessed provider adapters, or empty successful captures. Those would violate source-of-truth, provider boundary, evidence, and customer-claim safety. - **Release truth**: Current-release truth is blocked/no-op. ### 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**: N/A for runtime. Implementation may run existing focused regression tests as evidence only. - **Validation lane(s)**: docs/spec no-op plus optional fast-feedback focused existing tests. - **Why this classification and these lanes are sufficient**: No runtime behavior changes are allowed; the proof is the completed Spec 427 blocker matrix and `git diff --check`. - **New or expanded test families**: none. - **Fixture / helper cost impact**: none. - **Heavy-family visibility / justification**: none. - **Special surface test profile**: N/A. - **Standard-native relief or required special coverage**: `N/A - no rendered UI surface changed`. - **Reviewer handoff**: Confirm zero application-code diff and that implementation report records no eligible target types. - **Budget / baseline / trend impact**: none. - **Escalation needed**: none. - **Active feature PR close-out entry**: Guardrail / Exception / Smoke Coverage: `N/A - fail-safe no-op, no rendered UI surface changed`. - **Planned validation commands**: - `git diff --check` - `git status --short` - optional evidence-only regression: `cd apps/platform && ./vendor/bin/sail artisan test --compact tests/Unit/Support/TenantConfiguration/Spec427ExchangeTeamsSourceContractStateTest.php tests/Unit/Support/TenantConfiguration/Spec420M365CaptureEligibilityTest.php` ## User Scenarios & Testing *(mandatory)* ### User Story 1 - Reviewer Sees Fail-Safe Evidence Boundary (Priority: P1) A release reviewer needs Spec 428 to state that no Exchange/Teams content-backed evidence can be promoted because Spec 427 left all target types blocked. **Why this priority**: It prevents unsafe evidence/readiness claims in the M365 sequence. **Independent Test**: Read this spec and the Spec 427 implementation report. Confirm all four target resource types are blocked and no runtime capture task is authorized. **Acceptance Scenarios**: 1. **Given** Spec 427 final states are all `contract_blocked_repo_adapter_missing`, **When** Spec 428 is reviewed, **Then** it declares zero eligible types and fail-safe/no-op closure. 2. **Given** a later implementation loop starts Spec 428, **When** it reaches preflight, **Then** it must stop before runtime code changes unless a prior spec has changed the source-contract truth. ### User Story 2 - Operator Trust Is Not Overclaimed (Priority: P1) An operator or customer-facing workflow must not see Exchange, Teams, M365, certification, restore, or customer-ready claims from this spec. **Independent Test**: Confirm the active tasks forbid UI/customer-output changes and require no-promotion close-out language. **Acceptance Scenarios**: 1. **Given** there are no eligible contracts, **When** Spec 428 is completed, **Then** no content-backed, comparable, renderable, certified, restore-ready, or customer-ready claim is introduced. 2. **Given** a future source adapter is desired, **When** a developer tries to add it under Spec 428, **Then** the spec requires a separate or amended source-contract spec first. ## Functional Requirements - **FR-428-001**: The implementation MUST read Spec 427 final state as the source of truth for the four target types. - **FR-428-002**: The implementation MUST map `exchange.transportRule` to repo canonical `transportRule`. - **FR-428-003**: The implementation MUST map `exchange.acceptedDomain` to repo canonical `acceptedDomain`. - **FR-428-004**: The implementation MUST map `teams.appPermissionPolicy` to repo canonical `appPermissionPolicy`. - **FR-428-005**: The implementation MUST map `teams.meetingPolicy` to repo canonical `meetingPolicy`. - **FR-428-006**: The implementation MUST declare zero eligible types while all four final states remain `contract_blocked_repo_adapter_missing`. - **FR-428-007**: The implementation MUST NOT create or update `TenantConfigurationResource` rows. - **FR-428-008**: The implementation MUST NOT create or update `TenantConfigurationResourceEvidence` rows. - **FR-428-009**: The implementation MUST NOT add source contracts, provider adapters, Graph endpoints, runtime docs fetches, provider SDK calls, direct HTTP calls, or provider permission changes. - **FR-428-010**: The implementation MUST NOT create an OperationRun, OperationRun type, queue job, scheduler entry, notification, or audit event for capture. - **FR-428-011**: The implementation MUST NOT change compare, render, certification, restore, report, Review Pack, PDF, customer output, or UI behavior. - **FR-428-012**: The implementation MUST NOT introduce `tenant_id`, v1 adapters, fallback readers, dual writes, legacy aliases, or fake evidence fixtures as product truth. - **FR-428-013**: The implementation report MUST include the final eligibility matrix and explicitly state `FAIL-safe / no-op: no eligible verified contracts for evidence promotion`. - **FR-428-014**: If any target type becomes `contract_verified_pending_capture` before implementation begins, implementation MUST stop and this spec MUST be amended or replaced before runtime work. ## Non-Functional Requirements - **NFR-428-001 Source-of-truth clarity**: Spec 427 implementation report is authoritative for current eligibility. - **NFR-428-002 Auditability**: The no-op implementation report must be explicit enough for reviewers to understand why no runtime work was performed. - **NFR-428-003 Security**: No secrets, tokens, provider payloads, raw permission context, or raw provider errors are introduced, logged, or rendered. - **NFR-428-004 Workspace/provider isolation**: No runtime ownership change occurs; any future capture must enforce workspace + managed environment + provider connection same-scope rules. - **NFR-428-005 Product honesty**: The platform must not imply Exchange/Teams/M365 readiness from blocked contracts or typed helper code. ## Entities No new entities. Existing entities are read-only context: - `TenantConfigurationResourceType` - `TenantConfigurationResource` - `TenantConfigurationResourceEvidence` - `OperationRun` ## Out Of Scope - verifying new Exchange/Teams source contracts; - creating repo adapters or provider gateway methods; - adding Graph contracts or OAuth/provider permission scopes; - running capture; - treating empty data as content-backed evidence; - writing evidence rows; - changing OperationRun behavior; - adding UI, routes, navigation, dashboards, reports, Review Packs, PDFs, exports, restore/apply flows, or customer outputs; - comparing, rendering, certifying, or customer-claiming Exchange/Teams readiness; - adding Exchange/Teams-specific persistence or mini-platforms. ## Success Criteria *(mandatory)* - **SC-428-001**: Reviewers can see that all four target types are blocked by Spec 427 and none are eligible for content-backed evidence. - **SC-428-002**: The later implementation loop can complete without application code changes by documenting a fail-safe/no-op implementation report. - **SC-428-003**: No completed historical spec is modified. - **SC-428-004**: No application runtime file is modified. - **SC-428-005**: No UI/browser proof is required because no rendered product surface changes. ## Risks | Risk | Severity | Mitigation | | --- | ---: | --- | | No-op spec is misread as permission to implement capture | High | FR-428-006 through FR-428-014 and tasks require stop before runtime work. | | Blocked contracts are treated as empty success | High | Explicitly forbid fake empty capture and content-backed evidence rows. | | Existing Spec 422 compare/render support is confused with source-backed evidence | High | Draft-to-repo deviation states Spec 422 is completed context and live capture remains blocked. | | Future adapter work is hidden inside Spec 428 | High | Require amendment or separate spec before any source-adapter/source-contract work. | | Completed specs get rewritten during prep | Medium | Completed-spec guardrail lists them as read-only context. | ## Assumptions - The current branch starts from `platform-dev` at HEAD `bfb52b84 feat: implement spec 427 source contract enablement (#494)`. - Spec 427 implementation report is current repo truth for target eligibility. - The user-provided draft is authoritative for the desired sequence, but repo truth overrides its optimistic prerequisite assumption. - No source adapter or source-contract update is being requested in this preparation turn. ## Open Questions None block this no-op readiness package. Future product questions, out of scope here: - Which repo source adapter should make Exchange/Teams contracts verifiable? - Should a future source-adapter spec replace or amend Spec 427 state before reattempting evidence promotion? - Does existing Spec 422 typed compare/render support need a later reconciliation once real content-backed Exchange/Teams capture exists? ## Follow-Up Spec Candidates - Exchange/Teams source-adapter and source-contract enablement for the four blocked target types. - Exchange/Teams content-backed evidence promotion after at least one target reaches `contract_verified_pending_capture`. - Exchange/Teams compare/render reconciliation after real content-backed capture exists, considering completed Spec 422 context. - M365 customer claim guard and pilot readiness only after source-backed evidence is real and bounded.