TenantAtlas/specs/324-ui-productization-coverage-guardrails/spec.md

Feature Specification: UI Productization Coverage Guardrails

Feature Branch: 324-ui-productization-coverage-guardrails
Created: 2026-05-17
Status: Draft
Input: User supplied full Spec 324 draft requiring the Spec 323 UI/Productization audit baseline to become a proportional guardrail, with explicit Navigation and Filament provider surface coverage.
Type: Governance / Spec-Kit / tooling guardrail
Depends on: Spec 323 - Tenantial Enterprise UI Audit Foundation
Runtime Posture: No product runtime implementation. Governance, tooling, Spec Kit templates/prompts, and documentation only.

Candidate Source And Guardrail Result

Candidate source: Direct user-provided manual promotion for Spec 324. The active auto-prep queue in docs/product/spec-candidates.md says no safe automatic next-best-prep target remains, so this package proceeds only because the user supplied an explicit complete candidate.

Completed-spec guardrail: No existing specs/324-* package or 324-* branch was present before generation. Spec 323 is completed historical context and already introduced the first UI/Productization Coverage baseline. This spec does not rewrite Spec 323; it narrows the follow-up to durable proportional guardrail hardening, especially explicit Navigation and Filament provider/panel surface handling.

Close alternatives deferred:

• 325-tenantial-design-system-and-state-patterns: shared component and state cleanup rules after guardrails are enforceable.
• 326-tenantial-domain-pattern-coverage-pass: grouped domain pattern coverage after route/page archetypes are stabilized.
• 327-tenantial-enterprise-ui-implementation-wave-1: runtime UI implementation after design decisions and mockups/patterns exist.

Spec Candidate Check

• Problem: Spec 323 created a UI/Productization audit baseline, but future specs can still silently change reachable UI surfaces unless the UI impact question, proportional coverage decision, and mechanical guard are durable and explicit across templates, prompts, docs, and scripts.
• Today's failure: A feature can change Filament pages, routes, Blade views, Livewire components, navigation support code, or Filament panel/provider behavior without clearly acknowledging the UI/Productization impact. Navigation and Filament provider/panel surfaces are especially easy to miss because they are not always page files.
• User-visible improvement: Future feature work will make UI surface impact explicit before implementation and before completion, so reachable product surfaces do not become unclassified UI debt.
• Smallest enterprise-capable version: Update the Constitution/templates/prompts/checklists and the lightweight diff guard so UI-relevant file changes require a coverage acknowledgment while still allowing backend-only and non-material UI work to proceed with a short no-impact rationale.
• Explicit non-goals: No product UI redesign, no Filament resource/page behavior changes, no route behavior changes, no authorization changes, no migrations, no runtime tests, no business logic, no forced screenshot or page report for every tiny UI change, and no heavy design approval workflow.
• Permanent complexity imported: A maintained governance rule, template sections, prompt instructions, a small shell guard, and checklist items. No runtime entity, database table, service layer, enum/status family, or UI framework is introduced.
• Why now: Spec 323 made the UI audit baseline visible. The next risk is baseline decay as new features land, especially through navigation and Filament provider/panel surface changes.
• Why not local: A note in one spec or README would not prevent future silent omissions. The rule must live in Spec Kit templates/prompts and the mechanical guard.
• Approval class: Core Enterprise
• Red flags triggered: Governance guardrail and process taxonomy. Defense: the guardrail is proportional, docs/tooling-only, and explicitly avoids runtime semantic machinery.
• Score: Nutzen 2 | Dringlichkeit 2 | Scope 2 | Komplexitaet 1 | Produktnaehe 2 | Wiederverwendung 2 | Gesamt: 11/12
• Decision: approve

Spec Scope Fields

• Scope: workspace
• Primary Routes: N/A - no product routes are changed.
• Data Ownership: N/A - no workspace-owned or tenant-owned runtime data changes.
• RBAC: N/A - no runtime authorization behavior changes.

