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

Tasks: Spec 400 - Product Contract & Spec Completeness Audit

Input: specs/400-product-contract-spec-completeness-audit/spec.md, plan.md, checklists/requirements.md, user-provided Spec 400 draft, current roadmap/spec-candidate queue, recent Specs 376-399, Product Surface Contract, and repo truth.

Tests: No application tests are required or allowed by default because this spec performs a read-only audit and does not change runtime behavior. The later audit execution records read-only commands, evidence limitations, and dirty state before/after.

Test Governance Checklist

• Lane assignment is N/A - no runtime or test change.
• No Pest, browser, fixture, seed, factory, DB, workspace, tenant, provider, or session setup is introduced.
• Planned validation commands are read-only and do not pull in unrelated suite cost.
• Browser proof is N/A - no rendered UI surface changed unless the operator explicitly asks for read-only browser evidence.
• Dirty state before/after is recorded.
• Any final follow-up recommendation is grouped and bounded rather than implemented.

Phase 1: Preparation And Safety

Purpose: Establish repo truth and prove the audit can run without implementation.

• T001 Read specs/400-product-contract-spec-completeness-audit/spec.md, plan.md, tasks.md, and checklists/requirements.md.
• T002 Record current branch, HEAD, and dirty state before audit execution using read-only git commands.
• T003 Use response-only output unless the operator explicitly requests a spec-local report file; record the chosen output mode.
• T004 Re-read .specify/memory/constitution.md, .specify/README.md, AGENTS.md, docs/ai-coding-rules.md, and relevant docs/*-guidelines.md.
• T005 Re-read docs/product/spec-candidates.md, docs/product/roadmap.md, docs/product/standards/product-surface-contract.md, docs/product/implementation-ledger.md, and current UI audit artifacts.
• T006 Re-read recent productization specs 376-399 and preserve their completed close-out, validation, screenshot, task, smoke, and implementation-report history as read-only context.
• T007 Confirm no migrations, models, services, jobs, policies, routes, Filament resources/pages/widgets, Livewire components, views, tests, config, lock files, docs outside this package, or completed specs will be edited.

Phase 2: Surface Inventory And Evidence Collection

Purpose: Build the audit inventory from repo truth, not assumptions.

• T008 Inventory routes, panels, navigation, Filament pages/resources/widgets, Livewire/Blade views, policies, models, services, jobs, migrations, tests, and existing browser/artifact evidence relevant to the required surfaces.
• T009 For each required surface, record route or navigation entry, owning panel, primary model(s), primary role(s), workspace/environment scope, visible decision/action, evidence or OperationRun dependency, customer-visible status, and relevant tests/specs.
• T010 Inspect the Workspace-first admin surface and workspace/environment context-selection contracts.
• T011 Inspect the System panel surface and platform-plane access/proof contracts.
• T012 Inspect Baseline Compare, restore preview/readiness, backup/restore flows, and restore safety contract evidence.
• T013 Inspect provider connections, provider freshness, required permissions, and provider/platform boundary contract evidence.
• T014 Inspect evidence overview/anchors, findings, review packs, customer review workspace, reports/exports/customer output, and customer-visible evidence contracts.
• T015 Inspect OperationRun proof, audit trail, dashboard/readiness surfaces, governance inbox, support/operational handoff, and stale/failed/partial/empty/warning states.
• T016 Record inspected and not-inspected evidence explicitly, including blocker reasons for unavailable surfaces or missing artifacts.

Phase 3: Product Contract Scoring

Purpose: Convert the inventory into an evidence-backed completeness matrix.

• T017 Score every audited surface from 0 to 4 across product purpose, user/role ownership, scope boundary, RBAC/capability contract, source of truth, evidence/audit contract, customer visibility, state semantics, navigation/IA contract, and test/proof coverage.
• T018 Produce the Product Contract Coverage Matrix with surface, purpose, role/user, scope, RBAC, source of truth, evidence/audit, customer visibility, state semantics, test/proof, score, and risk.
• T019 Mark any score that depends on assumption, convention, or "probably" as a finding rather than proof.
• T020 Distinguish implementation presence from product-contract definition and test/browser proof.

Phase 4: Decision Debt, Defects, And Hallucination Risk

Purpose: Identify where future implementation would be unsafe without a product decision.

• T021 Create the Decision Debt Register with ID, surface, missing decision, why it matters, current evidence, severity, and recommended resolution type.
• T022 Classify each issue as product-contract gap, implementation defect, test gap, surface drift, terminology drift, duplicate/already covered, defer, or not-a-spec review feedback.
• T023 Create the Agent Hallucination Risk Map with surface, likely hallucination, trigger, impact, and containment.
• T024 Ensure every P0/P1 finding cites concrete repo/spec evidence such as file path, line number where practical, route, test, spec section, model/policy reference, or visible surface reference.
• T025 Avoid inventing intended behavior where repo/spec evidence is silent; treat silence as a finding.

Phase 5: Gap Grouping And Promotion Readiness

Purpose: Turn findings into the smallest actionable next step.

• T026 Group required future work into the minimum coherent Spec Gap List, separating amendments, new bounded specs, product decisions, test contract additions, browser proof additions, documentation clarifications, explicit defers, and non-spec review feedback.
• T027 Limit recommended new specs to the smallest necessary set and avoid one spec per tiny finding.
• T028 Produce surface freeze/reduction recommendations for each major surface.
• T029 Answer whether TenantPilot is ready for the next implementation block, full browser/UX/runtime audit, customer-facing hardening, and controlled pilot as Yes, No, or Conditional with one short reason each.
• T030 End with one operational recommended next action.

Phase 6: Final Report And Close-Out

Purpose: Deliver the audit result and prove no implementation occurred.

• T031 Write the final audit report using the exact required structure from spec.md.
• T032 If the operator did not explicitly request a file, keep the report in the final response only and do not create artifacts.
• T033 If the operator explicitly requested a file, write only the approved spec-local report path and record that file in dirty-state close-out.
• T034 Run final read-only dirty-state checks and record dirty state after audit execution.
• T035 If unexpected files changed, stop, report exact paths, whether the audit caused them, and whether the result remains trustworthy.
• T036 Confirm no application runtime code, tests, migrations, config, routes, views, policies, models, jobs, or completed specs were modified.
• T037 Confirm final response states Livewire v4 compliance, provider registration location, global search posture, destructive/high-impact action posture, asset strategy, browser/no-browser result, tests/run commands, deployment impact, and explicit no-implementation status.

Non-Goals Checklist

• NT001 Do not implement fixes or refactors.
• NT002 Do not change application code, tests, migrations, routes, config, policies, models, services, jobs, Filament resources/pages/widgets, Livewire components, Blade views, CSS, JavaScript, seeders, factories, or lock files.
• NT003 Do not rewrite completed specs, remove validation evidence, normalize completed task markers, or strip close-out language.
• NT004 Do not create fixtures, users, browser auth bypasses, screenshots, or generated reports unless explicitly authorized by the operator.
• NT005 Do not invent product decisions, statuses, role rules, readiness logic, customer-output categories, evidence types, or navigation structures.
• NT006 Do not turn every finding into a new spec.

Dependencies And Execution Order

• Phase 1 must complete before any repo inspection beyond already-read preparation context.
• Phase 2 inventory must complete before scoring.
• Phase 3 scoring feeds Phase 4 findings.
• Phase 4 findings feed Phase 5 gap grouping and readiness.
• Phase 6 must record dirty state and no-implementation proof.

Recommended Implementation Strategy

Treat the implementation of this spec as an audit, not a code change. Work from repo truth, keep evidence concrete, prefer fewer strong findings, and stop if answering the audit would require product decisions or runtime changes.