TenantAtlas/specs/305-feature-readiness-gate-audit/plan.md

Implementation Plan: Feature Readiness Gate Audit

Branch: 305-feature-readiness-gate-audit | Date: 2026-05-15 | Spec: specs/305-feature-readiness-gate-audit/spec.md Input: Feature specification from /specs/305-feature-readiness-gate-audit/spec.md

Summary

Create a docs-only readiness gate for TenantPilot after Specs 301-304. The implementation is repository inspection plus one audit artifact that decides whether the next productization feature, likely Decision Register & Approval Workflow v1, may start. No application runtime, migrations, tests, routes, UI, or roadmap content will be changed.

Technical Context

Language/Version: PHP 8.4.15, Laravel 12.52.0, Filament 5.2.1, Livewire 4.1.4 Primary Dependencies: Laravel, Filament v5, Livewire v4, Pest 4, PostgreSQL via Sail Storage: N/A for this feature; existing PostgreSQL schema is read only for audit evidence Testing: Existing Pest feature/unit/browser tests only; no new tests Validation Lanes: confidence via focused feature/unit tests; browser tests cited where existing and relevant; git diff --check Target Platform: Laravel Sail local development, Dokploy container deployment for staging/production unchanged Project Type: Laravel monolith under apps/platform plus docs/spec artifacts Performance Goals: N/A - docs-only Constraints: No runtime code changes, no migrations, no test edits, no UI surfaces, no Decision Register feature work Scale/Scope: One readiness gate over 12 requested audit areas

UI / Surface Guardrail Plan

• Guardrail scope: no operator-facing surface change.
• Native vs custom classification summary: N/A.
• Shared-family relevance: audit references navigation, governance, evidence, reviews, RBAC, audit, and OperationRun links as existing families only.
• State layers in scope: none.
• Audience modes in scope: N/A.
• Decision/diagnostic/raw hierarchy plan: N/A.
• Raw/support gating plan: N/A.
• One-primary-action / duplicate-truth control: The audit prevents duplicate next-feature truth by distinguishing existing Decision Register runtime from a legitimate follow-up spec.
• Handling modes by drift class or surface: Stale roadmap/spec-candidate truth is recorded as a condition, not silently rewritten.
• Repository-signal treatment: review-mandatory.
• Special surface test profiles: global-context-shell, standard-native-filament, shared-detail-family, monitoring-state-page evidence only.
• Required tests or manual smoke: focused feature/unit validation. No new browser smoke required for docs-only changes.
• Exception path and spread control: none.
• Active feature PR close-out entry: Guardrail.

Shared Pattern & System Fit

• Cross-cutting feature marker: yes, audit-only.
• Systems touched: Spec Kit docs under specs/305-feature-readiness-gate-audit/.
• Shared abstractions reused: No runtime reuse. Evidence can reference existing runtime abstractions such as WorkspaceScopedTenantRoutes, ScopesGlobalSearchToTenant, OperationRunLinks, governance builders, policy/capability helpers, and audit recorders.
• New abstraction introduced? why?: none.
• Why the existing abstraction was sufficient or insufficient: Existing repo structures provide enough evidence for a readiness decision.
• Bounded deviation / spread control: The only output beyond standard Spec Kit files is feature-readiness-audit.md.

OperationRun UX Impact

• Touches OperationRun start/completion/link UX?: no.
• Central contract reused: N/A.
• Delegated UX behaviors: N/A.
• Surface-owned behavior kept local: none.
• Queued DB-notification policy: N/A.
• Terminal notification path: N/A.
• Exception path: none.

Provider Boundary & Portability Fit

• Shared provider/platform boundary touched?: no.
• Provider-owned seams: N/A.
• Platform-core seams: N/A.
• Neutral platform terms / contracts preserved: Existing terms remain unchanged.
• Retained provider-specific semantics and why: none.
• Bounded extraction or follow-up path: none.

Constitution Check

GATE: Must pass before Phase 0 research. Re-check after Phase 1 design.

