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

Tasks: Spec 375 - UI Bloat Regression Guard v1

Input: specs/375-ui-bloat-regression-guard/spec.md, plan.md, checklists/requirements.md, user-provided Spec 375 draft, Specs 368 and 370-374 artifacts, and current repo guard/test conventions.

Tests: Required for later implementation. This spec adds repository guard/tooling behavior, not product UI behavior.

Test Governance Checklist

• Lane assignment is named and narrow: Heavy-Governance / surface-guard unless implementation proves a cheaper targeted guard lane.
• New or changed tests stay in the smallest honest family; no browser, DB, workspace, tenant, provider, session, queue, or seed fixture is introduced.
• Shared helpers and scanner fixtures stay cheap by default; no heavy application setup is hidden in a broad helper.
• Planned validation commands cover the guard without pulling in unrelated suite cost.
• No product page screenshot or browser smoke is required.
• Any material runtime, lane, baseline, trend, or CI strictness impact is recorded in artifacts/validation-report.md.

Phase 1: Preparation And Repo Truth

Purpose: Confirm Spec 375 is a guardrail implementation, not another UI refactor pass.

• T001 Re-read specs/375-ui-bloat-regression-guard/spec.md, plan.md, tasks.md, and checklists/requirements.md.
• T002 Re-read source inputs from Spec 368 where available:
  • specs/368-platform-ui-signal-to-noise-browser-audit/audit.md
  • specs/368-platform-ui-signal-to-noise-browser-audit/page-scorecard.csv
  • specs/368-platform-ui-signal-to-noise-browser-audit/findings.md
  • specs/368-platform-ui-signal-to-noise-browser-audit/spec-candidates.md
  • specs/368-platform-ui-signal-to-noise-browser-audit/artifacts/raw/browser-notes.md
• T003 Re-read Spec 370 IA contract artifacts:
  • specs/370-global-surface-information-architecture-contract/artifacts/surface-contract.md
  • specs/370-global-surface-information-architecture-contract/artifacts/ui-bloat-patterns.md
  • specs/370-global-surface-information-architecture-contract/artifacts/page-assessment-checklist.md
  • specs/370-global-surface-information-architecture-contract/artifacts/copy-and-terminology-rules.md
  • specs/370-global-surface-information-architecture-contract/artifacts/follow-up-spec-map.md
• T004 Re-read completed Spec 371-374 artifacts needed for guard rule inputs, recording missing artifacts as not available:
  • Spec 371 browser verification, page contracts, implementation notes, validation report
  • Spec 372 browser verification, customer surface contracts, customer safety checklist, implementation notes, validation report
  • Spec 373 browser verification, diagnostic surface contracts, diagnostic safety checklist, implementation notes, validation report
  • specs/374-diagnostic-entry-point-support-diagnostics-consolidation/artifacts/source-audit-summary.md
  • specs/374-diagnostic-entry-point-support-diagnostics-consolidation/artifacts/diagnostic-entrypoint-matrix.md
  • specs/374-diagnostic-entry-point-support-diagnostics-consolidation/artifacts/browser-verification-report.md
  • specs/374-diagnostic-entry-point-support-diagnostics-consolidation/artifacts/implementation-notes.md
  • specs/374-diagnostic-entry-point-support-diagnostics-consolidation/artifacts/validation-report.md
• T005 Inspect current guard/test conventions in apps/platform/tests/Feature/Guards, apps/platform/tests/Architecture, apps/platform/tests/Pest.php, apps/platform/tests/Support/TestLaneManifest.php, and scripts/check-ui-productization-coverage.
• T006 Inspect current console command conventions in apps/platform/app/Console/Commands only to decide whether an Artisan command is narrower than a Pest guard.
• T007 Create specs/375-ui-bloat-regression-guard/artifacts/source-summary.md with available/missing inputs, existing guard structures, repo-verified scan paths, absent path candidates, selected implementation option, rejected options, and verification classes.
• T008 Confirm no migrations, models, policies, routes, Filament pages/resources, Livewire components, views, panel providers, Graph contracts, jobs, queues, scheduler, storage, or runtime UI files need intentional product behavior changes.

Phase 2: Spec-Local Guard Artifacts Before Tooling

Purpose: Make the guard contract reviewable before implementation.

