TenantAtlas/specs/428-exchange-teams-content-backed-evidence-promotion/spec.md

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