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

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

Feature Branch: 395-product-surface-gate Created: 2026-06-21 Status: Draft / Ready for preparation review Input: User-provided Spec 395 draft, Product Surface Contract lineage from Specs 368, 370, 375, and 377, and current repo workflow/template guardrails.

Candidate Selection And Completed-Spec Guardrail

• Selected candidate: Product Surface Contract Enforcement and Surface Reduction Gate v1.
• Source: Direct user-provided full candidate "Spec 395 - Product Surface Contract Enforcement & Surface Reduction Gate v1".
• Roadmap relationship: Supports the UI and Product Maturity Polish lane, the decision-based operating model, and the post-Spec-377 need to keep productization gains from regressing.
• Why selected: docs/product/spec-candidates.md currently reports no safe automatic queue target, but the user provided an explicit P1 candidate. The candidate closes a real gap left by the productization program: the Product Surface Contract exists as guidance and guard context, but future specs can still add visible complexity unless the completion gate makes surface impact, browser proof, and product sanity review mandatory.
• Smallest viable slice: Update durable workflow rules, templates, PR/merge checklist, and guard tests so future specs must declare product-surface impact, no-legacy posture, page archetype, surface budgets, browser verification, human sanity review, and implementation report fields. Add or prepare the Technical Annex/status/deep-link/table-cap contract as documented review truth. Do not redesign all pages.
• Completed-spec check result: No specs/395-* package existed before this run. Related specs are historical inputs only:
  • Spec 370 defined a docs-only Global Surface Information Architecture Contract.
  • Spec 375 added a UI bloat regression guard and follow-up recommendations.
  • Spec 377 completed browser closeout as closed-with-follow-up, with no P0/P1 findings and only system-panel manual fixture follow-up.
  • Specs 368, 370, 375, and 377 must not be rewritten, normalized, reopened, or stripped of close-out, validation, completed task, smoke, browser, or review history.
• Close alternatives deferred:
  • Broad page redesign across Environment Dashboard, Evidence, Operations, Review, Provider, Restore, and System surfaces.
  • CI hard-fail expansion for every UI bloat rule before false-positive behavior is stable.
  • Manual system-panel browser fixture procedure from Spec 377.
  • Page-specific Receipt, Decision, Dashboard, and Inbox reduction passes.

Spec Candidate Check (mandatory - SPEC-GATE-001)

• Problem: TenantPilot has product-surface rules, but they are not yet a hard completion gate. Future specs can still pass tests while adding cards, statuses, tables, technical links, raw identifiers, readiness blocks, or proof paths that make the product harder to understand.
• Today's failure: A feature can add visible UI complexity without proving one primary question, one primary action, canonical status language, technical detail demotion, browser verification, or human product sanity review. The product can regress after the UI Signal-to-Noise program has been closed.
• User-visible improvement: Operators, customer reviewers, and maintainers get quieter product pages over time because every future UI-affecting spec must prove it reduces or preserves visible complexity and must provide focused browser evidence.
• Smallest enterprise-capable version: A workflow and merge-gate enforcement slice: constitution update, spec/plan/tasks/checklist template updates, AGENTS/PR checklist updates, a product-surface contract reference, targeted guard tests, implementation report requirements, and a bounded first reduction or documented follow-up.
• Explicit non-goals: No full navigation rebuild, no design-system replacement, no broad page redesign, no new runtime UI framework, no new persisted data, no new product feature, no new readiness domain, no wholesale Filament resource rewrite, and no compatibility shim for pre-production UI behavior.
• Permanent complexity imported: Durable workflow sections, merge checklist fields, guard tests, one product-surface contract reference, page archetype/surface budget vocabulary, Technical Annex rules, canonical status vocabulary, and implementation-report fields. These are governance and review contracts, not database or runtime product truth.
• Why now: Spec 377 closed the prior productization program with only narrow follow-up. Without a hard gate, future implementation specs can quietly recreate the same product-surface bloat.
• Why not local: Page-local fixes do not prevent the next unrelated feature from adding new surface noise. The drift is cross-surface and process-driven, so the remedy must live in templates, workflow instructions, PR/merge gates, and guard tests.
• Approval class: Core Enterprise.
• Red flags triggered: New cross-surface taxonomy/rules, meta-infrastructure, and many affected surfaces. Defense: the slice is workflow/guard-first, no new persisted truth, no runtime framework, no broad redesign, and it explicitly narrows page reductions into follow-up passes.
• Score: Nutzen: 2 | Dringlichkeit: 2 | Scope: 1 | Komplexitaet: 1 | Produktnaehe: 2 | Wiederverwendung: 2 | Gesamt: 10/12
• Decision: approve as a bounded enforcement and reduction-gate slice.

Problem Statement

TenantPilot must not show everything the system knows. It must show what the current user needs to know to make a safe decision.

The Product Surface Contract and UI Signal-to-Noise artifacts already define decision-first, diagnostics-second, evidence-aware product surfaces. The gap is enforcement. Future specs can still increase visible complexity unless the workflow blocks or documents that growth.

Recurring risk patterns:

