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

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

**Branch**: `395-product-surface-gate` | **Date**: 2026-06-21 | **Spec**: `specs/395-product-surface-gate/spec.md`
**Input**: Feature specification from `specs/395-product-surface-gate/spec.md`

## Summary

Install the Product Surface Contract as a hard workflow and merge gate without redesigning pages. The implementation should update durable principles, Spec Kit templates, AGENTS workflow instructions, PR/merge checklist, product-surface standards documentation, and targeted guard tests so future UI-affecting specs must declare surface impact, page archetype, surface budgets, technical demotion, canonical status vocabulary, focused browser verification, human product sanity review, and no-legacy behavior.

The default slice is workflow/guardrail only. Runtime UI changes are out of scope unless this spec and plan are first updated with exact affected surfaces and UI/Productization Coverage.

## Technical Context

**Language/Version**: PHP 8.4.15, Laravel 12.52, Filament 5.2.1, Livewire 4.1.4.
**Primary Dependencies**: Laravel, Filament, Livewire, Pest 4, existing Spec Kit scripts/templates, existing UI bloat/productization guards.
**Storage**: No database or persisted product data changes.
**Testing**: Pest 4 guard tests through Sail; optional browser smoke only if runtime UI is touched.
**Validation Lanes**: heavy-governance/surface-guard for workflow/template guard tests; browser lane only for rendered UI changes.
**Target Platform**: Laravel monolith under `apps/platform`, documentation/workflow files at repo root.
**Project Type**: Web application and Spec Kit workflow.
**Performance Goals**: Guard tests remain deterministic and avoid database/browser fixtures for the default slice.
**Constraints**: No runtime UI change by default; no new dependencies; no completed spec rewriting; no broad page redesign.
**Scale/Scope**: Cross-workflow enforcement for future specs touching `/admin`, `/system`, and product-facing surfaces.

## Repository Surfaces Likely Affected

