TenantAtlas/specs/395-product-surface-gate/tasks.md

# 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

- [x] Lane assignment is named and narrow: Heavy-Governance / `surface-guard` for workflow/template guard tests unless implementation proves a cheaper targeted lane.
- [x] 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.
- [x] Shared helpers and scanner fixtures stay cheap by default; no heavy application setup is hidden in a broad helper.
- [x] Planned validation commands cover the gate without pulling in unrelated suite cost.
- [x] Browser proof is explicitly `N/A` for docs/template/test-only work and required for any runtime rendered UI change.
- [x] 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.

- [x] T001 Re-read `specs/395-product-surface-gate/spec.md`, `plan.md`, `tasks.md`, and `checklists/requirements.md` before implementation.
- [x] T002 Record branch, HEAD, dirty state, selected implementation slice, and no-runtime-UI default in `specs/395-product-surface-gate/implementation-report.md`.
- [x] 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`.
- [x] 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`.
- [x] 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.
- [x] 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`.
- [x] 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.

- [x] 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.
- [x] 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.
- [x] T010 Update `docs/product/standards/README.md` or the selected standards index so reviewers can find the Product Surface Contract.
- [x] 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.
- [x] T012 Update `.specify/memory/constitution.md` with concise durable Product Surface Contract principles and a proportionality-aware exception path.
- [x] 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.
- [x] T014 Ensure Product Surface wording treats provider-specific terms as Technical Annex/provider diagnostics detail, not platform-core operator vocabulary.
- [x] 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.

- [x] 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.
- [x] 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.
- [x] 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.
- [x] T019 Update `.specify/templates/checklist-template.md` so generated checklists verify Product Surface sections, no-legacy behavior, exceptions, and browser/human sanity applicability.
- [x] T020 Update `.specify/README.md` to describe when the Product Surface Contract gate applies and how exceptions are handled.
- [x] T021 Update `AGENTS.md` to require Product Surface Contract review before UI-affecting implementation, while preserving Sail-first and Spec Kit workflow guidance.
- [x] 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.

- [x] 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.
- [x] 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.
- [x] T025 Add assertions that completed specs are not required to be rewritten and that the gate targets future specs/templates/workflow.
- [x] 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.
- [x] 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.
- [x] 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`.
- [x] T029 Update `apps/platform/tests/Pest.php` only if the selected test lane requires group registration.
- [x] 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.

- [x] 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.
- [x] 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.
- [x] 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.)*
- [x] 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.

- [x] T035 Run the narrow Product Surface guard command selected by implementation, expected shape: `cd apps/platform && ./vendor/bin/sail artisan test --compact --filter=ProductSurface`.
- [x] T036 Run existing related guard coverage as needed, expected shape: `cd apps/platform && ./vendor/bin/sail artisan test --compact --filter=UiBloatRegressionGuard`.
- [x] T037 Run `cd apps/platform && ./vendor/bin/sail bin pint --dirty --format agent` if PHP files changed.
- [x] T038 Run `git diff --check`.
- [x] 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.
- [x] 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.)*
- [x] 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.
- [x] T042 Complete `implementation-report.md` with changed files, commands run, results, known limitations, no completed-spec rewrite assertion, and follow-up candidates.
- [x] 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

- [x] NT001 Do not redesign product pages in the default slice.
- [x] NT002 Do not modify runtime UI files unless `spec.md` and `plan.md` are updated first with exact UI impact and verification requirements.
- [x] 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.
- [x] NT004 Do not add screenshot diff infrastructure, full visual regression, broad browser audit, accessibility audit, or performance audit.
- [x] NT005 Do not make all Product Surface rules CI-blocking before exception policy and false-positive behavior are proven.
- [x] NT006 Do not rewrite completed historical specs or remove implementation close-out, validation, or browser evidence from completed specs.
- [x] 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.