ahmido
4a50c6a580
Automated PR created by Codex via Gitea API. Co-authored-by: Ahmed Darrazi <ahmed.darrazi@live.de> Reviewed-on: #466
279 lines
9.1 KiB
Markdown
279 lines
9.1 KiB
Markdown
# Product Surface Contract
|
|
|
|
> Canonical review and merge-gate contract for product-facing UI surfaces.
|
|
> This is workflow and standards truth only. It is not a runtime framework,
|
|
> database model, presenter layer, enum family, or component library.
|
|
|
|
**Last reviewed**: 2026-06-21
|
|
|
|
## Purpose
|
|
|
|
TenantPilot product surfaces must help the current user make a safe decision.
|
|
They must not expose everything the system knows by default.
|
|
|
|
This contract applies when a spec adds, removes, renames, or materially changes
|
|
any reachable product surface, including pages, routes, navigation entries,
|
|
tables, forms, modals, drawers, wizard steps, actions, customer views,
|
|
status/readiness/evidence presentation, downloads, reports, provider state,
|
|
restore flows, or workspace/environment context presentation.
|
|
|
|
Docs-only, template-only, tooling-only, and test-only changes may record
|
|
`N/A - no rendered UI surface changed` when no reachable rendered UI changes.
|
|
|
|
## No Legacy Posture
|
|
|
|
TenantPilot is pre-production for this contract. Future product-surface work
|
|
must prefer clean canonical behavior over compatibility with old labels,
|
|
action keys, local status wording, duplicated UI, hidden routes, fallback
|
|
readers, or legacy fixtures unless an active spec explicitly approves a
|
|
compatibility exception.
|
|
|
|
Do not show old and new concepts together just to preserve pre-production UI
|
|
behavior.
|
|
|
|
## Product Layers
|
|
|
|
Every product-facing default view must separate these layers:
|
|
|
|
- **Product Layer**: visible by default. Shows status, reason, impact, one
|
|
dominant next action, compact business context, customer-safe evidence
|
|
summary, and a small status summary when useful.
|
|
- **Technical Evidence Layer**: hidden by default or moved to an internal
|
|
technical/audit path. Holds OperationRuns, raw evidence IDs, source keys,
|
|
detectors, fingerprints, UUIDs, payloads, provider payloads, diff internals,
|
|
logs, and full audit trails.
|
|
|
|
Product-facing default pages must not expose Technical Evidence Layer content
|
|
by default. Use one secondary/internal action such as `View audit trail`,
|
|
`View internal evidence details`, or `View technical details`, with appropriate
|
|
authorization.
|
|
|
|
## 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, reduce it to one archetype, split the page, or
|
|
document a temporary exception with a follow-up.
|
|
|
|
## Surface Budgets
|
|
|
|
Product-facing pages must satisfy these budgets unless 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 the default view.
|
|
- Max 0 OperationRun links in the default view.
|
|
- Max 0 raw Evidence deep links in the default view.
|
|
- Max 0 Source Key, Detector, or Technical Dimension blocks in the default view.
|
|
- Max 0 repeated readiness/status summaries on the same page.
|
|
|
|
Exceptions must include page, violated budget, reason, why the page is not
|
|
customer/product-facing if applicable, and a follow-up when 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
|
|
|
|
Old or internal terms must be mapped before display. Do not expose `Healthy`,
|
|
`OK`, `Warning`, `At risk`, `Degraded`, `Partially ready`, `Likely stale`,
|
|
or similar terms as independent top-level product states unless an active spec
|
|
records a mapping or exception.
|
|
|
|
## Readiness Truth
|
|
|
|
A page may show only one top-level readiness/status truth for a concept.
|
|
|
|
Required shape:
|
|
|
|
```text
|
|
Provider readiness: Expired
|
|
Reason: Verification is stale.
|
|
Next action: Verify provider.
|
|
```
|
|
|
|
Forbidden shape:
|
|
|
|
```text
|
|
Provider: Healthy
|
|
Verification: Stale
|
|
Permissions: Missing
|
|
Readiness: Ready
|
|
Action: Needs attention
|
|
```
|
|
|
|
Future readiness-producing specs must declare the canonical source, consumer
|
|
pages, display state, blocking reasons, and whether the state is customer-safe.
|
|
|
|
## Deep-Link Demotion
|
|
|
|
Default product views must not expose a graph of internal objects.
|
|
|
|
Demote these links from default product views:
|
|
|
|
- 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 include:
|
|
|
|
- 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 as secondary/internal actions only.
|
|
|
|
## Table Caps
|
|
|
|
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 and System Admin pages may show more rows, but they must be
|
|
clearly technical/system-facing.
|
|
|
|
## Action Model
|
|
|
|
Every product-facing page must define:
|
|
|
|
- Primary action.
|
|
- Secondary actions.
|
|
- Danger/destructive actions.
|
|
- Technical/audit actions.
|
|
|
|
There may be only one primary action. Destructive or high-impact actions must
|
|
be visually separated, authorization-checked, audit-logged when mutating, and
|
|
confirmation-protected.
|
|
|
|
## Role And Audience Boundaries
|
|
|
|
Customer/read-only default paths must not expose raw evidence, raw IDs,
|
|
OperationRun proof, fingerprints, payloads, source keys, internal reason
|
|
ownership, platform reason families, or debug semantics by default.
|
|
|
|
Operator diagnostics may expose more detail through progressive disclosure.
|
|
Support/raw evidence must be capability-gated where the audience model
|
|
distinguishes support or platform users from ordinary operators.
|
|
|
|
Provider-specific terms remain Technical Annex or provider diagnostics detail
|
|
unless the immediate product decision requires them.
|
|
|
|
## Browser Verification
|
|
|
|
Every implemented spec that changes rendered UI, routes, actions,
|
|
authorization, downloads, reports, readiness, evidence, provider state,
|
|
restore flows, customer output, or Product Surface Contract behavior must
|
|
include focused browser verification.
|
|
|
|
If no runtime UI files change, record browser proof as
|
|
`N/A - no rendered UI surface changed`.
|
|
|
|
If runtime UI changes, the implementation report must record affected routes,
|
|
the focused browser path, primary interaction executed, expected state,
|
|
console/runtime/network result, Livewire/Filament errors if any, and whether
|
|
any full-suite browser failures are unrelated.
|
|
|
|
## Human Product Sanity
|
|
|
|
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, and 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?
|
|
|
|
For docs/template/test-only contract changes, record this as a workflow sanity
|
|
check rather than a rendered-page review.
|
|
|
|
## Implementation Report Fields
|
|
|
|
Every Product Surface Contract implementation close-out must state:
|
|
|
|
- Active spec and selected slice.
|
|
- Branch, HEAD, and dirty state.
|
|
- Files changed.
|
|
- Runtime UI files changed yes/no.
|
|
- UI impact or no-impact decision.
|
|
- Product Surface exceptions, if any.
|
|
- Browser proof or `N/A - no rendered UI surface changed`.
|
|
- Human product sanity result.
|
|
- Visible complexity outcome.
|
|
- No-legacy confirmation.
|
|
- Completed-spec rewrite assertion.
|
|
- Tests/checks run and results.
|
|
- Livewire v4 compliance.
|
|
- Provider registration location.
|
|
- Global search posture.
|
|
- Destructive/high-impact action posture.
|
|
- Asset strategy and whether `filament:assets` is required.
|
|
- Deployment impact for env vars, migrations, queues, scheduler, storage, and assets.
|
|
- Unrelated failures and follow-up candidates.
|
|
|
|
## Completed Specs
|
|
|
|
This contract applies to future and active specs. Completed historical specs
|
|
must not be rewritten, normalized, reopened, or stripped of close-out,
|
|
validation, task, smoke, browser, or review history just to satisfy new gate
|
|
wording.
|