TenantAtlas/specs/375-ui-bloat-regression-guard/plan.md

Implementation Plan: UI Bloat Regression Guard v1

Branch: 375-ui-bloat-regression-guard | Date: 2026-06-13 | Spec: specs/375-ui-bloat-regression-guard/spec.md Input: Feature specification from specs/375-ui-bloat-regression-guard/spec.md

Summary

Build a narrow repository guard that scans TenantPilot UI source paths for known UI bloat and customer/auditor safety regression patterns from Specs 368 and 370-374. The implementation should prefer existing Pest guard conventions and surface-guard lane ownership, create spec-local rule/design/allowlist/scan artifacts, run an initial scan in warn mode, and avoid any runtime UI page refactor.

Technical Context

Language/Version: PHP 8.4.15, Laravel 12.52, Filament 5.2.1, Livewire 4.1.4 Primary Dependencies: Pest 4.3, PHPUnit 12, existing Laravel/Filament app and test harness Storage: N/A - no database or product persistence; spec-local Markdown reports only Testing: Pest guard/source-scan tests preferred; optional Artisan command test only if a command is selected Validation Lanes: heavy-governance / surface-guard by default; targeted command/test for local validation Target Platform: local Laravel app and Gitea-compatible CI runners Project Type: Laravel monolith under apps/platform plus repo-level scripts/docs Performance Goals: deterministic local scan; no browser, DB, provider, queue, or network dependency Constraints: no runtime UI refactor; no fast-feedback lane pollution unless scan cost is proven narrow; hard-fail only clear customer/auditor default-surface leakage in v1 Scale/Scope: configured scan over selected UI source directories, not full repository or generated assets

UI / Surface Guardrail Plan

• Guardrail scope: workflow-only guardrail change.
• Affected routes/pages/actions/states/navigation/panel/provider surfaces: none.
• No-impact class, if applicable: tooling-only / test-only / documentation-artifact change.
• Native vs custom classification summary: N/A - no rendered UI.
• Shared-family relevance: status messaging, header actions, dashboard/stat cards, evidence/report viewers, customer/auditor defaults, diagnostic entrypoints.
• State layers in scope: none for runtime; source-scan surface classification only.
• Audience modes in scope: customer/read-only, operator-MSP, support-platform as scanner classifications.
• Decision/diagnostic/raw hierarchy plan: derive guard rules from Spec 370-374 hierarchy: decision/customer-safe content first, diagnostics second, support/raw third.
• Raw/support gating plan: guard reports raw/support terms in customer/auditor defaults as blocking or manual review depending on context/allowlist.
• One-primary-action / duplicate-truth control: scanner flags missing primary question/next action, header action overload, repeated status/lifecycle/timestamp/count noise, and zero-card spam.
• Handling modes by drift class or surface: clear customer/auditor leakage is hard-stop candidate; diagnostic/operator ambiguity is review-mandatory; allowlisted legacy debt is report-only.
• Repository-signal treatment: report/warn by default, future hard-stop candidate for additional rules after allowlist cleanup.
• Special surface test profiles: surface-guard; no browser smoke.
• Required tests or manual smoke: targeted source-scan fixture/sample coverage and initial scan report.
• Exception path and spread control: allowlist entries must be explicit, reasoned, reviewed, and scoped by rule/file/pattern.
• Active feature PR close-out entry: Guardrail.
• UI/Productization coverage decision: No UI surface impact.
• Coverage artifacts to update: none.
• No-impact rationale: no reachable UI is added, removed, renamed, or materially changed.
• Navigation / Filament provider-panel handling: no panel/provider changes.
• Screenshot or page-report need: no; guard-only spec.

Shared Pattern & System Fit

• Cross-cutting feature marker: yes, because the guard reviews cross-surface UI interaction classes; no runtime shared interaction family changes.
• Systems touched: likely apps/platform/tests/Feature/Guards, apps/platform/tests/Architecture, apps/platform/tests/Pest.php, apps/platform/tests/Support/TestLaneManifest.php when heavy-governance ownership is selected, optional apps/platform/app/Console/Commands, optional repo scripts, and spec-local artifacts.
• Shared abstractions reused: existing source-scan guard patterns, Pest group/lane conventions, and scripts/check-ui-productization-coverage as a reference for report/fail behavior.
• New abstraction introduced? why?: at most one narrow scanner helper or guard test. It is justified only if inline test code would be too duplicated or unreadable.
• Why the existing abstraction was sufficient or insufficient: current UI coverage guard checks acknowledgement of UI impact, not source content bloat or customer-safety leakage.
• Bounded deviation / spread control: no product runtime abstraction; no framework under app/Support unless implementation proves test-local code is insufficient.

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 runtime provider seam.
• Provider-owned seams: N/A.
• Platform-core seams: N/A.
• Neutral platform terms / contracts preserved: guard language must describe provider/internal term leakage rather than making provider-specific labels platform truth.
• Retained provider-specific semantics and why: provider terms can remain legitimate in provider-owned diagnostic/operator surfaces and should be manual-review/allowlisted there.
• Bounded extraction or follow-up path: none.

