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)

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:

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.