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

Tasks: Spec 324 - UI Productization Coverage Guardrails

Input: specs/324-ui-productization-coverage-guardrails/spec.md and plan.md
Prerequisites: Spec 323 UI audit foundation exists on platform-dev
Tests: Shell/docs/tooling validation only. No runtime product tests unless implementation accidentally changes runtime behavior, which is out of scope.

Phase 1: Inspect Existing Spec-Kit Files

• T001 Locate Constitution file at .specify/memory/constitution.md.
• T002 Locate spec, plan, tasks, and checklist templates under .specify/templates/.
• T003 Locate implementation prompts under .codex/prompts/ and .github/agents/.
• T004 Locate existing scripts and CI/Gitea conventions for lightweight static checks.
• T005 Review Spec 323 as completed historical context and do not rewrite its close-out/task history.
• T006 Confirm no specs/324-* package existed before this feature branch except the active package.

Phase 2: Add Or Verify Constitution Principle

• T007 Add or verify the UI/Productization Coverage principle in .specify/memory/constitution.md.
• T008 Keep Constitution wording principle-level and avoid long script details.
• T009 Ensure Navigation and Filament provider/panel surfaces are covered by the principle or by template/prompt details without bloating the Constitution.

Phase 3: Update Spec Template

• T010 Update .specify/templates/spec-template.md to require the UI Surface Impact section.
• T011 Add or verify the UI/Productization Coverage section.
• T012 Add explicit UI Surface Impact options for Navigation changed.
• T013 Add explicit UI Surface Impact options for Filament panel/provider surface changed.
• T014 Add status/evidence/review and workspace/environment context presentation options where they fit the existing template.
• T015 Add or verify the no-impact rationale requirement.
• T016 Keep proportional guidance clear: not every UI change needs a screenshot or full page report.

Phase 4: Update Plan, Tasks, And Checklist Templates

• T017 Update .specify/templates/plan-template.md with a UI/Productization Guardrail Check section or verify the existing section satisfies Spec 324.
• T018 Ensure the plan template requires affected routes/pages/actions/states/navigation/panel surfaces where relevant.
• T019 Ensure the plan template supports backend-only, docs-only, tooling-only, test-only, and non-material UI no-impact rationale.
• T020 Update .specify/templates/tasks-template.md with proportional UI coverage task requirements.
• T021 Ensure the tasks template includes No UI surface impact with rationale for no-impact specs.
• T022 Update .specify/templates/checklist-template.md with UI/Productization Coverage checks.
• T023 Ensure checklist template explicitly considers Navigation and Filament provider/panel surface changes.

Phase 5: Update Agent Prompts

• T024 Update .codex/prompts/speckit.implement.md to require UI impact evaluation before implementation.
• T025 Update .codex/prompts/speckit.implement.md to require a coverage decision before completion.
• T026 Update .codex/prompts/speckit.implement.md to include Navigation and Filament provider/panel surface awareness.
• T027 Update .codex/prompts/speckit.implement.md to document proportional coverage expectations.
• T028 Apply the same implementation-prompt changes to .github/agents/speckit.implement.agent.md.
• T029 If another existing implementation prompt convention is discovered, update it only when it is clearly the same workflow surface.

Phase 6: Add Or Update Mechanical Guard

• T030 Update scripts/check-ui-productization-coverage.
• T031 Ensure the script is executable.
• T032 Detect Filament page/resource paths under apps/platform/app/Filament/.
• T033 Detect Blade view paths under apps/platform/resources/views/.
• T034 Detect Livewire paths under apps/platform/app/Livewire/.
• T035 Detect route paths under apps/platform/routes/.
• T036 Detect apps/platform/app/Support/Navigation/.
• T037 Detect apps/platform/app/Providers/Filament/.
• T038 Do not broaden to all apps/platform/app/Support/.
• T039 Do not broaden to all apps/platform/app/Providers/.
• T040 Detect concrete coverage acknowledgment through changed specs with checked UI impact, changed specs with checked no-impact plus nearby rationale, or real audit coverage artifacts.
• T041 Support checked no-impact rationale.
• T042 Provide the clear Spec 324 failure message.
• T043 Provide the expected pass message.
• T044 Avoid external dependencies.
• T045 Preserve local and CI/Gitea compatibility.
• T068 Ensure generic template/prompt/doc phrases do not count as coverage acknowledgment when guarded UI files changed.