• T009 Create specs/375-ui-bloat-regression-guard/artifacts/guard-rules.md documenting all ten rule groups, rule IDs, purpose, patterns, surface applicability, strictness, default result, allowlist behavior, and examples.
• T010 Create specs/375-ui-bloat-regression-guard/artifacts/scanner-design.md documenting scan scope, selected apps/platform/app/Support UI-support subpaths, absent path treatment, exclusions, file discovery, surface classification heuristic, pattern matching, strictness, report output, exit code behavior, allowlist storage path/format or explicit no-allowlist-file decision, limitations, and future improvements.
• T011 Create specs/375-ui-bloat-regression-guard/artifacts/allowlist-policy.md with allowlist schema, concrete allowlist file path/format or explicit v1 no-allowlist-file decision, allowed reasons, forbidden blanket patterns, review/expiry expectations, and examples.
• T012 Create specs/375-ui-bloat-regression-guard/artifacts/affected-files.md with planned file rows before implementation.
• T013 Create specs/375-ui-bloat-regression-guard/artifacts/validation-report.md with branch, HEAD, dirty state before implementation, planned validation commands, and no-runtime-UI-refactor assertion.
• T014 Create specs/375-ui-bloat-regression-guard/artifacts/follow-up-recommendations.md with planned sections for CI strictness, manual-review leftovers, Evidence/System browser fixtures, browser-scorecard integration, and post-productization closeout audit.

Phase 3: Tests First - Scanner Behavior

Purpose: Prove guard semantics before scanning the real repo.

• T015 Add targeted Pest coverage or equivalent guard tests for strictness modes: report, warn, and fail, including exit/result behavior for blocking versus non-blocking findings.
• T016 Add fixture/sample coverage for UIBLOAT_CUSTOMER_RAW_ID proving likely customer/auditor default files hard-fail on raw ID labels unless allowlisted.
• T017 Add fixture/sample coverage for UIBLOAT_CUSTOMER_INTERNAL_TERM proving blocked internal/debug/provider terms hard-fail in customer/auditor default files unless allowlisted.
• T018 Add fixture/sample coverage for UIBLOAT_ZERO_METRIC_CARD and UIBLOAT_REPEATED_STATUS proving ambiguous matches are warnings or manual-review findings, not v1 hard failures.
• T019 Add fixture/sample coverage for UIBLOAT_MISSING_PRIMARY_QUESTION, UIBLOAT_HEADER_ACTION_OVERLOAD, UIBLOAT_EVIDENCE_DIAGNOSTICS_MIXED, and UIBLOAT_TECH_METADATA_MAIN.
• T020 Add fixture/sample coverage for UIBLOAT_DIAGNOSTIC_GUIDANCE_MISSING and UIBLOAT_DIAGNOSTIC_ENTRYPOINT_AMBIGUOUS with manual-review default behavior.
• T021 Add allowlist validation coverage proving entries require rule ID, file, pattern, reason, surface type, audience, review/expiry marker, and owner/spec.
• T022 Add exclusion/separate-classification coverage proving routes, models, migrations, tests, specs, screenshots, generated reports, and translation dictionaries do not become runtime UI findings by default.

Phase 4: Guard Implementation

Purpose: Implement exactly one repo-conform guard entrypoint.

• T023 Implement the chosen guard entrypoint, preferring apps/platform/tests/Feature/Guards/UiBloatRegressionGuardTest.php unless the source summary documents why an Artisan command or script is narrower.
• T024 If a scanner helper is needed, keep it narrow and test-owned where practical; do not add a runtime product service or framework unless the source summary proves test-local code is insufficient.
• T025 Configure initial scan paths:
  • 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
• T026 Configure exclusions for vendor, node modules, storage, build artifacts, generated reports, screenshots, specs, and non-runtime tests; record absent scan candidates such as apps/platform/resources/views/components and apps/platform/app/View as not available if still missing, and do not scan apps/platform/app/Support wholesale.
• T027 Implement surface classification for likely customer/auditor, diagnostic/support, operator, and unknown files.
• T028 Implement findings with rule ID, file, pattern, surface classification, severity/result, reason, suggested action, and allowlist status.
• T029 Implement strictness behavior with warn as v1 default and non-zero result only for hard customer/auditor safety failures unless fail is intentionally selected.
• T030 Register and validate lane ownership: if a Pest guard is selected, group it in apps/platform/tests/Pest.php and either add a surface-guard family/hotspot in apps/platform/tests/Support/TestLaneManifest.php for test:heavy discovery or document targeted-only ownership in source-summary.md and validation-report.md.
• T031 If an Artisan command or repo script is chosen, add command/script validation and document why it is narrower than Pest; ensure it runs without database/browser/provider setup.