• Pages show too many readiness/status signals at once.
• Evidence, OperationRun, baseline, review, provider, report, and finding objects are over-linked.
• Receipt pages behave like dashboards.
• Decision pages behave like audit explorers.
• Customer-safe pages expose internal proof or technical context.
• Hot tables show too many rows by default.
• Technical terms become product language.
• Each feature creates local readiness/status logic.
• Specs can pass tests while still making the product surface worse.

No Legacy / No Backward Compatibility Constraint

TenantPilot is pre-production for this scope. No production customer UI compatibility is required unless a future spec explicitly records a compatibility exception.

Clean canonical product behavior wins over preserving old labels, action keys, routes, local status logic, tests, fixtures, or UI structures that encode wrong semantics.

Implementation must not:

• Preserve old action keys when the key encodes the wrong product meaning.
• Keep tests that assert overloaded default UI behavior.
• Add transitional UI that shows both old and new concepts.
• Add duplicate cards, tables, or statuses to explain old behavior.
• Keep local readiness/status logic when a canonical source exists.
• Add legacy aliases, compatibility shims, fallback readers, or hidden routes solely for pre-production behavior.

Product / Business Value

This spec converts product-surface quality from advice into an implementation completion gate. It protects TenantPilot's sellability and operator trust by making every future UI-affecting spec prove that it preserves or reduces visible complexity, demotes technical details, uses canonical status vocabulary, and provides browser and human review evidence where relevant.

Primary Users / Operators

• Product reviewer checking whether a spec can merge without increasing UI bloat.
• Implementation agent completing a UI-affecting spec and needing a concrete completion gate.
• MSP/operator using /admin surfaces and expecting one clear next action.
• Customer reviewer or auditor consuming customer-safe review/report/evidence surfaces.
• Platform/system operator using /system surfaces that may be technical but must not leak debug/default-framework clutter.

Spec Scope Fields (mandatory)

• Scope: canonical-view / workflow guardrail / product-surface governance.
• Primary Routes: No new route is introduced by the primary slice. The gate applies to future changes touching /admin, /system, and product-facing routes that expose readiness, evidence, operations, provider, review, baseline, restore, report, or governance state.
• Data Ownership: No database or product data ownership changes. New or updated contract artifacts are documentation/workflow truth. Guard tests may inspect repository files but must not create persisted product truth.
• RBAC: No runtime authorization behavior is changed by the gate. Future UI-affecting specs must keep workspace/tenant isolation, capability-first RBAC, and deny-as-not-found semantics explicit. Technical Annex or audit links must be internal/operator/system-authorized where applicable.

For canonical-view specs:

• Default filter behavior when tenant-context is active: N/A for this workflow-gate slice. Future touched pages must state route-owned workspace/environment scope and any default filter behavior.
• Explicit entitlement checks preventing cross-tenant leakage: Existing policies, gates, and UI enforcement remain authoritative. Future specs must prove that product-surface changes do not expose inaccessible records, global search hints, technical links, or audit paths across workspace/tenant boundaries.

UI Surface Impact (mandatory - UI-COV-001)

Does this spec add, remove, rename, or materially change any reachable UI surface?

• No UI surface impact
• Existing page changed
• New page/route 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

UI/Productization Coverage (mandatory when UI Surface Impact is not "No UI surface impact"; otherwise write N/A - no reachable UI surface impact plus rationale)

N/A - no reachable UI surface impact.

• No-impact rationale: The primary implementation slice updates workflow documentation, Spec Kit templates, PR/merge checklists, product-surface contract documentation, and guard tests. It does not add or change rendered pages, routes, navigation entries, Filament panel providers, resources, Livewire components, Blade views, CSS, JavaScript, modals, tables, forms, or user-facing actions. If implementation chooses a runtime UI reduction, it must first update this spec and plan with exact affected surfaces and UI/Productization Coverage.

Product Surface Impact

• Visible UI added: None by default.
• Visible UI removed: None by default. Runtime removal is allowed only after this spec and plan are updated with exact surfaces.
• Page archetypes touched directly by this implementation: None directly. The gate defines required archetypes for future touched pages: Dashboard, Receipt, Decision, Inbox, Wizard, Report, Search/Index, Technical Annex, Settings, and System Admin.
• Surface budgets applied: Future product-facing touched pages must apply the default budgets in this spec unless classified as Technical Annex or System Admin, or unless an explicit exception is documented.
• Technical details hidden/demoted: The gate requires future product-facing default views to demote OperationRun links, raw evidence links, source keys, detectors, fingerprints, UUIDs, payloads, provider payloads, raw report artifacts, and baseline diff internals to secondary internal/audit paths.
• Status vocabulary used: Product-facing states are limited to Ready, Needs attention, Blocked, Running, Failed, Expired, Not configured, Unknown, Historical, and Superseded, with severities Critical, High, Medium, Low, and Info.
• Visible complexity impact: The primary slice is neutral in runtime UI and reduces future complexity by adding hard completion gates. If any visible runtime change is made, the implementation report must prove complexity decreased or stayed neutral.

