TenantAtlas/specs/400-product-contract-spec-completeness-audit/plan.md

# 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.