ahmido/TenantAtlas
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects 1 Releases Wiki Activity
84bb094e5e
TenantAtlas/specs/400-product-contract-spec-completeness-audit/plan.md
ahmido 23225434ad spec: add completeness audit spec artifacts for product contract (#471) 
Automated PR provided by Codex via Gitea API.

Co-authored-by: Ahmed Darrazi <ahmed.darrazi@live.de>
Reviewed-on: #471
2026-06-22 21:36:59 +00:00

15 KiB
Raw Blame History

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:

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:

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:

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

specs/400-product-contract-spec-completeness-audit/
├── spec.md
├── plan.md
├── tasks.md
└── checklists/
    └── requirements.md

Optional Future Audit Artifact

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.