TenantAtlas/specs/294-provider-verification-runtime-semantics/plan.md

# Implementation Plan: Provider Verification Runtime Semantics Stabilization

**Branch**: `294-provider-verification-runtime-semantics` | **Date**: 2026-05-11 | **Spec**: [spec.md](./spec.md)
**Input**: Feature specification from `specs/294-provider-verification-runtime-semantics/spec.md`

**Note**: This plan is produced from the repo's Spec Kit workflow and remains preparation-only. It does not implement application code.

## Summary

Stabilize the remaining provider and verification runtime contract after Spec `293` by classifying the current failing lane first, then aligning the shared startable-fixture contract, the shared verification start gate, provider-operation dedupe/scope-busy behavior, provider-connection neutrality disclosure, and verification report summary counts to current repo truth. Keep route-cutover work, full-suite repair, new provider abstractions, and historical-spec rewrites out of scope.

## Inherited Baseline / Explicit Delta

### Inherited baseline

- Spec `293` already stabilized the route, workspace-aware link, and post-cutover panel baseline.
- The current remaining failing lane is confirmed by `cd apps/platform && ./vendor/bin/sail artisan test --compact tests/Feature/ProviderConnections tests/Feature/Verification`. The authoritative prep-time counts and grouped baseline live in `failure-classification.md`; this plan uses that baseline only as context.
- Historical Specs `238`, `188`, `084`, and `074` remain context only; none of them should be rewritten in this slice.
- The current repo already contains the owner seams this package should reuse: `StartVerification`, `ProviderOperationStartGate`, `OperationRunService`, `ProviderConnectionSurfaceSummary`, `ProviderConnectionTargetScopeNormalizer`, `ProviderConnectionTargetScopeDescriptor`, `MicrosoftProviderHealthCheck`, and `VerificationReportSchema`.

### Explicit delta in this plan

- Add one spec-local `failure-classification.md` artifact to pin the observed failure groups, their seams, and their candidate owners before implementation starts.
- Keep the implementation bounded to one feature lane and five pinned seam families.
- Repair fixture contract drift before widening runtime semantics.
- Repair surface/report baseline drift only through the existing shared summary/report owners.
- Reuse one existing provider-connection scope browser smoke only if visible provider-connection disclosure changes.

## Technical Context

**Language/Version**: PHP 8.4.15, Laravel 12.52  
**Primary Dependencies**: Pest 4, Filament 5.2.1, Livewire 4.1.4, current provider-operation and verification support seams  
**Storage**: no new runtime persistence; one spec-local `failure-classification.md` artifact only  
**Testing**: focused Pest feature reruns in `tests/Feature/ProviderConnections` and `tests/Feature/Verification`, plus conditional reuse of one existing browser smoke  
**Validation Lanes**: confidence, browser only when visible provider-connection disclosure changes  
**Target Platform**: Laravel monolith in `apps/platform`  
**Project Type**: web application  
**Performance Goals**: keep the slice bounded to the existing feature lane and avoid turning it into a new broad repair lane  
**Constraints**: no full-suite repair, no route-cutover repair, no new provider abstraction, no new schema version, no new panel, no new notification family, and no historical-spec rewrites  
**Scale/Scope**: one provider/verification stabilization slice covering 11 currently failing assertions across seven feature files and a small set of shared owner seams

## Pinned Failure-Classification Categories

- `surface-or-report-baseline-drift`
- `fixture-contract-drift`
- `provider-verification-runtime-regression`
- `dedupe-concurrency-contract-drift`
- `out-of-scope-existing-debt`
- `resolved-or-not-needed`

## Pinned Stabilization Seams

- `provider-neutrality-surface`
- `shared-startable-fixtures`
- `verification-start-contract`
- `provider-dispatch-concurrency`
- `verification-report-summary`

## Likely Affected Repo Surfaces

