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

Feature Specification: UI Bloat Regression Guard v1

Feature Branch: 375-ui-bloat-regression-guard Created: 2026-06-13 Status: Draft Input: User-provided Spec 375 draft, Specs 368 and 370-374 UI/productization artifacts, and current repo guard/test conventions.

Spec Candidate Check (mandatory - SPEC-GATE-001)

• Problem: Specs 370-374 improved TenantPilot UI information architecture, customer/auditor safety, and diagnostic guidance, but future feature work can regress into repeated status panels, zero-card spam, raw IDs, provider/debug language, missing primary next actions, and unclear diagnostic entrypoints.
• Today's failure: New or changed Filament pages can reintroduce "select * to UI" behavior without a focused guard noticing the drift before review. The highest-risk failure is a customer/auditor default surface exposing raw IDs or internal/debug/provider terms.
• User-visible improvement: Reviewers and implementers get an actionable guard report that separates blocking customer-safety failures from warnings and manual-review findings before UI bloat reaches users.
• Smallest enterprise-capable version: A deterministic static scanner or Pest guard that scans configured UI source paths, classifies likely surface audience, applies ten bounded rule groups, supports report, warn, and fail behavior, documents an allowlist policy, and writes an initial scan report.
• Explicit non-goals: No runtime UI refactor, no visual regression system, no screenshot diff infrastructure, no accessibility/performance audit, no new product feature, no new navigation, no migrations, no persisted product data, no page redesign, and no broad browser fixture work.
• Permanent complexity imported: One narrow guard/test/tooling entrypoint, stable rule IDs, a documented allowlist policy, and spec-local scan/validation artifacts. No new model, table, enum/status family, provider framework, UI component system, or product runtime source of truth.
• Why now: Spec 374 completed the diagnostic entrypoint consolidation after Specs 370-373. Guardrails should be installed immediately after the productization pass so future agents do not unknowingly undo the customer/auditor and diagnostic-surface safety rules.
• Why not local: A page-local checklist does not catch cross-surface regression patterns. The repo already has guard-oriented tests and UI/productization coverage scripts, so a narrow guard is the smallest reliable enforcement surface.
• Approval class: Core Enterprise.
• Red flags triggered: New meta-infrastructure and multiple surfaces. Defense: the guard is non-runtime, uses existing source-scan/test conventions, creates no product truth, defaults ambiguous findings to manual review, and hard-fails only clear customer/auditor safety violations.
• Score: Nutzen: 2 | Dringlichkeit: 2 | Scope: 2 | Komplexitaet: 1 | Produktnaehe: 1 | Wiederverwendung: 2 | Gesamt: 10/12
• Decision: approve as a narrow guardrail slice.

Candidate Selection And Completed-Spec Guardrail

• Selected candidate: UI Bloat Regression Guard v1.
• Source: User-provided Spec 375 draft attached to the request.
• Roadmap relationship: Supports the current UI/product maturity lane and protects the Spec 370-374 surface productization sequence.
• Related completed specs:
  • Spec 370 is a completed docs-only global surface IA contract with checklist and validation artifacts.
  • Spec 371 is a completed operator-surface productization package with implementation/browser artifacts.
  • Spec 372 is a completed customer/auditor safety package with customer-surface contracts, checklist, and browser artifacts.
  • Spec 373 is a completed diagnostic-surface separation package with diagnostic artifacts and validation.
  • Spec 374 is completed/repo-real context for diagnostic entrypoint and support diagnostics consolidation.
• Guardrail result: Specs 370-374 are inputs only. This spec must not rewrite, normalize, reopen, or remove their implementation history, validation results, completed task markers, browser evidence, or close-out language.
• Close alternatives deferred:
  • Browser Audit Fixture Coverage for Evidence/System Surfaces v1.
  • Browser scorecard integration for guard output.
  • Final post-productization browser closeout audit.
  • CI hard-fail expansion after allowlist cleanup.

Spec Scope Fields (mandatory)

• Scope: canonical-view / repository guardrail.
• Primary Routes: N/A - no reachable product routes are added, removed, renamed, or changed.
• Data Ownership: No database tables or tenant/workspace-owned records are changed. Spec-local scan reports are documentation artifacts only.
• RBAC: No authorization behavior changes. Guard scanning must not infer access rights or weaken existing Gates/Policies.

For canonical-view specs:

• Default filter behavior when tenant-context is active: N/A - no runtime query or tenant filter behavior changes.
• Explicit entitlement checks preventing cross-tenant leakage: N/A for runtime behavior. The guard must ignore routes/models/migrations as runtime UI findings unless they are rendered default-visible UI copy.