Mandatory Product Layers

Product Layer

Visible by default. Allowed content:

• Workspace or environment state.
• Readiness, confidence, or risk when it changes action.
• Primary issue or decision.
• Impact.
• Next recommended action.
• Compact business context.
• Customer-safe evidence summary.
• Small status summary.

Technical Evidence Layer

Hidden by default or placed on a dedicated internal technical/audit page. Allowed content:

• OperationRuns.
• Raw evidence and evidence snapshot IDs.
• Source keys, detectors, technical dimensions, raw counts, coverage inventory.
• Payloads, fingerprints, UUIDs, internal IDs.
• Full audit trails and diff internals.

Rule

A product-facing default page must not expose Technical Evidence Layer content by default. If technical depth is necessary, expose it through one secondary/internal action such as View audit trail, View internal evidence details, or View technical details, and require appropriate authorization.

Mandatory Page Archetypes

Every touched product page must declare exactly one primary archetype:

• Dashboard Page: What needs attention now?
• Receipt Page: What happened, when, and can I trust it?
• Decision Page: What changed and what decision should I make?
• Inbox Page: What work items need triage?
• Wizard Page: What step am I on and what do I do next?
• Report Page: What customer/operator summary can be consumed or exported?
• Search/Index Page: How do I find a record?
• Technical Annex Page: What are the internal technical details?
• Settings Page: What behavior is configured?
• System Admin Page: What is the platform/system state?

If a page mixes archetypes, the implementation must reduce it to one archetype, split the page, or document a temporary exception with a follow-up.

Surface Budget Rules

Product-facing pages must satisfy these budgets unless explicitly classified as Technical Annex or System Admin, or unless the active spec records an exception:

• Max 1 primary user question.
• Max 1 primary action.
• Max 2 secondary actions.
• Max 4 summary metrics above the fold.
• Max 1 main table visible by default.
• Max 8 visible rows before Show more, pagination, or full table.
• Max 1 readiness/status model.
• Max 1 decision flow.
• Max 0 raw technical identifiers in default view.
• Max 0 OperationRun links in default view.
• Max 0 raw Evidence deep links in default view.
• Max 0 Source Key, Detector, or Technical Dimension blocks in default view.
• Max 0 repeated readiness/status summaries on the same page.

Each exception must include page, violated budget, reason, why it is not customer/product-facing, and follow-up if temporary.

Canonical Status Vocabulary

Allowed product-facing states:

• Ready
• Needs attention
• Blocked
• Running
• Failed
• Expired
• Not configured
• Unknown
• Historical
• Superseded

Allowed severity states:

• Critical
• High
• Medium
• Low
• Info

Forbidden as independent top-level product states unless explicitly mapped:

• Healthy
• Calm
• OK
• Warning
• At risk
• Unhealthy
• Degraded
• Incomplete
• Partially ready
• Partially complete
• Complete with warnings
• Action needed
• Needs follow-up
• Coverage ready
• Trustworthy artifact
• Usable with warnings
• Likely stale
• Internal only
• Terminal follow-up

If old terms are still needed internally, they must be mapped before display.

Readiness Truth Rule

A page may show only one top-level readiness/status truth for a given concept.

Required pattern:

Provider readiness: Expired
Reason: Verification is stale.
Next action: Verify provider.

Forbidden pattern:

Provider: Healthy
Verification: Stale
Permissions: Missing
Readiness: Ready
Action: Needs attention

Future readiness-producing specs must declare canonical source, consumer pages, display state, blocking reasons, and whether the state is customer-safe.

Deep-Link Demotion Rules

Default product views must not expose a graph of internal objects.

Default-view links to demote:

• OperationRun.
• Evidence Snapshot or Evidence Artifact.
• Baseline Snapshot/Profile internals.
• Detector, Source Key, raw Finding fingerprint.
• Provider payload.
• Raw report artifact.
• Restore operation proof.
• Technical logs.

Allowed default product links:

• Open workspace.
• Open environment.
• Review blockers.
• Open customer workspace.
• Download customer output.
• Compare to current.
• Verify provider.
• Resolve finding.
• Open report.
• Start restore.

Internal/audit links are allowed only as secondary/internal actions.

Table Cap Rules

Product-facing hot tables must default to:

• Max 8 visible rows.
• Pagination or Show all for more.
• Clear row status.
• One row primary action.
• No raw IDs as primary labels.
• No excessive inline links.

Technical Annex/System Admin pages may show more rows, but must be clearly technical/system-facing.

Action Model Rules

Every product-facing page must define:

• Primary action.
• Secondary actions.
• Danger/destructive actions.
• Technical/audit actions.

There may be only one primary action. Destructive/high-impact actions must be visually separated, authorization-checked, audit-logged when they mutate, and confirmation-protected.

Browser Verification Plan

Every implemented spec that changes UI, routes, actions, authorization, downloads, reports, readiness, evidence, provider state, restore flows, customer output, or Product Surface Contract behavior must include focused browser verification.

Spec 395 implementation must:

• Run targeted guard/template tests for the workflow gate.
• If no runtime UI files change, record that browser smoke is not required for runtime proof, and optionally run the focused existing smoke matrix as confidence only.
• If any runtime UI surface changes, run focused browser smoke for affected pages and direct-route bypasses where relevant.
• Check console, Livewire, Filament, network, and 500 errors where browser proof is required.
• Document full browser-suite failures as unrelated only when focused affected browser proof is green and no touched surface fails.

Suggested focus surfaces when runtime UI is touched:

• Environment Dashboard.
• Workspace Overview.
• Evidence Overview or Evidence Snapshot.
• Customer Review Workspace.
• Review Pack Detail.
• Provider Connections / Required Permissions.
• Operations Hub.
• System Dashboard when fixture access exists.

Human Product Sanity Check

A 5 to 15 minute human product sanity check is required for:

• Customer-facing surfaces.
• Dashboards.
• Readiness/status surfaces.
• Review/report output.
• Restore/wizard flows.
• Provider onboarding/readiness.
• Evidence/baseline pages.
• Navigation changes.
• Product Surface Contract changes.

The reviewer must answer:

• Does the page immediately communicate its purpose?
• Is there exactly one dominant next action?
• Are technical details demoted?
• Are status labels understandable and canonical?
• Does the page feel less complex or at least not worse?
• Would a customer/operator trust the flow?

If the answer is no for a touched surface, the implementation is not complete unless the issue is documented as pre-existing and not worsened.

Cross-Cutting / Shared Pattern Reuse

• Cross-cutting feature?: yes, workflow and product-surface guardrail.
• Interaction class(es): status messaging, action links, header actions, dashboard signals, evidence/report viewers, technical/audit detail links, browser verification, implementation close-out reports.
• Systems touched: Spec Kit templates, constitution, AGENTS instructions, PR checklist, product standards, guard tests, and existing UI bloat/productization coverage guard context.
• Existing pattern(s) to extend: UI-COV-001, Spec 370 Global Surface IA Contract, Spec 375 UI bloat guard, .specify/templates/checklist-template.md, scripts/check-ui-productization-coverage, and existing Pest guard families.
• Shared contract / presenter / builder / renderer to reuse: No runtime shared presenter/builder is introduced. Existing BadgeCatalog, BadgeRenderer, ActionSurfaceDeclaration, UiBloatScanner, UiEnforcement, and WorkspaceUiEnforcement remain the preferred implementation paths when future runtime surfaces are changed.
• Why the existing shared path is sufficient or insufficient: Existing paths cover action surface and bloat detection, but do not yet make no-legacy, product-surface impact, focused browser proof, human sanity review, surface budgets, Technical Annex rules, and implementation report fields mandatory for every future UI-affecting spec.
• Allowed deviation and why: Workflow docs and tests may introduce review vocabulary, but must not create a runtime UI framework or duplicate existing surface enums.
• Consistency impact: Future specs must use one product-surface vocabulary, one status vocabulary, and one completion report shape.
• Review focus: Confirm the implementation remains a gate and reduction contract, not a broad page rewrite.

OperationRun UX Impact

N/A - no OperationRun start or link semantics are changed by the gate itself.

Future touched product pages must demote OperationRun links from default product views unless the page is explicitly Technical Annex/System Admin or the spec records an exception. Any future action that creates, queues, deduplicates, completes, or links an OperationRun must continue to reuse the central OperationRun UX contract.

Provider Boundary / Platform Core Check

• Shared provider/platform boundary touched?: no runtime provider seam change.
• Boundary classification: platform-core product-surface vocabulary with provider-owned examples.
• Seams affected: Future provider readiness/status display and technical detail demotion rules.
• Neutral platform terms preserved or introduced: workspace, environment, provider connection, readiness, evidence, operation, audit trail, technical details, product surface.
• Provider-specific semantics retained and why: Provider-specific terms may remain in provider-owned diagnostics and Technical Annex content. They are not allowed as default product language unless needed for the user decision.
• Why this does not deepen provider coupling accidentally: The gate demotes provider payloads and provider-specific internals from platform-core product UI by default.
• Follow-up path: document-in-feature for contained exceptions; follow-up-spec for recurring provider-surface drift.

UI / Surface Guardrail Impact

Surface / Change	Operator-facing surface change?	Native vs Custom	Shared-Family Relevance	State Layers Touched	Exception Needed?	Low-Impact / N/A Note
Workflow rules, templates, AGENTS, PR checklist	no rendered surface change	N/A	product-surface review workflow	none	no	Gate-only implementation
Product Surface Contract documentation	no rendered surface change	N/A	status/action/evidence/technical annex rules	none	no	Documentation/standards contract
Guard tests	no rendered surface change	N/A	heavy-governance surface guard	none	no	Validates workflow gate exists
Optional runtime UI reduction	only if spec/plan updated first	native/shared first	depends on selected surface	page/detail	maybe	Not in default slice

Decision-First Surface Role

N/A - no rendered operator-facing surface is changed by the default slice.

Future touched pages must declare whether they are Primary Decision, Secondary Context, or Tertiary Evidence/Diagnostics surfaces and must keep one primary user question.