UI Surface Impact

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 added
• New table/form/state added
• Customer-facing surface changed
• Dangerous action changed
• Status/evidence/review presentation changed
• Workspace/environment context presentation changed

No-impact rationale: Spec 324 changes governance, Spec Kit templates/prompts, audit documentation, and a local shell guard. It must reference product UI paths as guard inputs, but it must not change reachable product UI behavior, routes, navigation behavior, Filament resources/pages, Livewire components, Blade views, authorization, or business logic.

UI/Productization Coverage

N/A - no reachable product UI surface impact.

• Route/page/surface: N/A
• Current or new page archetype: N/A
• Design depth: Internal/Hidden governance tooling
• Repo-truth level: repo-verified
• Existing pattern reused: Spec 323 UI audit foundation and current scripts/check-ui-productization-coverage
• New pattern required: none
• Screenshot required: no
• Page audit required: no
• Customer-safe review required: no product UI content changes
• Dangerous-action review required: no runtime actions
• 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
  • Not applicable, no reachable product UI surface impact

Summary

Spec 324 turns the Spec 323 UI/Productization audit baseline into a durable delivery guardrail.

After this spec, every future feature that adds, removes, renames, or materially changes a reachable UI surface must explicitly declare UI Surface Impact and either update the UI/Productization coverage artifacts or document why no update is required.

The guardrail must remain proportional:

• strategic new surfaces require deeper coverage
• normal domain pages can reuse patterns
• small existing surface changes can use coverage acknowledgment
• backend-only, docs-only, tooling-only, and non-material UI work can declare no UI impact with a short rationale
• not every UI change requires a screenshot or full page report

Product Context

Tenantial/TenantPilot is becoming a sellable Enterprise SaaS governance platform, not a raw Microsoft admin mirror or generic Filament admin tool.

The product direction is:

• decision-first
• evidence-first
• workspace-first
• customer-safe where applicable
• capability-aware
• audit-ready
• calm enterprise UX
• progressive disclosure for technical depth
• no misleading status
• no green success state unless verified

Spec 323 created visibility into current UI/productization coverage. Spec 324 ensures future feature work cannot silently create unclassified UI debt.

Problem Statement

Without a durable guardrail, the Spec 323 audit can become stale.

Future specs may introduce or change:

• Filament pages and resources
• Livewire components
• Blade views
• routes
• navigation entries and navigation support code
• Filament panel/provider behavior
• modals, drawers, wizard steps
• table actions and bulk actions
• dangerous actions
• customer-facing surfaces
• evidence/review/export surfaces
• status or context presentation

without updating the UI/Productization coverage baseline.

That would recreate the same problem Spec 323 solved: reachable product UI surfaces without explicit productization decisions.

Objective

Implement a lightweight but durable UI/Productization Coverage Guardrail.

After this spec:

1. Future specs must explicitly declare UI Surface Impact.
2. UI-impacting specs must document the required productization coverage decision.
3. Backend-only, docs-only, tooling-only, or non-material UI changes can declare no UI impact with a short rationale.
4. Agent prompts require UI impact evaluation before implementation and before completion.
5. A mechanical guard detects UI-relevant diffs and requires coverage acknowledgment.
6. Navigation and Filament provider surface changes are included in the mechanical guard and explicitly represented in templates/prompts.
7. The guard remains proportional and does not require a full page report for every tiny UI change.
8. No product runtime behavior is changed.

Non-Goals

This spec must not:

• redesign any product page
• implement Spec 323 audit recommendations
• create target mockups
• modify product UI behavior
• modify Filament resources/pages for product functionality
• modify Livewire runtime behavior
• modify application routes
• modify authorization logic
• modify business logic
• modify database schema
• modify runtime tests
• force every UI change to create a screenshot
• force every UI change to create a full page report
• block legitimate backend-only work
• introduce heavy manual design approval workflows
• create compatibility layers
• create new product capabilities

