ahmido
e35706b846
## Summary - add the Spec 324 package for UI Productization Coverage Guardrails, including spec, plan, tasks, and requirements checklist - update Spec Kit templates and implementation prompts so future work must record UI surface impact, including navigation and Filament panel/provider surfaces - harden the UI productization coverage guard script and add the validation helper for lightweight guard execution - document the proportional guardrail flow in the UI/UX enterprise audit README ## Validation - not run in this step - change set is docs/tooling/governance only; no product runtime implementation included Co-authored-by: Ahmed Darrazi <ahmed.darrazi@live.de> Reviewed-on: #384
154 lines
9.2 KiB
Markdown
154 lines
9.2 KiB
Markdown
# 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
|
|
|
|
- [x] T001 Locate Constitution file at `.specify/memory/constitution.md`.
|
|
- [x] T002 Locate spec, plan, tasks, and checklist templates under `.specify/templates/`.
|
|
- [x] T003 Locate implementation prompts under `.codex/prompts/` and `.github/agents/`.
|
|
- [x] T004 Locate existing scripts and CI/Gitea conventions for lightweight static checks.
|
|
- [x] T005 Review Spec 323 as completed historical context and do not rewrite its close-out/task history.
|
|
- [x] T006 Confirm no `specs/324-*` package existed before this feature branch except the active package.
|
|
|
|
## Phase 2: Add Or Verify Constitution Principle
|
|
|
|
- [x] T007 Add or verify the UI/Productization Coverage principle in `.specify/memory/constitution.md`.
|
|
- [x] T008 Keep Constitution wording principle-level and avoid long script details.
|
|
- [x] 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
|
|
|
|
- [x] T010 Update `.specify/templates/spec-template.md` to require the UI Surface Impact section.
|
|
- [x] T011 Add or verify the UI/Productization Coverage section.
|
|
- [x] T012 Add explicit UI Surface Impact options for `Navigation changed`.
|
|
- [x] T013 Add explicit UI Surface Impact options for `Filament panel/provider surface changed`.
|
|
- [x] T014 Add status/evidence/review and workspace/environment context presentation options where they fit the existing template.
|
|
- [x] T015 Add or verify the no-impact rationale requirement.
|
|
- [x] T016 Keep proportional guidance clear: not every UI change needs a screenshot or full page report.
|
|
|
|
## Phase 4: Update Plan, Tasks, And Checklist Templates
|
|
|
|
- [x] T017 Update `.specify/templates/plan-template.md` with a UI/Productization Guardrail Check section or verify the existing section satisfies Spec 324.
|
|
- [x] T018 Ensure the plan template requires affected routes/pages/actions/states/navigation/panel surfaces where relevant.
|
|
- [x] T019 Ensure the plan template supports backend-only, docs-only, tooling-only, test-only, and non-material UI no-impact rationale.
|
|
- [x] T020 Update `.specify/templates/tasks-template.md` with proportional UI coverage task requirements.
|
|
- [x] T021 Ensure the tasks template includes `No UI surface impact` with rationale for no-impact specs.
|
|
- [x] T022 Update `.specify/templates/checklist-template.md` with UI/Productization Coverage checks.
|
|
- [x] T023 Ensure checklist template explicitly considers Navigation and Filament provider/panel surface changes.
|
|
|
|
## Phase 5: Update Agent Prompts
|
|
|
|
- [x] T024 Update `.codex/prompts/speckit.implement.md` to require UI impact evaluation before implementation.
|
|
- [x] T025 Update `.codex/prompts/speckit.implement.md` to require a coverage decision before completion.
|
|
- [x] T026 Update `.codex/prompts/speckit.implement.md` to include Navigation and Filament provider/panel surface awareness.
|
|
- [x] T027 Update `.codex/prompts/speckit.implement.md` to document proportional coverage expectations.
|
|
- [x] T028 Apply the same implementation-prompt changes to `.github/agents/speckit.implement.agent.md`.
|
|
- [x] 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
|
|
|
|
- [x] T030 Update `scripts/check-ui-productization-coverage`.
|
|
- [x] T031 Ensure the script is executable.
|
|
- [x] T032 Detect Filament page/resource paths under `apps/platform/app/Filament/`.
|
|
- [x] T033 Detect Blade view paths under `apps/platform/resources/views/`.
|
|
- [x] T034 Detect Livewire paths under `apps/platform/app/Livewire/`.
|
|
- [x] T035 Detect route paths under `apps/platform/routes/`.
|
|
- [x] T036 Detect `apps/platform/app/Support/Navigation/`.
|
|
- [x] T037 Detect `apps/platform/app/Providers/Filament/`.
|
|
- [x] T038 Do not broaden to all `apps/platform/app/Support/`.
|
|
- [x] T039 Do not broaden to all `apps/platform/app/Providers/`.
|
|
- [x] 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.
|
|
- [x] T041 Support checked no-impact rationale.
|
|
- [x] T042 Provide the clear Spec 324 failure message.
|
|
- [x] T043 Provide the expected pass message.
|
|
- [x] T044 Avoid external dependencies.
|
|
- [x] T045 Preserve local and CI/Gitea compatibility.
|
|
- [x] T068 Ensure generic template/prompt/doc phrases do not count as coverage acknowledgment when guarded UI files changed.
|
|
|
|
## Phase 7: Update Guardrail Documentation
|
|
|
|
- [x] T046 Update `docs/ui-ux-enterprise-audit/README.md` or the existing guardrail documentation path with standalone usage.
|
|
- [x] T047 Document `scripts/check-ui-productization-coverage HEAD`.
|
|
- [x] T048 Document proportional coverage: strategic page, domain page, small existing surface change, backend-only work.
|
|
- [x] T049 Document Navigation and Filament provider/panel surface handling.
|
|
- [x] T050 Document that full page reports and screenshots are not required for every tiny UI change.
|
|
|
|
## Phase 8: Validate Guard Behavior
|
|
|
|
- [x] T051 Validate no UI diff passes.
|
|
- [x] T052 Validate backend-only diff passes.
|
|
- [x] T053 Validate docs-only diff passes.
|
|
- [x] T054 Validate UI diff without coverage fails.
|
|
- [x] T055 Validate UI diff with coverage acknowledgment passes.
|
|
- [x] T056 Validate UI diff with no-impact rationale passes.
|
|
- [x] T057 Validate Navigation surface diff is detected.
|
|
- [x] T058 Validate Filament provider surface diff is detected.
|
|
- [x] T059 Validate Navigation/provider surface diff with coverage acknowledgment passes.
|
|
- [x] T060 Revert any temporary validation diffs before final state.
|
|
- [x] T069 Validate UI diff with unchecked template heading fails.
|
|
- [x] T070 Validate UI diff with unchecked spec checkbox fails.
|
|
- [x] T071 Validate UI diff with checked UI impact item in spec passes.
|
|
- [x] T072 Validate UI diff with checked no-impact and rationale passes.
|
|
- [x] T073 Validate UI diff with checked no-impact but no rationale fails.
|
|
- [x] T074 Validate UI diff with real audit coverage artifact update passes.
|
|
- [x] T075 Validate Navigation/provider diff without acknowledgment fails.
|
|
- [x] T076 Validate Navigation/provider diff with checked acknowledgment passes.
|
|
- [x] T077 Validate backend-only and docs-only diffs pass.
|
|
- [x] T078 Validate untracked guarded UI file without acknowledgment fails.
|
|
|
|
## Phase 9: Final Validation
|
|
|
|
- [x] T061 Run `bash -n scripts/check-ui-productization-coverage`.
|
|
- [x] T062 Run `bash scripts/check-ui-productization-coverage HEAD`.
|
|
- [x] T063 Run `git diff --check`.
|
|
- [x] T064 Confirm no product runtime files changed.
|
|
- [x] T065 Confirm no product UI implementation was performed.
|
|
- [x] T066 Confirm no business logic changed.
|
|
- [x] T067 Document full suite not run because this spec is governance/tooling/docs-only.
|
|
- [x] T079 Run `bash -n scripts/validate-ui-productization-coverage-guard`.
|
|
- [x] T080 Run `bash scripts/validate-ui-productization-coverage-guard`.
|
|
|
|
## Runtime Stop Conditions
|
|
|
|
- [x] NT001 Evaluated and not triggered: no product Filament pages/resources were modified for runtime behavior.
|
|
- [x] 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.
|
|
- [x] NT003 Evaluated and not triggered: no new package, dependency, CI framework, or toolchain was needed.
|
|
- [x] NT004 Evaluated and not triggered: the guard remains limited to targeted Navigation and Filament provider paths.
|
|
- [x] 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.
|