Spec 324: add UI productization coverage guardrails #384
@ -55,7 +55,7 @@ ## Outline
|
||||
|
||||
4. **UI/Productization Coverage Guardrail**:
|
||||
- Before implementing, determine whether this spec adds, removes, renames, or materially changes any reachable UI surface.
|
||||
- A UI surface includes pages, routes, navigation entries, tables, forms, modals, drawers, wizard steps, actions, dangerous-action confirmations, empty/loading/error states, customer-facing views, and operator workflow surfaces.
|
||||
- A UI surface includes pages, routes, navigation entries, navigation support code, Filament panel/provider surfaces, Livewire surfaces, Blade views, tables, forms, modals, drawers, wizard steps, actions, dangerous-action confirmations, empty/loading/error states, status/evidence/review presentation, customer-facing views, workspace/environment context presentation, and operator workflow surfaces.
|
||||
- If UI is affected:
|
||||
- update the UI/UX audit inventory under `docs/ui-ux-enterprise-audit/`
|
||||
- assign page archetype
|
||||
@ -65,6 +65,8 @@ ## Outline
|
||||
- review customer-safe and dangerous-action implications where applicable
|
||||
- update the coverage matrix or unresolved/manual-review ledger
|
||||
- If no reachable UI surface is affected, ensure the active spec contains exactly `- [x] No UI surface impact` with a short rationale.
|
||||
- Keep coverage proportional: small non-material UI changes, backend-only work, docs-only work, tooling-only work, and test-only work may use a checked no-impact rationale; strategic, customer-facing, dangerous-action-bearing, or materially new surfaces may require screenshots or page reports.
|
||||
- Re-check this decision before completion so implementation drift does not leave a changed reachable surface unclassified.
|
||||
- Do not mark the spec complete if a new or changed reachable UI surface remains unclassified.
|
||||
|
||||
5. **Project Setup Verification**:
|
||||
|
||||
4
.github/agents/speckit.implement.agent.md
vendored
4
.github/agents/speckit.implement.agent.md
vendored
@ -55,7 +55,7 @@ ## Outline
|
||||
|
||||
4. **UI/Productization Coverage Guardrail**:
|
||||
- Before implementing, determine whether this spec adds, removes, renames, or materially changes any reachable UI surface.
|
||||
- A UI surface includes pages, routes, navigation entries, tables, forms, modals, drawers, wizard steps, actions, dangerous-action confirmations, empty/loading/error states, customer-facing views, and operator workflow surfaces.
|
||||
- A UI surface includes pages, routes, navigation entries, navigation support code, Filament panel/provider surfaces, Livewire surfaces, Blade views, tables, forms, modals, drawers, wizard steps, actions, dangerous-action confirmations, empty/loading/error states, status/evidence/review presentation, customer-facing views, workspace/environment context presentation, and operator workflow surfaces.
|
||||
- If UI is affected:
|
||||
- update the UI/UX audit inventory under `docs/ui-ux-enterprise-audit/`
|
||||
- assign page archetype
|
||||
@ -65,6 +65,8 @@ ## Outline
|
||||
- review customer-safe and dangerous-action implications where applicable
|
||||
- update the coverage matrix or unresolved/manual-review ledger
|
||||
- If no reachable UI surface is affected, ensure the active spec contains exactly `- [x] No UI surface impact` with a short rationale.
|
||||
- Keep coverage proportional: small non-material UI changes, backend-only work, docs-only work, tooling-only work, and test-only work may use a checked no-impact rationale; strategic, customer-facing, dangerous-action-bearing, or materially new surfaces may require screenshots or page reports.
|
||||
- Re-check this decision before completion so implementation drift does not leave a changed reachable surface unclassified.
|
||||
- Do not mark the spec complete if a new or changed reachable UI surface remains unclassified.
|
||||
|
||||
5. **Project Setup Verification**:
|
||||
|
||||
@ -21,6 +21,8 @@ ## Applicability And Low-Impact Gate
|
||||
- [ ] CHK029 The spec includes exactly one coherent UI Surface Impact decision: either checked `No UI surface impact` with rationale, or one or more concrete UI impact boxes with completed UI/Productization Coverage.
|
||||
- [ ] CHK030 If reachable UI changed, the review confirms page archetype, design depth, repo-truth level, target pattern/mockup need, customer-safe review need, and dangerous-action review need are recorded.
|
||||
- [ ] CHK031 If reachable UI changed, `docs/ui-ux-enterprise-audit/route-inventory.md` and `docs/ui-ux-enterprise-audit/design-coverage-matrix.md` are updated, or `unresolved-pages.md` records why review is blocked.
|
||||
- [ ] CHK032 Navigation entries/support code and Filament panel/provider changes were explicitly considered as possible reachable UI surface changes, with either coverage artifacts or a checked no-impact rationale.
|
||||
- [ ] CHK033 Screenshot and full page-report expectations are proportional; small non-material or pattern-reusing UI changes are not forced into unnecessary audit artifacts.
|
||||
|
||||
## Native, Shared-Family, And State Ownership
|
||||
|
||||
|
||||
@ -33,6 +33,8 @@ ## UI / Surface Guardrail Plan
|
||||
> **Fill for operator-facing or guardrail-relevant workflow changes. Docs-only or template-only work may use concise `N/A`. Copy the spec classification forward; do not rename or expand it here.**
|
||||
|
||||
- **Guardrail scope**: [no operator-facing surface change / changed surfaces / workflow-only guardrail change]
|
||||
- **Affected routes/pages/actions/states/navigation/panel/provider surfaces**: [N/A / list exact surfaces]
|
||||
- **No-impact class, if applicable**: [backend-only / docs-only / tooling-only / test-only / non-material UI / N/A]
|
||||
- **Native vs custom classification summary**: [native / custom / mixed / N/A]
|
||||
- **Shared-family relevance**: [none / list affected shared families]
|
||||
- **State layers in scope**: [shell / page / detail / URL-query / none]
|
||||
@ -49,6 +51,8 @@ ## UI / Surface Guardrail Plan
|
||||
- **UI/Productization coverage decision**: [No UI surface impact / coverage artifacts updated / unresolved manual-review entry / N/A]
|
||||
- **Coverage artifacts to update**: [`route-inventory.md` / `design-coverage-matrix.md` / `page-reports/...` / `grouped-follow-up-candidates.md` / `unresolved-pages.md` / none]
|
||||
- **No-impact rationale**: [Required when `No UI surface impact` is checked in the spec]
|
||||
- **Navigation / Filament provider-panel handling**: [N/A / coverage artifact updated / checked no-impact rationale because rendered UI is unchanged]
|
||||
- **Screenshot or page-report need**: [yes/no + proportional rationale; not every small UI change requires either]
|
||||
|
||||
## Shared Pattern & System Fit
|
||||
|
||||
|
||||
@ -42,10 +42,14 @@ ## UI Surface Impact *(mandatory — UI-COV-001)*
|
||||
- [ ] No UI surface impact
|
||||
- [ ] Existing page changed
|
||||
- [ ] New page/route added
|
||||
- [ ] New modal/drawer/action added
|
||||
- [ ] Navigation changed
|
||||
- [ ] Filament panel/provider surface changed
|
||||
- [ ] New modal/drawer/wizard/action added
|
||||
- [ ] New table/form/state added
|
||||
- [ ] Customer-facing surface changed
|
||||
- [ ] Dangerous action changed
|
||||
- [ ] Status/evidence/review presentation changed
|
||||
- [ ] Workspace/environment context presentation changed
|
||||
|
||||
If any box except "No UI surface impact" is checked, complete the UI/Productization Coverage section below. "No UI surface impact" MUST NOT be checked together with another impact box; if a guarded file path changes for non-surface reasons, keep only "No UI surface impact" checked and explain the rationale below.
|
||||
|
||||
@ -65,6 +69,7 @@ ## UI/Productization Coverage *(mandatory when UI Surface Impact is not "No UI s
|
||||
- [ ] `docs/ui-ux-enterprise-audit/route-inventory.md`
|
||||
- [ ] `docs/ui-ux-enterprise-audit/design-coverage-matrix.md`
|
||||
- [ ] `docs/ui-ux-enterprise-audit/page-reports/...`
|
||||
- [ ] `docs/ui-ux-enterprise-audit/strategic-surfaces.md`
|
||||
- [ ] `docs/ui-ux-enterprise-audit/grouped-follow-up-candidates.md`
|
||||
- [ ] `docs/ui-ux-enterprise-audit/unresolved-pages.md`
|
||||
- [ ] `N/A - no reachable UI surface impact`
|
||||
@ -300,7 +305,7 @@ ## Requirements *(mandatory)*
|
||||
- record any allowed deviation, the consistency it must preserve, and its ownership/spread-control cost,
|
||||
- and make the reviewer focus explicit so parallel local UX paths do not appear silently.
|
||||
|
||||
**Constitution alignment (UI-COV-001):** Every spec MUST complete the UI Surface Impact block. If the feature adds, removes, renames, or materially changes any reachable UI surface, the spec MUST also complete UI/Productization Coverage and state:
|
||||
**Constitution alignment (UI-COV-001):** Every spec MUST complete the UI Surface Impact block. If the feature adds, removes, renames, or materially changes any reachable UI surface, including navigation entries, Filament panel/provider surfaces, Livewire surfaces, Blade views, forms, tables, modals, drawers, actions, status/evidence/review presentation, customer-facing views, or workspace/environment context presentation, the spec MUST also complete UI/Productization Coverage and state:
|
||||
- the affected route/page/surface,
|
||||
- page archetype,
|
||||
- design depth,
|
||||
@ -310,6 +315,7 @@ ## Requirements *(mandatory)*
|
||||
- dangerous-action review need,
|
||||
- and which `docs/ui-ux-enterprise-audit/` artifacts were updated or why the surface is unresolved/manual review.
|
||||
If there is no reachable UI impact, the spec MUST check exactly `No UI surface impact` and provide a short rationale.
|
||||
Coverage is proportional: small non-material UI diffs may use a checked no-impact rationale, normal domain pages may reuse existing patterns, and only strategic, customer-facing, dangerous-action-bearing, or materially new surfaces require screenshots or full page reports.
|
||||
|
||||
**Constitution alignment (DECIDE-AUD-001 / OPSURF-001):** If this feature changes a detail or status surface, the spec MUST describe:
|
||||
- how the surface separates customer-readable decision content, operator diagnostics, and support/raw evidence,
|
||||
|
||||
@ -64,10 +64,13 @@ # Tasks: [FEATURE NAME]
|
||||
**UI / Surface Guardrails**: If this feature adds or changes operator-facing surfaces or the workflow that governs them, tasks MUST include:
|
||||
- determining before implementation whether the spec adds, removes, renames, or materially changes any reachable UI surface,
|
||||
- checking exactly `No UI surface impact` in the spec with a short rationale when no reachable UI surface is affected,
|
||||
- classifying backend-only, docs-only, tooling-only, test-only, and non-material UI work with a no-impact rationale instead of creating unnecessary page reports,
|
||||
- treating navigation entries, navigation support code, and Filament panel/provider changes as reachable UI surface signals when they affect rendered product access or panel behavior,
|
||||
- updating `docs/ui-ux-enterprise-audit/route-inventory.md` and `docs/ui-ux-enterprise-audit/design-coverage-matrix.md` when reachable UI is added or materially changed,
|
||||
- assigning page archetype, design depth, repo-truth level, target pattern/mockup need, customer-safe review need, and dangerous-action review need for each affected surface,
|
||||
- linking the affected surface to an existing page report, domain pattern, component pattern, new page report, unresolved/manual-review entry, or grouped follow-up candidate,
|
||||
- adding screenshot/page-audit tasks when the new or changed surface is strategic, customer-facing, dangerous-action-bearing, or materially different from an existing pattern,
|
||||
- avoiding screenshot/page-audit tasks for tiny, non-material, or pattern-reusing UI changes when the spec documents why proportional coverage is sufficient,
|
||||
- ensuring no new or changed reachable UI surface remains unclassified before the feature is marked complete,
|
||||
- carrying forward the spec's native/custom classification, shared-family relevance, state-layer ownership, and exception need into implementation work without renaming the same decision,
|
||||
- classifying any triggered repository signals with one handling mode (`hard-stop-candidate`, `review-mandatory`, `exception-required`, or `report-only`),
|
||||
|
||||
@ -48,7 +48,32 @@ ## Ongoing Design Coverage Gate
|
||||
|
||||
After Spec 323, every UI-relevant feature must update this registry when it introduces or materially changes a reachable page, modal, drawer, form, table, action, or customer-facing state.
|
||||
|
||||
The mechanical PR guard is `scripts/check-ui-productization-coverage`. The PR fast-feedback workflow runs it against `origin/dev`: if guarded UI surface paths change under `apps/platform/app/Filament/`, `apps/platform/app/Support/Navigation/`, `apps/platform/app/Providers/Filament/`, `apps/platform/resources/views/`, `apps/platform/app/Livewire/`, or `apps/platform/routes/`, the PR must also update a UI coverage artifact or the active spec must contain a checked `- [x] No UI surface impact` decision.
|
||||
The mechanical PR guard is `scripts/check-ui-productization-coverage`. The PR fast-feedback workflow runs it against `origin/dev`: if guarded UI surface paths change under `apps/platform/app/Filament/`, `apps/platform/app/Support/Navigation/`, `apps/platform/app/Providers/Filament/`, `apps/platform/resources/views/`, `apps/platform/app/Livewire/`, or `apps/platform/routes/`, the PR must also update a real UI coverage artifact, or the active spec must contain a checked UI impact decision or a checked `- [x] No UI surface impact` decision with nearby non-empty rationale.
|
||||
|
||||
Standalone usage:
|
||||
|
||||
```bash
|
||||
bash scripts/check-ui-productization-coverage HEAD
|
||||
```
|
||||
|
||||
The guard checks committed changes against the supplied base ref and also considers staged, unstaged, and untracked local files where Git can report them. It is a silent-omission guard, not a design-review substitute.
|
||||
|
||||
Unchecked template checkboxes, unchecked spec checkboxes, headings, and generic phrases in templates/prompts/docs do not satisfy the guard when guarded UI files changed. Template and prompt changes remain allowed without coverage acknowledgment when no guarded UI file changed.
|
||||
|
||||
Guard regression cases can be run with:
|
||||
|
||||
```bash
|
||||
bash scripts/validate-ui-productization-coverage-guard
|
||||
```
|
||||
|
||||
Coverage remains proportional:
|
||||
|
||||
- Strategic, customer-facing, dangerous-action-bearing, or materially new surfaces usually need inventory and matrix updates, and may need a screenshot or page report.
|
||||
- Normal domain pages may reuse an existing page report, domain pattern, or grouped follow-up candidate.
|
||||
- Small non-material UI changes may use a checked no-impact rationale when rendered behavior and product meaning are unchanged.
|
||||
- Backend-only, docs-only, tooling-only, and test-only work should declare no UI surface impact in the active spec instead of creating page reports.
|
||||
|
||||
Navigation support code and Filament panel/provider files are guarded because they can change reachable UI without touching a page class. If such a path changes only for a non-surface reason, the active spec must explain that no-impact rationale.
|
||||
|
||||
Required close-out for new UI surfaces:
|
||||
|
||||
|
||||
@ -25,47 +25,148 @@ if ! git -C "${ROOT_DIR}" rev-parse --verify "${BASE_REF}^{commit}" >/dev/null 2
|
||||
fi
|
||||
|
||||
if BASE_COMMIT="$(git -C "${ROOT_DIR}" merge-base "${BASE_REF}" HEAD 2>/dev/null)"; then
|
||||
CHANGED_FILES="$(git -C "${ROOT_DIR}" diff --name-only --diff-filter=ACMRT "${BASE_COMMIT}...HEAD")"
|
||||
BASE_RANGE="${BASE_COMMIT}...HEAD"
|
||||
else
|
||||
CHANGED_FILES="$(git -C "${ROOT_DIR}" diff --name-only --diff-filter=ACMRT "${BASE_REF}..HEAD")"
|
||||
BASE_RANGE="${BASE_REF}..HEAD"
|
||||
fi
|
||||
|
||||
ui_changes=()
|
||||
coverage_changes=()
|
||||
spec_no_impact_files=()
|
||||
collect_changed_files() {
|
||||
git -C "${ROOT_DIR}" diff --name-only --diff-filter=ACDMRT "${BASE_RANGE}" 2>/dev/null || true
|
||||
git -C "${ROOT_DIR}" diff --cached --name-only --diff-filter=ACDMRT 2>/dev/null || true
|
||||
git -C "${ROOT_DIR}" diff --name-only --diff-filter=ACDMRT 2>/dev/null || true
|
||||
git -C "${ROOT_DIR}" ls-files --others --exclude-standard 2>/dev/null || true
|
||||
}
|
||||
|
||||
while IFS= read -r file; do
|
||||
[[ -z "${file}" ]] && continue
|
||||
|
||||
case "${file}" in
|
||||
apps/platform/app/Filament/*|apps/platform/app/Support/Navigation/*|apps/platform/app/Providers/Filament/*|apps/platform/resources/views/*|apps/platform/app/Livewire/*|apps/platform/routes/*)
|
||||
ui_changes+=("${file}")
|
||||
is_ui_surface_path() {
|
||||
case "$1" in
|
||||
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/*)
|
||||
return 0
|
||||
;;
|
||||
esac
|
||||
|
||||
case "${file}" in
|
||||
return 1
|
||||
}
|
||||
|
||||
is_coverage_artifact_path() {
|
||||
case "$1" in
|
||||
docs/ui-ux-enterprise-audit/route-inventory.md|\
|
||||
docs/ui-ux-enterprise-audit/design-coverage-matrix.md|\
|
||||
docs/ui-ux-enterprise-audit/grouped-follow-up-candidates.md|\
|
||||
docs/ui-ux-enterprise-audit/strategic-surfaces.md|\
|
||||
docs/ui-ux-enterprise-audit/unresolved-pages.md|\
|
||||
docs/ui-ux-enterprise-audit/page-reports/*)
|
||||
coverage_changes+=("${file}")
|
||||
return 0
|
||||
;;
|
||||
esac
|
||||
|
||||
if [[ "${file}" == specs/*/spec.md && -f "${ROOT_DIR}/${file}" ]] \
|
||||
&& grep -Eq '^- \[[xX]\] No UI surface impact[[:space:]]*$' "${ROOT_DIR}/${file}"; then
|
||||
spec_no_impact_files+=("${file}")
|
||||
return 1
|
||||
}
|
||||
|
||||
has_checked_no_impact_with_rationale() {
|
||||
local file="$1"
|
||||
|
||||
[[ -f "${ROOT_DIR}/${file}" ]] || return 1
|
||||
|
||||
awk '
|
||||
BEGIN {
|
||||
window = 0
|
||||
awaiting_block = 0
|
||||
found = 0
|
||||
}
|
||||
|
||||
/^- \[[xX]\] No UI surface impact[[:space:]]*$/ {
|
||||
window = 20
|
||||
awaiting_block = 0
|
||||
next
|
||||
}
|
||||
|
||||
window > 0 {
|
||||
if ($0 ~ /^[[:space:]]*([*-][[:space:]]*)?(\*\*)?(No-impact[[:space:]]+rationale|Rationale)(\*\*)?[[:space:]]*:/) {
|
||||
rationale_line = $0
|
||||
sub(/^[[:space:]]*([*-][[:space:]]*)?(\*\*)?(No-impact[[:space:]]+rationale|Rationale)(\*\*)?[[:space:]]*:[[:space:]]*/, "", rationale_line)
|
||||
|
||||
if (rationale_line ~ /[^[:space:]]/) {
|
||||
found = 1
|
||||
exit
|
||||
}
|
||||
|
||||
awaiting_block = 4
|
||||
window--
|
||||
next
|
||||
}
|
||||
|
||||
if (awaiting_block > 0) {
|
||||
if ($0 ~ /^[[:space:]]*$/) {
|
||||
awaiting_block--
|
||||
window--
|
||||
next
|
||||
}
|
||||
|
||||
if ($0 ~ /^- \[[ xX]\]/ || $0 ~ /^##/) {
|
||||
awaiting_block = 0
|
||||
window--
|
||||
next
|
||||
}
|
||||
|
||||
found = 1
|
||||
exit
|
||||
}
|
||||
|
||||
window--
|
||||
}
|
||||
|
||||
END {
|
||||
exit found ? 0 : 1
|
||||
}
|
||||
' "${ROOT_DIR}/${file}"
|
||||
}
|
||||
|
||||
has_checked_ui_impact() {
|
||||
local file="$1"
|
||||
|
||||
[[ -f "${ROOT_DIR}/${file}" ]] || return 1
|
||||
|
||||
grep -Eq '^- \[[xX]\] (Existing page changed|New page/route added|Navigation changed|Filament panel/provider surface changed|New modal/drawer/wizard/action added|New modal/drawer/wizard added|New modal/drawer/action added|New table/form/state added|Customer-facing surface changed|Dangerous action changed|Status/evidence/review presentation changed|Workspace/environment context presentation changed)[[:space:]]*$' "${ROOT_DIR}/${file}"
|
||||
}
|
||||
|
||||
ui_changes=()
|
||||
coverage_changes=()
|
||||
spec_no_impact_files=()
|
||||
spec_impact_files=()
|
||||
|
||||
while IFS= read -r file; do
|
||||
[[ -z "${file}" ]] && continue
|
||||
|
||||
if is_ui_surface_path "${file}"; then
|
||||
ui_changes+=("${file}")
|
||||
fi
|
||||
done <<< "${CHANGED_FILES}"
|
||||
|
||||
if is_coverage_artifact_path "${file}"; then
|
||||
coverage_changes+=("${file}")
|
||||
fi
|
||||
|
||||
if [[ "${file}" == specs/*/spec.md ]]; then
|
||||
if has_checked_ui_impact "${file}"; then
|
||||
spec_impact_files+=("${file}")
|
||||
fi
|
||||
|
||||
if has_checked_no_impact_with_rationale "${file}"; then
|
||||
spec_no_impact_files+=("${file}")
|
||||
fi
|
||||
fi
|
||||
done < <(collect_changed_files | sort -u)
|
||||
|
||||
if [[ ${#ui_changes[@]} -eq 0 ]]; then
|
||||
echo "UI/Productization Coverage guard passed: no guarded UI surface paths changed."
|
||||
exit 0
|
||||
fi
|
||||
|
||||
if [[ ${#coverage_changes[@]} -gt 0 || ${#spec_no_impact_files[@]} -gt 0 ]]; then
|
||||
if [[ ${#coverage_changes[@]} -gt 0 || ${#spec_impact_files[@]} -gt 0 || ${#spec_no_impact_files[@]} -gt 0 ]]; then
|
||||
echo "UI/Productization Coverage guard passed."
|
||||
echo "Guarded UI surface changes:"
|
||||
printf ' - %s\n' "${ui_changes[@]}"
|
||||
@ -75,8 +176,13 @@ if [[ ${#coverage_changes[@]} -gt 0 || ${#spec_no_impact_files[@]} -gt 0 ]]; the
|
||||
printf ' - %s\n' "${coverage_changes[@]}"
|
||||
fi
|
||||
|
||||
if [[ ${#spec_impact_files[@]} -gt 0 ]]; then
|
||||
echo "Checked UI impact decision found in:"
|
||||
printf ' - %s\n' "${spec_impact_files[@]}"
|
||||
fi
|
||||
|
||||
if [[ ${#spec_no_impact_files[@]} -gt 0 ]]; then
|
||||
echo "No-impact decision found in:"
|
||||
echo "Checked no-impact decision with nearby rationale found in:"
|
||||
printf ' - %s\n' "${spec_no_impact_files[@]}"
|
||||
fi
|
||||
|
||||
@ -86,15 +192,18 @@ fi
|
||||
cat >&2 <<'EOF'
|
||||
UI/Productization Coverage guard failed.
|
||||
|
||||
Guarded UI surface files changed, but no UI coverage artifact changed and no
|
||||
active spec contains:
|
||||
Guarded UI surface files changed, but no UI coverage artifact changed, no
|
||||
changed spec contains a checked UI impact decision, and no changed spec
|
||||
contains a checked no-impact decision with nearby rationale:
|
||||
|
||||
- [x] No UI surface impact
|
||||
|
||||
Required: update at least one relevant artifact under
|
||||
docs/ui-ux-enterprise-audit/ (route inventory, design coverage matrix, page
|
||||
reports, grouped follow-up candidates, strategic surfaces, or unresolved
|
||||
pages), or document the checked no-impact decision in the active spec.
|
||||
pages), document a checked proportional UI Surface Impact decision in the
|
||||
active spec, or document the checked no-impact decision with a nearby
|
||||
non-empty Rationale / No-impact rationale block in the active spec.
|
||||
|
||||
Guarded UI surface changes:
|
||||
EOF
|
||||
|
||||
189
scripts/validate-ui-productization-coverage-guard
Executable file
189
scripts/validate-ui-productization-coverage-guard
Executable file
@ -0,0 +1,189 @@
|
||||
#!/usr/bin/env bash
|
||||
|
||||
set -euo pipefail
|
||||
|
||||
SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
|
||||
ROOT_DIR="$(cd "${SCRIPT_DIR}/.." && pwd)"
|
||||
GUARD_SOURCE="${ROOT_DIR}/scripts/check-ui-productization-coverage"
|
||||
TEMP_ROOT="$(mktemp -d "${TMPDIR:-/tmp}/ui-productization-guard.XXXXXX")"
|
||||
FAILED=0
|
||||
|
||||
trap 'rm -rf "${TEMP_ROOT}"' EXIT
|
||||
|
||||
write_file() {
|
||||
local path="$1"
|
||||
local content="$2"
|
||||
|
||||
mkdir -p "$(dirname "${path}")"
|
||||
printf '%b' "${content}" > "${path}"
|
||||
}
|
||||
|
||||
append_file() {
|
||||
local path="$1"
|
||||
local content="$2"
|
||||
|
||||
mkdir -p "$(dirname "${path}")"
|
||||
printf '%b' "${content}" >> "${path}"
|
||||
}
|
||||
|
||||
setup_repo() {
|
||||
local case_id="$1"
|
||||
local repo="${TEMP_ROOT}/${case_id}"
|
||||
|
||||
mkdir -p "${repo}"
|
||||
git -C "${repo}" init -q
|
||||
git -C "${repo}" config user.email "guard-validation@example.test"
|
||||
git -C "${repo}" config user.name "Guard Validation"
|
||||
|
||||
mkdir -p "${repo}/scripts"
|
||||
cp "${GUARD_SOURCE}" "${repo}/scripts/check-ui-productization-coverage"
|
||||
chmod +x "${repo}/scripts/check-ui-productization-coverage"
|
||||
|
||||
write_file "${repo}/apps/platform/app/Filament/Dashboard.php" "<?php\n// baseline\n"
|
||||
write_file "${repo}/apps/platform/app/Support/Navigation/WorkspaceNavigation.php" "<?php\n// baseline\n"
|
||||
write_file "${repo}/apps/platform/app/Providers/Filament/AdminPanelProvider.php" "<?php\n// baseline\n"
|
||||
write_file "${repo}/apps/platform/app/Services/BackendOnlyService.php" "<?php\n// baseline\n"
|
||||
write_file "${repo}/docs/ui-ux-enterprise-audit/route-inventory.md" "# Route Inventory\n"
|
||||
write_file "${repo}/docs/process-note.md" "# Process Note\n"
|
||||
write_file "${repo}/.specify/templates/spec-template.md" "# Baseline Template\n"
|
||||
|
||||
git -C "${repo}" add .
|
||||
git -C "${repo}" commit -q -m "baseline"
|
||||
|
||||
printf '%s\n' "${repo}"
|
||||
}
|
||||
|
||||
touch_filament_page() {
|
||||
local repo="$1"
|
||||
|
||||
append_file "${repo}/apps/platform/app/Filament/Dashboard.php" "// guarded UI change\n"
|
||||
}
|
||||
|
||||
add_spec() {
|
||||
local repo="$1"
|
||||
local content="$2"
|
||||
|
||||
write_file "${repo}/specs/999-guard-validation/spec.md" "${content}"
|
||||
}
|
||||
|
||||
case_ui_unchecked_template_heading() {
|
||||
local repo="$1"
|
||||
|
||||
touch_filament_page "${repo}"
|
||||
append_file "${repo}/.specify/templates/spec-template.md" "## UI Surface Impact\n\n- [ ] No UI surface impact\n- [ ] Navigation changed\n"
|
||||
}
|
||||
|
||||
case_ui_unchecked_spec_checkbox() {
|
||||
local repo="$1"
|
||||
|
||||
touch_filament_page "${repo}"
|
||||
add_spec "${repo}" "# Spec\n\n## UI Surface Impact\n\n- [ ] Existing page changed\n\nRationale: unchecked should not pass.\n"
|
||||
}
|
||||
|
||||
case_ui_checked_impact_spec() {
|
||||
local repo="$1"
|
||||
|
||||
touch_filament_page "${repo}"
|
||||
add_spec "${repo}" "# Spec\n\n## UI Surface Impact\n\n- [x] Existing page changed\n"
|
||||
}
|
||||
|
||||
case_ui_checked_no_impact_with_rationale() {
|
||||
local repo="$1"
|
||||
|
||||
touch_filament_page "${repo}"
|
||||
add_spec "${repo}" "# Spec\n\n## UI Surface Impact\n\n- [x] No UI surface impact\n- [ ] Existing page changed\n\nRationale: guarded file changed for an internal refactor with identical rendered UI.\n"
|
||||
}
|
||||
|
||||
case_ui_checked_no_impact_without_rationale() {
|
||||
local repo="$1"
|
||||
|
||||
touch_filament_page "${repo}"
|
||||
add_spec "${repo}" "# Spec\n\n## UI Surface Impact\n\n- [x] No UI surface impact\n- [ ] Existing page changed\n"
|
||||
}
|
||||
|
||||
case_ui_real_audit_coverage_artifact() {
|
||||
local repo="$1"
|
||||
|
||||
touch_filament_page "${repo}"
|
||||
append_file "${repo}/docs/ui-ux-enterprise-audit/route-inventory.md" "\n| UI-999 | /admin/example | page | Example |\n"
|
||||
}
|
||||
|
||||
case_navigation_provider_without_acknowledgment() {
|
||||
local repo="$1"
|
||||
|
||||
append_file "${repo}/apps/platform/app/Support/Navigation/WorkspaceNavigation.php" "// navigation changed\n"
|
||||
append_file "${repo}/apps/platform/app/Providers/Filament/AdminPanelProvider.php" "// provider changed\n"
|
||||
}
|
||||
|
||||
case_navigation_provider_with_checked_acknowledgment() {
|
||||
local repo="$1"
|
||||
|
||||
append_file "${repo}/apps/platform/app/Support/Navigation/WorkspaceNavigation.php" "// navigation changed\n"
|
||||
append_file "${repo}/apps/platform/app/Providers/Filament/AdminPanelProvider.php" "// provider changed\n"
|
||||
add_spec "${repo}" "# Spec\n\n## UI Surface Impact\n\n- [x] Navigation changed\n- [x] Filament panel/provider surface changed\n"
|
||||
}
|
||||
|
||||
case_backend_only_diff() {
|
||||
local repo="$1"
|
||||
|
||||
append_file "${repo}/apps/platform/app/Services/BackendOnlyService.php" "// backend-only change\n"
|
||||
}
|
||||
|
||||
case_docs_only_diff() {
|
||||
local repo="$1"
|
||||
|
||||
append_file "${repo}/docs/process-note.md" "\n## UI Surface Impact\n\nPlain documentation phrase without guarded UI changes.\n"
|
||||
}
|
||||
|
||||
case_untracked_guarded_ui_without_acknowledgment() {
|
||||
local repo="$1"
|
||||
|
||||
write_file "${repo}/apps/platform/app/Filament/NewUntrackedPage.php" "<?php\n// untracked guarded UI file\n"
|
||||
}
|
||||
|
||||
run_case() {
|
||||
local case_id="$1"
|
||||
local expected="$2"
|
||||
local setup_function="$3"
|
||||
local repo
|
||||
local status
|
||||
local output_file="${TEMP_ROOT}/${case_id}.out"
|
||||
|
||||
repo="$(setup_repo "${case_id}")"
|
||||
"${setup_function}" "${repo}"
|
||||
|
||||
set +e
|
||||
(
|
||||
cd "${repo}"
|
||||
bash scripts/check-ui-productization-coverage HEAD
|
||||
) >"${output_file}" 2>&1
|
||||
status=$?
|
||||
set -e
|
||||
|
||||
if [[ "${expected}" == "pass" && ${status} -eq 0 ]] || [[ "${expected}" == "fail" && ${status} -ne 0 ]]; then
|
||||
printf 'PASS %s (%s)\n' "${case_id}" "${expected}"
|
||||
return
|
||||
fi
|
||||
|
||||
FAILED=1
|
||||
printf 'FAIL %s expected %s but exit status was %s\n' "${case_id}" "${expected}" "${status}" >&2
|
||||
sed 's/^/ /' "${output_file}" >&2
|
||||
}
|
||||
|
||||
run_case "ui_unchecked_template_heading_fails" "fail" "case_ui_unchecked_template_heading"
|
||||
run_case "ui_unchecked_spec_checkbox_fails" "fail" "case_ui_unchecked_spec_checkbox"
|
||||
run_case "ui_checked_impact_spec_passes" "pass" "case_ui_checked_impact_spec"
|
||||
run_case "ui_checked_no_impact_with_rationale_passes" "pass" "case_ui_checked_no_impact_with_rationale"
|
||||
run_case "ui_checked_no_impact_without_rationale_fails" "fail" "case_ui_checked_no_impact_without_rationale"
|
||||
run_case "ui_real_audit_coverage_artifact_passes" "pass" "case_ui_real_audit_coverage_artifact"
|
||||
run_case "navigation_provider_without_acknowledgment_fails" "fail" "case_navigation_provider_without_acknowledgment"
|
||||
run_case "navigation_provider_with_checked_acknowledgment_passes" "pass" "case_navigation_provider_with_checked_acknowledgment"
|
||||
run_case "backend_only_diff_passes" "pass" "case_backend_only_diff"
|
||||
run_case "docs_only_diff_passes" "pass" "case_docs_only_diff"
|
||||
run_case "untracked_guarded_ui_without_acknowledgment_fails" "fail" "case_untracked_guarded_ui_without_acknowledgment"
|
||||
|
||||
if [[ ${FAILED} -ne 0 ]]; then
|
||||
exit 1
|
||||
fi
|
||||
|
||||
printf 'All UI/Productization Coverage guard validation cases passed.\n'
|
||||
@ -0,0 +1,68 @@
|
||||
# Requirements Checklist - Spec 324
|
||||
|
||||
**Purpose**: Implementation acceptance checklist for Spec 324.
|
||||
**Created**: 2026-05-17
|
||||
**Feature**: `specs/324-ui-productization-coverage-guardrails/spec.md`
|
||||
|
||||
## Scope
|
||||
|
||||
- [x] Spec remains governance/tooling/docs only.
|
||||
- [x] No product runtime behavior is changed.
|
||||
- [x] No UI redesign is implemented.
|
||||
- [x] No business logic is changed.
|
||||
|
||||
## Constitution
|
||||
|
||||
- [x] UI/Productization principle is present.
|
||||
- [x] Constitution wording is concise.
|
||||
- [x] Process detail remains in templates/scripts, not Constitution.
|
||||
|
||||
## Templates
|
||||
|
||||
- [x] Spec template requires UI Surface Impact.
|
||||
- [x] Spec template supports no-impact rationale.
|
||||
- [x] UI-impacting specs must document coverage decisions.
|
||||
- [x] Navigation changes are explicitly represented.
|
||||
- [x] Filament panel/provider surface changes are explicitly represented.
|
||||
- [x] Plan/tasks/checklist templates include guardrail checks.
|
||||
|
||||
## Agent Prompts
|
||||
|
||||
- [x] Prompts require UI impact evaluation before implementation.
|
||||
- [x] Prompts require coverage decision before completion.
|
||||
- [x] Prompts describe proportional coverage.
|
||||
- [x] Prompts include navigation/provider surface awareness.
|
||||
|
||||
## Script
|
||||
|
||||
- [x] Script exists.
|
||||
- [x] Script is executable.
|
||||
- [x] UI-relevant path triggers are not too broad.
|
||||
- [x] Script detects Filament paths.
|
||||
- [x] Script detects Blade view paths.
|
||||
- [x] Script detects Livewire paths.
|
||||
- [x] Script detects routes.
|
||||
- [x] Script detects `apps/platform/app/Support/Navigation/`.
|
||||
- [x] Script detects `apps/platform/app/Providers/Filament/`.
|
||||
- [x] Script does not trigger on all of `apps/platform/app/Support/`.
|
||||
- [x] Script does not trigger on all of `apps/platform/app/Providers/`.
|
||||
- [x] Coverage acknowledgment detection works.
|
||||
- [x] Unchecked template headings and generic prompt/doc phrases do not satisfy guarded UI changes.
|
||||
- [x] Failure message is clear.
|
||||
- [x] No-impact rationale is supported.
|
||||
- [x] Script avoids external dependencies.
|
||||
|
||||
## Validation
|
||||
|
||||
- [x] `bash -n scripts/check-ui-productization-coverage` was run.
|
||||
- [x] `bash -n scripts/validate-ui-productization-coverage-guard` was run.
|
||||
- [x] `bash scripts/validate-ui-productization-coverage-guard` was run.
|
||||
- [x] `bash scripts/check-ui-productization-coverage HEAD` was run.
|
||||
- [x] `git diff --check` was run.
|
||||
- [x] Full suite was intentionally not run.
|
||||
|
||||
## Preparation Notes
|
||||
|
||||
- This checklist is intentionally left as an implementation acceptance checklist, not a completed preparation-quality checklist.
|
||||
- The preparation pass found no open question that blocks implementation.
|
||||
- The later implementation pass should check these items off as the guardrail work is completed and validated.
|
||||
287
specs/324-ui-productization-coverage-guardrails/plan.md
Normal file
287
specs/324-ui-productization-coverage-guardrails/plan.md
Normal file
@ -0,0 +1,287 @@
|
||||
# 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.
|
||||
441
specs/324-ui-productization-coverage-guardrails/spec.md
Normal file
441
specs/324-ui-productization-coverage-guardrails/spec.md
Normal file
@ -0,0 +1,441 @@
|
||||
# Feature Specification: UI Productization Coverage Guardrails
|
||||
|
||||
**Feature Branch**: `324-ui-productization-coverage-guardrails`
|
||||
**Created**: 2026-05-17
|
||||
**Status**: Draft
|
||||
**Input**: User supplied full Spec 324 draft requiring the Spec 323 UI/Productization audit baseline to become a proportional guardrail, with explicit Navigation and Filament provider surface coverage.
|
||||
**Type**: Governance / Spec-Kit / tooling guardrail
|
||||
**Depends on**: Spec 323 - Tenantial Enterprise UI Audit Foundation
|
||||
**Runtime Posture**: No product runtime implementation. Governance, tooling, Spec Kit templates/prompts, and documentation only.
|
||||
|
||||
## Candidate Source And Guardrail Result
|
||||
|
||||
**Candidate source**: Direct user-provided manual promotion for Spec 324. The active auto-prep queue in `docs/product/spec-candidates.md` says no safe automatic next-best-prep target remains, so this package proceeds only because the user supplied an explicit complete candidate.
|
||||
|
||||
**Completed-spec guardrail**: No existing `specs/324-*` package or `324-*` branch was present before generation. Spec 323 is completed historical context and already introduced the first UI/Productization Coverage baseline. This spec does not rewrite Spec 323; it narrows the follow-up to durable proportional guardrail hardening, especially explicit Navigation and Filament provider/panel surface handling.
|
||||
|
||||
**Close alternatives deferred**:
|
||||
|
||||
- `325-tenantial-design-system-and-state-patterns`: shared component and state cleanup rules after guardrails are enforceable.
|
||||
- `326-tenantial-domain-pattern-coverage-pass`: grouped domain pattern coverage after route/page archetypes are stabilized.
|
||||
- `327-tenantial-enterprise-ui-implementation-wave-1`: runtime UI implementation after design decisions and mockups/patterns exist.
|
||||
|
||||
## Spec Candidate Check
|
||||
|
||||
- **Problem**: Spec 323 created a UI/Productization audit baseline, but future specs can still silently change reachable UI surfaces unless the UI impact question, proportional coverage decision, and mechanical guard are durable and explicit across templates, prompts, docs, and scripts.
|
||||
- **Today's failure**: A feature can change Filament pages, routes, Blade views, Livewire components, navigation support code, or Filament panel/provider behavior without clearly acknowledging the UI/Productization impact. Navigation and Filament provider/panel surfaces are especially easy to miss because they are not always page files.
|
||||
- **User-visible improvement**: Future feature work will make UI surface impact explicit before implementation and before completion, so reachable product surfaces do not become unclassified UI debt.
|
||||
- **Smallest enterprise-capable version**: Update the Constitution/templates/prompts/checklists and the lightweight diff guard so UI-relevant file changes require a coverage acknowledgment while still allowing backend-only and non-material UI work to proceed with a short no-impact rationale.
|
||||
- **Explicit non-goals**: No product UI redesign, no Filament resource/page behavior changes, no route behavior changes, no authorization changes, no migrations, no runtime tests, no business logic, no forced screenshot or page report for every tiny UI change, and no heavy design approval workflow.
|
||||
- **Permanent complexity imported**: A maintained governance rule, template sections, prompt instructions, a small shell guard, and checklist items. No runtime entity, database table, service layer, enum/status family, or UI framework is introduced.
|
||||
- **Why now**: Spec 323 made the UI audit baseline visible. The next risk is baseline decay as new features land, especially through navigation and Filament provider/panel surface changes.
|
||||
- **Why not local**: A note in one spec or README would not prevent future silent omissions. The rule must live in Spec Kit templates/prompts and the mechanical guard.
|
||||
- **Approval class**: Core Enterprise
|
||||
- **Red flags triggered**: Governance guardrail and process taxonomy. Defense: the guardrail is proportional, docs/tooling-only, and explicitly avoids runtime semantic machinery.
|
||||
- **Score**: Nutzen 2 | Dringlichkeit 2 | Scope 2 | Komplexitaet 1 | Produktnaehe 2 | Wiederverwendung 2 | **Gesamt: 11/12**
|
||||
- **Decision**: approve
|
||||
|
||||
## Spec Scope Fields
|
||||
|
||||
- **Scope**: workspace
|
||||
- **Primary Routes**: N/A - no product routes are changed.
|
||||
- **Data Ownership**: N/A - no workspace-owned or tenant-owned runtime data changes.
|
||||
- **RBAC**: N/A - no runtime authorization behavior changes.
|
||||
|
||||
## UI Surface Impact
|
||||
|
||||
Does this spec add, remove, rename, or materially change any reachable UI surface?
|
||||
|
||||
- [x] No UI surface impact
|
||||
- [ ] Existing page changed
|
||||
- [ ] New page/route added
|
||||
- [ ] Navigation changed
|
||||
- [ ] Filament panel/provider surface changed
|
||||
- [ ] New modal/drawer/wizard added
|
||||
- [ ] New table/form/state added
|
||||
- [ ] Customer-facing surface changed
|
||||
- [ ] Dangerous action changed
|
||||
- [ ] Status/evidence/review presentation changed
|
||||
- [ ] Workspace/environment context presentation changed
|
||||
|
||||
**No-impact rationale**: Spec 324 changes governance, Spec Kit templates/prompts, audit documentation, and a local shell guard. It must reference product UI paths as guard inputs, but it must not change reachable product UI behavior, routes, navigation behavior, Filament resources/pages, Livewire components, Blade views, authorization, or business logic.
|
||||
|
||||
## UI/Productization Coverage
|
||||
|
||||
N/A - no reachable product UI surface impact.
|
||||
|
||||
- **Route/page/surface**: N/A
|
||||
- **Current or new page archetype**: N/A
|
||||
- **Design depth**: Internal/Hidden governance tooling
|
||||
- **Repo-truth level**: repo-verified
|
||||
- **Existing pattern reused**: Spec 323 UI audit foundation and current `scripts/check-ui-productization-coverage`
|
||||
- **New pattern required**: none
|
||||
- **Screenshot required**: no
|
||||
- **Page audit required**: no
|
||||
- **Customer-safe review required**: no product UI content changes
|
||||
- **Dangerous-action review required**: no runtime actions
|
||||
- **Coverage files updated or explicitly not needed**:
|
||||
- [ ] `docs/ui-ux-enterprise-audit/route-inventory.md`
|
||||
- [ ] `docs/ui-ux-enterprise-audit/design-coverage-matrix.md`
|
||||
- [ ] `docs/ui-ux-enterprise-audit/page-reports/...`
|
||||
- [ ] `docs/ui-ux-enterprise-audit/strategic-surfaces.md`
|
||||
- [ ] `docs/ui-ux-enterprise-audit/grouped-follow-up-candidates.md`
|
||||
- [ ] `docs/ui-ux-enterprise-audit/unresolved-pages.md`
|
||||
- [x] Not applicable, no reachable product UI surface impact
|
||||
|
||||
## Summary
|
||||
|
||||
Spec 324 turns the Spec 323 UI/Productization audit baseline into a durable delivery guardrail.
|
||||
|
||||
After this spec, every future feature that adds, removes, renames, or materially changes a reachable UI surface must explicitly declare UI Surface Impact and either update the UI/Productization coverage artifacts or document why no update is required.
|
||||
|
||||
The guardrail must remain proportional:
|
||||
|
||||
- strategic new surfaces require deeper coverage
|
||||
- normal domain pages can reuse patterns
|
||||
- small existing surface changes can use coverage acknowledgment
|
||||
- backend-only, docs-only, tooling-only, and non-material UI work can declare no UI impact with a short rationale
|
||||
- not every UI change requires a screenshot or full page report
|
||||
|
||||
## Product Context
|
||||
|
||||
Tenantial/TenantPilot is becoming a sellable Enterprise SaaS governance platform, not a raw Microsoft admin mirror or generic Filament admin tool.
|
||||
|
||||
The product direction is:
|
||||
|
||||
- decision-first
|
||||
- evidence-first
|
||||
- workspace-first
|
||||
- customer-safe where applicable
|
||||
- capability-aware
|
||||
- audit-ready
|
||||
- calm enterprise UX
|
||||
- progressive disclosure for technical depth
|
||||
- no misleading status
|
||||
- no green success state unless verified
|
||||
|
||||
Spec 323 created visibility into current UI/productization coverage. Spec 324 ensures future feature work cannot silently create unclassified UI debt.
|
||||
|
||||
## Problem Statement
|
||||
|
||||
Without a durable guardrail, the Spec 323 audit can become stale.
|
||||
|
||||
Future specs may introduce or change:
|
||||
|
||||
- Filament pages and resources
|
||||
- Livewire components
|
||||
- Blade views
|
||||
- routes
|
||||
- navigation entries and navigation support code
|
||||
- Filament panel/provider behavior
|
||||
- modals, drawers, wizard steps
|
||||
- table actions and bulk actions
|
||||
- dangerous actions
|
||||
- customer-facing surfaces
|
||||
- evidence/review/export surfaces
|
||||
- status or context presentation
|
||||
|
||||
without updating the UI/Productization coverage baseline.
|
||||
|
||||
That would recreate the same problem Spec 323 solved: reachable product UI surfaces without explicit productization decisions.
|
||||
|
||||
## Objective
|
||||
|
||||
Implement a lightweight but durable UI/Productization Coverage Guardrail.
|
||||
|
||||
After this spec:
|
||||
|
||||
1. Future specs must explicitly declare UI Surface Impact.
|
||||
2. UI-impacting specs must document the required productization coverage decision.
|
||||
3. Backend-only, docs-only, tooling-only, or non-material UI changes can declare no UI impact with a short rationale.
|
||||
4. Agent prompts require UI impact evaluation before implementation and before completion.
|
||||
5. A mechanical guard detects UI-relevant diffs and requires coverage acknowledgment.
|
||||
6. Navigation and Filament provider surface changes are included in the mechanical guard and explicitly represented in templates/prompts.
|
||||
7. The guard remains proportional and does not require a full page report for every tiny UI change.
|
||||
8. No product runtime behavior is changed.
|
||||
|
||||
## Non-Goals
|
||||
|
||||
This spec must not:
|
||||
|
||||
- redesign any product page
|
||||
- implement Spec 323 audit recommendations
|
||||
- create target mockups
|
||||
- modify product UI behavior
|
||||
- modify Filament resources/pages for product functionality
|
||||
- modify Livewire runtime behavior
|
||||
- modify application routes
|
||||
- modify authorization logic
|
||||
- modify business logic
|
||||
- modify database schema
|
||||
- modify runtime tests
|
||||
- force every UI change to create a screenshot
|
||||
- force every UI change to create a full page report
|
||||
- block legitimate backend-only work
|
||||
- introduce heavy manual design approval workflows
|
||||
- create compatibility layers
|
||||
- create new product capabilities
|
||||
|
||||
## Core Principle
|
||||
|
||||
Every reachable product UI surface must have an explicit productization coverage decision.
|
||||
|
||||
A feature is not complete if it introduces, removes, renames, or materially changes a reachable UI surface without classifying or acknowledging the surface by:
|
||||
|
||||
- UI impact
|
||||
- page archetype where applicable
|
||||
- design depth
|
||||
- repo-truth level
|
||||
- target pattern or mockup requirement
|
||||
- customer-safe implications where applicable
|
||||
- dangerous-action handling where applicable
|
||||
|
||||
No reachable product surface may remain unclassified, undesigned, or without a recommended target state.
|
||||
|
||||
## Definitions
|
||||
|
||||
### UI Surface
|
||||
|
||||
A UI surface is any user-visible product interaction point, including pages, routes, navigation items, sidebar entries, topbar/context elements, dashboard cards, tables, forms, modals, drawers, wizard steps, actions, bulk actions, dangerous action confirmations, empty/loading/error states, notification surfaces, customer-facing views, operator workflow surfaces, audit/evidence export surfaces, Filament panel surfaces, and Filament render hook surfaces.
|
||||
|
||||
### Reachable UI Surface
|
||||
|
||||
A UI surface is reachable if it can be accessed through navigation, direct route, redirect, deep link, action button, modal/drawer trigger, resource action, workflow step, customer link, operator link, Filament resource/page registration, or panel provider registration.
|
||||
|
||||
A permission-protected or guarded page can still be a reachable UI surface.
|
||||
|
||||
### Material UI Change
|
||||
|
||||
A material UI change includes new pages, removed pages, renamed pages, new routes, changed routes, new navigation items, changed navigation grouping, changed sidebar/topbar behavior, changed primary actions, changed dangerous actions, new modals/drawers/wizards, changed customer-facing copy, changed status presentation, changed evidence/review/export presentation, changed workspace/environment context presentation, changed table/form/state that affects product understanding, changed Filament provider/panel behavior that affects reachable UI, and changed navigation support code that affects reachable UI.
|
||||
|
||||
### Non-Material UI Change
|
||||
|
||||
Examples that usually do not require a full coverage update:
|
||||
|
||||
- typo fix
|
||||
- minor copy correction without meaning change
|
||||
- pure CSS spacing fix
|
||||
- icon alignment
|
||||
- test-only selector adjustment
|
||||
- internal refactor with identical rendered UI
|
||||
- backend-only service change
|
||||
- job/command change with no UI surface effect
|
||||
|
||||
Even for non-material UI changes, the spec must explicitly state why no UI coverage update is needed.
|
||||
|
||||
## Guardrail Model
|
||||
|
||||
Spec 324 uses four enforcement layers:
|
||||
|
||||
1. Constitution principle
|
||||
2. Spec/plan/tasks/checklist template requirements
|
||||
3. Agent implementation prompt requirements
|
||||
4. Lightweight mechanical diff guard
|
||||
|
||||
### Layer 1 - Constitution
|
||||
|
||||
The Constitution stores the permanent principle. It must stay concise and principle-level.
|
||||
|
||||
### Layer 2 - Spec Templates
|
||||
|
||||
Templates force every future feature spec to answer:
|
||||
|
||||
```text
|
||||
Does this spec add, remove, rename, or materially change any reachable UI surface?
|
||||
```
|
||||
|
||||
The spec template must explicitly include Navigation and Filament panel/provider surface changes as selectable impact types.
|
||||
|
||||
### Layer 3 - Agent Prompts
|
||||
|
||||
Implementation prompts require the agent to evaluate UI impact before implementation and before marking work complete.
|
||||
|
||||
### Layer 4 - Mechanical Diff Guard
|
||||
|
||||
A lightweight script detects UI-relevant file changes and verifies that the diff contains a coverage acknowledgment.
|
||||
|
||||
The script is not a design reviewer. It only prevents silent omission.
|
||||
|
||||
## Current Repo Findings
|
||||
|
||||
The preparation pass found these relevant repo facts:
|
||||
|
||||
- `.specify/memory/constitution.md` already contains UI-COV-001 from Spec 323.
|
||||
- `scripts/check-ui-productization-coverage` already exists and already includes targeted triggers for `apps/platform/app/Support/Navigation/` and `apps/platform/app/Providers/Filament/`.
|
||||
- `.gitea/workflows/test-pr-fast-feedback.yml` already runs the guard.
|
||||
- `.specify/templates/spec-template.md` contains a UI Surface Impact section, but its checkbox list does not yet explicitly include Navigation changed, Filament panel/provider surface changed, status/evidence/review presentation changed, or workspace/environment context presentation changed.
|
||||
- `.codex/prompts/speckit.implement.md` and `.github/agents/speckit.implement.agent.md` include UI/Productization Coverage guardrail language, but should explicitly name Filament panel/provider surfaces and proportional coverage expectations.
|
||||
- Before Spec 324 implementation, the guard only accepted changed audit files or a checked no-impact decision. Spec 324 should make coverage acknowledgment detection proportional but concrete: guarded UI changes pass only with a checked spec impact decision, a checked no-impact decision with nearby rationale, or a real UI audit coverage artifact update. Generic template, prompt, or documentation phrases must not satisfy the guard when guarded UI files changed.
|
||||
|
||||
## Functional Requirements
|
||||
|
||||
- **FR-324-001**: The Constitution MUST contain a concise UI/Productization Coverage principle and MUST NOT include long script implementation details.
|
||||
- **FR-324-002**: The spec template MUST require every future spec to answer whether it adds, removes, renames, or materially changes a reachable UI surface.
|
||||
- **FR-324-003**: The spec template MUST include explicit UI Surface Impact options for `Navigation changed` and `Filament panel/provider surface changed`.
|
||||
- **FR-324-004**: The spec template MUST include proportional UI/Productization Coverage fields for route/page, new or existing surface, page archetype, design depth, repo-truth level, pattern reuse, screenshot need, page report need, customer-safe review, dangerous-action review, and coverage artifact updates.
|
||||
- **FR-324-005**: The plan template MUST require a UI/Productization Guardrail Check before implementation and MUST include no-impact rationale handling for backend-only, docs-only, tooling-only, test-only, or non-material UI work.
|
||||
- **FR-324-006**: The tasks template MUST include proportional UI coverage tasks for reachable UI changes and a no-impact task for specs with no UI surface impact.
|
||||
- **FR-324-007**: The checklist template MUST include UI/Productization Coverage checks, including Navigation and Filament provider/panel surface changes.
|
||||
- **FR-324-008**: Agent implementation prompts MUST require UI impact evaluation before code changes and before completion.
|
||||
- **FR-324-009**: Agent implementation prompts MUST explicitly include pages, routes, navigation entries, Filament panel/provider surfaces, Livewire surfaces, Blade views, tables, forms, modals, drawers, actions, status states, customer-facing views, and evidence/review/export surfaces.
|
||||
- **FR-324-010**: Agent implementation prompts MUST state proportionality: not every small UI change needs a page report or screenshot.
|
||||
- **FR-324-011**: `scripts/check-ui-productization-coverage` MUST exist and be executable.
|
||||
- **FR-324-012**: The guard MUST treat exactly these required product paths as UI-relevant: `apps/platform/app/Filament/`, `apps/platform/resources/views/`, `apps/platform/app/Livewire/`, `apps/platform/routes/`, `apps/platform/app/Support/Navigation/`, and `apps/platform/app/Providers/Filament/`.
|
||||
- **FR-324-013**: The guard MUST NOT broaden UI-relevant provider/support matching to all of `apps/platform/app/Support/` or all of `apps/platform/app/Providers/`.
|
||||
- **FR-324-014**: The guard MUST evaluate staged and unstaged changes where feasible and MAY accept a base ref argument such as `HEAD`.
|
||||
- **FR-324-015**: The guard MUST pass when no UI-relevant files changed.
|
||||
- **FR-324-016**: The guard MUST pass when UI-relevant files changed and coverage acknowledgment exists through a checked UI Surface Impact item in a changed `specs/*/spec.md`, a checked no-impact declaration with nearby non-empty rationale in a changed `specs/*/spec.md`, or a real UI audit coverage artifact update.
|
||||
- **FR-324-017**: The guard MUST fail with a clear message when UI-relevant files changed and no coverage acknowledgment exists.
|
||||
- **FR-324-018**: The guard MUST support checked no-impact rationale through the active spec and MUST fail checked no-impact declarations that have no nearby non-empty rationale block.
|
||||
- **FR-324-019**: The guard MUST avoid external dependencies and work in local shell and CI/Gitea environments.
|
||||
- **FR-324-020**: The README or guardrail documentation under `docs/ui-ux-enterprise-audit/` MUST document standalone usage and proportional expectations.
|
||||
- **FR-324-021**: Spec 324 MUST include `spec.md`, `plan.md`, `tasks.md`, and `checklists/requirements.md`.
|
||||
- **FR-324-022**: Validation MUST include `bash -n scripts/check-ui-productization-coverage`, `bash scripts/check-ui-productization-coverage HEAD`, and `git diff --check`.
|
||||
- **FR-324-023**: Full runtime test suite execution MUST be explicitly documented as not run unless runtime product behavior changes, which is out of scope.
|
||||
- **FR-324-024**: Final implementation diff MUST 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/`, or `apps/platform/tests/`.
|
||||
- **FR-324-025**: The guard MUST NOT treat unchecked template checkboxes, unchecked spec checkboxes, headings, or generic phrases in templates/prompts/docs as valid coverage acknowledgment when guarded UI files changed.
|
||||
|
||||
## Non-Functional Requirements
|
||||
|
||||
- **NFR-324-001**: The guardrail must remain proportional and low-friction.
|
||||
- **NFR-324-002**: The guard must be deterministic shell tooling without external runtime dependencies.
|
||||
- **NFR-324-003**: Documentation must distinguish coverage acknowledgment from a full page report or screenshot requirement.
|
||||
- **NFR-324-004**: Any implementation must preserve Spec 323 audit artifacts and completed-spec history.
|
||||
- **NFR-324-005**: No product runtime behavior, route behavior, UI behavior, authorization behavior, or database schema may change.
|
||||
|
||||
## User Scenarios And Testing
|
||||
|
||||
### User Story 1 - Future UI Work Cannot Skip Coverage (Priority: P1)
|
||||
|
||||
As a maintainer reviewing a future UI-changing feature, I want the spec and guard to require a UI Surface Impact decision so the feature cannot silently add unclassified UI debt.
|
||||
|
||||
**Independent Test**: Change a UI-relevant file without docs/spec acknowledgment and verify the guard fails with the required message.
|
||||
|
||||
**Acceptance Scenarios**:
|
||||
|
||||
1. **Given** a staged or unstaged change under `apps/platform/app/Filament/`, **When** no coverage acknowledgment exists, **Then** the guard fails.
|
||||
2. **Given** the same UI-relevant change and a spec containing UI Surface Impact and UI/Productization Coverage, **When** the guard runs, **Then** the guard passes.
|
||||
|
||||
### User Story 2 - Non-Material Or Backend Work Can Proceed (Priority: P1)
|
||||
|
||||
As a maintainer of backend or non-material UI work, I want to declare no UI impact with rationale so the guard does not force unnecessary audit artifacts.
|
||||
|
||||
**Independent Test**: Change a non-UI backend file and verify the guard passes; change a guarded UI path with a checked no-impact rationale and verify the guard passes.
|
||||
|
||||
**Acceptance Scenarios**:
|
||||
|
||||
1. **Given** only backend service files changed, **When** the guard runs, **Then** the guard passes without requiring coverage docs.
|
||||
2. **Given** a guarded UI file changed for non-material reasons and the active spec marks `No UI surface impact` with rationale, **When** the guard runs, **Then** the guard passes.
|
||||
|
||||
### User Story 3 - Navigation And Provider Surfaces Are Not Missed (Priority: P1)
|
||||
|
||||
As a reviewer, I want navigation support code and Filament provider/panel changes to be explicitly considered because they can materially change reachable UI without changing a page file.
|
||||
|
||||
**Independent Test**: Change `apps/platform/app/Support/Navigation/...` or `apps/platform/app/Providers/Filament/...` without acknowledgment and verify the guard fails; add coverage acknowledgment and verify it passes.
|
||||
|
||||
**Acceptance Scenarios**:
|
||||
|
||||
1. **Given** a navigation support path changed without acknowledgment, **When** the guard runs, **Then** the guard fails.
|
||||
2. **Given** a Filament provider path changed without acknowledgment, **When** the guard runs, **Then** the guard fails.
|
||||
3. **Given** either path changed with `Navigation changed` or `Filament panel/provider surface changed` acknowledged in the active spec, **When** the guard runs, **Then** the guard passes.
|
||||
|
||||
## Edge Cases
|
||||
|
||||
- UI-relevant file path changed only for comment or selector cleanup.
|
||||
- A spec updates `.specify/templates/` but no product runtime UI surface.
|
||||
- Navigation helper changed for an internal refactor with identical rendered UI.
|
||||
- Filament provider changed for asset/provider registration with no reachable UI behavior change.
|
||||
- Coverage artifacts change but no UI-relevant files change.
|
||||
- Base ref is unavailable in CI.
|
||||
- Both staged and unstaged diffs exist.
|
||||
- No Git base ref is supplied.
|
||||
|
||||
## Proportionality Review
|
||||
|
||||
- **New source of truth?**: No runtime source of truth. The guardrail updates governance truth only.
|
||||
- **New persisted entity/table/artifact?**: No runtime persistence. Spec Kit and docs artifacts only.
|
||||
- **New abstraction?**: No application abstraction. A shell guard exists as repository tooling.
|
||||
- **New enum/state/reason family?**: No runtime state family.
|
||||
- **New cross-domain UI framework/taxonomy?**: No runtime UI framework. The spec refines docs-only UI coverage categories introduced by Spec 323.
|
||||
- **Current operator problem**: Future features can degrade product trust by adding or changing reachable UI without a productization decision.
|
||||
- **Existing structure is insufficient because**: Spec 323 created the baseline, but template/prompt/script enforcement must explicitly cover Navigation and Filament provider/panel surfaces and no-impact proportionality.
|
||||
- **Narrowest correct implementation**: Update existing governance surfaces and one lightweight shell guard; do not create a new service, package, CI framework, or runtime layer.
|
||||
- **Ownership cost**: Future maintainers must keep guard path patterns and acknowledgment phrases aligned with the UI audit docs.
|
||||
- **Alternative intentionally rejected**: Heavy design approval gates and full screenshot/page-report requirements for every UI change.
|
||||
- **Release truth**: Current-release governance hardening.
|
||||
|
||||
## Testing / Lane / Runtime Impact
|
||||
|
||||
- **Test purpose / classification**: N/A for runtime; shell/docs guard validation only.
|
||||
- **Validation lane(s)**: docs/tooling validation; PR fast-feedback guard where integrated.
|
||||
- **Why this classification and these lanes are sufficient**: The change is governance/tooling/docs-only and does not alter Laravel runtime behavior.
|
||||
- **New or expanded test families**: none.
|
||||
- **Fixture / helper cost impact**: none.
|
||||
- **Heavy-family visibility / justification**: none.
|
||||
- **Special surface test profile**: N/A.
|
||||
- **Reviewer handoff**: Confirm no runtime files changed, guard script syntax passes, guard behavior is validated with representative cases, and `git diff --check` passes.
|
||||
- **Budget / baseline / trend impact**: none.
|
||||
- **Escalation needed**: none.
|
||||
- **Planned validation 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`
|
||||
|
||||
## Acceptance Criteria
|
||||
|
||||
Spec 324 is complete when:
|
||||
|
||||
1. Constitution contains a concise UI/Productization Coverage principle.
|
||||
2. Spec template requires UI Surface Impact declaration.
|
||||
3. UI-impacting specs have a required UI/Productization Coverage section.
|
||||
4. No-impact specs require a rationale.
|
||||
5. Navigation changes are explicitly represented in templates/prompts.
|
||||
6. Filament panel/provider surface changes are explicitly represented in templates/prompts.
|
||||
7. Plan/tasks/checklist templates include proportional UI coverage guardrails.
|
||||
8. Agent prompts require UI impact evaluation before implementation and completion.
|
||||
9. `scripts/check-ui-productization-coverage` exists.
|
||||
10. The script is executable.
|
||||
11. The script detects UI-relevant product paths.
|
||||
12. The script detects `apps/platform/app/Support/Navigation/`.
|
||||
13. The script detects `apps/platform/app/Providers/Filament/`.
|
||||
14. The script does not broadly trigger on all Support/Provider paths.
|
||||
15. The script detects coverage acknowledgment.
|
||||
16. The script rejects unchecked template headings, unchecked spec checkboxes, and generic template/prompt/doc phrases when UI-relevant files changed.
|
||||
17. The script fails clearly when UI-relevant files change without concrete coverage acknowledgment.
|
||||
18. The script passes when no UI-relevant files changed.
|
||||
19. The script passes when UI-relevant files changed and coverage is acknowledged.
|
||||
20. The script supports no-impact rationale.
|
||||
21. The script does not require full page reports or screenshots for tiny UI changes.
|
||||
22. No product runtime behavior is changed.
|
||||
23. `bash -n scripts/check-ui-productization-coverage` passes.
|
||||
24. `bash scripts/validate-ui-productization-coverage-guard` passes.
|
||||
25. `bash scripts/check-ui-productization-coverage HEAD` passes.
|
||||
26. `git diff --check` passes.
|
||||
27. Full suite is explicitly documented as not run.
|
||||
28. Spec 324 tasks and checklist are complete.
|
||||
|
||||
## Definition Of Done
|
||||
|
||||
- Guardrail principle exists or is verified.
|
||||
- Templates force the UI impact question.
|
||||
- Prompts guide agents correctly.
|
||||
- Mechanical guard exists and is validated.
|
||||
- Navigation/provider surface paths are covered mechanically and explicitly in future-spec artifacts.
|
||||
- Guard remains proportional.
|
||||
- Guard supports backend-only and non-material UI changes.
|
||||
- No runtime product behavior changed.
|
||||
- Validation commands are documented.
|
||||
- Future specs cannot silently add unclassified UI surfaces.
|
||||
|
||||
## Assumptions
|
||||
|
||||
- Spec 323 remains the baseline UI audit package and is not rewritten.
|
||||
- The existing Gitea fast-feedback workflow remains the integration point for the guard.
|
||||
- Bash is available in local and CI environments.
|
||||
- No new toolchain is needed.
|
||||
|
||||
## Open Questions
|
||||
|
||||
None block implementation. During implementation, if a template or prompt file named in this spec is absent, document the missing file instead of creating unrelated structures blindly.
|
||||
153
specs/324-ui-productization-coverage-guardrails/tasks.md
Normal file
153
specs/324-ui-productization-coverage-guardrails/tasks.md
Normal file
@ -0,0 +1,153 @@
|
||||
# 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.
|
||||
Loading…
Reference in New Issue
Block a user