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

# Implementation Plan: Spec 428 - Exchange/Teams Content-Backed Evidence Promotion

**Branch**: `428-exchange-teams-content-backed-evidence-promotion` | **Date**: 2026-07-04 | **Spec**: `specs/428-exchange-teams-content-backed-evidence-promotion/spec.md`
**Input**: Fail-safe/no-op feature specification from `specs/428-exchange-teams-content-backed-evidence-promotion/spec.md`

## Summary

Spec 428 is prepared as a fail-safe/no-op package. The user-provided draft expected promotion from verified Exchange/Teams source contracts to content-backed evidence, but current repo truth from Spec 427 says all four target types remain `contract_blocked_repo_adapter_missing`. The implementation plan is therefore to perform preflight, document the blocker matrix, create an implementation report, run only no-runtime validation, and stop with zero application changes.

## Technical Context

**Language/Version**: PHP 8.4.15, Laravel 12
**Primary Dependencies**: Filament v5, Livewire v4, Pest v4, Laravel Sail
**Storage**: PostgreSQL via existing Coverage v2 tables; no schema changes
**Testing**: Pest 4 optional existing focused regression only; no new tests required for no-op runtime
**Validation Lanes**: docs/spec no-op; optional fast-feedback focused existing tests
**Target Platform**: Laravel monolith under `apps/platform`
**Project Type**: web application monorepo
**Performance Goals**: N/A - no runtime path
**Constraints**: no application code, no migrations, no provider calls, no UI, no evidence rows
**Scale/Scope**: four target resource types, all blocked by completed Spec 427

## UI / Surface Guardrail Plan

- **Guardrail scope**: no operator-facing surface change.
- **Affected routes/pages/actions/states/navigation/panel/provider surfaces**: N/A.
- **No-impact class, if applicable**: spec-only/no-runtime.
- **Native vs custom classification summary**: N/A.
- **Shared-family relevance**: none.
- **State layers in scope**: none.
- **Audience modes in scope**: N/A.
- **Decision/diagnostic/raw hierarchy plan**: N/A.
- **Raw/support gating plan**: N/A.
- **One-primary-action / duplicate-truth control**: N/A.
- **Handling modes by drift class or surface**: hard-stop-candidate if implementation attempts runtime UI, customer output, evidence capture, or provider work.
- **Repository-signal treatment**: report-only for completed Spec 427 blocker truth; hard-stop-candidate for any runtime capture request under this spec.
- **Special surface test profiles**: N/A.
- **Required tests or manual smoke**: `N/A - no rendered UI surface changed`.
- **Exception path and spread control**: none.
- **Active feature PR close-out entry**: Guardrail / Exception / Smoke Coverage: `N/A - fail-safe no-op, no rendered UI surface changed`.
- **UI/Productization coverage decision**: No UI surface impact.
- **Coverage artifacts to update**: none.
- **No-impact rationale**: No routes, UI files, Filament resources/pages/widgets, navigation, reports, downloads, or customer surfaces change.
- **Navigation / Filament provider-panel handling**: no panel change.
- **Screenshot or page-report need**: no.

## Product Surface Contract Plan

- **Product Surface Contract reference**: N/A for runtime; spec records no rendered product surface changed.
- **No-legacy posture**: canonical no-op; no compatibility exception.
- **Page archetype and surface budget plan**: N/A.
- **Technical Annex and deep-link demotion plan**: N/A; no evidence, OperationRun, payload, or source key is rendered.
- **Canonical status vocabulary plan**: Internal blocker vocabulary remains `contract_blocked_repo_adapter_missing` and `capture_blocked_missing_contract`.
- **Product Surface exceptions**: none.
- **Browser verification plan**: `N/A - no rendered UI surface changed`.
- **Human Product Sanity plan**: N/A.
- **Visible complexity outcome target**: neutral.
- **Implementation report target**: `specs/428-exchange-teams-content-backed-evidence-promotion/implementation-report.md`.

## Filament / Livewire / Deployment Posture