Constitution Check

GATE: Must pass before implementation. Re-check after guard design is finalized.

• Inventory-first: N/A - no inventory/snapshot behavior.
• Read/write separation: passes - no product write/change function; guard only reads source files and writes spec-local reports.
• Graph contract path: passes - no Graph calls.
• Deterministic capabilities: N/A - no capability resolver changes.
• RBAC-UX: passes - no authorization behavior changes; future implementation must not treat UI visibility as security.
• Workspace isolation: passes - no runtime workspace/tenant queries.
• Tenant isolation: passes - no tenant-owned data reads.
• Run observability: passes - no long-running remote/queued work and no OperationRun semantics.
• OperationRun start UX: N/A.
• Data minimization: guard reports must not include secrets, credentials, provider raw responses, or sensitive customer data.
• Test governance: surface-guard/heavy-governance classification is explicit; no hidden browser/DB fixtures.
• Proportionality: one narrow guard is justified by current UI safety/productization risk.
• No premature abstraction: prefer a single test/scanner path; avoid reusable framework unless needed for readability and tests.
• Persisted truth: no product persistence; spec-local reports only.
• Behavioral state: rule IDs are tooling diagnostics, not product state.
• UI semantics: guard consumes Spec 370-374 UI semantics and must not create a new UI interpretation framework.
• Shared pattern first: reuse existing guard/test/script conventions.
• Provider boundary: provider terms are scanner indicators only.
• V1 explicitness / few layers: direct text scanning and simple heuristics preferred over AST-heavy or browser-required tooling.
• Spec discipline / bloat check: proportionality review is complete.
• Filament-native UI: no rendered Filament UI changes; if implementation touches Filament source only by scanning it, no asset or provider updates are needed.
• UI/Productization coverage: no-impact decision is checked and rationalized.

Test Governance Check

• Test purpose / classification by changed surface: Heavy-Governance / surface-guard for broad source scanning; unit-like sample cases may live inside the guard test.
• Affected validation lanes: heavy-governance or explicit targeted guard test/command; no browser lane.
• Why this lane mix is the narrowest sufficient proof: The feature protects cross-surface source patterns and does not render UI.
• Narrowest proving command(s):
  • cd apps/platform && php vendor/bin/pest tests/Feature/Guards/UiBloatRegressionGuardTest.php or exact selected guard file.
  • If heavy-governance ownership is registered: targeted lane manifest/placement contract coverage proving the guard is discoverable by test:heavy, or a documented targeted-only validation if not registered.
  • If an Artisan command is selected: cd apps/platform && php artisan tenantpilot:check-ui-bloat --strictness=warn.
  • git diff --check.
  • cd apps/platform && php vendor/bin/pint --dirty if PHP changed.
• Fixture / helper / factory / seed / context cost risks: none expected; use source fixture strings/files only.
• Expensive defaults or shared helper growth introduced?: no; any scanner helper must avoid DB/application boot beyond what Pest already needs.
• Heavy-family additions, promotions, or visibility changes: one new bounded surface-guard family or test.
• Surface-class relief / special coverage rule: no product page browser smoke.
• Closing validation and reviewer handoff: reviewer confirms no runtime UI refactor, no raw hard-fail expansion beyond customer/auditor defaults, no hidden fast-feedback lane cost, and report artifacts are complete.
• Budget / baseline / trend follow-up: record guard runtime and lane impact in validation report.
• Review-stop questions: lane fit, breadth, false positives, allowlist quality, hidden cost, and scope creep.
• Escalation path: document-in-feature; follow-up-spec only if CI hardening or browser integration becomes structural.
• Active feature PR close-out entry: Guardrail.
• Why no dedicated follow-up spec is needed: v1 guard setup is bounded; follow-up specs are limited to browser fixture coverage, scorecard integration, and CI strictness expansion.

Project Structure

Documentation (this feature)

