TenantAtlas/specs/195-action-surface-closure/quickstart.md

# Quickstart: Action Surface Enforcement, Enrollment, and Exception Closure

## Goal

Implement Spec 195 by making every residual action-bearing surface explicitly reviewable without widening the generic action-surface runtime contract.

## Implementation Sequence

### 1. Add the Spec 195 residual closure inventory

Touch:

- `apps/platform/app/Support/Ui/ActionSurface/ActionSurfaceExemptions.php`
- `apps/platform/app/Support/Ui/ActionSurface/ActionSurfaceValidator.php`

Do:

- Add `spec195ResidualSurfaceInventory()` with one entry per residual target surface.
- Add validator support for:
  - allowed closure decisions
  - allowed reason categories
  - required structured evidence descriptors
  - duplicate key detection
  - truthful `discoveryState`
  - stale baseline-exemption detection

Do not:

- auto-discover every system page
- introduce new persistence
- add a new runtime resolver or registry outside the existing action-surface support layer

### 2. Close the non-discovered system/detail surfaces explicitly

Audit and classify:

- `App\Filament\System\Pages\Dashboard`
- `App\Filament\System\Pages\Ops\ViewRun`
- `App\Filament\System\Pages\Ops\Runbooks`
- `App\Filament\System\Pages\RepairWorkspaceOwners`
- `App\Filament\System\Pages\Directory\ViewTenant`
- `App\Filament\System\Pages\Directory\ViewWorkspace`

Expected direction:

- `Dashboard`, `ViewRun`, `Runbooks`, `RepairWorkspaceOwners` => `separately_governed`
- `ViewTenant`, `ViewWorkspace` => `harmless_special_case` if they remain read-mostly contextual drilldowns

Only move one of these pages into `actionSurfaceDeclaration()` if the implementation audit shows it already fits the existing declaration-backed list/detail model naturally.

### 3. Reclassify the currently baseline-exempt special pages

Audit and classify:

- `App\Filament\Pages\BreakGlassRecovery`
- `App\Filament\Pages\ChooseWorkspace`
- `App\Filament\Pages\ChooseTenant`
- `App\Filament\Pages\Tenancy\RegisterTenant`
- `App\Filament\Pages\Workspaces\ManagedTenantOnboardingWizard`
- `App\Filament\Pages\Workspaces\ManagedTenantsLanding`
- `App\Filament\Pages\TenantDashboard`

Expected direction:

- `BreakGlassRecovery` => retire if it remains inaccessible and actionless; otherwise keep it as `intentional_exemption` with `security_flow_exception`
- `ChooseWorkspace`, `ChooseTenant` => `harmless_special_case`
- `RegisterTenant`, `ManagedTenantOnboardingWizard` => `separately_governed`
- `ManagedTenantsLanding` => explicit closure plus focused test
- `TenantDashboard` => `harmless_special_case` for the page shell while widget behavior stays governed by existing tests

### 4. Add CI regression protection

Touch:

- `tests/Feature/Guards/ActionSurfaceContractTest.php`
- `tests/Feature/Guards/ActionSurfaceValidatorTest.php`
- `tests/Feature/Guards/Spec195ResidualActionSurfaceClosureGuardTest.php`

Do:

- fail when a residual target has no closure entry
- fail when a non-enrolled residual target has no reason category
- fail when a discovered residual page remains in `baseline()` but has no matching Spec 195 inventory entry
- fail when a retired residual surface still keeps a baseline exemption

### Reviewer Classification Workflow

Use this path whenever an audit uncovers a residual page that is not already in the seed inventory.

1. Identify whether the page is inside primary discovery or outside it.
2. Add or update the residual inventory entry with `surfaceKey`, `surfaceName`, `pageClass`, `panelPlane`, `surfaceKind`, `discoveryState`, `closureDecision`, `reasonCategory` where relevant, `explicitReason`, structured `evidence`, and `followUpAction`.
3. If the page legitimately fits the generic contract, extend the existing contract tests instead of inventing a new local rule.
4. If the page remains separate, harmless, exempt, or retired, add or update focused guard and page-level evidence before merge.
5. Run the focused verification pack and confirm the reviewer can classify the page from guard output alone.
6. Treat the validator failure output as part of the workflow: missing Spec 195 entries should name the class and the concrete file path reviewers must classify next.

### 5. Fill current coverage gaps only where needed

Likely new tests:

- `tests/Feature/System/Spec195/SystemDirectoryResidualSurfaceTest.php`
- `tests/Feature/Workspaces/Spec195ManagedTenantsLandingTest.php`

Reuse existing evidence instead of duplicating it for:

