ahmido/TenantAtlas
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects 1 Releases Wiki Activity
5bc9867397
TenantAtlas/specs/195-action-surface-closure/quickstart.md
Ahmed Darrazi 5bc9867397 feat: close spec 195 action surface residuals
2026-04-13 09:46:47 +02:00

8.4 KiB
Raw Blame History

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.

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.