surface-check — the driver for THE UI SURFACE CHECKLIST

<!-- rules:stamp -->

Rules from common-docs/systems/platform/ui-shell/FEATURE.md — edit there, never here (python3 common-docs/meta/scripts/one_home.py --write).

1. Delete means archive, everywhere. A delete that does not archive is a defect.
2. A menu regroup ships as a side-by-side demo page with a what-goes-where list, never as a direct change.
3. Every surface mounts the canonical menu. Use NonEditableContextMenu or EditableContextMenu from features/context-menu-v3/. Never use a bespoke DropdownMenu or a raw contextmenu handler, and never keep both.
4. A menu without a source is a defect. A menu with no contentSource, entity or surfaceName opens with every verb dark. Fix these before unwired surfaces.
5. Lists built on EntityListPage inherit the row menu through ItemContextMenu. They need their own wiring only for surface-specific sections.
6. A window or overlay mounts its own menu. It never delegates to the page under it.
7. Reuse the domain's action registry. Never create a second one.
8. Secret-bearing surfaces follow VaultContextMenu. Pass getApplicationScope, force selection: "", put names and field keys in the content (never values or notes), and pass no entity.
9. Done means the menu opens clean. The console shows no INERT MENU or VALUE MAPPING GAP scream.
10. Chat is a universal agent host. Never bind a page-agent roster to it.
11. Anything with an id shows it through the one canonical id component (display plus one-click copy).
12. Flagship and first-run screens get a bespoke elevated stage, not the 28px app-chrome controls.
13. Before a link goes to Arman, every screen on its path passes the Steve Jobs bar (walked and fixed by an Opus reviewer).
14. Admin tables filter, search and sort on the server, and people are picked by name or email, never by id.
15. Wasted vertical space is the worst sin; every status shown is backed by real state.
16. A new output style or menu layout is a NEW function used only by the new path; never thin a shared builder.
17. A page fetches only what it shows, each thing once; every removed fetch ships its on-engagement load.

<!-- rules:stamp-end -->

Read CHECKLIST.md once. It is the one list. This file is how you run it on a surface end to end without coming back with questions.

The doctrine (Arman, 2026-08-22 — quoted)

• "When a surface passes, then we know it absolutely meets all of these things." Every section gets a verdict; "didn't look" is a fail.
• "These are agents who are gonna be empowered to also fix and improve and enhance." You fix. A finding without a fix is only acceptable when the fix is an ARMAN-class decision (product semantics) — then you log a chip / review row and keep going.
• "If they come back to me with questions, that just kills the whole thing." The checklist's DECIDE rules exist so you never ask. Decide by the rule, log the decision, move on.
• "Have a way to know which ones haven't been checked in a long time or have never been checked." Every verifier-passed run ends by writing the ledger row. An unlogged check did not happen; an unverified worker run is only a candidate.

Invocation

/surface-check <surfaceName | route | overlayId> or a claimed surface-certification Work Loop contract. A brand-new surface with nothing built yet goes through surface-authoring first; this skill checks one that exists.