- `apps/platform/tests/Feature/ProviderConnections/ProviderConnectionNeutralitySpec238Test.php`
- `apps/platform/tests/Feature/ProviderConnections/ProviderDispatchGateStartSurfaceTest.php`
- `apps/platform/tests/Feature/ProviderConnections/ProviderOperationConcurrencyTest.php`
- `apps/platform/tests/Feature/Verification/VerificationAuthorizationTest.php`
- `apps/platform/tests/Feature/Verification/VerificationStartAfterCompletionTest.php`
- `apps/platform/tests/Feature/Verification/VerificationStartDedupeTest.php`
- `apps/platform/tests/Feature/Verification/ProviderConnectionHealthCheckWritesReportTest.php`
- `apps/platform/tests/Pest.php`
- `apps/platform/app/Services/Verification/StartVerification.php`
- `apps/platform/app/Services/Providers/ProviderOperationStartGate.php`
- `apps/platform/app/Services/OperationRunService.php` only if targeted reruns prove the run-identity owner needs a one-hop correction
- `apps/platform/app/Support/Providers/TargetScope/ProviderConnectionSurfaceSummary.php`
- `apps/platform/app/Support/Providers/TargetScope/ProviderConnectionTargetScopeNormalizer.php`
- `apps/platform/app/Support/Providers/TargetScope/ProviderConnectionTargetScopeDescriptor.php`
- `apps/platform/app/Services/Providers/MicrosoftProviderHealthCheck.php`
- `apps/platform/app/Support/Verification/VerificationReportSchema.php`
- existing verification report writer or provider-connection resource/view seams only if targeted reruns prove they are the direct owners

## Filament v5 / Surface Notes

- **Livewire v4.0+ compliance**: all touched admin surfaces remain on Filament v5 with Livewire v4
- **Provider registration location**: unchanged in `apps/platform/bootstrap/providers.php`
- **Global search rule**: `ProviderConnectionResource` remains non-globally-searchable; no new searchable resource is introduced
- **Destructive actions**: no new destructive action is planned; touched existing mutations must preserve `->action(...)`, `->requiresConfirmation()`, and server-side authorization
- **Asset strategy**: no asset registration or `filament:assets` deployment-step change is planned

## Stabilization Fit

- classify the target lane before changing runtime or tests
- align fixture contract drift before classifying runtime regressions
- prefer fixing stale expectations through the current shared owners instead of page-local or test-local shims
- allow a runtime fix only when the targeted rerun proves a canonical shared owner is wrong after fixture alignment
- keep visible provider-scope and report disclosure changes behind existing surfaces only
- keep remaining unrelated debt explicit in `failure-classification.md`

## UI / Surface Guardrail Plan

- **Guardrail scope**: existing provider connection resource surfaces, existing verification entry points, and existing verification report detail surfaces only
- **Native vs custom classification summary**: native Filament resource/detail surfaces and existing shared detail surfaces only
- **Shared-family relevance**: provider connection summary family, verification start-result family, and verification report family
- **State layers in scope**: table, detail, form, action-result follow-through, and DB-backed report detail only
- **Audience modes in scope**: operator-MSP, support-platform, and readonly-entitled report viewers
- **Decision/diagnostic/raw hierarchy plan**: neutral target-scope summary and report summary stay decision-first; nested provider identity detail and per-check evidence remain secondary
- **Raw/support gating plan**: raw payloads remain absent; provider-owned identity detail remains nested only
- **One-primary-action / duplicate-truth control**: no new action family; existing primary actions stay primary and no duplicate summary layer is introduced
- **Handling modes by drift class or surface**: in-scope provider/verification drift is implementation-required; unrelated debt is report-only in `failure-classification.md`
- **Repository-signal treatment**: review-mandatory if implementation tries to widen into route cutover, full-suite repair, or new provider abstractions
- **Special surface test profiles**: `standard-native-filament`, `shared-detail-family`
- **Required tests or manual smoke**: focused feature lane always; one existing provider-connection scope browser smoke only when visible provider-connection disclosure changes
- **Exception path and spread control**: no exception path is planned; if implementation would need one, stop and reclassify rather than widen silently
- **Active feature PR close-out entry**: `RuntimeSemantics`

## Shared Pattern & System Fit

- **Cross-cutting feature marker**: yes
- **Systems touched**: current provider connection summary, current verification start path, current provider-operation start gate, current verification report schema/writer path, and the current shared test-fixture contract
- **Shared abstractions reused**: `StartVerification`, `ProviderOperationStartGate`, `OperationRunService`, `ProviderConnectionSurfaceSummary`, `ProviderConnectionTargetScopeNormalizer`, `ProviderConnectionTargetScopeDescriptor`, and `VerificationReportSchema`
- **New abstraction introduced? why?**: none
- **Why the existing abstraction was sufficient or insufficient**: the abstractions already exist and own the relevant behavior; the missing piece is contract stabilization, not a new framework
- **Bounded deviation / spread control**: runtime changes are allowed only inside the current owner seams and only after fixture alignment proves the current owner is at fault

## OperationRun UX Impact