Phase 7: Update Guardrail Documentation

• T046 Update docs/ui-ux-enterprise-audit/README.md or the existing guardrail documentation path with standalone usage.
• T047 Document scripts/check-ui-productization-coverage HEAD.
• T048 Document proportional coverage: strategic page, domain page, small existing surface change, backend-only work.
• T049 Document Navigation and Filament provider/panel surface handling.
• T050 Document that full page reports and screenshots are not required for every tiny UI change.

Phase 8: Validate Guard Behavior

• T051 Validate no UI diff passes.
• T052 Validate backend-only diff passes.
• T053 Validate docs-only diff passes.
• T054 Validate UI diff without coverage fails.
• T055 Validate UI diff with coverage acknowledgment passes.
• T056 Validate UI diff with no-impact rationale passes.
• T057 Validate Navigation surface diff is detected.
• T058 Validate Filament provider surface diff is detected.
• T059 Validate Navigation/provider surface diff with coverage acknowledgment passes.
• T060 Revert any temporary validation diffs before final state.
• T069 Validate UI diff with unchecked template heading fails.
• T070 Validate UI diff with unchecked spec checkbox fails.
• T071 Validate UI diff with checked UI impact item in spec passes.
• T072 Validate UI diff with checked no-impact and rationale passes.
• T073 Validate UI diff with checked no-impact but no rationale fails.
• T074 Validate UI diff with real audit coverage artifact update passes.
• T075 Validate Navigation/provider diff without acknowledgment fails.
• T076 Validate Navigation/provider diff with checked acknowledgment passes.
• T077 Validate backend-only and docs-only diffs pass.
• T078 Validate untracked guarded UI file without acknowledgment fails.

Phase 9: Final Validation

• T061 Run bash -n scripts/check-ui-productization-coverage.
• T062 Run bash scripts/check-ui-productization-coverage HEAD.
• T063 Run git diff --check.
• T064 Confirm no product runtime files changed.
• T065 Confirm no product UI implementation was performed.
• T066 Confirm no business logic changed.
• T067 Document full suite not run because this spec is governance/tooling/docs-only.
• T079 Run bash -n scripts/validate-ui-productization-coverage-guard.
• T080 Run bash scripts/validate-ui-productization-coverage-guard.

Runtime Stop Conditions

• NT001 Evaluated and not triggered: no product Filament pages/resources were modified for runtime behavior.
• NT002 Evaluated and not triggered: no Livewire components, Blade views, product routes, policies, services, jobs, models, migrations, config, runtime tests, or business logic were modified.
• NT003 Evaluated and not triggered: no new package, dependency, CI framework, or toolchain was needed.
• NT004 Evaluated and not triggered: the guard remains limited to targeted Navigation and Filament provider paths.
• NT005 Evaluated and not triggered: product runtime behavior did not become necessary.

Requirement Coverage Map

Requirement(s)	Task Coverage
FR-324-001	T007-T009
FR-324-002, FR-324-003, FR-324-004	T010-T016
FR-324-005, FR-324-006, FR-324-007	T017-T023
FR-324-008, FR-324-009, FR-324-010	T024-T029
FR-324-011, FR-324-012, FR-324-013, FR-324-014, FR-324-015, FR-324-016, FR-324-017, FR-324-018, FR-324-019, FR-324-025	T030-T045, T051-T059, T068-T078
FR-324-020	T046-T050
FR-324-021	Preparation package files
FR-324-022, FR-324-023, FR-324-024	T061-T067, T079-T080

Dependencies

1. Phase 1 must complete before file updates.
2. Phase 2 through Phase 5 can proceed independently by file group after inspection.
3. Phase 6 depends on inspection of the current guard script.
4. Phase 7 depends on final guard behavior.
5. Phase 8 depends on the updated guard script.
6. Phase 9 depends on all implementation tasks.

MVP Scope

The minimum viable Spec 324 implementation is:

1. Templates/prompts explicitly cover Navigation and Filament provider/panel surfaces.
2. Guard script detects the required UI paths without broad Support/Provider matching.
3. Guard accepts proportional coverage acknowledgment or checked no-impact rationale.
4. Documentation explains standalone usage and proportional expectations.
5. Validation commands pass.
6. No runtime product behavior changes.