# 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 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 ```text specs/324-ui-productization-coverage-guardrails/ ├── spec.md ├── plan.md ├── tasks.md └── checklists/ └── requirements.md ``` Potential implementation files: ```text .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: ```text 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.