This skill never selects or claims fleet work. In an autonomous run, the work_loop(action="claim") result is the sole claim authority. Do not query or update ui.ui_surface.check_claimed_*; those columns are a legacy display aid, not a lock. No target in the claimed contract means no work: return to the coordinator for another atomic claim. (Exception: a worker dispatched under the surface campaign — surface-authoring/references/campaign-worker.md — claims through that brief's expiring check_claimed_* query, because cloud sessions have no Work Loop tool. One claim system per run, never both.) A direct human request may name a surface without Work Loop, but it still needs independent verification before it is certified.

Fleet eligibility includes agent-native surfaces. Chat, Agent Builder, runners, tests, and window panels receive the same check when registered. S5 tests outside-helper access and native/resident isolation separately; a saved binding or placement is never approval to inherit page values.

Step 1 — Gather, briefly (≤ 10 minutes)

1. Manifest (features/surfaces/manifests/<x>.manifest.ts) → label, readiness, inheritsFrom, values, writeTargets, urlPattern/overlayId.
2. The route (route-to-surface.ts) and the feature dir (app/... → features/<name>/); its FEATURE.md + Change Log; docs/handoffs/* mentioning it.
3. Claimed contract + last ledger entry: select last_check from ui.ui_surface where name = … — prior failures and the contract's required rule version first.
4. Open the page on the live site (https://www.aimatrx.com, signed in as admin@admin.com, e.g. node scripts/real-tests/pw.mjs <run> signin), desktop 1280×800, right-click once with the console open. Certification is read on live once a release carries the change (push, then check). The local preview (pnpm preview:start) is only a fix-and-look loop while you repair; it is never certification evidence.

Browser availability. Live proof is a completion gate. If the isolated in-app Browser is unavailable, finish safe static repairs, record the exact missing proof, and settle the Work Loop item with retry; never complete it and never write certification. The host has one machine-wide in-app Browser, so parallel workers may share neither a tab nor browser state: the certification coordinator serializes the live Browser lane while static audits, repairs, and tests remain parallel. Use it only while the coordinator has granted this claim ownership. Each live pass starts from a fresh isolated session, closes its tabs, and resets Browser state before the next worker or verifier receives the lane. Evidence captured during overlapping Browser use is invalid and must be rerun.

Step 2 — Run S1 → S18 in order, fixing as you go

For each section in CHECKLIST.md: invoke the owning skill when you touch that area (they hold the rule bodies and the verification protocol), run the named check commands scoped to this surface's files, fix, re-run. Record one of: pass · fixed (what, commit) · na (one-line why) · deferred-visual (code done + statically checked; name the exact eyes-on step) · arman (decision needed → chip id / review row) · blocked (what blocks, never "unclear").

deferred-visual, arman, or blocked is an honest worker verdict but not a certification verdict. It settles as retry or defer, never complete.

Rules while fixing:

• Reuse → Extend → Compose → Create. Invoke no-dead-ends before building any surface; context-docs before editing any FEATURE.md; code-splitting before any dynamic import; supabase-realtime before any .channel(; type-safety for any type error.
• Never remove, rename, or hide a feature to make a section pass (THE LOSSLESS LAW). Never disable a check. Never eslint-disable.
• Batch commits per section (git add <your files> → git commit --only -m "surface-check(<surface>): S6 context menu — …"), push often. Shared checkout: never tree-wide git ops; never verify a variant by editing a production file in place.
• Periodic integration, type-sync, and release sweeps do not pause the check. Checkpoint the coherent owned set and continue immediately. Suspend only an exact overlapping path while it is isolated; keep all non-overlapping work moving.
• Mobile = in-app browser at 375×812 (resize_window mobile preset), both themes (document.documentElement.classList.toggle('dark')).

Step 3 — Verify live (non-negotiable)

Use the real route or overlay with representative real data, never a manufactured test-only state. Capture four fresh viewport/theme proofs: desktop light, desktop dark, mobile light, mobile dark. The set also proves the top edge (S8), desktop context menu (S6), and mobile long-press sheet (S9). Record the tested URL/overlay, fixture identity, timestamp, commit, and a durable reference for each artifact (file/attachment id, persisted browser artifact, or committed path; never an expiring signed URL). Console: zero INERT MENU / VALUE MAPPING GAP screams and zero hydration errors. pnpm type-check clean for your files. Error Inspector clean on a normal load. Static analysis or a deferred-visual verdict can support repair, but can never satisfy this step.

A clean load is not a workflow proof. For every primary user outcome and each declared write target, run one representative real-data path end to end (or the contract's safe restored canary), wait for every asynchronous action to settle, and inspect the resulting UI, console, and Error Inspector again. A button click, spinner, optimistic state, or session-complete shell is not proof that the downstream agent/write succeeded. Record the terminal result and restore the canary. If an unsafe side effect cannot be restored, the item contract must provide a safe fixture; never silently skip the outcome.

The tested dependency graph must be reproducible from the recorded commit. A workspace package build copied over node_modules, an unpublished package subpath, a locally patched install, or any other future-only dependency overlay may unblock diagnosis but is not certification evidence. Publish and adopt the package (or use the released API), perform a clean install/preview, and rerun the entire live matrix. Otherwise settle retry with the exact package boundary.

When a local preview is used for a repair loop, it must also prove it is serving that checkout, not merely answer on the expected port. Before treating a route response as evidence, record the preview checkout SHA, confirm Next's inferred workspace root is that checkout, and confirm the generated app-path manifest contains the target. A parent directory's unrelated lockfile can make Next infer the wrong root and return a confident 404 for a real route. Move the clean checkout outside that poisoned parent or repair the managed preview; never count the 404 or the repaired reload until the served root and SHA match.

Step 4 — Submit a certification candidate

{
  "surfaceName": "matrx-user/<local-slug>",
  "checklistVersion": 2,
  "ruleVersion": "<required by claimed contract>",
  "commit": "<sha>",
  "worker": "agent:surface-check/<surface-local-slug>",
  "workerResult": "candidate-pass",
  "verificationDepth": "live",
  "sections": {
    "S1": {"status": "pass", "evidence": ["<durable ref>"]},
    "S2": {"status": "fixed", "note": "added 3 values, 1 always", "evidence": ["<durable ref>"]}
  },
  "liveProof": {
    "desktopLight": "<durable ref>",
    "desktopDark": "<durable ref>",
    "mobileLight": "<durable ref>",
    "mobileDark": "<durable ref>",
    "contextMenu": "<durable ref>",
    "longPress": "<durable ref>",
    "console": "clean at <timestamp>",
    "errorInspector": "clean at <timestamp>",
    "target": "<route or overlay + representative record>"
  },
  "notes": "<3 lines max>"
}

Every S1–S18 key is mandatory; na carries a reason. candidate-pass requires only pass/fixed/na, checklist version 2, the contract's current rule version, and all live-proof fields. Send this candidate through Work Loop complete; the service creates the independent verifier. The worker never writes last_checked_at, last_checked_by, or a final result: pass. For a direct human-requested run, dispatch a fresh verifier before ledger promotion.

The verifier starts from a fresh Browser session and current checkout, reads the original claimed contract plus worker candidate, attacks the changed surface, and re-runs the live matrix. It does not repair its own finding. Rejection names the failed section and durable evidence; Work Loop creates repair/retry work. Only a passed verifier writes ui.ui_surface.last_checked_* with the candidate, verifier, verifiedAt, and result: "pass", then releases any legacy display claim fields. This makes the ledger the durable per-surface checklist without letting the builder certify itself.

Then: agent-review-queue row for anything Arman should sample; tangential work goes to a subagent you dispatch with a named lane (law 7) — or, as a claimed Work Loop worker, back to your coordinator in your report — never a spawn_task chip; FEATURE.md Change Log line surface-check <date>: candidate (<n> fixes) and, after verifier promotion, certified r<ruleVersion>.

Admin view of the ledger: /administration/ui/surfaces (Last checked column, never-checked filter — see the skill's open items if not yet built).

What is ARMAN-class (log, don't ask)

Product semantics only: creating a new parent surface or re-homing one in the hierarchy (and anything that edits a SIBLING's manifest — you were scoped to one surface and other agents may be inside the others), whether a feature exists, a grouping of menu rows not yet approved, and whether a text field's length matters when THE LENGTH RULE is genuinely ambiguous (default: ON if typicalCharCount ≥ 1,000, else OFF — log it). Context approval must cite its actual approval provenance; it is not created by certification.

NOT Arman-class — decide these yourself: whether THIS surface's existing inheritsFrom is correct, its own label/readiness/groups, every value and write target it should declare, and every fix the sections name. Everything else has a rule — apply it.

The blast-radius screamer — run it BEFORE you touch vocabulary

pnpm check:surface-impact <surface> is the only thing in the repo that can see who is mapped to a Surface Value, because a value is a NAME that outside things bind to by string and TypeScript never sees it. It reads the live DB and reports five consumer kinds — agent bindings (platform.associations), shortcut mappings (agent.shortcut, checked by nothing else), write twins (updates_value), data-surface-value DOM attributes, and descendants — plus SHADOWED_VALUE where a child re-declares what its parent conveys.

Per-value verdicts: DO NOT RENAME/REMOVE (live consumers) · inherited — changes ripple (descendants depend on the name) · safe to change.

Rules: run it before AND after any vocabulary change; --strict exits 1 on breakage; every consumer it lists is migrated in the SAME change. A baseline name on a skipBaselineValues surface is a WARN (the launch floor fills it) — never "fix" that by re-adding baselines to a surface that deliberately opted out. It is also an advisory release gate ("Surface value blast radius").

Open items for this system (build when you hit them; out of scope → dispatch a subagent with a named lane)

1. Ledger columns — LIVE (ui.ui_surface.last_checked_at / last_checked_by / last_check; check_claimed_* is display-only, never lock authority).
2. /administration/ui/surfaces Checked column + never/stale filter — LIVE (sortable; never-checked first). Still missing: the per-section result popover reading last_check.sections.
3. A check:textareas ratchet (NOT BUILT — no such script yet) — non-Pro textarea count per feature, baseline only goes down (S7 has no guard today; ~528 sites).
4. Structural guards for S5 — a static candidate report that compares explicit Mandate/agent launch points with invocation-contract records, manifest roles, and live bindings; plus a guard that rejects unapproved automatic inheritance for native subject agents and permanent residents. Historical tool-call reduction still requires runtime telemetry, so the static report is a scout, not proof.
5. Add a structural campaign-eligibility guard that requires every registered surface, including agent-native routes, to carry the current S5 contract and evidence; until it lands, the explicit S5 gate above is mandatory.
6. create<X>Scope builders are hand-written and drift silently — nothing validates that a builder's param keys match its manifest's value names. A generated ValueNameOf<M> type would make a rename a compile error.