Tasks: Spec 395 - Product Surface Contract Enforcement and Surface Reduction Gate v1

Input: specs/395-product-surface-gate/spec.md, plan.md, checklists/requirements.md, user-provided Spec 395 candidate, Specs 370, 375, and 377 artifacts, and current repo workflow/test conventions.

Tests: Required for later implementation because this spec changes repository workflow enforcement and guard tests. The default slice is docs/templates/tests only and does not require browser proof unless runtime UI is touched after updating the spec and plan.

Test Governance Checklist

Lane assignment is named and narrow: Heavy-Governance / surface-guard for workflow/template guard tests unless implementation proves a cheaper targeted lane.
New or changed tests stay in the smallest honest family; no browser, DB, workspace, tenant, provider, session, queue, or seed fixture is introduced for the default slice.
Shared helpers and scanner fixtures stay cheap by default; no heavy application setup is hidden in a broad helper.
Planned validation commands cover the gate without pulling in unrelated suite cost.
Browser proof is explicitly N/A for docs/template/test-only work and required for any runtime rendered UI change.
Any material runtime, lane, baseline, trend, or CI strictness impact is recorded in specs/395-product-surface-gate/implementation-report.md.

Phase 1: Preparation And Repo Truth

Purpose: Confirm Spec 395 installs a workflow gate and does not reopen completed productization specs.

T001 Re-read specs/395-product-surface-gate/spec.md, plan.md, tasks.md, and checklists/requirements.md before implementation.
T002 Record branch, HEAD, dirty state, selected implementation slice, and no-runtime-UI default in specs/395-product-surface-gate/implementation-report.md.
T003 Re-read current workflow sources: .specify/memory/constitution.md, .specify/templates/spec-template.md, .specify/templates/plan-template.md, .specify/templates/tasks-template.md, .specify/templates/checklist-template.md, .specify/README.md, AGENTS.md, and .gitea/pull_request_template.md.
T004 Re-read product-surface sources: docs/ui/operator-ux-surface-standards.md, docs/ui/action-surface-contract.md, docs/product/standards/README.md, and docs/ui-ux-enterprise-audit/README.md.
T005 Re-read completed source context without rewriting it: Spec 370 surface IA artifacts, Spec 375 UI bloat guard artifacts, and Spec 377 closeout artifacts.
T006 Inspect guard/test conventions in apps/platform/tests/Feature/Guards, apps/platform/tests/Architecture, apps/platform/tests/Pest.php, apps/platform/tests/Support/TestLaneManifest.php, scripts/check-ui-productization-coverage, and scripts/validate-ui-productization-coverage-guard.
T007 Confirm no migrations, models, policies, routes, Filament pages/resources, Livewire components, views, panel providers, Graph contracts, jobs, queues, scheduler, storage, or runtime UI files are intentionally changed for the default slice.

Phase 2: Product Surface Contract And Workflow Wording

Purpose: Make the contract durable in one canonical documentation location and reference it from workflow gates.

T008 Select the canonical Product Surface Contract location after checking existing docs; prefer docs/product/standards/product-surface-contract.md unless the source review proves an existing document is the better owner.
T009 Create or update the selected Product Surface Contract document with page archetypes, surface budgets, Technical Annex rules, canonical status vocabulary, readiness truth rule, deep-link demotion, table caps, role/audience boundaries, action model, exception format, browser proof rule, and human sanity rule.
T010 Update docs/product/standards/README.md or the selected standards index so reviewers can find the Product Surface Contract.
T011 Update docs/ui/operator-ux-surface-standards.md, docs/ui/action-surface-contract.md, and docs/ui-ux-enterprise-audit/README.md where they need direct Product Surface Contract references, or record in specs/395-product-surface-gate/implementation-report.md why the canonical contract location is sufficient without direct edits.
T012 Update .specify/memory/constitution.md with concise durable Product Surface Contract principles and a proportionality-aware exception path.
T013 If .specify/memory/constitution.md changes, update its Last Amended date and record the required amendment rationale plus impacted templates/specs list in specs/395-product-surface-gate/implementation-report.md and the PR close-out.
T014 Ensure Product Surface wording treats provider-specific terms as Technical Annex/provider diagnostics detail, not platform-core operator vocabulary.
T015 Ensure Product Surface wording does not introduce a runtime presenter, enum/status family, persisted taxonomy, component framework, or broad UI redesign requirement.

Phase 3: Spec Kit Templates And PR Gate

Purpose: Make future UI-affecting work declare surface impact before implementation.

T016 Update .specify/templates/spec-template.md with required sections for No Legacy, Product Surface Impact, UI Surface Impact, Browser Verification Plan, Human Product Sanity Check, Product Surface exceptions, and Merge Gate Checklist.
T017 Update .specify/templates/plan-template.md so plans carry Livewire v4 compliance, provider registration location, global search posture, destructive-action posture, asset strategy, testing plan, and deployment impact for Filament/UI-relevant work.
T018 Update .specify/templates/tasks-template.md so task lists include Product Surface classification, browser/no-browser rationale, human sanity review, close-out report, and stop-before-runtime-UI-change instructions.
T019 Update .specify/templates/checklist-template.md so generated checklists verify Product Surface sections, no-legacy behavior, exceptions, and browser/human sanity applicability.
T020 Update .specify/README.md to describe when the Product Surface Contract gate applies and how exceptions are handled.
T021 Update AGENTS.md to require Product Surface Contract review before UI-affecting implementation, while preserving Sail-first and Spec Kit workflow guidance.
T022 Update .gitea/pull_request_template.md with a Product Surface close-out block covering guardrail class, UI impact, exceptions, browser proof, human sanity, tests, and deployment impact.