Phase 5: Initial Scan And Reporting

Purpose: Establish initial repo state without fixing broad UI debt.

• T032 Run the selected guard in warn mode against the configured source paths.
• T033 Create specs/375-ui-bloat-regression-guard/artifacts/initial-scan-report.md with command run, timestamp, files scanned, findings by rule, findings by severity, blocking failures, warnings, manual-review findings, allowlisted findings, known existing debt, false positives, and recommended follow-ups.
• T034 If existing findings appear, classify them as known debt, manual review, false positive, or allowlisted; do not broad-refactor pages.
• T035 If a clear customer/auditor hard failure appears in existing runtime UI, stop broad fixes and document whether it is in-scope as a small safety fix or deferred known debt; do not silently refactor.
• T036 Update artifacts/allowlist-policy.md and the selected actual allowlist file only with scoped, reasoned entries; if no allowlist file is selected for v1, document the empty/no-allowlist decision instead.
• T037 Update artifacts/follow-up-recommendations.md with CI strictness, browser-scorecard, Evidence/System fixture, and closeout audit recommendations.

Phase 6: Validation And Close-Out Artifacts

Purpose: Finish with bounded proof and no runtime UI scope creep.

• T038 Run the exact targeted Pest guard test or selected command, plus targeted lane registration/placement validation when apps/platform/tests/Pest.php or apps/platform/tests/Support/TestLaneManifest.php changes.
• T039 Run the guard in warn mode and confirm initial scan report generation.
• T040 Run cd apps/platform && php vendor/bin/pint --dirty if PHP files changed.
• T041 Run git diff --check.
• T042 Complete artifacts/affected-files.md with final touched files, purpose, change type, runtime/tooling/spec classification, risk, and verification level.
• T043 Complete artifacts/validation-report.md with branch, HEAD, dirty state before/after, commands run, guard result, initial scan result, tests run, git diff --check, Pint result if applicable, known limitations, and recommended next spec.
• T044 Confirm final implementation response states Livewire v4 compliance, provider registration location, global search status, destructive-action safety, asset strategy, tests, and deployment impact.

Non-Goals Checklist

• NT001 Do not refactor runtime UI pages.
• NT002 Do not modify Customer Review Workspace, Environment Review, Review Pack, Stored Report, Evidence Snapshot, OperationRun, Backup Set, Restore Run, Operations Hub, Environment Dashboard, Baseline Profile, Provider Connections, Environment Diagnostics, Required Permissions, System Panel, or diagnostic entrypoint runtime behavior.
• NT003 Do not add migrations, models, persisted product truth, enum/status families, jobs, policies, routes, Livewire components, Filament pages/resources, navigation entries, or Graph calls.
• NT004 Do not add screenshot diff infrastructure, full visual regression, broad browser audit, accessibility audit, or performance audit.
• NT005 Do not make broad heuristic findings CI-blocking before allowlist cleanup.
• NT006 Do not rewrite completed historical specs or remove implementation close-out/validation/browser evidence.

Dependencies And Execution Order

• Phase 1 must complete before selecting implementation option.
• Phase 2 must complete before code/tooling edits.
• Phase 3 tests should precede scanner implementation.
• Phase 4 implements the narrow guard.
• Phase 5 runs initial scan and records debt without broad fixes.
• Phase 6 validates and closes artifacts.

Recommended Implementation Strategy

Start with a Pest guard under tests/Feature/Guards because the repo already has many source-scan guard tests and lane classification for surface-guard. If it should run in test:heavy, register the guard in tests/Pest.php and tests/Support/TestLaneManifest.php; otherwise document targeted-only ownership. Only choose an Artisan command if source-summary evidence shows local/report ergonomics require command behavior now. Keep v1 warn-first and customer-safety-hard-fail-only.