• Inventory-first: pass. The audit distinguishes current repo evidence from roadmap/spec-candidate intent.
• Read/write separation: pass. No writes to runtime data or external systems.
• Graph contract path: N/A. No Graph calls or contracts changed.
• Deterministic capabilities: pass. Existing capability/RBAC tests may be cited; no capability logic changed.
• RBAC-UX: pass. The audit verifies admin/system separation, workspace isolation, global search posture, and retired tenant-panel routes as evidence.
• Workspace isolation: pass. The audit checks workspace-first admin runtime and environment-bound surfaces.
• Destructive-like actions require confirmation: pass. No actions changed; existing destructive action posture is evidence only.
• Tenant isolation: pass. No runtime reads/writes changed.
• Run observability: pass. No new OperationRun creation; existing link/execution truth is audited.
• OperationRun start UX: pass. No start/link semantics are changed.
• Ops-UX lifecycle: pass. No lifecycle code changed.
• Ops-UX summary counts: pass. No summary counts changed.
• Ops-UX guards: pass. Existing guard tests are used where relevant.
• Automation: N/A.
• Data minimization: pass. No data storage/logging changes.
• Test governance (TEST-GOV-001): pass. The spec records the focused validation lane without adding tests.
• Proportionality (PROP-001): pass. Documentation artifact only; no runtime structure.
• No premature abstraction (ABSTR-001): pass. No new abstractions.
• Persisted truth (PERSIST-001): pass. No persisted runtime truth.
• Behavioral state (STATE-001): pass. No new states.
• UI semantics (UI-SEM-001): pass. No UI semantics changed.
• Shared pattern first (XCUT-001): pass. Audit references existing shared paths only.
• Provider boundary (PROV-001): pass. No provider boundary changes.
• V1 explicitness / few layers (V1-EXP-001, LAYER-001): pass. One docs artifact.
• Spec discipline / bloat check (SPEC-DISC-001, BLOAT-001): pass. Scope is limited to the readiness gate.
• Badge semantics (BADGE-001): N/A.
• Filament-native UI (UI-FIL-001): pass. No Filament UI changes.
• UI/UX surface taxonomy (UI-CONST-001 / UI-SURF-001): N/A.
• Decision-first operating model (DECIDE-001): pass. The audit itself gates a product decision; no operator surface changes.
• Audience-aware disclosure (DECIDE-AUD-001 / OPSURF-001): N/A.
• UI/UX inspect model (UI-HARD-001): N/A.
• UI/UX action hierarchy (UI-HARD-001 / UI-EX-001): N/A.
• UI/UX scope, truth, and naming (UI-HARD-001 / UI-NAMING-001 / OPSURF-001): pass. No naming changes.
• UI/UX placeholder ban (UI-HARD-001): N/A.
• UI naming (UI-NAMING-001): N/A.
• Operator surfaces (OPSURF-001): pass. No operator surface changes.
• Filament UI Action Surface Contract: pass. No Filament Resource/RelationManager/Page changes.
• Filament UI UX-001 (Layout & IA): N/A.
• Action-surface discipline (ACTSURF-001 / HDR-001): N/A.
• UI review workflow: pass. Guardrail classification is explicit and not duplicated into runtime work.

Test Governance Check

• Test purpose / classification by changed surface: N/A for changed files; existing focused tests are used as readiness evidence.
• Affected validation lanes: confidence via existing feature/unit tests; browser lane is not required for a docs-only diff.
• Why this lane mix is the narrowest sufficient proof: The artifact changes only documentation. Focused tests prove the repo foundations being audited are currently green where practical.
• Narrowest proving command(s):
  • cd apps/platform && ./vendor/bin/sail artisan test --compact tests/Feature/Guards/NoLegacyTenantPanelRuntimeTest.php tests/Feature/Guards/NoActiveTenantResourceRoutesTest.php tests/Feature/Workspaces/WorkspaceIntendedUrlLegacyRejectionTest.php
  • cd apps/platform && ./vendor/bin/sail artisan test --compact tests/Feature/Filament/PanelNavigationSegregationTest.php tests/Feature/Filament/AdminTenantSurfaceParityTest.php tests/Feature/Filament/AdminSharedSurfacePanelParityTest.php tests/Feature/Filament/TenantOwnedResourceScopeParityTest.php tests/Feature/Filament/InventoryCoverageAdminTenantParityTest.php tests/Feature/Filament/EntraGroupAdminScopeTest.php tests/Feature/Filament/EntraGroupGlobalSearchScopeTest.php tests/Feature/Filament/PolicyResourceAdminSearchParityTest.php tests/Feature/Filament/PolicyVersionAdminSearchParityTest.php
  • cd apps/platform && ./vendor/bin/sail artisan test --compact tests/Unit/Support/GovernanceDecisions/GovernanceDecisionRegisterBuilderTest.php tests/Unit/Support/GovernanceInbox/GovernanceInboxSectionBuilderTest.php tests/Feature/Governance/DecisionRegisterPageTest.php tests/Feature/Governance/DecisionRegisterAuthorizationTest.php tests/Feature/Governance/GovernanceInboxPageTest.php tests/Feature/Governance/GovernanceInboxAuthorizationTest.php tests/Feature/Findings/FindingExceptionDecisionRegisterNavigationTest.php tests/Feature/Findings/FindingExceptionDetailDecisionSummaryTest.php tests/Feature/Findings/FindingExceptionDecisionRegisterBoundariesTest.php
  • cd apps/platform && ./vendor/bin/sail artisan test --compact tests/Feature/Evidence/EvidenceSnapshotResourceTest.php tests/Feature/Evidence/EvidenceSnapshotAuditLogTest.php tests/Feature/EnvironmentReview/EnvironmentReviewAuditLogTest.php tests/Feature/EnvironmentReview/EnvironmentReviewRegisterTest.php tests/Feature/EnvironmentReview/EnvironmentReviewRegisterRbacTest.php tests/Feature/Reviews/CustomerReviewWorkspacePageTest.php tests/Feature/Reviews/CustomerReviewWorkspaceAuthorizationTest.php tests/Feature/Reviews/CustomerReviewWorkspacePackAccessTest.php tests/Feature/Reviews/CustomerReviewWorkspaceLaunchLinksTest.php tests/Feature/Filament/GovernanceArtifacts/GovernanceArtifactDeepLinkContractTest.php
  • cd apps/platform && ./vendor/bin/sail artisan test --compact tests/Feature/Monitoring/OperationsDashboardDrillthroughTest.php tests/Feature/Operations/LegacyRunRoutesNotFoundTest.php tests/Feature/ProviderConnections/LegacyRedirectTest.php tests/Feature/RequiredPermissions/RequiredPermissionsLegacyRouteTest.php tests/Feature/Guards/ManagedEnvironmentCanonicalRouteContractTest.php tests/Feature/Filament/PolicyVersionResolvedReferenceLinksTest.php
  • git diff --check