Core Principle

Every reachable product UI surface must have an explicit productization coverage decision.

A feature is not complete if it introduces, removes, renames, or materially changes a reachable UI surface without classifying or acknowledging the surface by:

• UI impact
• page archetype where applicable
• design depth
• repo-truth level
• target pattern or mockup requirement
• customer-safe implications where applicable
• dangerous-action handling where applicable

No reachable product surface may remain unclassified, undesigned, or without a recommended target state.

Definitions

UI Surface

A UI surface is any user-visible product interaction point, including pages, routes, navigation items, sidebar entries, topbar/context elements, dashboard cards, tables, forms, modals, drawers, wizard steps, actions, bulk actions, dangerous action confirmations, empty/loading/error states, notification surfaces, customer-facing views, operator workflow surfaces, audit/evidence export surfaces, Filament panel surfaces, and Filament render hook surfaces.

Reachable UI Surface

A UI surface is reachable if it can be accessed through navigation, direct route, redirect, deep link, action button, modal/drawer trigger, resource action, workflow step, customer link, operator link, Filament resource/page registration, or panel provider registration.

A permission-protected or guarded page can still be a reachable UI surface.

Material UI Change

A material UI change includes new pages, removed pages, renamed pages, new routes, changed routes, new navigation items, changed navigation grouping, changed sidebar/topbar behavior, changed primary actions, changed dangerous actions, new modals/drawers/wizards, changed customer-facing copy, changed status presentation, changed evidence/review/export presentation, changed workspace/environment context presentation, changed table/form/state that affects product understanding, changed Filament provider/panel behavior that affects reachable UI, and changed navigation support code that affects reachable UI.

Non-Material UI Change

Examples that usually do not require a full coverage update:

• typo fix
• minor copy correction without meaning change
• pure CSS spacing fix
• icon alignment
• test-only selector adjustment
• internal refactor with identical rendered UI
• backend-only service change
• job/command change with no UI surface effect

Even for non-material UI changes, the spec must explicitly state why no UI coverage update is needed.

Guardrail Model

Spec 324 uses four enforcement layers:

1. Constitution principle
2. Spec/plan/tasks/checklist template requirements
3. Agent implementation prompt requirements
4. Lightweight mechanical diff guard

Layer 1 - Constitution

The Constitution stores the permanent principle. It must stay concise and principle-level.

Layer 2 - Spec Templates

Templates force every future feature spec to answer:

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

The spec template must explicitly include Navigation and Filament panel/provider surface changes as selectable impact types.

Layer 3 - Agent Prompts

Implementation prompts require the agent to evaluate UI impact before implementation and before marking work complete.

Layer 4 - Mechanical Diff Guard

A lightweight script detects UI-relevant file changes and verifies that the diff contains a coverage acknowledgment.

The script is not a design reviewer. It only prevents silent omission.

Current Repo Findings

The preparation pass found these relevant repo facts:

• .specify/memory/constitution.md already contains UI-COV-001 from Spec 323.
• scripts/check-ui-productization-coverage already exists and already includes targeted triggers for apps/platform/app/Support/Navigation/ and apps/platform/app/Providers/Filament/.
• .gitea/workflows/test-pr-fast-feedback.yml already runs the guard.
• .specify/templates/spec-template.md contains a UI Surface Impact section, but its checkbox list does not yet explicitly include Navigation changed, Filament panel/provider surface changed, status/evidence/review presentation changed, or workspace/environment context presentation changed.
• .codex/prompts/speckit.implement.md and .github/agents/speckit.implement.agent.md include UI/Productization Coverage guardrail language, but should explicitly name Filament panel/provider surfaces and proportional coverage expectations.
• Before Spec 324 implementation, the guard only accepted changed audit files or a checked no-impact decision. Spec 324 should make coverage acknowledgment detection proportional but concrete: guarded UI changes pass only with a checked spec impact decision, a checked no-impact decision with nearby rationale, or a real UI audit coverage artifact update. Generic template, prompt, or documentation phrases must not satisfy the guard when guarded UI files changed.