Audience-Aware Disclosure

N/A for rendered UI in this slice.

The gate requires future detail/status surfaces to separate customer-safe decision content, operator diagnostics, and support/raw evidence. Customer/read-only default paths must not expose raw JSON, fingerprints, OperationRun proof links, internal reason ownership, platform reason families, payloads, or debug semantics by default.

UI/UX Surface Classification

N/A for rendered UI in this slice.

Future affected pages must declare a page archetype and surface budget compliance. The Product Surface Contract must not be treated as a replacement for existing Filament action-surface classifications.

Operator Surface Contract

N/A - no new or materially refactored operator-facing page is introduced by the default slice.

Proportionality Review (mandatory when structural complexity is introduced)

• New source of truth?: yes, workflow/standards truth for product-surface completion gates. No runtime or database truth.
• New persisted entity/table/artifact?: yes, documentation/template/test artifacts only. No database persistence.
• New abstraction?: no runtime abstraction. Guard tests may add a focused test family or assertions.
• New enum/state/reason family?: no runtime enum. A canonical product-facing vocabulary is introduced as review/display guidance.
• New cross-domain UI framework/taxonomy?: yes, a documented page archetype/surface budget/Technical Annex gate, explicitly not a runtime framework.
• Current operator problem: Future specs can increase visible complexity and expose technical internals by default, causing operator confusion and reducing trust.
• Existing structure is insufficient because: Specs 370 and 375 provide contract and guard context, but templates, AGENTS workflow, PR checklist, and implementation report requirements do not yet make these checks unavoidable.
• Narrowest correct implementation: Add concise durable rules to constitution/workflow docs, update templates/checklists, add targeted guard tests, and document the product-surface contract. Avoid broad page rewrites and runtime frameworkization.
• Ownership cost: Reviewers and agents must complete additional product-surface sections. Guard tests and templates require maintenance when the workflow changes.
• Alternative intentionally rejected: A full UI redesign, visual regression framework, product-surface runtime engine, new component library, or broad hard-fail scanner expansion. These are broader than needed for v1 enforcement.
• Release truth: current-release truth. The platform is now mature enough that product-surface drift is a sellability and trust risk.

Compatibility posture

Pre-production no-legacy posture applies. Clean canonical behavior wins.

Testing / Lane / Runtime Impact

• Test purpose / classification: Heavy-Governance / surface-guard for template/workflow/product-surface gate tests; Browser only when runtime UI changes are made.
• Validation lane(s): targeted guard tests, heavy-governance lane ownership check, optional browser lane for touched UI surfaces, git diff --check, and Pint if PHP changes.
• Why this classification and these lanes are sufficient: The default implementation is workflow/guardrail breadth across templates and docs, not local runtime behavior. If UI changes occur, browser proof becomes blocking for affected surfaces.
• New or expanded test families: One targeted Spec 395 workflow/product-surface gate guard family may be added or existing guard tests may be extended.
• Fixture / helper cost impact: No database, workspace, provider, queue, or browser fixture is required for workflow guard tests. Browser fixture cost is opt-in only when runtime UI surfaces change.
• Heavy-family visibility / justification: Surface gate tests are heavy-governance owned and must not silently enter fast-feedback.
• Special surface test profile: surface-guard; browser smoke when runtime UI changes.
• Standard-native relief or required special coverage: No rendered UI means no runtime browser proof required. Any runtime UI change must use native Filament/shared primitives and focused smoke.
• Reviewer handoff: Reviewers must confirm template sections, AGENTS/PR checklist gate, contract documentation, guard coverage, no runtime UI drift unless explicitly scoped, and no completed specs rewritten.
• Budget / baseline / trend impact: Potential small heavy-governance cost. Record if a new guard family is added.
• Escalation needed: document-in-feature for contained exceptions; follow-up-spec for broad page reduction passes or CI strictness expansion.
• Active feature PR close-out entry: Guardrail / Smoke Coverage / Human Product Sanity.
• Planned validation commands:
  • git diff --check
  • cd apps/platform && ./vendor/bin/sail artisan test --compact --filter=ProductSurface
  • cd apps/platform && ./vendor/bin/sail artisan test --compact --filter=UiBloatRegressionGuard
  • cd apps/platform && ./vendor/bin/sail bin pint --dirty --format agent if PHP files change
  • Focused browser smoke only if runtime UI changes are made.

User Scenarios & Testing

User Story 1 - Future specs cannot skip product-surface impact (Priority: P1)

As a maintainer, I want every future spec that changes UI or workflow surfaces to declare product-surface impact, archetype, budget, technical demotion, browser verification, and human sanity requirements, so visible complexity cannot increase silently.

Why this priority: This is the main enforcement gap after Spec 377.

Independent Test: Inspect the updated spec template and guard test output. A future sample UI spec without Product Surface Impact, Browser Verification Plan, Human Product Sanity Check, or Merge Gate Checklist must fail or be clearly incomplete.

Acceptance Scenarios:

