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

Plan: Spec 324 - UI Productization Coverage Guardrails

Branch: 324-ui-productization-coverage-guardrails | Date: 2026-05-17 | Spec: specs/324-ui-productization-coverage-guardrails/spec.md

Summary

Spec 324 hardens the Spec 323 UI/Productization audit baseline into a durable guardrail for future work. The implementation is docs/tooling/spec-kit only: verify or update the Constitution principle, templates, prompts, README guidance, and scripts/check-ui-productization-coverage so UI-relevant diffs require a proportional coverage decision. Navigation support paths and Filament provider/panel paths must be explicitly covered without broadening to all Support or Provider code.

Technical Context

• Language/Version: Bash for the guard script; Markdown for Spec Kit and docs artifacts.
• Primary Dependencies: Git CLI; existing Spec Kit templates/prompts; no new packages.
• Storage: N/A - no database or runtime storage.
• Testing: Shell syntax and guard behavior checks; git diff --check.
• Validation Lanes: docs/tooling validation only.
• Target Platform: local shell and Gitea/CI Linux shell.
• Project Type: Laravel/Filament monorepo, but this spec changes no runtime product code.
• Performance Goals: guard should run quickly using git diff and text matching only.
• Constraints: no product UI, route, authorization, database, business logic, runtime test, or dependency changes.
• Scale/Scope: one governance guardrail slice following Spec 323.

Current Repo Findings

The preparation pass verified before implementation:

