# Implementation Plan: Spec 400 - Product Contract & Spec Completeness Audit **Branch**: `400-product-contract-spec-completeness-audit` | **Date**: 2026-06-22 | **Spec**: `specs/400-product-contract-spec-completeness-audit/spec.md` **Input**: Feature specification from `specs/400-product-contract-spec-completeness-audit/spec.md` ## Summary Prepare a read-only product-contract completeness audit that determines whether TenantPilot is sufficiently specified for customer-ready productization. The later audit execution must inspect repository truth, score critical product surfaces, identify decision debt and hallucination risk, group minimal follow-up specs, answer promotion readiness, and stop without implementation. The default audit output is the final response. A durable report file under this spec package is allowed only if the operator explicitly asks for one during audit execution. ## Technical Context **Language/Version**: PHP 8.4.15, Laravel 12.52.0, Filament 5.2.1, Livewire 4.1.4. **Primary Dependencies**: Laravel, Filament, Livewire, Pest 4, PostgreSQL, existing Spec Kit artifacts, existing Product Surface Contract and UI audit artifacts. **Storage**: No database, migration, persisted product truth, fixture, or runtime artifact changes. **Testing**: N/A for preparation and runtime behavior; later audit execution records read-only validation commands and dirty state. **Validation Lanes**: N/A for runtime; optional `git diff --check` and read-only repo inspection during audit execution. **Target Platform**: TenantPilot Laravel monolith under `apps/platform`; Spec Kit artifacts under `specs/400-product-contract-spec-completeness-audit/`. **Project Type**: Web application plus Spec Kit workflow. **Performance Goals**: Audit should prefer targeted repo inspection and evidence-backed findings over exhaustive noisy scans. **Constraints**: Read-only only; no application code, tests, migrations, routes, views, policies, completed spec rewrites, or docs outside this spec package. **Scale/Scope**: Whole-product product-contract audit over critical admin, system, customer/report, evidence, operation, restore, provider, dashboard, and governance surfaces. ## Repository Surfaces Likely Inspected Governance and roadmap: ```text AGENTS.md .specify/ docs/ai-coding-rules.md docs/product/roadmap.md docs/product/spec-candidates.md docs/product/standards/product-surface-contract.md docs/ui-ux-enterprise-audit/ docs/product/implementation-ledger.md docs/product/operator-semantic-taxonomy.md ``` Recent and related specs: ```text specs/376-browser-audit-fixture-coverage-evidence-system-surfaces/ specs/377-post-productization-browser-reaudit-closeout-gate/ specs/378-management-report-pdf-v1/ specs/379-management-report-pdf-runtime/ specs/380-management-report-pdf-staging-runtime-validation/ specs/381-provider-resource-identity-binding/ specs/382-baseline-matching-canonicalization/ specs/383-baseline-result-semantics/ specs/384-baseline-subject-resolution-ui/ specs/385-evidence-review-readiness/ specs/386-review-publication-resolution-workflow-v1/ specs/387-review-publication-resolution-decision-ux-v1/ specs/388-resolution-proof-currentness-contract-v1/ specs/389-governance-inbox-resolution-intake-v1/ specs/390-restore-readiness-resolution-adapter-v1/ specs/391-operations-hub-stability-debug-safe-runtime/ specs/392-customer-output-gating-review-pack-navigation/ specs/393-evidence-anchor-reconciliation-v1/ specs/394-provider-freshness-permission-semantics/ specs/395-product-surface-gate/ specs/396-system-panel-branding/ specs/397-receipt-page-reduction/ specs/398-decision-page-contract-migration/ specs/399-dashboard-inbox-table-contract/ ``` Application surfaces for read-only inspection: ```text apps/platform/routes/ apps/platform/app/Providers/ apps/platform/bootstrap/providers.php apps/platform/app/Filament/ apps/platform/resources/views/ apps/platform/app/Models/ apps/platform/app/Policies/ apps/platform/app/Services/ apps/platform/app/Jobs/ apps/platform/database/migrations/ apps/platform/database/factories/ apps/platform/tests/ ``` ## Audit Method 1. Record branch, HEAD, and dirty state before any audit command. 2. Build a surface inventory from routes, Filament panels/pages/resources/widgets, Livewire/Blade views, models, policies, tests, and recent specs. 3. For each primary surface, identify route/navigation entry, owning panel, primary model(s), primary user role(s), workspace/environment scope, visible decision/action, evidence or OperationRun dependency, customer-visible status, and relevant tests/specs. 4. Score product-contract completeness across the required dimensions using the 0-4 model from `spec.md`. 5. Identify decision debt, implementation defects, test gaps, surface drift, terminology drift, and agent hallucination risk. 6. Compare recent critical specs against implementation evidence where relevant. 7. Group findings into must-fix before customer pilot, should-fix before broader productization, can defer, duplicate/already covered, and not-a-spec review feedback. 8. Produce final audit report using the required structure. 9. Record dirty state after the audit and stop if unexpected file changes occurred. ## Output Strategy - **Default**: final audit report in the assistant response only. - **Optional**: a spec-local report file under `specs/400-product-contract-spec-completeness-audit/` only when the operator explicitly asks for file output during audit execution. - **Forbidden by default**: generated reports in `docs/`, runtime screenshots, new fixtures, tests, application files, or completed-spec edits. ## UI / Surface Guardrail Plan - **Guardrail scope**: read-only audit of existing surfaces. - **Affected routes/pages/actions/states/navigation/panel/provider surfaces**: none changed; many inspected. - **No-impact class**: spec preparation and read-only audit. - **Native vs custom classification summary**: N/A for changes; audit may classify existing surfaces. - **Shared-family relevance**: evidence/report viewers, status messaging, dashboards, inboxes, restore readiness, provider readiness, operation proof, customer output, and technical/audit links are audit targets only. - **State layers in scope**: shell/page/detail/query state are inspected but not changed. - **Audience modes in scope**: customer/read-only, operator/MSP, support/platform, and system admin as audit classifications. - **Decision/diagnostic/raw hierarchy plan**: inspect whether the hierarchy is specified; do not alter hierarchy. - **Raw/support gating plan**: inspect customer-safe vs operator diagnostic vs support/raw boundaries. - **One-primary-action / duplicate-truth control**: inspect whether surfaces define one primary question/action and avoid repeated readiness/status truth. - **Handling modes**: report-only for this spec; follow-up-spec only when structural, evidence-backed gaps require it. - **Repository-signal treatment**: report findings only. - **Special surface test profiles**: N/A for preparation. - **Required tests or manual smoke**: none for preparation; later audit may use existing evidence or read-only browser inspection if explicitly scoped. - **Exception path and spread control**: Product Surface exceptions discovered during audit become findings, not fixes. - **Active feature PR close-out entry**: N/A for runtime; preparation final response records no implementation. - **UI/Productization coverage decision**: No UI surface impact. - **Coverage artifacts to update**: none. - **No-impact rationale**: no rendered UI changes. - **Screenshot or page-report need**: no for preparation. Later audit may reference existing screenshots or create none unless explicitly authorized. ## Product Surface Contract Plan - **Product Surface Contract reference**: `docs/product/standards/product-surface-contract.md`. - **No-legacy posture**: no compatibility changes; completed specs remain historical context. - **Page archetype and surface budget plan**: audit existing surfaces against archetype/budget definitions where evidence exists. - **Technical Annex and deep-link demotion plan**: inspect whether technical links and raw evidence are default product content or demoted by contract. - **Canonical status vocabulary plan**: inspect whether product-facing states are mapped or exceptioned. - **Product Surface exceptions**: none in preparation; audit may report exceptions/gaps. - **Browser verification plan**: `N/A - no rendered UI surface changed`. - **Human Product Sanity plan**: final report sanity check. - **Visible complexity outcome target**: neutral runtime; report may recommend later reduction. - **Implementation report target**: final response; optional spec-local audit report only by explicit operator request. ## Filament / Livewire / Deployment Posture - **Livewire v4 compliance**: Livewire 4.1.4 confirmed by Laravel Boost; no Livewire code change. - **Panel provider registration location**: `apps/platform/bootstrap/providers.php`; no panel provider change. - **Global search posture**: no globally searchable resource is changed. Audit may inspect search posture as evidence. - **Destructive/high-impact action posture**: no action is added or changed. Audit may inspect whether existing destructive/high-impact contracts are specified. - **Asset strategy**: no assets, no `FilamentAsset` registration, no `filament:assets` deployment change. - **Testing plan**: no tests are added or changed. Later audit records read-only commands and limitations. - **Deployment impact**: none. No env vars, migrations, queues, scheduler, storage, assets, provider scopes, or Dokploy changes. ## Domain / Model Implications No model, migration, enum, table, persisted artifact, service, job, policy, route, query, Graph contract, OperationRun type, audit event, or customer-output artifact is introduced or changed. The audit may read models and migrations to classify source-of-truth, ownership, and scope. Reading does not create domain truth. ## RBAC / Security / Audit Implications - No authorization behavior changes. - The audit inspects whether specs, policies, gates, tests, and UI enforcement define workspace isolation, managed-environment entitlement, platform-plane separation, 404/403 semantics, customer visibility, and audit responsibility. - Security findings are report-only and must cite evidence. - The audit must never weaken auth, create smoke login routes, seed users, or bypass policies. ## OperationRun / Evidence / Result Truth Implications The audit must distinguish: - execution truth: `OperationRun` state, outcome, summary counts, failure reason, and audit trail; - artifact truth: review packs, stored reports, evidence snapshots, backup sets, and report/download outputs; - backup/snapshot truth: immutable capture and source/currentness; - recovery/evidence truth: restore preview/readiness, proof, stale/failure state, and customer-safe output; - operator next action: the decision/action the surface supports. No OperationRun or evidence behavior changes are allowed. ## Constitution Check - Inventory-first: PASS, audit inspects inventory/snapshot truth only. - Read/write separation: PASS, no writes or change functions. - Graph contract path: PASS, no Graph calls. - Deterministic capabilities: PASS by inspection only; no resolver changes. - RBAC-UX: PASS, audit checks contracts but changes none. - Workspace isolation: PASS, audit checks evidence but changes none. - Tenant isolation: PASS, audit checks evidence but changes none. - Run observability: PASS, audit inspects OperationRun proof contracts but creates no runs. - OperationRun start UX: N/A. - Ops-UX 3-surface feedback: N/A. - Data minimization: PASS, no sensitive output beyond cited repo evidence; avoid copying secrets or raw sensitive payloads into the report. - Test governance: PASS, no tests or lanes added. - Proportionality: PASS, report-only audit outputs are the narrowest current-release gate. - No premature abstraction: PASS, no runtime abstraction. - Persisted truth: PASS, no database persistence. - Behavioral state: PASS, severity/scoring labels are report-only. - UI semantics: PASS, audit uses existing Product Surface language and does not create runtime semantics. - Shared pattern first: PASS, no runtime interaction class is implemented. - Provider boundary: PASS, provider/platform seams are inspected only. - V1 explicitness / few layers: PASS, no layers added. - Spec discipline / bloat check: PASS, one coherent audit spec instead of many speculative micro-specs. - Filament-native UI: PASS by no runtime UI changes. - UI/Productization coverage: PASS, No UI surface impact recorded. - Product Surface Contract Gate: PASS, audit-only application and no completed-spec rewriting. ## Test Governance Check - **Test purpose / classification by changed surface**: N/A - no runtime or test changes. - **Affected validation lanes**: none. - **Why this lane mix is the narrowest sufficient proof**: No code behavior changes need test proof. - **Narrowest proving command(s)**: - `git status --short --branch` - `git diff --name-only` - `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 - no rendered UI surface changed`. - **Closing validation and reviewer handoff**: confirm final audit is read-only, evidence-backed, and recommendation-bounded. - **Budget / baseline / trend follow-up**: none. - **Review-stop questions**: Did any command dirty the tree? Did any finding lack evidence? Did any recommendation invent a product decision? Did any completed spec get rewritten? - **Escalation path**: follow-up-spec only from final report recommendations, not during audit execution. - **Active feature PR close-out entry**: N/A. - **Why no dedicated follow-up spec is needed now**: This spec is the gate that determines which follow-up specs, if any, are needed. ## Project Structure ### Spec Package ```text specs/400-product-contract-spec-completeness-audit/ ├── spec.md ├── plan.md ├── tasks.md └── checklists/ └── requirements.md ``` ### Optional Future Audit Artifact ```text specs/400-product-contract-spec-completeness-audit/ └── artifacts/ └── product-contract-audit-report.md ``` The optional artifact path is not created by preparation and must not be created during audit execution unless the operator explicitly requests file output. ## Implementation Phases 1. Repo-truth and dirty-state initialization. 2. Surface inventory and evidence collection. 3. Product contract scoring. 4. Decision debt and hallucination-risk classification. 5. Spec gap grouping and promotion readiness decision. 6. Final report and dirty-state close-out. ## Stop Conditions Stop and report immediately if: - the working tree is dirty before audit execution and the changes are unrelated; - a read-only command unexpectedly modifies files; - a required surface cannot be inspected and no existing evidence can substitute; - the audit would require product decisions to continue; - implementation or test changes appear necessary to answer the audit.