1. Given a future spec changes a product-facing page, When it is written from the template, Then it contains Product Surface Impact with page archetype, budgets, status vocabulary, technical detail demotion, and complexity impact.
2. Given a future spec claims no UI surface impact, When guarded UI paths changed, Then the workflow requires a checked no-impact rationale or coverage artifact.
3. Given visible complexity increases, When the spec is reviewed, Then it must explicitly justify the exception and name a follow-up if temporary.

User Story 2 - Implementations cannot complete without focused proof (Priority: P1)

As an implementation reviewer, I want every UI-affecting spec to report focused tests, browser smoke, console/runtime error checks, human product sanity status, and visible complexity outcome before merge.

Why this priority: Tests alone can pass while the product surface gets worse.

Independent Test: Inspect AGENTS/PR checklist/template updates and guard tests. The completion gate must require focused browser verification and implementation report fields for UI-affecting specs.

Acceptance Scenarios:

1. Given a spec changes UI, routes, actions, downloads, readiness, evidence, reports, provider state, restore flows, or customer output, When the implementation report is prepared, Then it lists focused tests, affected browser smoke, console/runtime checks, human sanity status, and complexity impact.
2. Given full browser suite failures are unrelated, When the report claims non-blocking status, Then it records the focused affected matrix as green, lists unrelated failures, and proves no touched surface failed.
3. Given a UI-affecting implementation skipped browser proof, When reviewed, Then the merge checklist blocks completion unless the spec is purely internal and explains why browser proof is not applicable.

User Story 3 - Product surfaces have measurable default budgets (Priority: P2)

As a product reviewer, I want page archetypes, surface budgets, status vocabulary, Technical Annex rules, deep-link demotion, and table caps documented and enforceable, so future UI reviews have concrete pass/fail criteria.

Why this priority: Reviewers need measurable rules, not generic "make it calmer" comments.

Independent Test: Review the Product Surface Contract documentation and guard tests. The contract must name budgets, archetypes, forbidden default technical links, canonical statuses, table caps, and exception format.

Acceptance Scenarios:

1. Given a future touched page has more than one readiness model or more than one primary action, When reviewed, Then it must reduce the conflict or document an explicit exception.
2. Given a future default product view exposes OperationRun or raw Evidence links, When reviewed, Then those links must be demoted to a Technical Annex/internal/audit path or justified as a Technical Annex/System Admin exception.
3. Given a hot product-facing table has more than 8 default rows, When reviewed, Then it must paginate, show more, move full detail to Technical Annex, or be classified as Technical Annex/System Admin.

User Story 4 - First reduction work stays bounded (Priority: P3)

As a maintainer, I want Spec 395 to start reducing surface drift without turning into a broad redesign, so the gate ships while page-specific reductions remain separate.

Why this priority: The gate should prevent future drift and create a bounded path for reductions, not hide a large refactor.

Independent Test: Inspect the implementation report. It must either document a low-risk reduction made through a central/touched path or explain why runtime reductions require separate follow-up specs.

Acceptance Scenarios:

1. Given a low-risk central reduction is available in a touched contract/guard path, When implemented, Then it demotes or clarifies technical details without adding visible complexity.
2. Given all runtime reductions require page-specific refactors, When the implementation closes, Then it records follow-up candidates for Receipt Page Reduction, Decision Page Reduction, and Dashboard/Inbox Link Budget rather than changing unrelated pages.

Edge Cases

• A spec changes guarded UI files only for test fixtures or non-rendered support code.
• A System Admin page legitimately needs technical detail.
• A Technical Annex page needs long tables or raw IDs.
• A customer-facing page needs evidence provenance without exposing raw evidence.
• A browser smoke matrix cannot access /system in the in-app browser but has existing Pest Browser proof.
• Existing tests assert deprecated labels or overloaded UI behavior.
• A future spec creates a new status term for internal logic but product UI maps it to canonical vocabulary.

Requirements (mandatory)

Functional Requirements