• Fixture / helper / factory / seed / context cost risks: none.
• Expensive defaults or shared helper growth introduced?: no.
• Heavy-family additions, promotions, or visibility changes: none.
• Surface-class relief / special coverage rule: N/A.
• Closing validation and reviewer handoff: Confirm tests were run or explicitly recorded as skipped with reason; confirm git status --short stays under specs/305-feature-readiness-gate-audit/.
• Budget / baseline / trend follow-up: none.
• Review-stop questions: Does the audit accidentally start a feature spec, change application code, or treat stale docs as stronger than repo truth?
• Escalation path: document-in-feature if validation exposes an existing blocker.
• Active feature PR close-out entry: Guardrail.
• Why no dedicated follow-up spec is needed: This is the dedicated readiness gate requested by the user.

Filament v5 Output Contract

• Livewire v4.0+ compliance: The installed runtime is Livewire 4.1.4 with Filament 5.2.1; this feature makes no runtime changes and introduces no Livewire v3 references.
• Provider registration location: Existing panel providers remain registered in apps/platform/bootstrap/providers.php. This feature does not modify provider registration.
• Globally searchable resources: Existing audited posture only. EntraGroupResource is globally searchable and has a View page. InventoryItemResource has a View page. Policy, PolicyVersion, FindingException, EvidenceSnapshot, EnvironmentReview, ReviewPack, and StoredReport surfaces are disabled for global search or remain non-global-search evidence as recorded in the audit.
• Destructive actions: None introduced or changed. Existing destructive actions remain outside this docs-only diff; confirmation and authorization are validated only through existing tests/resource inspection.
• Asset strategy: No assets added or changed. Existing deployment posture for Filament assets remains unchanged; deploys that publish registered Filament assets still run cd apps/platform && php artisan filament:assets.
• Testing plan: Existing focused Filament/navigation, governance, findings, evidence, review, OperationRun/route-retirement, and git diff --check validations are listed above. No Livewire tests are added or modified.

Project Structure

Documentation (this feature)

specs/305-feature-readiness-gate-audit/
|-- checklists/
|   `-- requirements.md
|-- feature-readiness-audit.md
|-- plan.md
|-- spec.md
`-- tasks.md

Source Code (repository root)

apps/platform/
`-- unchanged

specs/301-admin-inventory-navigation-cutover/
specs/302-tenant-owned-surface-route-audit/
specs/303-admin-directory-groups-cutover/
specs/304-tenant-panel-dead-code-retirement/
`-- read-only evidence

Structure Decision: Documentation-only Spec Kit artifact under specs/305-feature-readiness-gate-audit/; no source code structure changes.

Complexity Tracking

Violation	Why Needed	Simpler Alternative Rejected Because
None	N/A	N/A

Phase Plan

1. Audit prep: Read Constitution, roadmap/spec candidates, Specs 301-304, related close-out notes, and relevant runtime/test evidence.
2. Evidence collection: Inspect route/provider state, resource/global-search posture, governance/finding/evidence/review/OperationRun/RBAC/audit foundations, and existing tests.
3. Artifact creation: Write feature-readiness-audit.md with the required readiness matrix, blocker actions, validation evidence, and next-feature recommendation.
4. Validation: Run focused tests where practical and git diff --check.
5. Close-out: Confirm only spec artifacts changed and summarize GO / GO WITH CONDITIONS / NO-GO.