• .specify/memory/constitution.md already contains UI-COV-001 from Spec 323.
• .specify/templates/spec-template.md, .specify/templates/plan-template.md, .specify/templates/tasks-template.md, and .specify/templates/checklist-template.md already contain UI/Productization-related baseline text from Spec 323.
• The pre-implementation spec template did not yet explicitly list Navigation changed, Filament panel/provider surface changed, Status/evidence/review presentation changed, or Workspace/environment context presentation changed in the UI Surface Impact checkbox block.
• .codex/prompts/speckit.implement.md and .github/agents/speckit.implement.agent.md already included a UI/Productization Coverage Guardrail section, but needed explicit Filament panel/provider surfaces and proportional coverage instructions.
• scripts/check-ui-productization-coverage already exists and is executable in the repository state.
• The guard already targets apps/platform/app/Support/Navigation/* and apps/platform/app/Providers/Filament/*.
• .gitea/workflows/test-pr-fast-feedback.yml already invokes the guard.
• No specs/324-* package existed before this preparation.

UI/Productization Guardrail Check

This plan does not change reachable product UI surfaces.

• Affected routes/pages/actions/states/navigation/panel surfaces: N/A for runtime product surfaces.
• UI audit inventory update required: no.
• Page archetype: N/A.
• Design depth: Internal/Hidden governance tooling.
• Repo-truth level: repo-verified.
• Existing domain/component pattern reused: Spec 323 UI audit foundation and current guard script.
• Customer-safe implications: none, no product/customer-facing UI changes.
• Dangerous-action implications: none, no runtime actions.
• No-impact rationale: the implementation may change templates, prompts, docs, CI guard wording, and shell tooling, but must not change product routes, navigation behavior, Filament resources/pages, Livewire components, Blade views, authorization, data, or business logic.

Shared Pattern & System Fit

• Cross-cutting feature marker: yes, governance workflow only.
• Systems touched: Spec Kit templates/prompts, UI audit README, PR fast-feedback guard script.
• Shared abstractions reused: existing Spec Kit file layout and existing scripts/check-ui-productization-coverage.
• New abstraction introduced? why?: none.
• Why the existing abstraction was sufficient or insufficient: existing guard exists but needs explicit proportional behavior and template/prompt coverage for Navigation and Filament provider/panel surfaces.
• Bounded deviation / spread control: do not broaden provider/support path matching beyond the two required targeted directories.

OperationRun UX Impact

N/A - no OperationRun start, completion, link, notification, or monitoring behavior.

Provider Boundary & Portability Fit

N/A - no provider runtime seam changes. The spec mentions apps/platform/app/Providers/Filament/ only as a guarded file path category for UI surface coverage decisions.

Constitution Check

• Inventory-first: N/A, no inventory/runtime data behavior.
• Read/write separation: PASS, no product write actions.
• Graph contract path: N/A, no Graph calls.
• Deterministic capabilities: N/A, no capabilities.
• RBAC-UX: PASS, no runtime authorization changes.
• Workspace isolation: PASS, no runtime scope changes.
• Tenant isolation: PASS, no tenant-owned reads/writes.
• OperationRun UX: N/A.
• Test governance: PASS, docs/tooling validation only; full suite not planned.
• Proportionality: PASS, guard remains lightweight and avoids heavy design approval workflow.
• No premature abstraction: PASS, reuse existing script and templates.
• Persisted truth: PASS, no database or runtime artifact persistence.
• Behavioral state: PASS, no runtime state/status changes.
• UI semantics: PASS, no runtime UI semantic framework.
• Shared pattern first: PASS, reuse Spec 323 guardrail surfaces.
• Provider boundary: PASS, no provider platform-core behavior changed.
• UI/Productization coverage: PASS, this is the guardrail improvement itself and the active spec marks no product UI surface impact.

Implementation Phases

Phase 1 - Inspect Existing Conventions

Inspect existing Constitution, Spec Kit templates, prompts, scripts, CI/Gitea workflow, and Spec 323 artifacts. Confirm which files exist and document missing files instead of creating unrelated structures.

Phase 2 - Constitution Principle

Verify the UI/Productization Coverage principle exists and remains concise. Update only if missing or too narrow for Navigation and Filament provider/panel surfaces.

Phase 3 - Template Updates

Update:

• .specify/templates/spec-template.md
• .specify/templates/plan-template.md
• .specify/templates/tasks-template.md
• .specify/templates/checklist-template.md

Required emphasis:

• UI Surface Impact is mandatory.
• Navigation changes are explicit.
• Filament panel/provider surface changes are explicit.
• No-impact rationale is required when no UI surface impact is selected.
• Proportional coverage avoids page report/screenshot overreach.

Phase 4 - Prompt Updates

Update:

• .codex/prompts/speckit.implement.md
• .github/agents/speckit.implement.agent.md

If other repository prompt conventions are present and relevant, update only the existing equivalent files.

Required emphasis:

• evaluate UI impact before implementation
• evaluate UI impact before completion
• include Navigation and Filament panel/provider surfaces
• keep proportional coverage language visible

Phase 5 - Mechanical Guard Update

Update scripts/check-ui-productization-coverage.

The guard must:

• be executable
• detect staged and unstaged changes where feasible
• optionally accept a base ref such as HEAD
• use git diff --name-only, git diff --cached --name-only, git diff, and git diff --cached
• trigger on required UI paths:
  • apps/platform/app/Filament/
  • apps/platform/resources/views/
  • apps/platform/app/Livewire/
  • apps/platform/routes/
  • apps/platform/app/Support/Navigation/
  • apps/platform/app/Providers/Filament/
• avoid broad matches for all Support or Provider paths
• detect coverage acknowledgment in changed docs/spec/template/prompt diffs
• accept guarded UI changes only when a changed spec has a checked UI impact item, a changed spec has checked no-impact with nearby non-empty rationale, or a real UI audit coverage artifact changed
• reject unchecked template headings, unchecked spec checkboxes, and generic template/prompt/doc phrases as acknowledgments when guarded UI files changed
• support checked no-impact rationale
• print the expected pass/fail messages

Phase 6 - Guardrail Documentation

Update docs/ui-ux-enterprise-audit/README.md or the existing guardrail documentation path to document:

• standalone usage
• CI/Gitea usage
• proportional coverage model
• no-impact rationale model
• Navigation and Filament provider/panel surface handling

Do not create unrelated documentation structures.

Phase 7 - Validation

Run:

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

Validate representative cases where feasible without leaving runtime product diffs:

• no UI diff passes
• backend-only diff passes
• docs-only diff passes
• UI diff without coverage fails
• UI diff with coverage acknowledgment passes
• UI diff with no-impact rationale passes
• UI diff with unchecked template heading fails
• UI diff with unchecked spec checkbox fails
• UI diff with checked no-impact but no rationale fails
• UI diff with real audit coverage artifact update passes
• navigation/provider surface diff without acknowledgment fails
• navigation/provider surface diff with acknowledgment passes
• untracked guarded UI file without acknowledgment fails

Temporary local validation diffs may be created only if fully reverted before final state.

Phase 8 - Final Review

Confirm:

• no product runtime behavior changed
• no product UI implementation happened
• no business logic changed
• no database/schema changes
• no runtime tests changed
• full suite not run and reason documented

Project Structure

specs/324-ui-productization-coverage-guardrails/
├── spec.md
├── plan.md
├── tasks.md
└── checklists/
    └── requirements.md

Potential implementation files:

.specify/memory/constitution.md
.specify/templates/spec-template.md
.specify/templates/plan-template.md
.specify/templates/tasks-template.md
.specify/templates/checklist-template.md
.codex/prompts/speckit.implement.md
.github/agents/speckit.implement.agent.md
scripts/check-ui-productization-coverage
docs/ui-ux-enterprise-audit/README.md

Do 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/
apps/platform/tests/

The guard script may reference product paths as strings.

Risk Controls

• Keep Constitution wording concise.
• Keep script lightweight and dependency-free.
• Allow no-impact rationale.
• Do not require full page report or screenshot for every small UI diff.
• Do not modify runtime product code.
• Do not broaden guard matching to unrelated backend/provider/support paths.
• Preserve completed Spec 323 history.
• Document any missing template or prompt file instead of inventing unrelated structures.

Test Governance Check

• Test purpose / classification by changed surface: docs/tooling validation, N/A for runtime.
• Affected validation lanes: shell guard validation and git diff --check.
• Why this lane mix is the narrowest sufficient proof: the spec changes only governance/tooling/docs files.
• Narrowest proving 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
• 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.
• Closing validation and reviewer handoff: verify final diff excludes product runtime changes and representative guard cases are documented.
• Budget / baseline / trend follow-up: none.
• Escalation path: none.
• Active feature PR close-out entry: Guardrail.
• Why no dedicated follow-up spec is needed: Spec 324 is the dedicated bounded follow-up for the Spec 323 guardrail gap.

Readiness Gate

This package is ready for implementation when:

• spec.md, plan.md, tasks.md, and checklists/requirements.md exist.
• Scope remains governance/tooling/docs only.
• Required files and path triggers are explicit.
• Navigation and Filament provider/panel surfaces are explicitly named.
• No product runtime file changes are planned.
• Validation commands are concrete.
• No open question blocks implementation.