specs/375-ui-bloat-regression-guard/
|-- spec.md
|-- plan.md
|-- tasks.md
|-- checklists/
|   `-- requirements.md
`-- artifacts/
    |-- source-summary.md
    |-- guard-rules.md
    |-- scanner-design.md
    |-- allowlist-policy.md
    |-- initial-scan-report.md
    |-- affected-files.md
    |-- validation-report.md
    `-- follow-up-recommendations.md

Likely Source/Test Surfaces

apps/platform/tests/Feature/Guards/
apps/platform/tests/Architecture/
apps/platform/tests/Pest.php
apps/platform/tests/Support/TestLaneManifest.php  # if heavy-governance lane ownership is selected
apps/platform/app/Console/Commands/        # only if command is narrower than Pest-only guard
scripts/                                  # only if repo-level script is chosen

Initial Scan Scope

apps/platform/app/Filament
apps/platform/resources/views/filament
apps/platform/app/Support/EnvironmentDashboard
apps/platform/app/Support/Navigation
apps/platform/app/Support/OpsUx
apps/platform/app/Support/SupportDiagnostics
apps/platform/app/Support/Ui
apps/platform/app/Support/Workspaces

Candidate paths apps/platform/resources/views/components and apps/platform/app/View are not present in current repo truth and must be recorded as not available if still absent during implementation. Additional apps/platform/app/Support subpaths may be added only when scanner-design.md documents why they are UI-support paths; apps/platform/app/Support must not be scanned wholesale in v1.

Exclusions / Separate Classification

vendor
node_modules
storage
bootstrap/cache
public/build
database dumps
spec artifacts
screenshots
generated reports
tests unless explicitly used as scanner fixtures
translation dictionaries unless implementation proves rendered default UI copy is being checked

Structure Decision: Use a single repo-conform guard entrypoint. Prefer apps/platform/tests/Feature/Guards/UiBloatRegressionGuardTest.php because existing broad UI/source guard tests live under tests/Feature/Guards. If the guard is intended to run in test:heavy, it must be grouped in apps/platform/tests/Pest.php and registered as a surface-guard family/hotspot in apps/platform/tests/Support/TestLaneManifest.php; otherwise the source summary and validation report must document targeted-only ownership.

Complexity Tracking

Violation	Why Needed	Simpler Alternative Rejected Because
New source scanner/guard	Existing UI coverage guard does not detect specific bloat/customer-safety copy patterns	Manual checklist alone does not reliably catch cross-surface drift
Rule IDs and allowlist policy	Findings need stable review language and controlled exceptions	Unstructured grep output would be noisy and unactionable

Proportionality Review

• Current operator problem: Future UI work can reintroduce unsafe customer/auditor copy and noisy, unprioritized surfaces without early review feedback.
• Existing structure is insufficient because: scripts/check-ui-productization-coverage proves coverage acknowledgement, not the content quality of changed source.
• Narrowest correct implementation: One source scanner/test/command, ten bounded rule groups, warn default, hard-fail only clear customer/auditor leakage, and spec-local artifacts.
• Ownership cost created: Rule maintenance, initial scan debt triage, allowlist review, and one guard lane/test.
• Alternative intentionally rejected: Full browser visual regression and broad screenshot diffs are too expensive and unnecessary for v1; page refactors are explicitly not this spec.
• Release truth: Current-release truth protecting completed UI productization.

Implementation Phases

Phase 1 - Repo Truth And Source Inputs

Verify existing guard/test/script conventions, existing console command patterns, Spec 368 inputs, and Spec 370-374 artifacts. Record available and missing inputs in artifacts/source-summary.md.

Phase 2 - Guard Rules And Design Artifacts

Create guard-rules.md, scanner-design.md, and allowlist-policy.md before runtime/tooling changes so review can stop scope growth early.

Phase 3 - Tests First / Fixture Cases

Add targeted sample cases proving customer/auditor hard failures, manual-review heuristics, allowlist shape, and strictness behavior.

Phase 4 - Scanner / Entrypoint Implementation

Implement one repo-conform entrypoint. Prefer Pest guard unless final discovery proves Artisan command or script is narrower.

Phase 5 - Initial Scan And Report

Run the guard in warn mode, generate initial-scan-report.md, and classify findings without broad UI fixes.

Phase 6 - Validation And Close-Out Artifacts

Complete affected files, validation report, follow-up recommendations, and run targeted validation commands.

Deployment / Ops Considerations

• Environment variables: none.
• Migrations: none.
• Queues/scheduler: none.
• Storage/volumes: none.
• Filament assets: no registered assets expected; filament:assets is not required unless implementation unexpectedly registers assets, which should be treated as scope drift.
• CI: v1 may run as a targeted guard or report-only heavy-governance check. Do not make broad heuristic failures CI-blocking before allowlist cleanup.

Filament v5 Output Contract

• Livewire v4.0+ compliance: The app has Livewire 4.1.4; this spec must not introduce Livewire v3 references.
• Provider registration location: No panel providers are changed. If an implementation unexpectedly touches panel providers, Laravel 12 registration remains apps/platform/bootstrap/providers.php.
• Global search: No resources or global search behavior are changed.
• Destructive actions: No destructive/high-impact actions are added or changed. Any existing destructive actions observed by scanner remain runtime-owned and must retain confirmation, authorization, and audit behavior.
• Asset strategy: No new Filament assets. No deploy filament:assets impact expected.
• Testing plan: targeted Pest/source-scan guard or selected command test; no browser smoke required.

Risk Controls

• Keep scanner deterministic and text-based.
• Default ambiguous findings to manual review.
• Keep hard failures narrow.
• Separate existing debt from new blocking failures.
• Do not auto-fix files.
• Document every allowlist entry.
• Record any chosen implementation option and rejected alternatives.