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

# Quickstart: Provider Verification Runtime Semantics Stabilization

## Purpose

`294` is the bounded follow-up to Spec `293`. It exists only to stabilize the remaining provider and verification runtime semantics block still failing inside:

- `tests/Feature/ProviderConnections`
- `tests/Feature/Verification`

It is not a full-suite repair, not a route-cutover package, and not a broader provider-boundary refresh.

## Preconditions

- Stay on branch `294-provider-verification-runtime-semantics`.
- Run all PHP, Artisan, and formatter commands through Sail.
- Keep the macOS PATH workaround when using terminal commands in this workspace:

```bash
export PATH="/bin:/usr/bin:/usr/local/bin:$PATH"
```

- Treat Spec `293` as inherited context only.
- Do not implement any route-cutover or `/admin/t/...` repair under this package.

## Read Order

1. `spec.md`
2. `plan.md`
3. `research.md`
4. `data-model.md`
5. `failure-classification.md`
6. `tasks.md`
7. `checklists/requirements.md`

## Implementation Intent

- Classify the current failing lane before changing tests or runtime.
- Clear fixture-contract drift before widening runtime changes.
- Reuse the current shared owners: `StartVerification`, `ProviderOperationStartGate`, `OperationRunService`, `ProviderConnectionSurfaceSummary`, and `VerificationReportSchema`.
- Keep provider-neutral disclosure primary and provider-specific identity detail nested.
- Keep validation bounded to the target feature lane, with one conditional existing provider-connection scope browser smoke only if provider-connection disclosure changes visibly.

## 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`

## Grouping Unit

`294` tracks one failure group per failing test file or failing scenario cluster that shares one seam and one category. The authoritative grouped baseline lives in `failure-classification.md`.

## Review Scenarios

### Scenario 1: Verification start contract

- Canonical startable verification fixtures should return `started`.
- Repeated active starts should return `deduped`.
- Post-completion starts should create a new run.
- `blocked` should remain reserved for real prerequisite failures.

### Scenario 2: Provider-operation concurrency

- Same-operation active reruns should dedupe.
- Different active operations on the same provider connection should return one shared `scopeBusy` follow-through.
- Queue counts and created runs must stay aligned with the shared gate contract.

### Scenario 3: Surface and report baselines

- Provider connection surfaces should keep neutral target-scope disclosure as the primary truth.
- Provider-specific Microsoft identity detail may stay nested, but must not replace the neutral disclosure.
- Verification report counts must track the current emitted check inventory, not a stale literal ceiling.

## Planned Proof Commands

### Full in-scope lane

```bash
export PATH="/bin:/usr/bin:/usr/local/bin:$PATH" && cd apps/platform && ./vendor/bin/sail artisan test --compact tests/Feature/ProviderConnections tests/Feature/Verification
```

### Verification start cluster

```bash
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
```

### Provider dispatch and concurrency cluster

```bash
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
```

### Surface and report baseline cluster

```bash
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
```

### Conditional existing browser smoke

Run this only if implementation changes visible provider-connection disclosure:

```bash
export PATH="/bin:/usr/bin:/usr/local/bin:$PATH" && cd apps/platform && ./vendor/bin/sail artisan test --compact tests/Browser/Spec281ProviderConnectionScopeSmokeTest.php
```

### Formatting

```bash
export PATH="/bin:/usr/bin:/usr/local/bin:$PATH" && cd apps/platform && ./vendor/bin/sail bin pint --dirty --format agent
```

## Stop Conditions

Stop and split the work out of `294` if any of the following becomes necessary:

- route-cutover or `/admin/t/...` repair
- full-suite cleanup outside `tests/Feature/ProviderConnections` and `tests/Feature/Verification`
- a new provider abstraction, provider-profile table, capability registry, or verification schema version
- reopening historical Specs `238`, `188`, `084`, or `074` as implementation targets
- adding a new browser family instead of reusing the existing provider-scope smoke

## Expected Close-Out State

- the full in-scope ProviderConnections/Verification lane is green
- `failure-classification.md` reflects the final disposition of every currently failing group
- any visible provider-connection disclosure change is backed by the existing provider-connection scope browser smoke
- no out-of-scope debt has been silently absorbed