• FR-395-001: The implementation MUST update durable workflow rules so future specs include Product Surface Impact, No Legacy constraint, Browser Verification Plan, Human Product Sanity Check, and Merge Gate Checklist.
• FR-395-002: The spec template MUST require page archetype, surface budgets, technical detail demotion, status vocabulary, visible complexity impact, browser verification plan, and human sanity requirement when UI, routes, labels, readiness, statuses, actions, downloads, reports, evidence, provider state, restore flow, customer output, or page behavior changes.
• FR-395-003: The plan and tasks templates MUST carry product-surface proof into implementation phases, validation commands, browser smoke, human sanity, and implementation report tasks.
• FR-395-004: AGENTS/workflow instructions MUST require focused tests, affected regression tests, focused browser smoke, direct-route checks where relevant, console/network/runtime checks where relevant, formatting/lint/diff checks, acceptance-criteria reporting, unrelated failure triage, and browser evidence for UI-affecting specs.
• FR-395-005: PR/merge checklist MUST include no-legacy confirmation, product-surface impact, browser smoke, human sanity, visible complexity outcome, status vocabulary, technical detail demotion, table caps, deep-link demotion, and implementation report completion.
• FR-395-006: Product Surface Contract documentation MUST define mandatory page archetypes, product/technical layers, surface budgets, Technical Annex rules, canonical status vocabulary, readiness truth rule, deep-link demotion, table caps, role boundaries, action model, exception format, browser verification, human sanity review, and implementation report fields.
• FR-395-007: Future touched product-facing pages MUST declare exactly one primary archetype or document an exception with follow-up.
• FR-395-008: Future touched product-facing pages MUST satisfy surface budgets or document an exception.
• FR-395-009: Future touched product-facing default views MUST demote technical evidence-layer content to internal/audit/Technical Annex paths unless the page is Technical Annex/System Admin or has a documented exception.
• FR-395-010: Future touched pages MUST use canonical status vocabulary or explicitly map old/internal terms before display.
• FR-395-011: The implementation MUST add or update targeted guard tests proving the workflow artifacts contain required sections and at least one high-risk regression guard remains active.
• FR-395-012: The implementation MUST not rewrite completed specs or remove implementation close-out, validation results, completed tasks, smoke results, browser evidence, or review history from completed specs.
• FR-395-013: The implementation MUST perform a small first reduction step only when it is low-risk and directly connected to the touched gate/contract path. Otherwise it MUST document why runtime reductions are follow-up specs.
• FR-395-014: Any runtime UI reduction performed under this spec MUST be preceded by an update to this spec and plan with exact affected surfaces, UI/Productization Coverage, tests, browser smoke, and human sanity expectations.
• FR-395-015: The implementation report MUST list files changed, workflow/template changes, merge checklist changes, tests, browser smokes, human sanity status, no-legacy confirmation, visible complexity outcome, unrelated failures, and follow-up surface-reduction backlog.

Non-Functional Requirements

• NFR-395-001: The gate MUST keep detailed product-surface rules in one canonical Product Surface Contract location; templates, AGENTS, and PR/checklist updates MUST reference that contract and include only the completion prompts needed for implementation review instead of duplicating full rule tables.
• NFR-395-002: Rules must be measurable and reviewable, not subjective.
• NFR-395-003: Enforcement must not introduce a runtime Product Surface framework, database table, model, enum, service, presenter, or component library in v1.
• NFR-395-004: Browser verification must be focused and proportional. Full browser suite failures are non-blocking only when unrelated and documented.
• NFR-395-005: Human sanity review must be lightweight, 5 to 15 minutes, and focused on trust, clarity, actionability, and visible complexity.
• NFR-395-006: Guard tests must remain deterministic and avoid browser, database, provider, queue, or workspace fixtures unless a runtime UI change is explicitly scoped.

RBAC / Security Requirements

• SEC-395-001: UI visibility remains non-authoritative; future action and technical/audit paths must be server-authorized.
• SEC-395-002: Technical Annex/internal/audit paths must be capability-gated where they expose raw evidence, OperationRun details, provider payloads, source keys, detectors, fingerprints, UUIDs, payloads, or technical logs.
• SEC-395-003: Customer-facing default paths must not expose raw evidence, raw IDs, OperationRun proof, fingerprints, payloads, source keys, internal reason ownership, or debug semantics by default.
• SEC-395-004: Destructive/high-impact actions remain subject to ->action(...), ->requiresConfirmation(), policy/gate authorization, audit logging where mutating, and tests.

Auditability / Observability Requirements

• AUD-395-001: The implementation report must record branch, HEAD, dirty state, commands run, tests, browser smoke, human sanity status, affected surfaces, runtime files changed yes/no, and known limitations.
• AUD-395-002: Product-surface exceptions must be attributable to the active spec and include follow-up where temporary.
• AUD-395-003: No AuditLog or OperationRun records are created by the workflow gate itself.

Data / Truth Source Requirements

• DATA-395-001: The Product Surface Contract is workflow/standards truth for review and merge gates, not product data truth.
• DATA-395-002: Spec 370, Spec 375, and Spec 377 artifacts are historical inputs and context.
• DATA-395-003: Future runtime page truth remains in application code, tests, browser proof, and implementation reports.

UI Action Matrix (mandatory when Filament is changed)

N/A - the default slice changes no Filament Resource, RelationManager, Page, panel provider, action, table, form, modal, widget, or navigation entry.

If implementation later scopes a runtime UI reduction, this matrix must be completed before code changes.

Acceptance Criteria

