TenantAtlas/specs/169-action-surface-v11/quickstart.md

Quickstart: Action Surface Contract v1.1

Goal

Validate that the action-surface contract now governs behavior, not just declaration presence: every enrolled reference surface declares an explicit constitution-aligned surfaceType, the primary validator discovers the enrolled system-panel list pages, clickable-row and explicit-inspect rules are enforced, and representative More menus keep helpers first, workflow actions next, and destructive actions last.

Prerequisites

1. Start Sail.
2. Ensure the database and factories are available for the current test suite.
3. Keep the current baseline exemptions intact for deferred choosers, dashboards, widgets, onboarding flows, and non-enrolled system pages.
4. Ensure representative tenant-plane and system-plane test helpers continue to work:
   • tenant helper for standard resources and monitoring pages
   • platform helper for system-panel pages

Implementation Validation Order

1. Run low-level validator coverage

vendor/bin/sail artisan test --compact tests/Feature/Guards/ActionSurfaceValidatorTest.php

Expected outcome:

• Missing surfaceType fails.
• Invalid surfaceType and inspect-affordance combinations fail with actionable messages.
• PrimaryLinkColumn requires an explicit reason when used.

2. Run representative rendered action-surface guards

vendor/bin/sail artisan test --compact tests/Feature/Guards/ActionSurfaceContractTest.php

Expected outcome:

• Clickable-row references still render recordUrl() and do not expose redundant lone View actions.
• Explicit-inspect history and queue references preserve context and do not regress to row click.
• Reporting and evidence registers remain scan-first clickable-row registries rather than being misclassified as audit surfaces.
• System-panel reference pages are discovered by the primary validator without stale baseline exemptions.
• Representative More menus keep helpers first, workflow actions next, destructive actions last, and do not render empty placeholder groups.

3. Run RBAC-aware tenant reference coverage

vendor/bin/sail artisan test --compact tests/Feature/Rbac/TenantActionSurfaceConsistencyTest.php

Expected outcome:

• Tenant resource row-click and overflow behavior remains aligned with disabled-vs-forbidden capability semantics.
• Existing More-menu placement still cooperates with RBAC visibility rules.

4. Format touched implementation files

vendor/bin/sail bin pint --dirty --format agent

Expected outcome:

• Touched PHP files follow the repo’s Pint rules.

Manual Smoke Check

1. Open /admin/operations and confirm the list still opens records through row click without a redundant row-level View action.
2. Open /admin/audit-log and confirm inspection stays explicit and context-preserving rather than row-click navigation.
3. Open /admin/finding-exceptions/queue and confirm inspection remains explicit while decision actions stay tied to the selected record context.
4. Open /system/ops/runs and /system/directory/tenants as a platform user and confirm those pages still behave as read-only registries while now also belonging to the main validator discovery pass.
5. Confirm deferred surfaces such as chooser pages, dashboards, widgets, and runbooks remain out of scope.

Non-Goals For This Slice

• No new database migration or persisted artifact.
• No new asset or filament:assets deployment change.
• No new policy or capability family.
• No new public HTTP API; the contract artifact is internal planning documentation only.