UI Surface Impact (mandatory - UI-COV-001)

Does this spec add, remove, rename, or materially change any reachable UI surface?

• No UI surface impact
• Existing page changed
• New page/route added
• Navigation changed
• Filament panel/provider surface changed
• New modal/drawer/wizard/action added
• New table/form/state added
• Customer-facing surface changed
• Dangerous action changed
• Status/evidence/review presentation changed
• Workspace/environment context presentation changed

UI/Productization Coverage (mandatory when UI Surface Impact is not "No UI surface impact"; otherwise write N/A - no reachable UI surface impact plus rationale)

• Route/page/surface: N/A - repository guard/test/tooling only.
• Current or new page archetype: N/A.
• Design depth: N/A.
• Repo-truth level: repo-verified guardrail need, no page change.
• Existing pattern reused: Existing Pest guard/source-scan conventions under apps/platform/tests/Feature/Guards, apps/platform/tests/Architecture, and scripts/check-ui-productization-coverage.
• New pattern required: none for product UI.
• Screenshot required: no. This is a static guard spec, not a UI productization pass.
• Page audit required: no.
• Customer-safe review required: yes for guard rules, no for changed UI because no UI changes are in scope.
• Dangerous-action review required: no changed dangerous action.
• Coverage files updated or explicitly not needed:
  • docs/ui-ux-enterprise-audit/route-inventory.md
  • docs/ui-ux-enterprise-audit/design-coverage-matrix.md
  • docs/ui-ux-enterprise-audit/page-reports/...
  • docs/ui-ux-enterprise-audit/strategic-surfaces.md
  • docs/ui-ux-enterprise-audit/grouped-follow-up-candidates.md
  • docs/ui-ux-enterprise-audit/unresolved-pages.md
  • N/A - no reachable UI surface impact
• No-impact rationale when applicable: The later implementation may add tests, a guard command, config, script, and spec-local reports, but it must not change rendered product pages, navigation, Filament panels, modals, tables, forms, actions, or customer/auditor surfaces.

Cross-Cutting / Shared Pattern Reuse (mandatory when the feature touches notifications, status messaging, action links, header actions, dashboard signals/cards, alerts, navigation entry points, evidence/report viewers, or any other existing shared operator interaction family; otherwise write N/A - no shared interaction family touched)

• Cross-cutting feature?: yes, as a guardrail over cross-surface UI classes; no runtime shared interaction family is modified.
• Interaction class(es): status messaging, header actions, dashboard/stat cards, evidence/report viewers, customer/auditor default surfaces, diagnostic entrypoints.
• Systems touched: Existing source files are scanned; no runtime shared UI system should be changed by default.
• Existing pattern(s) to extend: Existing source-scan/Pest guard patterns and scripts/check-ui-productization-coverage.
• Shared contract / presenter / builder / renderer to reuse: None in runtime. Reuse Spec 370 contract artifacts and existing guard test conventions instead of adding a product UI framework.
• Why the existing shared path is sufficient or insufficient: Existing UI coverage guard protects changed UI files from missing coverage decisions, but it does not inspect source content for repeated status noise, raw ID leakage, customer/internal copy, or diagnostic guidance regression.
• Allowed deviation and why: A focused source-scanning guard is allowed because the existing coverage guard answers "was coverage acknowledged?" not "did known bloat patterns reappear?"
• Consistency impact: Findings must use stable rule IDs and preserve Spec 370-374 language without creating a second product taxonomy.
• Review focus: Verify the implementation stays a narrow guard, does not auto-fix pages, and does not hard-fail ambiguous heuristic matches in v1.

OperationRun UX Impact (mandatory when the feature creates, queues, deduplicates, resumes, blocks, completes, or deep-links to an OperationRun; otherwise write N/A - no OperationRun start or link semantics touched)

• Touches OperationRun start/completion/link UX?: no.
• Shared OperationRun UX contract/layer reused: N/A.
• Delegated start/completion UX behaviors: N/A.
• Local surface-owned behavior that remains: none.
• Queued DB-notification policy: N/A.
• Terminal notification path: N/A.
• Exception required?: none.

Provider Boundary / Platform Core Check (mandatory when the feature changes shared provider/platform seams, identity scope, governed-subject taxonomy, compare strategy selection, provider connection descriptors, or operator vocabulary that may leak provider-specific semantics into platform-core truth; otherwise write N/A - no shared provider/platform boundary touched)