• AC-395-001: Spec template includes Product Surface Impact, No Legacy / No Backward Compatibility Constraint, Browser Verification Plan, Human Product Sanity Check, and Merge Gate Checklist requirements.
• AC-395-002: Plan/tasks/checklist templates carry product-surface proof through implementation, validation, and close-out.
• AC-395-003: Constitution or equivalent project principles include concise durable product-surface enforcement rules without duplicating detailed implementation text.
• AC-395-004: AGENTS/workflow docs require focused browser smoke after UI-affecting implementation and forbid marking UI-affecting specs complete without browser evidence or a justified no-browser path.
• AC-395-005: PR/merge checklist includes product-surface completion gate items.
• AC-395-006: Surface budgets, page archetypes, Technical Annex rules, canonical status vocabulary, readiness truth rule, deep-link demotion, table caps, role boundaries, action model, and exception format are documented in one reviewable contract location.
• AC-395-007: At least one targeted guard test proves the new workflow/template/checklist gate exists.
• AC-395-008: Existing Spec 375 UI bloat guard or equivalent targeted architecture guard remains active and is referenced rather than duplicated unnecessarily.
• AC-395-009: No runtime UI complexity increases.
• AC-395-010: Any first reduction is low-risk, bounded, tested, browser-verified if rendered UI changes, and documented; otherwise follow-up candidates are recorded.
• AC-395-011: No completed spec history is rewritten or removed.
• AC-395-012: git diff --check passes and targeted guard tests pass.
• AC-395-013: Implementation report includes Livewire v4 compliance, provider registration location, global-search posture, destructive/high-impact action status, asset strategy, tests/browser verification, and deployment impact.

Key Entities (documentation/workflow only)

• Product Surface Contract: Review and merge-gate contract describing page archetypes, budgets, Technical Annex rules, status vocabulary, table caps, deep-link demotion, and exception format.
• Page Archetype Declaration: A required future-spec declaration of a touched page's single primary product role.
• Surface Budget Exception: A documented exception with page, violated budget, reason, non-customer/product-facing rationale, and follow-up if temporary.
• Technical Annex: Internal/audit/technical detail path that holds raw and diagnostic details outside the default product layer.
• Implementation Completion Gate: Required close-out proof fields for tests, browser smoke, human sanity review, no-legacy posture, complexity outcome, and unrelated failure triage.

Success Criteria

• SC-395-001: A future UI-affecting spec generated from templates cannot omit product-surface impact, browser verification, human sanity, and merge-gate questions.
• SC-395-002: Reviewers can determine from the PR checklist whether visible complexity increased, stayed neutral, or decreased.
• SC-395-003: Product-surface exceptions are attributable and cannot remain silent.
• SC-395-004: The implementation changes no runtime UI by default and no runtime UI complexity increases.
• SC-395-005: Targeted guard tests prove the workflow gate is present.

Out Of Scope

• Full TenantPilot navigation rebuild.
• Visual redesign of every page.
• New design system or component library.
• New product capability, readiness domain, evidence domain, provider feature, restore feature, or report feature.
• Broad Filament resource rewrite.
• New persisted data, migrations, models, services, jobs, queues, OperationRun types, routes, policies, or assets for the default gate slice.
• Creating a generic runtime product-surface framework.
• CI hard-fail expansion for all UI bloat scanner rules before false-positive behavior is stable.
• Manual system-panel browser fixture procedure from Spec 377.
• Rewriting or normalizing completed specs.

Merge Gate Checklist

Spec 395 may be implemented and merged only when:

• Spec template includes No Legacy constraint.
• Spec template includes Product Surface Impact.
• Spec template includes Browser Verification Plan.
• Spec template includes Human Product Sanity Check.
• Spec template includes Merge Gate Checklist.
• AGENTS/workflow docs require focused browser smoke after UI-affecting implementation.
• AGENTS/workflow docs require affected regression tests.
• AGENTS/workflow docs forbid legacy compatibility shims by default.
• Surface budgets are documented.
• Page archetypes are documented.
• Technical Annex rules are documented.
• Canonical status vocabulary is documented.
• Deep-link demotion rules are documented.
• Table cap rules are documented.
• Implementation completion gate exists.
• At least one targeted architecture/regression guard is added or updated where practical.
• Focused Spec 395 tests pass.
• Focused browser smoke passes when runtime UI is touched, or no-browser applicability is justified.
• Pint passes when PHP changes.
• git diff --check passes.
• Human product sanity check is completed when runtime/product-surface changes are made.
• Visible UI complexity did not increase.

Risks

• Gate becomes checklist theater: Mitigate with guard tests, concrete required report fields, and PR checklist items.
• Too much enforcement blocks technical pages: Mitigate with explicit Technical Annex and System Admin exceptions.
• Browser verification slows development: Mitigate with focused affected smoke, not mandatory full suite.
• False positives in guard tests: Mitigate by reusing existing Spec 375 guard behavior and making ambiguous findings manual review.
• Surface reduction becomes too broad: Mitigate by limiting runtime reductions to low-risk touched paths and moving broader passes to follow-up specs.

Assumptions

• Existing Spec 370, 375, and 377 artifacts remain available as historical context.
• Existing UiBloatRegressionGuardTest, UiBloatScanner, UI coverage guard, and test lane manifest provide enough guard infrastructure for Spec 395 without new dependencies.
• The implementation will use Sail for Laravel/Pest/Pint commands.
• No application code change is required for the default enforcement slice.

Open Questions

• None blocking preparation.
• Non-blocking implementation decision: whether the Product Surface Contract lives only in existing docs or gets a new docs/product/standards/product-surface-contract.md file. The implementation should choose the narrowest discoverable location and avoid duplicate standards text.

Follow-Up Spec 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.