Functional Requirements

• FR-324-001: The Constitution MUST contain a concise UI/Productization Coverage principle and MUST NOT include long script implementation details.
• FR-324-002: The spec template MUST require every future spec to answer whether it adds, removes, renames, or materially changes a reachable UI surface.
• FR-324-003: The spec template MUST include explicit UI Surface Impact options for Navigation changed and Filament panel/provider surface changed.
• FR-324-004: The spec template MUST include proportional UI/Productization Coverage fields for route/page, new or existing surface, page archetype, design depth, repo-truth level, pattern reuse, screenshot need, page report need, customer-safe review, dangerous-action review, and coverage artifact updates.
• FR-324-005: The plan template MUST require a UI/Productization Guardrail Check before implementation and MUST include no-impact rationale handling for backend-only, docs-only, tooling-only, test-only, or non-material UI work.
• FR-324-006: The tasks template MUST include proportional UI coverage tasks for reachable UI changes and a no-impact task for specs with no UI surface impact.
• FR-324-007: The checklist template MUST include UI/Productization Coverage checks, including Navigation and Filament provider/panel surface changes.
• FR-324-008: Agent implementation prompts MUST require UI impact evaluation before code changes and before completion.
• FR-324-009: Agent implementation prompts MUST explicitly include pages, routes, navigation entries, Filament panel/provider surfaces, Livewire surfaces, Blade views, tables, forms, modals, drawers, actions, status states, customer-facing views, and evidence/review/export surfaces.
• FR-324-010: Agent implementation prompts MUST state proportionality: not every small UI change needs a page report or screenshot.
• FR-324-011: scripts/check-ui-productization-coverage MUST exist and be executable.
• FR-324-012: The guard MUST treat exactly these required product paths as UI-relevant: apps/platform/app/Filament/, apps/platform/resources/views/, apps/platform/app/Livewire/, apps/platform/routes/, apps/platform/app/Support/Navigation/, and apps/platform/app/Providers/Filament/.
• FR-324-013: The guard MUST NOT broaden UI-relevant provider/support matching to all of apps/platform/app/Support/ or all of apps/platform/app/Providers/.
• FR-324-014: The guard MUST evaluate staged and unstaged changes where feasible and MAY accept a base ref argument such as HEAD.
• FR-324-015: The guard MUST pass when no UI-relevant files changed.
• FR-324-016: The guard MUST pass when UI-relevant files changed and coverage acknowledgment exists through a checked UI Surface Impact item in a changed specs/*/spec.md, a checked no-impact declaration with nearby non-empty rationale in a changed specs/*/spec.md, or a real UI audit coverage artifact update.
• FR-324-017: The guard MUST fail with a clear message when UI-relevant files changed and no coverage acknowledgment exists.
• FR-324-018: The guard MUST support checked no-impact rationale through the active spec and MUST fail checked no-impact declarations that have no nearby non-empty rationale block.
• FR-324-019: The guard MUST avoid external dependencies and work in local shell and CI/Gitea environments.
• FR-324-020: The README or guardrail documentation under docs/ui-ux-enterprise-audit/ MUST document standalone usage and proportional expectations.
• FR-324-021: Spec 324 MUST include spec.md, plan.md, tasks.md, and checklists/requirements.md.
• FR-324-022: Validation MUST include bash -n scripts/check-ui-productization-coverage, bash scripts/check-ui-productization-coverage HEAD, and git diff --check.
• FR-324-023: Full runtime test suite execution MUST be explicitly documented as not run unless runtime product behavior changes, which is out of scope.
• FR-324-024: Final implementation diff MUST not modify product runtime files under apps/platform/app/Filament/, apps/platform/app/Livewire/, apps/platform/resources/views/, apps/platform/routes/, apps/platform/config/, apps/platform/database/, or apps/platform/tests/.
• FR-324-025: The guard MUST NOT treat unchecked template checkboxes, unchecked spec checkboxes, headings, or generic phrases in templates/prompts/docs as valid coverage acknowledgment when guarded UI files changed.