• Shared provider/platform boundary touched?: no runtime seam change.
• Boundary classification: N/A.
• Seams affected: none.
• Neutral platform terms preserved or introduced: The guard should prefer neutral findings such as "provider/internal term in customer default surface" and must not normalize Microsoft-specific runtime semantics.
• Provider-specific semantics retained and why: Some provider terms remain legitimate in provider-owned operator/diagnostic surfaces; the guard must classify those as manual-review or allowlisted rather than hard-fail outside customer/auditor defaults.
• Why this does not deepen provider coupling accidentally: The scanner uses provider terms as leakage indicators, not as platform-core truth.
• Follow-up path: none for runtime. Future guard strictness changes should be documented in this spec's follow-up recommendations.

UI / Surface Guardrail Impact (mandatory when operator-facing surfaces are changed; otherwise write N/A)

Surface / Change	Operator-facing surface change?	Native vs Custom	Shared-Family Relevance	State Layers Touched	Exception Needed?	Low-Impact / N/A Note
UI bloat guard/test/tooling	no rendered surface change	N/A	status/action/evidence/diagnostic guardrail only	none	no	N/A - repository guard only
Spec-local artifacts and initial scan report	no	N/A	review workflow evidence	none	no	N/A - documentation artifacts

Decision-First Surface Role (mandatory when operator-facing surfaces are changed)

N/A - no operator-facing product surface is added or materially changed.

Audience-Aware Disclosure (mandatory when operator-facing surfaces are changed)

N/A - no rendered detail or status surface is changed. The guard exists to protect customer/read-only default paths from raw JSON, fingerprints, IDs, internal reason ownership, platform reason families, and debug semantics.

UI/UX Surface Classification (mandatory when operator-facing surfaces are changed)

N/A - no operator-facing list, detail, queue, audit, config, report, table, or form surface is changed.

Operator Surface Contract (mandatory when operator-facing surfaces are changed)

N/A - no new or materially refactored operator-facing page is in scope.

Proportionality Review (mandatory when structural complexity is introduced)

• New source of truth?: no product source of truth.
• New persisted entity/table/artifact?: no database or product artifact. Spec-local Markdown reports are required implementation evidence only.
• New abstraction?: yes, a narrow guard/scanner abstraction may be introduced in tests/tooling if it is the smallest repo-conform implementation.
• New enum/state/reason family?: no product enum or state family. Stable rule IDs are tooling diagnostics, not domain state.
• New cross-domain UI framework/taxonomy?: no. The guard consumes Spec 370-374 contracts and must not become a UI framework.
• Current operator problem: Future changes can silently reintroduce unsafe customer/auditor copy, status duplication, zero-card spam, unclear next actions, and diagnostic ambiguity.
• Existing structure is insufficient because: Existing coverage guards prove acknowledgement of UI surface impact, but they do not scan rendered-source copy and action structures for known bloat/leakage patterns.
• Narrowest correct implementation: One scanner/test/command path, configurable scanned paths, bounded rule groups, allowlist policy, and initial report. No page rewrites and no browser dependency.
• Ownership cost: Rule maintenance, false-positive triage, allowlist review, a targeted test/guard lane, and scan report upkeep.
• Alternative intentionally rejected: A full browser visual-regression framework is too broad for v1; manual-only review is too easy to miss; page-by-page refactors would violate the guard-only scope.
• Release truth: Current-release truth. It protects already completed sellability and safety improvements.

Compatibility posture

This feature assumes a pre-production environment. No legacy aliases, migration shims, or runtime compatibility paths are needed.

Testing / Lane / Runtime Impact (mandatory for runtime behavior changes)

