diff --git a/specs/428-exchange-teams-content-backed-evidence-promotion/checklists/requirements.md b/specs/428-exchange-teams-content-backed-evidence-promotion/checklists/requirements.md new file mode 100644 index 00000000..0cdf834e --- /dev/null +++ b/specs/428-exchange-teams-content-backed-evidence-promotion/checklists/requirements.md @@ -0,0 +1,76 @@ +# Requirements Checklist: Spec 428 - Exchange/Teams Content-Backed Evidence Promotion + +**Purpose**: Validate preparation readiness for the fail-safe/no-op Spec 428 package. +**Created**: 2026-07-04 +**Feature**: `specs/428-exchange-teams-content-backed-evidence-promotion/spec.md` + +## Candidate And Repo Truth + +- [x] User-provided Spec 428 draft was read as the candidate source. +- [x] `docs/product/spec-candidates.md` was checked; the automatic queue is not the candidate source. +- [x] `docs/product/roadmap.md` was checked for roadmap context. +- [x] Existing `specs/` were checked; Spec 428 did not already exist. +- [x] Completed Specs 414, 415, 417, 419, 420, 422, 426, and 427 are read-only context. +- [x] Spec 427 implementation report was checked for final source-contract states. +- [x] Draft prerequisite conflict is documented: no target type reached `contract_verified_pending_capture`. + +## Eligibility + +- [x] `exchange.transportRule` maps to `transportRule`. +- [x] `exchange.acceptedDomain` maps to `acceptedDomain`. +- [x] `teams.appPermissionPolicy` maps to `appPermissionPolicy`. +- [x] `teams.meetingPolicy` maps to `meetingPolicy`. +- [x] `transportRule` is `contract_blocked_repo_adapter_missing`. +- [x] `acceptedDomain` is `contract_blocked_repo_adapter_missing`. +- [x] `appPermissionPolicy` is `contract_blocked_repo_adapter_missing`. +- [x] `meetingPolicy` is `contract_blocked_repo_adapter_missing`. +- [x] Eligible type count is zero. +- [x] Spec 428 outcome is fail-safe/no-op, not capture promotion. + +## Scope Guard + +- [x] No source-contract verification is in scope. +- [x] No provider adapter is in scope. +- [x] No Graph endpoint or provider permission change is in scope. +- [x] No runtime provider call is in scope. +- [x] No resource row or evidence row is in scope. +- [x] No OperationRun creation or queue job is in scope. +- [x] No compare/render expansion is in scope. +- [x] No certification, restore, report, Review Pack, PDF, export, or customer output is in scope. +- [x] No UI surface impact is in scope. +- [x] No `tenant_id`, legacy adapter, fallback reader, dual write, or fake evidence path is in scope. + +## Product Surface + +- [x] UI Surface Impact is checked as `No UI surface impact`. +- [x] Product Surface Impact is `N/A - no rendered product surface changed`. +- [x] Browser proof is `N/A - no rendered UI surface changed`. +- [x] Human Product Sanity is `N/A - no product surface changed`. +- [x] Product Surface exceptions are `none`. + +## Spec Readiness + +- [x] `spec.md` exists. +- [x] `plan.md` exists. +- [x] `tasks.md` exists. +- [x] The spec has problem, user value, functional requirements, non-goals, acceptance criteria, assumptions, risks, and follow-ups. +- [x] The plan identifies affected repo surfaces as Spec Kit artifacts only and read-only dependency evidence. +- [x] The tasks are ordered, bounded, verifiable, and enforce no runtime changes. +- [x] RBAC, workspace/managed-environment/provider scope, OperationRun, evidence/result truth, and UX no-impact posture are addressed as no-op constraints. +- [x] No open question blocks safe no-op implementation. + +## Preparation Analyze Result + +- [x] `speckit-analyze` prerequisite check resolves this feature directory. +- [x] Cross-artifact analysis found no critical, high, medium, or low findings requiring artifact changes. +- [x] Functional and non-functional requirements are covered by implementation tasks. +- [x] Constitution alignment issues are none. +- [x] Unmapped implementation tasks are none; preflight, guard, validation, and report tasks support the no-op close-out. +- [x] Residual risk is limited to future source-adapter/evidence-capture work, which must amend or replace this spec before runtime changes. + +## Gate Result + +- [x] Candidate Selection Gate: PASS WITH CONDITIONS - direct candidate, safe only as fail-safe/no-op. +- [x] Spec Readiness Gate: PASS WITH CONDITIONS - ready for no-op implementation report, not ready for evidence capture. +- [x] Preparation Analyze Gate: PASS - no findings requiring artifact changes. +- [x] Workflow outcome: keep as fail-safe closure; split any future source-adapter or capture promotion work into a new/amended spec. diff --git a/specs/428-exchange-teams-content-backed-evidence-promotion/plan.md b/specs/428-exchange-teams-content-backed-evidence-promotion/plan.md new file mode 100644 index 00000000..854a35b9 --- /dev/null +++ b/specs/428-exchange-teams-content-backed-evidence-promotion/plan.md @@ -0,0 +1,223 @@ +# 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. diff --git a/specs/428-exchange-teams-content-backed-evidence-promotion/spec.md b/specs/428-exchange-teams-content-backed-evidence-promotion/spec.md new file mode 100644 index 00000000..e052292b --- /dev/null +++ b/specs/428-exchange-teams-content-backed-evidence-promotion/spec.md @@ -0,0 +1,351 @@ +# 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. diff --git a/specs/428-exchange-teams-content-backed-evidence-promotion/tasks.md b/specs/428-exchange-teams-content-backed-evidence-promotion/tasks.md new file mode 100644 index 00000000..e905709f --- /dev/null +++ b/specs/428-exchange-teams-content-backed-evidence-promotion/tasks.md @@ -0,0 +1,81 @@ +# Tasks: Spec 428 - Exchange/Teams Content-Backed Evidence Promotion + +**Input**: Design documents from `specs/428-exchange-teams-content-backed-evidence-promotion/` +**Prerequisites**: `spec.md`, `plan.md`, `checklists/requirements.md` + +**Implementation Mode**: fail-safe/no-op. Do not edit application runtime code. + +## Test Governance Checklist + +- [ ] Lane assignment is named as no-runtime/no-op with optional fast-feedback existing regressions only. +- [ ] New or changed tests are not added unless implementation is amended into runtime scope. +- [ ] Shared helpers, factories, seeds, fixtures, and context defaults remain unchanged. +- [ ] Planned validation commands cover the no-op closure without pulling in unrelated lane cost. +- [ ] Browser proof is explicitly `N/A - no rendered UI surface changed`. +- [ ] Human Product Sanity and Product Surface implementation-report close-out are `N/A - no rendered UI surface changed`. +- [ ] Any future runtime source-adapter or evidence-capture work is escalated to an amended or separate spec. + +## Phase 1: Preflight + +- [ ] T001 Capture current branch, HEAD, and `git status --short` in `specs/428-exchange-teams-content-backed-evidence-promotion/implementation-report.md`. +- [ ] T002 Confirm completed Specs 414, 415, 417, 419, 420, 422, 426, and 427 are read-only context and are not edited. +- [ ] T003 Confirm the active implementation diff contains only `specs/428-exchange-teams-content-backed-evidence-promotion/` unless the spec is formally amended. +- [ ] T004 Confirm no runtime files under `apps/platform/app/`, `apps/platform/config/`, `apps/platform/database/`, `apps/platform/resources/`, `apps/platform/routes/`, or `apps/platform/tests/` are changed. +- [ ] T005 Confirm no UI, route, navigation, Filament provider, browser-rendered product surface, report, Review Pack, PDF, export, restore, certification, or customer-output scope is planned. + +## Phase 2: Spec 427 Eligibility Matrix + +- [ ] T006 Read `specs/427-exchange-teams-verified-source-contract-enablement/implementation-report.md` and copy the final source-contract matrix into the Spec 428 implementation report. +- [ ] T007 Map `exchange.transportRule` to repo canonical `transportRule`. +- [ ] T008 Map `exchange.acceptedDomain` to repo canonical `acceptedDomain`. +- [ ] T009 Map `teams.appPermissionPolicy` to repo canonical `appPermissionPolicy`. +- [ ] T010 Map `teams.meetingPolicy` to repo canonical `meetingPolicy`. +- [ ] T011 Record `transportRule` final state as `contract_blocked_repo_adapter_missing` and Spec 428 outcome as `not_eligible_noop`. +- [ ] T012 Record `acceptedDomain` final state as `contract_blocked_repo_adapter_missing` and Spec 428 outcome as `not_eligible_noop`. +- [ ] T013 Record `appPermissionPolicy` final state as `contract_blocked_repo_adapter_missing` and Spec 428 outcome as `not_eligible_noop`. +- [ ] T014 Record `meetingPolicy` final state as `contract_blocked_repo_adapter_missing` and Spec 428 outcome as `not_eligible_noop`. +- [ ] T015 Record the final eligibility count as zero. + +## Phase 3: No-Promotion Guard + +- [ ] T016 Confirm no source contract, provider adapter, Graph endpoint, provider permission, runtime Microsoft docs fetch, direct HTTP call, or provider SDK bypass is added. +- [ ] T017 Confirm no `TenantConfigurationResource` or `TenantConfigurationResourceEvidence` creation/update path is added. +- [ ] T018 Confirm no OperationRun, queue job, scheduler entry, OperationRun type, notification, or audit event is added for Exchange/Teams capture. +- [ ] T019 Confirm no capture outcome is changed from blocked to empty/success/content-backed. +- [ ] T020 Confirm no content-backed, comparable, renderable, certified, restore-ready, customer-ready, full Exchange, full Teams, or full M365 claim is added. +- [ ] T021 Confirm no `tenant_id`, legacy adapter, fallback reader, dual write, Coverage v1 bridge, or fake evidence fixture is introduced as product truth. +- [ ] T022 Confirm existing Spec 422 compare/render support is treated as completed context only and not expanded by this spec. + +## Phase 4: Validation + +- [ ] T023 Run `git diff --check`. +- [ ] T024 Run `git status --short` and confirm only active Spec 428 artifacts changed. +- [ ] T025 Optionally run `cd apps/platform && ./vendor/bin/sail artisan test --compact tests/Unit/Support/TenantConfiguration/Spec427ExchangeTeamsSourceContractStateTest.php tests/Unit/Support/TenantConfiguration/Spec420M365CaptureEligibilityTest.php` if Sail is available; if skipped, document why no runtime tests are required for the no-op closure. +- [ ] T026 Do not run browser tests; record `N/A - no rendered UI surface changed`. + +## Phase 5: Implementation Report + +- [ ] T027 Create `specs/428-exchange-teams-content-backed-evidence-promotion/implementation-report.md`. +- [ ] T028 Record Candidate Selection Gate result: PASS WITH CONDITIONS as fail-safe/no-op only. +- [ ] T029 Record Spec Readiness Gate result, Preparation Analyze Gate result, and any residual risk. +- [ ] T030 Record dirty state before/after. +- [ ] T031 Record files changed. +- [ ] T032 Record eligible target type list as empty. +- [ ] T033 Record blocked target type list with all four target types. +- [ ] T034 Record no OperationRun proof because no capture runs. +- [ ] T035 Record no evidence persistence proof because no evidence rows. +- [ ] T036 Record no payload hash, normalization, identity, permission failure, or redaction runtime proof because no capture occurred. +- [ ] T037 Record no compare/render, no certification, no restore, no customer claim, no `tenant_id`, and no mini-platform confirmation. +- [ ] T038 Record Product Surface impact as `N/A - no rendered UI surface changed`. +- [ ] T039 Record Livewire v4 compliance unchanged, provider registration unchanged under `apps/platform/bootstrap/providers.php`, global search unchanged, destructive/high-impact actions none, asset strategy none, deployment impact none. +- [ ] T040 Record deferred work: source-adapter/source-contract enablement before any future content-backed evidence promotion. + +## Stop Conditions + +Stop before implementation and amend or replace this spec if any of the following becomes true: + +- any target type reaches `contract_verified_pending_capture`; +- runtime evidence capture is requested; +- source adapters or Graph contracts are required; +- UI/customer/report/restore/certification/compare-render changes are required; +- application code or tests need to change for reasons other than documenting the no-op.