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
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.