• Test purpose / classification: Heavy-Governance / surface-guard for broad source scanning, with targeted unit-like cases inside the guard test where practical.
• Validation lane(s): heavy-governance or explicit targeted guard command; not fast-feedback by default unless the implementation proves the scan is narrow and cheap.
• Why this classification and these lanes are sufficient: Broad UI source scanning is a surface-guard concern and should not silently enter fast-feedback.
• New or expanded test families: One bounded Spec 375 UI bloat guard family.
• Fixture / helper cost impact: No database, browser, workspace, tenant, provider, session, or seed fixture should be required.
• Heavy-family visibility / justification: Explicit because it scans multiple UI source directories and protects cross-surface behavior.
• Special surface test profile: surface-guard / standard-native relief for runtime pages.
• Standard-native relief or required special coverage: No product page smoke required. The guard itself needs targeted source fixture/sample coverage and initial scan output.
• Reviewer handoff: Reviewers must verify no broad page refactor, no hidden browser/auth fixture dependency, no broad hard-fail heuristic, and no fast-feedback lane pollution unless intentionally documented.
• Budget / baseline / trend impact: Possible new heavy-governance cost. The implementation must document runtime and whether it changes lane budgets.
• Escalation needed: document-in-feature. Escalate to follow-up-spec only if scan breadth or CI strictness becomes structural.
• Active feature PR close-out entry: Guardrail.
• Planned validation commands:
  • git diff --check
  • cd apps/platform && ./vendor/bin/pint --dirty if PHP files change
  • targeted Pest guard test or guard command selected during implementation
  • guard run in warn mode to generate the initial scan report

User Scenarios & Testing (mandatory)

User Story 1 - Reviewer Sees UI Bloat Findings Before Merge (Priority: P1)

As a TenantPilot maintainer reviewing a future UI change, I want a guard report that highlights known bloat patterns so I can stop unsafe or noisy UI before it merges.

Why this priority: It protects the completed UI IA/productization investment from drift.

Independent Test: Run the guard against fixture/sample files and current UI paths; verify findings are grouped by rule, severity, file, pattern, reason, and suggested action.

Acceptance Scenarios:

1. Given a UI source file with repeated status/lifecycle text, When the guard runs in warn mode, Then it reports a UIBLOAT_REPEATED_STATUS manual-review finding without failing the run.
2. Given a source file with multiple zero metric labels, When the guard runs, Then it reports UIBLOAT_ZERO_METRIC_CARD as warning or manual-review rather than treating every zero as blocking.

---

User Story 2 - Customer/Auditor Default Surfaces Stay Safe (Priority: P1)

As a customer/auditor surface reviewer, I want clear hard-fail rules for raw IDs and internal/debug/provider terms in default-visible customer/auditor surfaces.

Why this priority: This is the highest trust risk identified by Specs 368, 370, and 372.

Independent Test: Run fixture/sample cases for likely customer/auditor files containing raw ID labels or blocked internal terms.

Acceptance Scenarios:

1. Given a likely customer/auditor view file includes operation context in default-visible copy, When the guard runs in warn or fail mode, Then the finding is blocking unless explicitly allowlisted.
2. Given a customer/auditor view file contains a raw ID label inside a documented collapsed technical-details block, When the guard runs, Then it reports manual-review or allowlisted status instead of a blanket fail.

---

User Story 3 - Diagnostic Guidance And Entrypoint Drift Is Visible (Priority: P2)

As an operator/support reviewer, I want diagnostic pages and actions flagged when they lose guidance or blur Support Diagnostics versus Repair Diagnostics semantics.

Why this priority: Spec 373 and Spec 374 deliberately separated guidance-first diagnostics and entrypoint semantics.

Independent Test: Run fixture/sample cases for diagnostic files with technical terms but no guidance markers, and for ambiguous "Diagnostics Hub" or broad health labels pointing at repair-only routes.

Acceptance Scenarios:

1. Given a diagnostic file has many technical details and no "recommended first check" or similar guidance marker, When the guard runs, Then it reports UIBLOAT_DIAGNOSTIC_GUIDANCE_MISSING as manual-review.
2. Given copy uses broad "All diagnostics" language for a repair-only route, When the guard runs, Then it reports UIBLOAT_DIAGNOSTIC_ENTRYPOINT_AMBIGUOUS as manual-review unless the case is clearly customer-facing and misleading.

---

User Story 4 - Allowlist And Initial Scan Are Reviewable (Priority: P2)

As a maintainer, I want existing debt, false positives, and intentional exceptions documented so the guard does not become ignored noise.

Why this priority: A guard that cannot distinguish known debt from blocking regressions will be bypassed.

Independent Test: Review allowlist-policy.md and initial-scan-report.md; verify every allowlist entry shape requires rule ID, file, pattern, reason, surface type, audience, review marker, and owner/spec.

Acceptance Scenarios:

1. Given a finding is known existing debt, When the initial scan report is generated, Then it is recorded separately from new blocking failures.
2. Given an allowlist entry lacks a reason or review marker, When the guard validates allowlist shape, Then it fails or reports a clear guard configuration error.

Functional Requirements