Phase 4: Guard Tests And Lane Registration

Purpose: Make workflow omissions fail in a deterministic, non-browser guard.

T023 Add or update apps/platform/tests/Feature/Guards/ProductSurfaceContractGateTest.php to assert required Product Surface sections exist in templates, AGENTS workflow guidance, PR checklist, and the canonical contract document.
T024 Reuse existing apps/platform/tests/Feature/Guards/UiBloatRegressionGuardTest.php patterns where helpful, but do not duplicate the static scanner as the Product Surface Contract gate.
T025 Add assertions that completed specs are not required to be rewritten and that the gate targets future specs/templates/workflow.
T026 Add assertions for no-runtime-UI default behavior: docs/template/test-only changes may record browser N/A, while rendered UI changes must declare browser proof.
T027 Add assertions for required implementation close-out fields: Livewire v4 compliance, provider registration location, global search posture, destructive-action posture, asset strategy, testing/browser result, and deployment impact.
T028 Update apps/platform/tests/Support/TestLaneManifest.php if a new guard family is added, classifying it as surface-guard / heavy-governance or documenting targeted-only ownership in implementation-report.md.
T029 Update apps/platform/tests/Pest.php only if the selected test lane requires group registration.
T030 Keep guard fixtures local, cheap, and file-based; do not introduce database, browser, tenant, provider, or session setup.

Phase 5: First Reduction Boundary Decision

Purpose: Decide whether this v1 gate can safely include a tiny direct surface reduction or should defer all page changes.

T031 Inspect high-risk central paths with rg for repeated technical links, raw/support default labels, duplicate status truth, table overload, and implementation-first action names.
T032 Record the inspection result in specs/395-product-surface-gate/implementation-report.md with either no runtime reduction included or one bounded proposed runtime reduction.
T033 If a runtime reduction is proposed, stop before editing runtime files and update spec.md and plan.md with exact affected surfaces, UI/Productization Coverage, UI Action Matrix if applicable, browser proof, and human sanity criteria. (N/A: no runtime reduction proposed.)
T034 If no low-risk runtime reduction is included, record follow-up candidates only; do not broad-refactor pages.

Phase 6: Validation And Close-Out

Purpose: Finish with bounded proof and clear reviewer handoff.

T035 Run the narrow Product Surface guard command selected by implementation, expected shape: cd apps/platform && ./vendor/bin/sail artisan test --compact --filter=ProductSurface.
T036 Run existing related guard coverage as needed, expected shape: cd apps/platform && ./vendor/bin/sail artisan test --compact --filter=UiBloatRegressionGuard.
T037 Run cd apps/platform && ./vendor/bin/sail bin pint --dirty --format agent if PHP files changed.
T038 Run git diff --check.
T039 If no runtime UI was changed, record browser proof as N/A - no rendered UI surface changed in implementation-report.md and PR close-out.
T040 If runtime UI was changed after approved spec/plan update, run a focused browser smoke for the affected routes and capture screenshots or page-report evidence. (N/A: no runtime UI changed.)
T041 Complete the Human Product Sanity Check result in implementation-report.md, including whether the default screen reads product-first and whether technical detail is demoted.
T042 Complete implementation-report.md with changed files, commands run, results, known limitations, no completed-spec rewrite assertion, and follow-up candidates.
T043 Confirm final implementation response states Livewire v4 compliance, provider registration location, global search status, destructive-action safety, asset strategy, tests/browser coverage, and deployment impact.

Non-Goals Checklist

NT001 Do not redesign product pages in the default slice.
NT002 Do not modify runtime UI files unless spec.md and plan.md are updated first with exact UI impact and verification requirements.
NT003 Do not add migrations, models, persisted product truth, enum/status families, jobs, policies, routes, Livewire components, Filament pages/resources, navigation entries, or Graph calls.
NT004 Do not add screenshot diff infrastructure, full visual regression, broad browser audit, accessibility audit, or performance audit.
NT005 Do not make all Product Surface rules CI-blocking before exception policy and false-positive behavior are proven.
NT006 Do not rewrite completed historical specs or remove implementation close-out, validation, or browser evidence from completed specs.
NT007 Do not create a runtime Product Surface framework, presenter, registry, or component system.

Dependencies And Execution Order

Phase 1 must complete before any workflow or test edits.
Phase 2 establishes the contract before templates reference it.
Phase 3 updates workflow gates before guard tests assert them.
Phase 4 implements guard enforcement and lane ownership.
Phase 5 decides whether runtime reduction stays deferred or requires an explicit spec/plan update.
Phase 6 validates and closes the implementation report.

Recommended Implementation Strategy

Implement the default docs/templates/tests slice first. Prefer a targeted Pest guard under tests/Feature/Guards because the repo already uses file-based guard tests and surface-guard lane classification. Keep browser proof out of the default slice, but make any future rendered UI change a hard stop until the spec and plan declare exact affected surfaces, page archetypes, exception handling, focused browser proof, and human sanity review.

12 KiB Raw Blame History