Primary workflow and standards 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
.specify/README.md
AGENTS.md
.gitea/pull_request_template.md
docs/product/standards/README.md
docs/ui/operator-ux-surface-standards.md
docs/ui/action-surface-contract.md
docs/ui-ux-enterprise-audit/README.md
```

Possible new or updated contract location, to be selected by implementation after checking current docs:

```text
docs/product/standards/product-surface-contract.md
```

Primary test/guard files:

```text
apps/platform/tests/Feature/Guards/UiBloatRegressionGuardTest.php
apps/platform/tests/Feature/Guards/ProductSurfaceContractGateTest.php
apps/platform/tests/Support/TestLaneManifest.php
scripts/check-ui-productization-coverage
scripts/validate-ui-productization-coverage-guard
```

Existing guard/test context to reuse:

```text
apps/platform/tests/Feature/Guards/ActionSurfaceContractTest.php
apps/platform/tests/Feature/Guards/BrowserLaneIsolationTest.php
apps/platform/tests/Architecture/Spec392DeprecatedCustomerOutputDownloadGuardTest.php
apps/platform/tests/Feature/ProviderConnections/Spec394ProviderFreshnessProductSanityTest.php
```

Runtime UI files are not in the default scope.

## UI / Surface Guardrail Plan

- **Guardrail scope**: workflow-only guardrail change by default.
- **Affected routes/pages/actions/states/navigation/panel/provider surfaces**: No rendered surface in the default slice.
- **No-impact class, if applicable**: docs-only, template-only, tooling/test-only.
- **Native vs custom classification summary**: N/A for rendered UI; future runtime work must be native/shared-primitives first.
- **Shared-family relevance**: status messaging, action links, evidence/report viewers, technical/audit links, implementation close-out reports.
- **State layers in scope**: workflow/template state only; no shell/page/detail runtime state.
- **Audience modes in scope**: operator-MSP, customer/read-only, support-platform, and system admin as review categories, not runtime modes.
- **Decision/diagnostic/raw hierarchy plan**: product layer first, technical evidence layer demoted to Technical Annex/internal/audit paths.
- **Raw/support gating plan**: documented as future default; no runtime gating change in default slice.
- **One-primary-action / duplicate-truth control**: templates and contract require future touched pages to identify one primary question and one primary action.
- **Handling modes by drift class or surface**: hard-stop for missing gate sections; review-mandatory for budget exceptions; follow-up-spec for broad page reductions.
- **Repository-signal treatment**: guarded UI path changes require UI impact decision or coverage artifacts; workflow docs/tests must enforce this.
- **Special surface test profiles**: `surface-guard` for guard tests; browser smoke only when runtime UI changes.
- **Required tests or manual smoke**: targeted Pest guard tests for template/workflow content; focused browser smoke if runtime UI changes.
- **Exception path and spread control**: every Product Surface exception requires page, violated budget, reason, why not customer/product-facing, and follow-up if temporary.
- **Active feature PR close-out entry**: Guardrail / Smoke Coverage / Human Product Sanity.
- **UI/Productization coverage decision**: `No UI surface impact` for the default slice.
- **Coverage artifacts to update**: none unless runtime UI changes. If runtime UI changes, update route inventory/design matrix/page report or explicit no-impact rationale before code.
- **No-impact rationale**: workflow/template/docs/tests only.
- **Navigation / Filament provider-panel handling**: no provider or navigation change by default.
- **Screenshot or page-report need**: no for default slice; yes for any runtime UI reduction that changes rendered pages.

## Shared Pattern & System Fit

- **Cross-cutting feature marker**: yes, as a workflow/guardrail and standards change.
- **Systems touched**: Spec Kit templates, constitution, AGENTS, PR checklist, product UI standards, UI bloat guard, UI coverage guard, test lane manifest.
- **Shared abstractions reused**: existing `UiBloatScanner`, UI coverage guard script, Pest guard patterns, `TestLaneManifest` surface-guard lane ownership, existing action-surface standards.
- **New abstraction introduced? why?**: No runtime abstraction. A new guard test file may be introduced to enforce workflow content.
- **Why existing abstraction was sufficient or insufficient**: Existing guards detect UI bloat and coverage acknowledgment, but do not ensure every future spec/implementation includes Product Surface Impact, Browser Verification Plan, Human Product Sanity Check, or Merge Gate Checklist.
- **Bounded deviation / spread control**: New workflow terms are documentation and review terms only. They must not become a runtime presenter, enum, table, or component framework.

## OperationRun UX Impact

- **Touches OperationRun start/completion/link UX?**: no.
- **Central contract reused**: N/A.
- **Delegated UX behaviors**: N/A.
- **Surface-owned behavior kept local**: none.
- **Queued DB-notification policy**: N/A.
- **Terminal notification path**: N/A.
- **Exception path**: none.

The Product Surface Contract requires future product default views to demote OperationRun links unless the page is Technical Annex/System Admin or an exception is documented.

## Provider Boundary & Portability Fit

- **Shared provider/platform boundary touched?**: no runtime seam.
- **Provider-owned seams**: no code change; provider payload and required-permission examples remain provider-owned technical detail.
- **Platform-core seams**: product-surface vocabulary, page archetypes, default status vocabulary, and Technical Annex rules.
- **Neutral platform terms / contracts preserved**: workspace, environment, provider connection, evidence, operation, audit trail, technical details.
- **Retained provider-specific semantics and why**: Microsoft/provider terms may appear in provider diagnostics and Technical Annex examples. They must not become default platform product vocabulary.
- **Bounded extraction or follow-up path**: document-in-feature for contained exceptions; follow-up-spec for repeated provider-surface drift.

## Domain / Model Implications

No new model, migration, table, enum, persisted state, OperationRun type, queue job, policy, route, or service is planned. The only "entities" are documentation and workflow artifacts.

If implementation discovers that enforcement needs runtime storage or a new status enum, it must stop and update the spec/plan because that exceeds this v1 scope.

## UI / Filament / Livewire Implications

- Livewire v4.1.4 compliance remains unchanged.
- Filament panel providers remain registered in `apps/platform/bootstrap/providers.php`; no panel provider change is planned.
- No Filament Resource, RelationManager, Page, action, table, form, modal, widget, cluster, render hook, asset, or navigation entry is changed by default.
- If runtime UI changes become necessary, implementation must update the UI Surface Impact and UI Action Matrix before editing code.
- Global search posture is unchanged. No globally searchable resource is added or modified.
- No destructive/high-impact action is added or changed.
- No Filament asset registration is planned; `filament:assets` is not required for this slice.

## Constitution Check

- Inventory-first: N/A, no inventory or snapshot behavior.
- Read/write separation: PASS, no runtime writes.
- Graph contract path: PASS, no Graph calls.
- Deterministic capabilities: N/A.
- RBAC-UX: PASS, no authorization changes; future specs must preserve capability-first RBAC.
- Workspace isolation: PASS, no runtime queries.
- Tenant isolation: PASS, no runtime queries.
- Run observability: N/A, no long-running or remote work.
- OperationRun start UX: N/A.
- Ops-UX 3-surface feedback: N/A.
- Automation: N/A.
- Data minimization: PASS, no sensitive runtime data captured by default.
- Test governance: PASS, surface-guard lane is explicit.
- Proportionality: PASS with review in `spec.md`; new governance vocabulary is documentation/workflow truth only.
- No premature abstraction: PASS, no runtime abstraction.
- Persisted truth: PASS, no database persistence.
- Behavioral state: PASS, no runtime state family.
- UI semantics: PASS with risk; gate must not create a runtime UI semantics framework.
- Shared pattern first: PASS, reuse existing UI bloat/productization guard paths.
- Provider boundary: PASS, provider internals are demoted from default product UI.
- V1 explicitness / few layers: PASS, direct template/docs/tests updates.
- Spec discipline / bloat check: PASS, the broad gate is grouped into one coherent spec rather than many micro-specs.
- Badge semantics: PASS, no badge mapping change. Future status display must use BADGE-001.
- Filament-native UI: PASS by no runtime UI changes. Future runtime work must use native/shared primitives.
- UI/Productization coverage: PASS, this plan carries a checked no-impact rationale.
- Filament Action Surface Contract: PASS, no action topology change.
- UX-001 Layout and IA: N/A for runtime UI.

## Test Governance Check

- **Test purpose / classification by changed surface**: Heavy-Governance / surface-guard for template/docs/workflow gate tests.
- **Affected validation lanes**: targeted guard test; heavy-governance ownership if added to manifest.
- **Why this lane mix is the narrowest sufficient proof**: The change is cross-workflow and surface-governance oriented; it should not enter fast-feedback unless implementation proves a tiny targeted assertion is cheap and non-broad.
- **Narrowest proving commands**:
  - `cd apps/platform && ./vendor/bin/sail artisan test --compact --filter=ProductSurface`
  - `cd apps/platform && ./vendor/bin/sail artisan test --compact --filter=UiBloatRegressionGuard`
  - `git diff --check`
  - `cd apps/platform && ./vendor/bin/sail bin pint --dirty --format agent` if PHP files change
- **Fixture / helper / factory / seed / context cost risks**: none for workflow guard tests.
- **Expensive defaults or shared helper growth introduced?**: no.
- **Heavy-family additions, promotions, or visibility changes**: possible new `product-surface-contract-gate` family in `TestLaneManifest`, classified as `surface-guard`.
- **Surface-class relief / special coverage rule**: no browser proof for docs/template/test-only default slice.
- **Closing validation and reviewer handoff**: confirm guard tests pass, workflow artifacts contain required sections, no runtime files changed unless spec/plan updated, and completed specs are untouched.
- **Budget / baseline / trend follow-up**: document runtime of any new guard family; no lane budget change expected.
- **Review-stop questions**: Does the implementation create a runtime framework? Did it touch UI without updating coverage? Did it skip browser proof for rendered UI? Did it rewrite completed specs?
- **Escalation path**: document-in-feature for contained exceptions; follow-up-spec for broad page reductions or CI hard-fail expansion.
- **Active feature PR close-out entry**: Guardrail / Smoke Coverage / Human Product Sanity.
- **Why no dedicated follow-up spec is needed**: The enforcement gate is a bounded workflow change. Page-specific reductions remain follow-up candidates and are explicitly out of the default slice.

## Project Structure

### Documentation And Workflow

```text
.specify/
├── memory/constitution.md
├── templates/spec-template.md
├── templates/plan-template.md
├── templates/tasks-template.md
├── templates/checklist-template.md
└── README.md