• FR-375-001: The implementation MUST create a repo-conform UI bloat scanner as exactly one primary entrypoint: a Pest guard, an Artisan command, or a script. Prefer existing Pest guard conventions unless repo discovery proves a command/script is narrower.
• FR-375-002: The scanner MUST discover files from repo-verified configured UI source paths, initially including apps/platform/app/Filament and apps/platform/resources/views/filament. Optional candidates such as apps/platform/resources/views/components and apps/platform/app/View MUST be recorded as not available when absent, and apps/platform/app/Support MUST be limited to explicit UI-support subpaths selected in scanner-design.md rather than scanned wholesale.
• FR-375-003: The scanner MUST exclude or separately classify vendor, node modules, storage, build artifacts, generated reports, screenshots, database dumps, specs, tests, and translations unless they are intentionally scanned as non-runtime findings.
• FR-375-004: The scanner MUST classify likely surfaces as customer/auditor, diagnostic/support, operator, or unknown using path and content heuristics.
• FR-375-005: The scanner MUST implement stable rule IDs for the ten v1 groups: zero metric/card spam, repeated status/lifecycle noise, customer raw IDs, customer internal/debug/provider terms, missing primary question/next action, header action overload, evidence/diagnostics mixing, technical metadata in main content, diagnostic guidance missing, and diagnostic entrypoint ambiguity.
• FR-375-006: The scanner MUST support report, warn, and fail strictness semantics or, if implementation evidence proves full strictness too large for v1, at minimum default to warn, distinguish blocking from non-blocking findings, and return non-zero only for hard customer/auditor safety failures.
• FR-375-007: The scanner MUST hard-fail clear customer/auditor default-surface raw ID labels and blocked internal/debug/provider terms unless explicitly allowlisted with reason.
• FR-375-008: Ambiguous heuristic matches MUST default to manual-review-required rather than blocking in v1.
• FR-375-009: The implementation MUST create artifacts/guard-rules.md, artifacts/scanner-design.md, artifacts/allowlist-policy.md, artifacts/source-summary.md, artifacts/initial-scan-report.md, artifacts/affected-files.md, artifacts/validation-report.md, and artifacts/follow-up-recommendations.md.
• FR-375-010: The source summary MUST classify required Spec 368 and Spec 370-374 inputs as available, not available, repo-verified, browser-verified, derived, or deferred, without claiming missing artifacts as verified.
• FR-375-011: The initial scan report MUST separate blocking failures, warnings, manual-review findings, allowlisted findings, false positives, known existing debt, and recommended follow-ups.
• FR-375-012: The allowlist policy and scanner design MUST name the concrete allowlist storage path and format, or explicitly record that v1 uses no committed allowlist file. If an allowlist file exists, it MUST forbid blanket allowlists for entire UI directories or all customer surfaces and require a rule ID, file, pattern, reason, surface type, audience, review/expiry marker, and owner/spec.
• FR-375-013: The guard MUST not auto-fix UI files, mutate runtime pages, or perform broad page refactors.
• FR-375-014: The implementation MUST document the selected implementation option and why the rejected options were broader or less repo-conform.
• FR-375-015: The implementation MUST record whether the guard belongs to heavy-governance/surface-guard lane ownership and whether any CI integration is report-only, warn-only, or deferred.

Non-Functional Requirements

• NFR-375-001: The guard must be deterministic and runnable without browser auth, database state, Graph/provider calls, queues, or external network access.
• NFR-375-002: Findings must be actionable: rule ID, file, matched pattern, surface classification, severity/result, reason, and suggested action.
• NFR-375-003: False-positive control is part of v1. Hard failures are limited to clear customer/auditor default-surface leakage.
• NFR-375-004: The guard must not expand fast-feedback lane cost silently.
• NFR-375-005: Reports should be human-readable. Machine-readable JSON is optional and may be deferred.

Rule Groups

The v1 guard must cover:

1. UIBLOAT_ZERO_METRIC_CARD
2. UIBLOAT_REPEATED_STATUS
3. UIBLOAT_CUSTOMER_RAW_ID
4. UIBLOAT_CUSTOMER_INTERNAL_TERM
5. UIBLOAT_MISSING_PRIMARY_QUESTION
6. UIBLOAT_HEADER_ACTION_OVERLOAD
7. UIBLOAT_EVIDENCE_DIAGNOSTICS_MIXED
8. UIBLOAT_TECH_METADATA_MAIN
9. UIBLOAT_DIAGNOSTIC_GUIDANCE_MISSING
10. UIBLOAT_DIAGNOSTIC_ENTRYPOINT_AMBIGUOUS

