ahmido/TenantAtlas
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects 1 Releases Wiki Activity
platform-dev
TenantAtlas/specs/305-feature-readiness-gate-audit/feature-readiness-audit.md
ahmido f24e72269c docs: add Spec 305 readiness gate audit (#360) 
## Summary
- add the Spec 305 docs-only readiness gate package under `specs/305-feature-readiness-gate-audit/`
- record a repo-based readiness audit after Specs 301-304 across workspace/admin runtime, environment-bound surfaces, legacy route retirement, governance, OperationRun links, evidence/reports, findings, reviews, RBAC, audit, navigation, and test lanes
- document the final recommendation as `GO WITH CONDITIONS`
- explicitly block a fresh greenfield `Decision Register & Approval Workflow v1` restart because repo truth already includes Spec 265 runtime and tests
- capture the required follow-up: reconcile stale product queue docs or start a narrowly scoped follow-up that builds on existing Decision Register truth

## Scope
- docs-only audit artifact plus Spec Kit files
- no application runtime changes
- no migrations
- no UI or route changes
- no test edits

## Key Conditions Recorded
- do not create a duplicate fresh Decision Register v1 spec
- reconcile stale `docs/product/implementation-ledger.md` and `docs/product/spec-candidates.md` before using them as queue truth
- keep future work on canonical workspace/environment admin routes
- split future artifact lifecycle or approval-mutation changes into explicit follow-up specs

## Filament / Runtime Notes
- remains compliant with Filament v5 on Livewire v4
- no provider registration changes; provider registration location remains `apps/platform/bootstrap/providers.php`
- no globally searchable resources were added or changed in this docs-only PR
- no destructive actions were added or changed
- no asset registration changes; existing deploy posture for `cd apps/platform && php artisan filament:assets` is unchanged

## Validation Notes
- the audit artifact records the focused repo validation evidence used for the readiness decision
- no new runtime validation was executed in this turn beyond committing and pushing the docs-only package

Co-authored-by: Ahmed Darrazi <ahmed.darrazi@live.de>
Reviewed-on: #360
2026-05-15 09:00:38 +00:00

105 lines
14 KiB
Markdown
Raw Permalink Blame History

# Feature Readiness Audit
**Spec**: 305-feature-readiness-gate-audit
**Branch**: `305-feature-readiness-gate-audit`
**Audit date**: 2026-05-15
**Scope**: Docs-only repo audit after Specs 301-304
**Result**: GO WITH CONDITIONS
## Executive Recommendation
TenantPilot is ready to resume productization planning on top of the workspace-first `/admin` runtime, environment-bound routes, retired legacy tenant-panel posture, governance foundations, OperationRun links, evidence/report artifacts, findings/risk acceptance, reviews/review packs, RBAC/capabilities, audit/event foundations, and focused test lanes.
The next feature must not restart `Decision Register & Approval Workflow v1` as a fresh greenfield spec. Repo evidence shows Decision Register work already exists under Spec 265 with runtime pages, builders, navigation, and tests. The valid next step is either:
1. Close out and reconcile the existing Decision Register implementation and stale product docs, or
2. Start a narrowly named follow-up spec that builds on the implemented Decision Register truth without duplicating Spec 265.
The recommendation is **GO WITH CONDITIONS**:
- **Condition 1**: Do not create a duplicate fresh `Decision Register & Approval Workflow v1` spec. Treat existing Spec 265/runtime as current repo truth.
- **Condition 2**: Reconcile stale product queue docs before using them as the source for next-feature selection. `docs/product/implementation-ledger.md` and `docs/product/spec-candidates.md` still describe Decision Register as not implemented or only partly repo-real.
- **Condition 3**: Keep the next productization slice on canonical workspace/environment routes and do not reintroduce `/admin/t` or `/admin/tenants` compatibility.
- **Condition 4**: If the next slice changes artifact lifecycle, retention, export, or approval mutation behavior, split that into an explicit feature spec rather than bundling it into this gate.
## Readiness Matrix
| # | Readiness Area | Status | Repo Evidence | Caveat / Blocker | Recommended Action |
|---|---|---|---|---|---|
| 1 | Workspace/Admin Runtime Readiness | ready | `apps/platform/bootstrap/providers.php` registers `AdminPanelProvider` and `SystemPanelProvider`; `apps/platform/app/Providers/Filament/AdminPanelProvider.php` owns the `/admin` panel; Spec 304 records tenant-panel runtime dead-code retirement. | No runtime caveat found for next planning. | Start next work from the workspace-first `/admin` runtime. Keep provider registration in `bootstrap/providers.php` for Laravel 11+/12. |
| 2 | Environment-bound Surface Readiness | ready with caveat | Canonical environment routes exist under `/admin/workspaces/{workspace}/environments/{environment}`; `WorkspaceScopedTenantRoutes`, `ResolvesPanelTenantContext`, and `TenantOwnedModelFamilies` define the current tenant/environment surface posture; Specs 301-303 validated Inventory and Entra Groups cutovers. | Governance artifact proof is distributed across several resource/test families rather than one single route-audit proof. | For the next runtime feature, cite the exact resource/test family touched and keep deep links canonical under workspace/environment routes. |
| 3 | Legacy Route/Panel Retirement Readiness | ready | Specs 302 and 304 record no active `/admin/t` or `/admin/tenants` route families; route inspection returns no matching legacy routes; 304 added guard coverage for absent tenant panel runtime and legacy route rejection. | No blocker found. | Do not add compatibility aliases. Any next feature route must be canonical workspace/admin only. |
| 4 | Governance Feature Foundation Readiness | ready with caveat | `GovernanceInbox` and `DecisionRegister` pages exist; `GovernanceInboxSectionBuilder` and `GovernanceDecisionRegisterBuilder` exist; governance inbox and Decision Register tests exist under `tests/Feature/Governance` and `tests/Unit/Support/Governance*`. | Product docs drift: roadmap/candidate docs still frame Decision Register as future/partly implemented while runtime/tests exist. | Reconcile Decision Register docs or open a follow-up spec that explicitly builds on Spec 265, not a fresh v1 restart. |
| 5 | OperationRun Link/Execution Truth Readiness | ready | `operation_runs` schema includes workspace/environment/user/type/status/outcome/context and run identity fields; `OperationRunLinks` and `OperationRunUrl` centralize run URLs; Specs 301-304 validation included dashboard drill-through and high-signal link checks. | No blocker for read/link productization. New run-producing features still need normal OperationRun start UX review. | Reuse central OperationRun link/start contracts for any future run-producing work. |
| 6 | Evidence/StoredReport Artifact Truth Readiness | ready with caveat | `evidence_snapshots`, `evidence_snapshot_items`, `finding_exception_evidence_references`, and `stored_reports` schemas are workspace/environment scoped; EvidenceSnapshot and StoredReport resources exist; artifact/deep-link tests exist. | Artifact lifecycle, retention, export semantics, and customer-facing disclosure should not be assumed beyond current repo truth. | Use existing artifact links as evidence truth. Split lifecycle/export/retention productization into its own spec if needed. |
| 7 | Findings/Risk Acceptance Readiness | ready | Finding and FindingException resources exist; `finding_exceptions` and `finding_exception_decisions` support current decision state; Decision Register builder derives rows from FindingException decisions; findings/decision navigation and boundary tests exist. | No blocker for using findings/risk acceptance as existing foundation. | Next feature may build on existing risk acceptance truth, but should not duplicate Spec 265. |
| 8 | Review/Review Pack Readiness | ready with caveat | EnvironmentReview, CustomerReviewWorkspace, ReviewRegister, ReviewPack, and review-pack schemas/resources/tests exist; review pack rows carry workspace/environment, operation run, evidence snapshot, environment review, file metadata, and checksum fields. | Current readiness is strong for linking and evidence packaging; broader approval workflow semantics are not proven by this audit. | Treat reviews/review packs as supporting evidence surfaces unless the next spec explicitly changes approval workflow behavior. |
| 9 | RBAC/Capability Readiness | ready | Capabilities, capability resolvers, policies, workspace membership checks, and 404/403 expectations are covered by existing RBAC and resource authorization tests; governance pages include access checks. | No blocker found. | Next feature must declare capability requirements and preserve non-member 404 / missing-capability 403 semantics. |
| 10 | Audit/Event Readiness | ready | `AuditLog` model and audit recorder/logger support exist; audit tests exist for evidence, environment review, findings, and governance flows; sensitive flow specs require audit logging. | No blocker for next planning. | Any new mutation in the next feature must declare audit events and tests. This docs-only audit adds none. |
| 11 | Navigation/IA Readiness | ready with caveat | Admin panel navigation is workspace-first; environment navigation registration is guarded by `NavigationScope`; Specs 301 and 303 cut over Inventory and Directory/Entra Groups; Spec 304 validates retired tenant-panel links are absent. | Product queue docs are stale around Decision Register. Also, navigation readiness depends on continuing to avoid storage-object-first IA for approval flows. | Use workflow-first navigation for the next productization feature and reconcile stale docs before selecting from the product queue. |
| 12 | Test Lane Readiness | ready with caveat | Focused test families exist for Filament navigation/global search, legacy route retirement, governance inbox, Decision Register, findings, evidence, reviews, OperationRun links, RBAC, and audit. Browser smoke tests exist for Specs 301, 303, and 265. | This audit does not add tests. Validation should run focused confidence commands and record outcomes. | Run the focused validation commands in this artifact and keep browser reruns optional unless runtime UI changes occur. |
## Decision Register & Approval Workflow v1 Gate
**Fresh feature-spec decision**: NO-GO for starting a new greenfield `Decision Register & Approval Workflow v1` spec.
**Productization decision**: GO WITH CONDITIONS for a follow-up or close-out path that builds on existing repo truth.
Repo evidence indicates Decision Register is not merely a future candidate:
- `specs/265-decision-register-approval/` exists.
- `apps/platform/app/Filament/Pages/Governance/DecisionRegister.php` exists.
- `apps/platform/app/Support/GovernanceDecisions/GovernanceDecisionRegisterBuilder.php` exists.
- `apps/platform/app/Providers/Filament/AdminPanelProvider.php` registers the Decision Register page.
- Tests exist for Decision Register page access, authorization, builder behavior, finding exception navigation, decision summary, decision register boundaries, and browser smoke.
The blocker is not runtime readiness. The blocker is product-planning truth: a fresh v1 spec would duplicate implemented work and conflict with stale docs. The recommended action is to reconcile Spec 265 and product queue documentation first, then choose a follow-up with a precise scope, for example a close-out, approval-mutation hardening, or decision-register evidence/workflow extension.
## Blocker Register
| Blocker | Applies To | Recommended Action |
|---|---|---|
| Fresh `Decision Register & Approval Workflow v1` would duplicate existing Spec 265/runtime work. | Next feature-spec selection | Do not start a fresh v1. Reconcile existing docs and either close out Spec 265 or create a follow-up spec with a narrower new scope. |
| Product docs drift around Decision Register implementation state. | Next feature-spec selection | Update or explicitly annotate `docs/product/implementation-ledger.md` and `docs/product/spec-candidates.md` before using them as queue truth. |
No runtime blocker was found in Specs 301-304 readiness areas.
## Validation Plan and Results
Focused validation passed. Browser smoke tests were not rerun because this feature is docs-only and does not change rendered surfaces, routes, assets, or runtime behavior. Existing browser smoke coverage for Specs 301, 303, and 265 remains cited as readiness evidence.
| Validation | Command / Evidence | Result |
|---|---|---|
| Legacy route/panel retirement | `cd apps/platform && ./vendor/bin/sail artisan test --compact tests/Feature/Guards/NoLegacyTenantPanelRuntimeTest.php tests/Feature/Guards/NoActiveTenantResourceRoutesTest.php tests/Feature/Workspaces/WorkspaceIntendedUrlLegacyRejectionTest.php` | passed: 20 tests, 42 assertions |
| Filament/navigation/global search from Specs 301-304 | `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` | passed: 58 tests, 159 assertions |
| Governance/Decision/Findings | `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` | passed: 27 tests, 137 assertions |
| Evidence/Reports/Reviews | `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` | passed: 51 tests, 362 assertions |
| OperationRun links and legacy route regressions | `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` | passed: 15 tests, 98 assertions |
| Combined implementation-loop gate rerun | `cd apps/platform && ./vendor/bin/sail artisan test --compact` with the focused files listed above | passed: 171 tests, 798 assertions |
| Diff whitespace | `git diff --check` | passed: no output |
| New-file whitespace scan | `rg -n "[[:blank:]]+$" specs/305-feature-readiness-gate-audit || true` | passed after removing Markdown trailing spaces |
| Scope check | `git status --short --branch` | passed: only `?? specs/305-feature-readiness-gate-audit/` |
## No-Change Confirmation
This audit does not change:
- Application runtime code
- Database migrations
- Factories, seeders, or fixtures
- Tests
- Filament resources/pages/widgets
- Routes
- Navigation registration
- Global search behavior
- OperationRun behavior
- RBAC/capability logic
- Audit/event behavior
- Product roadmap content
## Final Gate
**Overall recommendation**: GO WITH CONDITIONS.
TenantPilot can proceed toward the next productization effort after Specs 301-304, but the next effort should not be a fresh Decision Register v1. The repo is ready for a bounded follow-up once stale product docs are reconciled and the follow-up explicitly builds on existing Decision Register, governance, findings, evidence, reviews, RBAC, audit, navigation, and OperationRun foundations.
Reference in New Issue View Git Blame Copy Permalink