ahmido a981853748 spec: add Exchange Teams content-backed evidence promotion (#495 )

Spec package for 428 Exchange Teams content-backed evidence promotion. Includes spec, plan, tasks, and requirements checklist.

Co-authored-by: Ahmed Darrazi <ahmed.darrazi@live.de>
Reviewed-on: #495

2026-07-04 00:32:53 +00:00

25 KiB

Raw Blame History

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:

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:

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?

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)

No-legacy posture or approved exception recorded.
Product Surface Impact is completed or N/A is justified.
Browser proof is completed or N/A - no rendered UI surface changed is justified.
Human Product Sanity is completed or not applicable with rationale.
Product Surface exceptions are documented or 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, 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.