ahmido
f24e72269c
## 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
187 lines
14 KiB
Markdown
187 lines
14 KiB
Markdown
# 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)
|
|
|
|
```text
|
|
specs/305-feature-readiness-gate-audit/
|
|
|-- checklists/
|
|
| `-- requirements.md
|
|
|-- feature-readiness-audit.md
|
|
|-- plan.md
|
|
|-- spec.md
|
|
`-- tasks.md
|
|
```
|
|
|
|
### Source Code (repository root)
|
|
|
|
```text
|
|
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.
|