Non-Functional Requirements

• NFR-324-001: The guardrail must remain proportional and low-friction.
• NFR-324-002: The guard must be deterministic shell tooling without external runtime dependencies.
• NFR-324-003: Documentation must distinguish coverage acknowledgment from a full page report or screenshot requirement.
• NFR-324-004: Any implementation must preserve Spec 323 audit artifacts and completed-spec history.
• NFR-324-005: No product runtime behavior, route behavior, UI behavior, authorization behavior, or database schema may change.

User Scenarios And Testing

User Story 1 - Future UI Work Cannot Skip Coverage (Priority: P1)

As a maintainer reviewing a future UI-changing feature, I want the spec and guard to require a UI Surface Impact decision so the feature cannot silently add unclassified UI debt.

Independent Test: Change a UI-relevant file without docs/spec acknowledgment and verify the guard fails with the required message.

Acceptance Scenarios:

1. Given a staged or unstaged change under apps/platform/app/Filament/, When no coverage acknowledgment exists, Then the guard fails.
2. Given the same UI-relevant change and a spec containing UI Surface Impact and UI/Productization Coverage, When the guard runs, Then the guard passes.

User Story 2 - Non-Material Or Backend Work Can Proceed (Priority: P1)

As a maintainer of backend or non-material UI work, I want to declare no UI impact with rationale so the guard does not force unnecessary audit artifacts.

Independent Test: Change a non-UI backend file and verify the guard passes; change a guarded UI path with a checked no-impact rationale and verify the guard passes.

Acceptance Scenarios:

1. Given only backend service files changed, When the guard runs, Then the guard passes without requiring coverage docs.
2. Given a guarded UI file changed for non-material reasons and the active spec marks No UI surface impact with rationale, When the guard runs, Then the guard passes.

User Story 3 - Navigation And Provider Surfaces Are Not Missed (Priority: P1)

As a reviewer, I want navigation support code and Filament provider/panel changes to be explicitly considered because they can materially change reachable UI without changing a page file.

Independent Test: Change apps/platform/app/Support/Navigation/... or apps/platform/app/Providers/Filament/... without acknowledgment and verify the guard fails; add coverage acknowledgment and verify it passes.

Acceptance Scenarios:

1. Given a navigation support path changed without acknowledgment, When the guard runs, Then the guard fails.
2. Given a Filament provider path changed without acknowledgment, When the guard runs, Then the guard fails.
3. Given either path changed with Navigation changed or Filament panel/provider surface changed acknowledged in the active spec, When the guard runs, Then the guard passes.

Edge Cases

• UI-relevant file path changed only for comment or selector cleanup.
• A spec updates .specify/templates/ but no product runtime UI surface.
• Navigation helper changed for an internal refactor with identical rendered UI.
• Filament provider changed for asset/provider registration with no reachable UI behavior change.
• Coverage artifacts change but no UI-relevant files change.
• Base ref is unavailable in CI.
• Both staged and unstaged diffs exist.
• No Git base ref is supplied.

Proportionality Review

• New source of truth?: No runtime source of truth. The guardrail updates governance truth only.
• New persisted entity/table/artifact?: No runtime persistence. Spec Kit and docs artifacts only.
• New abstraction?: No application abstraction. A shell guard exists as repository tooling.
• New enum/state/reason family?: No runtime state family.
• New cross-domain UI framework/taxonomy?: No runtime UI framework. The spec refines docs-only UI coverage categories introduced by Spec 323.
• Current operator problem: Future features can degrade product trust by adding or changing reachable UI without a productization decision.
• Existing structure is insufficient because: Spec 323 created the baseline, but template/prompt/script enforcement must explicitly cover Navigation and Filament provider/panel surfaces and no-impact proportionality.
• Narrowest correct implementation: Update existing governance surfaces and one lightweight shell guard; do not create a new service, package, CI framework, or runtime layer.
• Ownership cost: Future maintainers must keep guard path patterns and acknowledgment phrases aligned with the UI audit docs.
• Alternative intentionally rejected: Heavy design approval gates and full screenshot/page-report requirements for every UI change.
• Release truth: Current-release governance hardening.