- **Touches OperationRun start/completion/link UX?**: yes
- **Central contract reused**: `ProviderOperationStartGate`, `StartVerification`, `OperationRunService`, and existing run-link helpers
- **Delegated UX behaviors**: `started`, `deduped`, `scopeBusy`, `blocked`, queue-dispatch decisions, and canonical run follow-through links remain delegated to the shared owners above
- **Surface-owned behavior kept local**: existing provider connection and verification entry points keep initiation placement only
- **Queued DB-notification policy**: unchanged
- **Terminal notification path**: unchanged
- **Exception path**: none

## Provider Boundary & Portability Fit

- **Shared provider/platform boundary touched?**: yes
- **Provider-owned seams**: nested Microsoft tenant identity details and provider-specific troubleshooting context
- **Platform-core seams**: neutral target-scope summary, verification start/result semantics, dedupe/scope-busy behavior, and report summary truth
- **Neutral platform terms / contracts preserved**: `provider connection`, `target scope`, `provider context`, `verification report`, `started`, `deduped`, `scope busy`, `blocked`
- **Retained provider-specific semantics and why**: Microsoft identity detail remains nested because current consent and verification troubleshooting still need it
- **Bounded extraction or follow-up path**: broader provider-boundary cleanup stays deferred; `294` only stabilizes the confirmed failing lane

## Constitution Check

*GATE: Must pass before implementation begins and again after the design artifacts are complete.*

- `Inventory-first, Snapshots-second`: PASS. `294` introduces no new inventory or snapshot truth.
- `Read/Write Separation by Default`: PASS. The slice stabilizes existing start/report behavior only.
- `Single Contract Path to Graph`: PASS by preservation. No new Graph seam is introduced.
- `PROV-001`: PASS. Shared neutral disclosure stays primary, provider-specific identity detail stays nested.
- `PROP-001`, `ABSTR-001`, `V1-EXP-001`, and `LAYER-001`: PASS. No new framework or layer is introduced.
- `PERSIST-001` and `STATE-001`: PASS. The only new vocabulary is spec-local failure classification, not runtime persistence or product state.
- `XCUT-001`: PASS. Existing shared provider/verification owners are reused.
- `RBAC-UX`: PASS by preservation. Non-member `404`, in-scope no-capability `403`, and no new raw capability checks are introduced.
- `TEST-GOV-001`: PASS. Proof stays in the narrowest honest feature lane with one conditional existing browser smoke only when needed.
- `UI-FIL-001`: PASS. Existing Filament surfaces remain native; no custom surface or asset family is introduced.
- `LEAN-001`: PASS. No compatibility shim, no legacy alias, and no historical-spec rewrite is planned.

**Gate evaluation**: PASS.

**Post-design re-check**: PASS while the same failure categories, seam names, proving commands, and out-of-scope boundary remain aligned across `spec.md`, `plan.md`, `research.md`, `data-model.md`, `quickstart.md`, `failure-classification.md`, `tasks.md`, and `checklists/requirements.md`.

## Test Governance Check

- **Test purpose / classification by changed surface**: Feature, with conditional Browser reuse only when visible provider-connection disclosure changes
- **Affected validation lanes**: confidence and conditional browser
- **Why this lane mix is the narrowest sufficient proof**: the failing contract already lives honestly in the targeted feature lane. Optional browser proof is justified only when visible provider-connection disclosure changes on a real provider surface. Verification-report disclosure remains bounded to feature-lane proof in `294`.
- **Narrowest proving command(s)**:
  - `export PATH="/bin:/usr/bin:/usr/local/bin:$PATH" && cd apps/platform && ./vendor/bin/sail artisan test --compact tests/Feature/ProviderConnections tests/Feature/Verification`
  - `export PATH="/bin:/usr/bin:/usr/local/bin:$PATH" && cd apps/platform && ./vendor/bin/sail artisan test --compact tests/Feature/Verification/VerificationAuthorizationTest.php tests/Feature/Verification/VerificationStartAfterCompletionTest.php tests/Feature/Verification/VerificationStartDedupeTest.php`
  - `export PATH="/bin:/usr/bin:/usr/local/bin:$PATH" && cd apps/platform && ./vendor/bin/sail artisan test --compact tests/Feature/ProviderConnections/ProviderDispatchGateStartSurfaceTest.php tests/Feature/ProviderConnections/ProviderOperationConcurrencyTest.php`
  - `export PATH="/bin:/usr/bin:/usr/local/bin:$PATH" && cd apps/platform && ./vendor/bin/sail artisan test --compact tests/Feature/ProviderConnections/ProviderConnectionNeutralitySpec238Test.php tests/Feature/Verification/ProviderConnectionHealthCheckWritesReportTest.php`
  - `export PATH="/bin:/usr/bin:/usr/local/bin:$PATH" && cd apps/platform && ./vendor/bin/sail artisan test --compact tests/Browser/Spec281ProviderConnectionScopeSmokeTest.php`
  - `export PATH="/bin:/usr/bin:/usr/local/bin:$PATH" && cd apps/platform && ./vendor/bin/sail bin pint --dirty --format agent`