AGENTS.md
.gitea/pull_request_template.md
docs/product/standards/
docs/ui/
```

### Source And Tests

```text
apps/platform/
├── tests/Feature/Guards/
├── tests/Support/TestLaneManifest.php
└── tests/Architecture/

scripts/
├── check-ui-productization-coverage
└── validate-ui-productization-coverage-guard
```

**Structure Decision**: Keep enforcement in existing workflow/docs/test guard locations. Do not create a new base folder or runtime module.

## Complexity Tracking

| Violation | Why Needed | Simpler Alternative Rejected Because |
|---|---|---|
| Cross-surface product-surface vocabulary | Future specs need concrete page archetype, budget, Technical Annex, and status vocabulary checks | A one-line checklist would not make exceptions, browser proof, and human review attributable |
| Guard/test workflow enforcement | Templates and docs alone are easy to ignore | Manual-only review already allowed product-surface drift to recur |

## Proportionality Review

- **Current operator problem**: UI-affecting specs can increase visible complexity and expose technical details while still passing tests.
- **Existing structure is insufficient because**: Spec 370/375/377 artifacts exist, but workflow templates and completion gates do not yet make their rules mandatory for future specs.
- **Narrowest correct implementation**: Update durable workflow artifacts and targeted guard tests. Do not add runtime framework, data persistence, or broad redesign.
- **Ownership cost created**: More required spec sections, PR checklist fields, and guard tests. Reviewers must enforce exceptions.
- **Alternative intentionally rejected**: Full redesign, browser visual regression framework, hard-fail scanner expansion for all rules, or runtime Product Surface service.
- **Release truth**: Current-release truth. The product needs regression prevention now after the closeout program.

## Implementation Phases

1. Repo safety and source verification.
2. Product Surface Contract wording and durable docs updates.
3. Spec Kit template and AGENTS/PR checklist gate updates.
4. Targeted guard tests and lane manifest updates.
5. Bounded first reduction decision: either low-risk direct reduction or follow-up documentation.
6. Validation, browser/human sanity applicability decision, and implementation report.

## Rollout And Deployment Considerations

- No env vars.
- No migrations.
- No queues or scheduler changes.
- No storage/volume changes.
- No Filament asset registration expected.
- Dokploy/Sail runtime behavior unchanged for default slice.
- If PHP tests are added, run through Sail.

## Risk Controls

- Guard against broad runtime edits by requiring spec/plan update before any rendered UI change.
- Guard against completed-spec rewriting by treating Specs 368, 370, 375, and 377 as read-only historical context.
- Keep Product Surface Contract in one documentation location and reference it from templates to avoid duplicate standards.
- Reuse existing `UiBloatRegressionGuardTest` and UI coverage guard behavior where possible.
- Classify new broad guard tests as surface-guard/heavy-governance, not fast-feedback.