105 lines
7.0 KiB
Markdown
105 lines
7.0 KiB
Markdown
# 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.
|