- **Fixture / helper / factory / seed / context cost risks**: moderate only around the startable-fixture contract; no broader provider context should become implicit in more tests
- **Expensive defaults or shared helper growth introduced?**: no; fixture alignment should reduce hidden drift, not widen helper cost
- **Heavy-family additions, promotions, or visibility changes**: none
- **Surface-class relief / special coverage rule**: `standard-native-filament` and `shared-detail-family` remain sufficient
- **Closing validation and reviewer handoff**: reviewers must rerun the exact commands above, confirm the targeted lane is green, and only require the existing provider-connection scope browser smoke if visible provider-connection disclosure changed
- **Budget / baseline / trend follow-up**: none beyond feature-local upkeep
- **Review-stop questions**: did the work widen into route cutover, full-suite repair, or a new provider framework; did it change visible provider/report disclosure without rerunning the named existing browser smoke
- **Escalation path**: `document-in-feature` for residual notes; `reject-or-split` for scope expansion
- **Active feature PR close-out entry**: `RuntimeSemantics`
- **Why no dedicated follow-up spec is needed**: `294` itself is the dedicated follow-up for the remaining provider/verification lane after `293`

## Review Checklist Status

- **Review checklist artifact**: `checklists/requirements.md`
- **Review outcome class**: `acceptable-special-case`
- **Workflow outcome**: `keep`
- **Test-governance outcome**: `keep`
- **Resolution note**: the package is implementation-ready as one bounded provider/verification stabilization slice following Spec `293`
- **Escalation rule**: if implementation starts repairing unrelated full-suite debt, route cutover, or broader provider-boundary work, stop and split it out of `294`

## Rollout Considerations

- record the currently observed failing groups in `failure-classification.md` before changing tests or runtime
- align fixture contract drift before calling anything a runtime regression
- stabilize verification start semantics before provider-operation concurrency semantics, because both depend on the same gate ownership
- stabilize surface/report baseline drift after the runtime start contract settles, so tests do not chase a moving owner contract
- rerun the full targeted lane after each bounded slice, not just isolated files
- use the existing provider-connection scope browser smoke only when visible provider-connection disclosure actually changes

## Risk Controls

- reject any implementation that widens into full-suite repair outside the targeted lane
- reject any implementation that reopens route-cutover or workspace-aware link work already handled by Spec `293`
- reject any implementation that adds a new provider framework, new profile table, or new verification schema version
- reject any implementation that fixes visible disclosure drift only in tests while leaving the shared summary/report owner inconsistent
- reject any implementation that leaves remaining target-lane failures unclassified in `failure-classification.md`

## Research & Design Outputs

- `research.md` records the stabilization decisions, rejected alternatives, and evidence anchors
- `data-model.md` captures the pinned failure categories, seam inventory, and `failure-classification.md` structure
- `quickstart.md` gives reviewers the read order, review scenarios, exact proof commands, and stop conditions
- `failure-classification.md` records the confirmed current failing groups, their seams, categories, candidate owners, and bounded follow-up status
- `checklists/requirements.md` records the readiness and bounded-scope checks for the package

## Project Structure

### Documentation (this feature)

```text
specs/294-provider-verification-runtime-semantics/
├── checklists/
│   └── requirements.md
├── data-model.md
├── failure-classification.md
├── plan.md
├── quickstart.md
├── research.md
├── spec.md
└── tasks.md
```

### Source Code (repository root)

```text
apps/platform/
├── app/
│   ├── Services/
│   └── Support/
└── tests/
    ├── Browser/
    └── Feature/
```

**Structure Decision**: keep the package inside the existing Laravel app and test structure. Reuse current provider/verification tests, shared owner seams, and one existing browser smoke instead of inventing a new stabilization subsystem.

## Complexity Tracking

| Violation | Why Needed | Simpler Alternative Rejected Because |
|---|---|---|
| Spec-local failure-classification vocabulary | The lane needs one shared bounded way to separate fixture drift, runtime regression, concurrency drift, and surface/report drift before implementation | Ad hoc notes or one-off fixes would make the package drift back into unsourced local patches |