- **Livewire v4 compliance**: unchanged; no Livewire code.
- **Panel provider registration location**: no panel/provider change; Laravel providers remain under `apps/platform/bootstrap/providers.php`.
- **Global search posture**: unchanged; no Filament Resource changed.
- **Destructive/high-impact action posture**: none.
- **Asset strategy**: no assets; no new `filament:assets` requirement.
- **Testing plan**: no new pages/widgets/relation managers/actions; optional existing unit regression only.
- **Deployment impact**: none - no env vars, migrations, queues, scheduler, storage, assets, or runtime provider permissions.

## Shared Pattern & System Fit

- **Cross-cutting feature marker**: no runtime touch.
- **Systems touched**: Spec artifacts only; completed Spec 427 implementation report as source evidence.
- **Shared abstractions reused**: none in runtime. Future capture must reuse `CoverageSourceContractResolver`, `GenericContentEvidenceCaptureService`, `GraphClientInterface` or repo-existing provider abstraction, `CanonicalIdentityResolver`, `OperationRunService`, and `ClaimGuard`.
- **New abstraction introduced? why?**: none.
- **Why the existing abstraction was sufficient or insufficient**: The existing source-contract resolver and Spec 427 report are sufficient to prove capture must remain blocked.
- **Bounded deviation / spread control**: The only deviation from the user draft is converting the optimistic promotion into the draft's own fail-safe/no-op branch because repo truth has zero eligible contracts.

## OperationRun UX Impact

- **Touches OperationRun start/completion/link UX?**: no.
- **Central contract reused**: N/A.
- **Delegated UX behaviors**: N/A.
- **Surface-owned behavior kept local**: none.
- **Queued DB-notification policy**: N/A.
- **Terminal notification path**: N/A.
- **Exception path**: none.

If any implementation attempts provider capture, queue work, run creation, or OperationRun linking, stop and amend/replace this spec before continuing.

## Provider Boundary & Portability Fit

- **Shared provider/platform boundary touched?**: no runtime seam change; provider boundary is evaluated for no-op safety.
- **Provider-owned seams**: Exchange/Teams source semantics remain provider-owned and blocked.
- **Platform-core seams**: Coverage v2 source-contract/evidence/claim truth remains platform-core and unchanged.
- **Neutral platform terms / contracts preserved**: workspace, managed environment, provider connection, resource type, source contract, capture outcome, evidence state, identity state.
- **Retained provider-specific semantics and why**: Exchange/Teams target names are retained only to identify blocked candidates.
- **Bounded extraction or follow-up path**: follow-up spec after real source adapter/source contract evidence exists.

## Constitution Check

- Inventory-first: no inventory or snapshot mutation.
- Read/write separation: no writes; no destructive action.
- Graph contract path: no Graph calls and no new graph contract.
- Deterministic capabilities: no capability changes.
- RBAC-UX: no route, policy, action, or global search changes.
- Workspace isolation: no runtime query or ownership changes.
- Tenant isolation: no tenant-plane read/write changes.
- Run observability: no OperationRun is created; provider capture is blocked.
- OperationRun start UX: N/A.
- Ops-UX 3-surface feedback: N/A.
- OperationRun lifecycle: no status/outcome transitions.
- Summary counts: no new counts.
- Data minimization: no payloads, secrets, logs, or provider metadata are created.
- Test governance: no runtime test-surface change; optional focused existing regression only.
- Proportionality: no new runtime structure.
- No premature abstraction: no new abstraction.
- Persisted truth: no new persistence.
- Behavioral state: no new state family.
- UI semantics: no UI.
- Shared pattern first: no shared interaction family touched.
- Provider boundary: no provider-specific runtime coupling added.
- V1 explicitness / few layers: direct no-op closure.
- Spec discipline / bloat check: fail-safe package is scoped to current repo truth.
- Badge semantics: no badge changes.
- Filament-native UI: N/A.
- UI/Productization coverage: no UI surface impact is recorded.

## Test Governance Check

- **Test purpose / classification by changed surface**: N/A - no runtime behavior changed.
- **Affected validation lanes**: optional fast-feedback existing regression; no browser lane.
- **Why this lane mix is the narrowest sufficient proof**: The implementation proof is repository state and Spec 427 blocker truth. New tests would add maintenance cost without runtime behavior.
- **Narrowest proving command(s)**:
  - `git status --short`
  - `git diff --check`
  - optional: `cd apps/platform && ./vendor/bin/sail artisan test --compact tests/Unit/Support/TenantConfiguration/Spec427ExchangeTeamsSourceContractStateTest.php tests/Unit/Support/TenantConfiguration/Spec420M365CaptureEligibilityTest.php`
