# Implementation Report: Spec 395 - Product Surface Contract Enforcement and Surface Reduction Gate v1

## Repo State

- **Branch**: `395-product-surface-gate`
- **Starting HEAD**: `a6c064cb feat: improve provider readiness semantics and freshness guidance (#465)`
- **Initial dirty state**: `specs/395-product-surface-gate/` existed as an untracked prepared spec directory before implementation.
- **Selected implementation slice**: default workflow/docs/templates/tests slice.
- **Runtime UI default**: no rendered UI, route, Filament, Livewire, Blade, CSS, JavaScript, navigation, panel provider, action, table, form, modal, resource, relation manager, widget, or asset change.

## Product Surface Contract Location

- **Canonical location**: `docs/product/standards/product-surface-contract.md`
- **Why this location**: `docs/product/standards/` already owns concrete product standards and indexes guard-enforced review contracts. Keeping the Product Surface Contract there avoids duplicating full rule tables across `.specify/`, AGENTS, and PR templates.
- **Related references updated**: `docs/product/standards/README.md`, `docs/ui/operator-ux-surface-standards.md`, `docs/ui/action-surface-contract.md`, and `docs/ui-ux-enterprise-audit/README.md`.

## Constitution Amendment

- **Amendment**: added `Product Surface Contract Gate (PSC-001)`.
- **Version change**: `2.14.0 -> 2.15.0`.
- **Last amended**: `2026-06-21`.
- **Rationale**: Future UI-affecting specs need a hard completion gate for page archetype, surface budgets, technical demotion, browser/no-browser proof, human sanity review, no-legacy posture, visible complexity outcome, and close-out evidence.
- **Impacted templates/specs list**: `.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`, `.gitea/pull_request_template.md`, and Spec 395 implementation artifacts.

## Guardrail And Test Governance

- **Test purpose / classification**: Heavy-Governance / `surface-guard`.
- **New guard family**: `product-surface-contract-gate`.
- **Lane registration**: `apps/platform/tests/Support/TestLaneManifest.php` and `apps/platform/tests/Pest.php`.
- **Fixture cost**: file-based repository assertions only; no browser, provider, tenant, workspace, session, queue, or seed fixture added by this feature.
- **Runtime/lane impact**: one new deterministic guard file in the existing surface-guard family; no fast-feedback lane expansion.

## Browser And Human Sanity

- **Browser proof**: `N/A - no rendered UI surface changed`.
- **No-browser rationale**: implementation changed workflow docs, standards docs, Spec Kit templates, PR checklist, and guard tests only.
- **Human Product Sanity**: workflow sanity check completed against the contract wording. The default rendered product surface is unchanged, and the gate requires future UI-affecting specs to prove one dominant action, technical demotion, canonical statuses, and neutral/decreased visible complexity.

## Runtime And Deployment Impact

- **Livewire v4 compliance**: unchanged; project runs Livewire 4.1.4 and no Livewire code changed.
- **Provider registration location**: unchanged; Laravel 12 panel providers remain in `apps/platform/bootstrap/providers.php`.
- **Global search posture**: unchanged; no Filament Resource or globally searchable resource changed.
- **Destructive/high-impact actions**: none added or changed.
- **Asset strategy**: no Filament assets registered; `filament:assets` is not required for this slice.
- **Environment variables**: none.
- **Migrations**: none.
- **Queues / scheduler**: unchanged.
- **Storage / volumes**: unchanged.

## Completed-Spec Rewrite Assertion

Specs 368, 370, 375, and 377 were read as historical context only. No completed spec close-out, validation result, completed task, smoke result, browser evidence, screenshot, or review history was rewritten or removed.

## First Reduction Boundary

- **Runtime reduction included**: no.
- **Reason**: all candidate runtime reductions would require page-specific UI coverage, browser proof, and human sanity criteria. Spec 395 v1 ships the gate first and records those runtime reductions as follow-up candidates.
- **Follow-up candidates**:
  - Receipt Page Reduction Pass: Evidence Snapshot, Baseline Snapshot, Restore Run Detail, Review Pack Receipt.
  - Decision Page Reduction Pass: Baseline Compare, Restore Preview, Review Resolution Decision.
  - Dashboard and Inbox Link Budget Pass: Environment Dashboard, Workspace Overview, Governance Inbox, Findings, Operations Hub.
  - CI strictness expansion for UI bloat/product-surface guard rules after allowlist cleanup.
  - Manual system-panel browser fixture or documented audit procedure from Spec 377.

## Validation Results

- `cd apps/platform && ./vendor/bin/sail artisan test --compact --filter=ProductSurface`: passed, 5 tests / 25 assertions. Final rerun duration: 11.88s.
- `cd apps/platform && ./vendor/bin/sail artisan test --compact --filter=UiBloatRegressionGuard`: passed, 10 tests / 40 assertions. Duration: 26.20s.
- `cd apps/platform && ./vendor/bin/sail artisan test --compact --filter=TestLaneManifest`: passed, 6 tests / 327 assertions. Duration: 25.94s.
- `cd apps/platform && ./vendor/bin/sail bin pint --dirty --format agent`: passed.
- `git diff --check`: passed.
- New/untracked file whitespace check via `git diff --check --no-index`: passed for `ProductSurfaceContractGateTest.php`, `product-surface-contract.md`, and Spec 395 artifacts.
- `bash scripts/check-ui-productization-coverage HEAD`: passed with `no guarded UI surface paths changed`.
- Runtime-reduction inspection: `rg` found page-specific candidates such as OperationRun links, `Open operation` labels, and System widget `Healthy` / `Warning` labels. No runtime reduction was included because each candidate requires exact surface coverage, browser proof, and human sanity criteria under a separate scoped UI update.

## Files Changed

- `.gitea/pull_request_template.md`
- `.specify/README.md`
- `.specify/memory/constitution.md`
- `.specify/templates/checklist-template.md`
- `.specify/templates/plan-template.md`
- `.specify/templates/spec-template.md`
- `.specify/templates/tasks-template.md`
- `Agents.md`
- `apps/platform/tests/Feature/Guards/ProductSurfaceContractGateTest.php`
- `apps/platform/tests/Pest.php`
- `apps/platform/tests/Support/TestLaneManifest.php`
- `docs/product/standards/README.md`
- `docs/product/standards/product-surface-contract.md`
- `docs/ui-ux-enterprise-audit/README.md`
- `docs/ui/action-surface-contract.md`
- `docs/ui/operator-ux-surface-standards.md`
- `specs/395-product-surface-gate/checklists/requirements.md`
- `specs/395-product-surface-gate/implementation-report.md`
- `specs/395-product-surface-gate/plan.md`
- `specs/395-product-surface-gate/spec.md`
- `specs/395-product-surface-gate/tasks.md`

## Known Limitations

- The Product Surface Contract is a workflow and review gate, not a complete runtime scanner for every rule.
- CI hard-fail expansion for all Product Surface rules remains out of scope until false-positive behavior is proven.