Testing / Lane / Runtime Impact

• Test purpose / classification: N/A for runtime; shell/docs guard validation only.
• Validation lane(s): docs/tooling validation; PR fast-feedback guard where integrated.
• Why this classification and these lanes are sufficient: The change is governance/tooling/docs-only and does not alter Laravel runtime behavior.
• New or expanded test families: none.
• Fixture / helper cost impact: none.
• Heavy-family visibility / justification: none.
• Special surface test profile: N/A.
• Reviewer handoff: Confirm no runtime files changed, guard script syntax passes, guard behavior is validated with representative cases, and git diff --check passes.
• Budget / baseline / trend impact: none.
• Escalation needed: none.
• Planned validation commands:
  • bash -n scripts/check-ui-productization-coverage
  • bash -n scripts/validate-ui-productization-coverage-guard
  • bash scripts/validate-ui-productization-coverage-guard
  • bash scripts/check-ui-productization-coverage HEAD
  • git diff --check

Acceptance Criteria

Spec 324 is complete when:

1. Constitution contains a concise UI/Productization Coverage principle.
2. Spec template requires UI Surface Impact declaration.
3. UI-impacting specs have a required UI/Productization Coverage section.
4. No-impact specs require a rationale.
5. Navigation changes are explicitly represented in templates/prompts.
6. Filament panel/provider surface changes are explicitly represented in templates/prompts.
7. Plan/tasks/checklist templates include proportional UI coverage guardrails.
8. Agent prompts require UI impact evaluation before implementation and completion.
9. scripts/check-ui-productization-coverage exists.
10. The script is executable.
11. The script detects UI-relevant product paths.
12. The script detects apps/platform/app/Support/Navigation/.
13. The script detects apps/platform/app/Providers/Filament/.
14. The script does not broadly trigger on all Support/Provider paths.
15. The script detects coverage acknowledgment.
16. The script rejects unchecked template headings, unchecked spec checkboxes, and generic template/prompt/doc phrases when UI-relevant files changed.
17. The script fails clearly when UI-relevant files change without concrete coverage acknowledgment.
18. The script passes when no UI-relevant files changed.
19. The script passes when UI-relevant files changed and coverage is acknowledged.
20. The script supports no-impact rationale.
21. The script does not require full page reports or screenshots for tiny UI changes.
22. No product runtime behavior is changed.
23. bash -n scripts/check-ui-productization-coverage passes.
24. bash scripts/validate-ui-productization-coverage-guard passes.
25. bash scripts/check-ui-productization-coverage HEAD passes.
26. git diff --check passes.
27. Full suite is explicitly documented as not run.
28. Spec 324 tasks and checklist are complete.

Definition Of Done

• Guardrail principle exists or is verified.
• Templates force the UI impact question.
• Prompts guide agents correctly.
• Mechanical guard exists and is validated.
• Navigation/provider surface paths are covered mechanically and explicitly in future-spec artifacts.
• Guard remains proportional.
• Guard supports backend-only and non-material UI changes.
• No runtime product behavior changed.
• Validation commands are documented.
• Future specs cannot silently add unclassified UI surfaces.

Assumptions

• Spec 323 remains the baseline UI audit package and is not rewritten.
• The existing Gitea fast-feedback workflow remains the integration point for the guard.
• Bash is available in local and CI environments.
• No new toolchain is needed.

Open Questions

None block implementation. During implementation, if a template or prompt file named in this spec is absent, document the missing file instead of creating unrelated structures blindly.