Optional future rule IDs such as scope/context ambiguity, provider-term business UI, card flood, duplicated timestamp, and customer action overload are follow-up candidates only unless implementation proves they are trivial configuration within the same v1 guard.

Data / Truth Source Requirements

• The guard derives findings from repository source text and configured rule patterns.
• The guard report is evidence for review, not product truth.
• No database persistence, new model, new migration, or customer-visible data store is allowed.
• Spec 368 and Specs 370-374 artifacts are source inputs; completed implementation evidence remains historical context.

RBAC / Security Requirements

• No runtime authorization behavior changes.
• No UI visibility changes.
• No secrets, tokens, credential payloads, provider raw responses, or customer data should be written into scan reports.
• The guard must avoid reading runtime environment secrets.

Auditability / Observability Requirements

• No AuditLog entries or OperationRun records are created by the guard.
• The validation report must record branch, HEAD, dirty state before/after, commands run, selected guard entrypoint, scan result, and known limitations.

Out Of Scope

• Runtime UI page refactors.
• 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 redesign.
• New migrations, models, persisted product artifacts, jobs, policies, routes, Livewire components, Filament pages/resources, navigation entries, or Graph calls.
• Browser screenshot capture or visual regression testing.
• Full accessibility, performance, or visual QA audit.
• CI hard-fail expansion beyond clear customer/auditor safety failures before allowlist cleanup.

Acceptance Criteria

• AC-375-001: guard-rules.md documents all ten rule groups, stable rule IDs, patterns, applicability, default result, strictness, allowlist behavior, and examples.
• AC-375-002: A repo-conform scanner/test/command exists and has a documented entrypoint.
• AC-375-003: Strictness semantics exist with warn as the v1 default and non-zero exit only for hard customer/auditor safety failures unless fail is intentionally selected.
• AC-375-004: Clear customer/auditor raw ID or internal/debug/provider default-surface findings are blocking unless allowlisted with reason.
• AC-375-005: initial-scan-report.md exists and separates blocking, warning, manual-review, allowlisted, false-positive, known-debt, and follow-up buckets.
• AC-375-006: allowlist-policy.md exists, forbids blanket allowlists, and records the concrete allowlist file path/format or the explicit v1 no-allowlist-file decision.
• AC-375-007: No runtime UI page refactor is performed.
• AC-375-008: Test/spec/generated/route/model/migration findings are ignored or separated from runtime UI findings.
• AC-375-009: Diagnostic guidance and diagnostic entrypoint regression rules are present and non-blocking by default.
• AC-375-010: git diff --check passes; pint --dirty passes if PHP changes; the selected guard test/command passes in warn mode; validation report records all commands.
• AC-375-011: follow-up-recommendations.md names what should become CI-blocking later, what stays manual review, whether Evidence/System browser fixture coverage is still needed, and whether browser-scorecard integration is deferred.

Success Criteria

• Future UI changes can be checked with one documented command/test before review.
• Customer/auditor default-surface raw ID/internal-term leaks are caught as blocking v1 failures.
• Ambiguous UI bloat patterns are visible without creating noisy blanket failures.
• Existing known debt is documented, not silently fixed or ignored.

Assumptions

• Existing guard/test conventions under 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 are sufficient to implement the v1 guard without new infrastructure, provided heavy-governance ownership is registered explicitly or documented as targeted-only.
• Browser verification is intentionally unnecessary for this guard-only spec.
• Spec 370-374 artifacts remain available as input context; missing optional artifacts must be recorded as not available.

Risks

• False positives: Mitigate by defaulting most heuristic rules to manual review, using allowlist policy, and limiting hard failures.
• Guard ignored due to noise: Mitigate with grouped findings, clear rule IDs, initial debt classification, and follow-up recommendations.
• Overfitting current pages: Mitigate by deriving rules from Spec 370-374 contracts rather than screenshots alone.
• Blocking valid diagnostics: Mitigate by treating diagnostic technicality as manual review unless customer/auditor leakage is clear.
• Implementation drift into refactor: Mitigate with explicit no-runtime-UI-refactor tasks and validation report.

Open Questions

• None block preparation. The implementation pass must choose Pest guard vs Artisan command vs script after final repo discovery.

Follow-Up Spec Candidates

• Spec 376 - Browser Audit Fixture Coverage for Evidence/System Surfaces v1.
• Browser scorecard integration for UI bloat guard output.
• UI bloat guard CI hard-fail expansion after allowlist cleanup.
• Final post-productization closeout browser audit after guard stabilization.