- **Fixture / helper / factory / seed / context cost risks**: none.
- **Expensive defaults or shared helper growth introduced?**: no.
- **Heavy-family additions, promotions, or visibility changes**: none.
- **Surface-class relief / special coverage rule**: N/A.
- **Closing validation and reviewer handoff**: Reviewers should confirm no application code diff and no eligible target types.
- **Budget / baseline / trend follow-up**: none.
- **Review-stop questions**: Did any runtime file change? Did any target state become verified? Did any evidence row/path/UI/customer claim get added?
- **Escalation path**: reject-or-split if implementation attempts runtime capture or source-adapter work.
- **Active feature PR close-out entry**: Guardrail / Exception / Smoke Coverage: `N/A - fail-safe no-op, no rendered UI surface changed`.
- **Why no dedicated follow-up spec is needed**: This package is the follow-up gate. Future source-adapter work is a separate feature candidate if product chooses to proceed.

## Project Structure

### Documentation (this feature)

```text
specs/428-exchange-teams-content-backed-evidence-promotion/
|-- spec.md
|-- plan.md
|-- tasks.md
|-- checklists/
|   `-- requirements.md
`-- implementation-report.md   # created during later no-op implementation loop
```

### Source Code

No source code changes are planned or allowed.

Relevant read-only evidence paths:

```text
specs/427-exchange-teams-verified-source-contract-enablement/implementation-report.md
specs/426-exchange-teams-core-evidence-identity-readiness/implementation-report.md
specs/420-m365-generic-evidence-coverage-pack/implementation-report.md
apps/platform/app/Services/TenantConfiguration/CoverageSourceContractResolver.php
apps/platform/app/Services/TenantConfiguration/CoverageSourceContractDecision.php
apps/platform/tests/Unit/Support/TenantConfiguration/Spec427ExchangeTeamsSourceContractStateTest.php
apps/platform/tests/Unit/Support/TenantConfiguration/Spec420M365CaptureEligibilityTest.php
```

**Structure Decision**: Spec-only no-op package. Do not create or edit runtime code, tests, migrations, routes, views, Filament resources, jobs, policies, services, or config.

## Complexity Tracking

| Violation | Why Needed | Simpler Alternative Rejected Because |
| --- | --- | --- |
| None | N/A | N/A |

## Proportionality Review

- **Current operator problem**: Prevent unsafe Exchange/Teams/M365 evidence-readiness claims after Spec 427 blocked all target contracts.
- **Existing structure is insufficient because**: Runtime is already safe, but the sequence needs an explicit no-op Spec Kit package so implementation does not proceed from an outdated optimistic draft assumption.
- **Narrowest correct implementation**: Documentation-only/no-op implementation report with blocker matrix.
- **Ownership cost created**: Minimal Spec Kit artifact maintenance.
- **Alternative intentionally rejected**: Fake provider responses, guessed endpoints, source-adapter work, evidence rows, or capture tests under Spec 428.
- **Release truth**: Current-release truth is blocked/no-op.

## Implementation Phases

### Phase 0 - Preflight

- Confirm current branch and HEAD.
- Confirm dirty state.
- Confirm completed specs remain read-only.
- Confirm no runtime file changes are needed.

### Phase 1 - Eligibility Matrix

- Read Spec 427 implementation report.
- Record all four target types as `contract_blocked_repo_adapter_missing`.
- Record zero eligible types.
- Record Spec 428 outcome as fail-safe/no-op.

### Phase 2 - No-Promotion Guard

- Confirm no provider calls, evidence rows, OperationRuns, UI changes, customer outputs, compare/render changes, certification, restore, or `tenant_id` changes are in scope.
- Confirm any attempt to add those changes stops implementation and requires a new/amended spec.

### Phase 3 - Validation And Close-Out

- Create `implementation-report.md`.
- Run `git diff --check`.
- Optionally run existing focused regression files if Sail is available.
- Record browser proof as `N/A - no rendered UI surface changed`.
- Record Livewire v4, provider registration, global search, destructive action, asset, deployment, and no completed-spec rewrite close-out fields.