- `ViewRun`
- `Runbooks`
- `RepairWorkspaceOwners`
- chooser flows
- tenant registration
- onboarding wizard
- tenant dashboard shell

## Suggested Test Pack

Run the minimum targeted verification pack through Sail.

```bash
export PATH="/bin:/usr/bin:/usr/local/bin:$PATH"
cd apps/platform && ./vendor/bin/sail artisan test --compact tests/Feature/Guards/ActionSurfaceContractTest.php
cd apps/platform && ./vendor/bin/sail artisan test --compact tests/Feature/Guards/ActionSurfaceValidatorTest.php
cd apps/platform && ./vendor/bin/sail artisan test --compact tests/Feature/Guards/Spec195ResidualActionSurfaceClosureGuardTest.php
cd apps/platform && ./vendor/bin/sail artisan test --compact tests/Feature/Guards/Spec194GovernanceActionSemanticsGuardTest.php
cd apps/platform && ./vendor/bin/sail artisan test --compact tests/Feature/Guards/LivewireTrustedStateGuardTest.php
cd apps/platform && ./vendor/bin/sail artisan test --compact tests/Feature/Guards/FilamentTableStandardsGuardTest.php
cd apps/platform && ./vendor/bin/sail artisan test --compact tests/Feature/System/Spec113/AuthorizationSemanticsTest.php
cd apps/platform && ./vendor/bin/sail artisan test --compact tests/Feature/System/Spec114/OpsTriageActionsTest.php
cd apps/platform && ./vendor/bin/sail artisan test --compact tests/Feature/System/OpsRunbooks/FindingsLifecycleBackfillStartTest.php
cd apps/platform && ./vendor/bin/sail artisan test --compact tests/Feature/Auth/BreakGlassWorkspaceOwnerRecoveryTest.php
cd apps/platform && ./vendor/bin/sail artisan test --compact tests/Feature/Auth/TenantChooserSelectionTest.php
cd apps/platform && ./vendor/bin/sail artisan test --compact tests/Feature/Workspaces/ChooseWorkspacePageTest.php
cd apps/platform && ./vendor/bin/sail artisan test --compact tests/Feature/Workspaces/WorkspaceAuditTrailTest.php
cd apps/platform && ./vendor/bin/sail artisan test --compact tests/Feature/TenantRBAC/TenantSwitcherScopeTest.php
cd apps/platform && ./vendor/bin/sail artisan test --compact tests/Feature/Rbac/RegisterTenantAuthorizationTest.php
cd apps/platform && ./vendor/bin/sail artisan test --compact tests/Feature/TenantRBAC/TenantBootstrapAssignTest.php
cd apps/platform && ./vendor/bin/sail artisan test --compact tests/Feature/Rbac/OnboardingWizardUiEnforcementTest.php
cd apps/platform && ./vendor/bin/sail artisan test --compact tests/Feature/Onboarding/OnboardingDraftAccessTest.php
cd apps/platform && ./vendor/bin/sail artisan test --compact tests/Feature/Filament/TenantDashboardDbOnlyTest.php
cd apps/platform && ./vendor/bin/sail artisan test --compact tests/Feature/Rbac/TenantDashboardArrivalContextVisibilityTest.php
cd apps/platform && ./vendor/bin/sail artisan test --compact tests/Feature/System/Spec195/SystemDirectoryResidualSurfaceTest.php
cd apps/platform && ./vendor/bin/sail artisan test --compact tests/Feature/Workspaces/Spec195ManagedTenantsLandingTest.php
cd apps/platform && ./vendor/bin/sail bin pint --dirty --format agent
```

## Manual Review Checklist

1. Confirm that the primary discovery count does not grow unexpectedly when Spec 195 lands.
2. Confirm that every in-scope residual surface has exactly one closure decision.
3. Confirm that non-discovered system/detail pages are now reviewable through the residual inventory and guard output.
4. Confirm that discovered special pages still exempted from the generic contract now carry explicit reason categories, explicit reasons, and structured evidence.
5. Confirm that `BreakGlassRecovery` is either retired from active exemptions or explicitly kept as `intentional_exemption` with `security_flow_exception` and current evidence.
6. Confirm that the weakest surfaces, expected to be `ManagedTenantsLanding` and system directory detail pages, have explicit focused tests.
7. Confirm that any newly audited residual surface beyond the initial seed was added to the inventory, contract, and guard expectations.

## Deployment Notes

- No migration is expected.
- No provider registration change is expected.
- No new assets are expected.
- Existing `cd apps/platform && php artisan filament:assets` deploy handling remains sufficient but unchanged.