⚠️ BEFORE CAPTURING ANY BASELINE: verify CARD-CONTRACT.md first
The AgentCard anatomy changed on 2026-07-20 — recomposed to the evolved-D synthesis (status-first, two-row, actions-in-flow) in 76574e20f3 under #15536.
apps/agentos/CARD-CONTRACT.md did not follow it for a week. It kept describing the pre-recompose anatomy and took three unrelated edits in the meantime (ac4b089c00, 90de2ce569, e59c7f19e4). Realigned in PR #16044.
Why this warning sits in the body rather than a comment: a baseline harness is the one artifact that turns a stale contract into permanent wrong ground truth. Baselines do not merely record the old anatomy — they make it the thing every future diff is judged against, so the failure surfaces as a flood of false positives on correct changes, blaming everyone else. That is the most expensive way to discover it.
Nothing was actually captured against the stale contract: this leaf was deferred from v13.2 on 2026-07-16 as quality infrastructure outside release-gate scope, so the stale-anatomy window opened and closed with no one inside it. The instruction stands anyway, because the next capture may not be so lucky.
So: before capturing, confirm CARD-CONTRACT.md matches the component it claims to describe — check git log on both and compare dates. Per @neo-opus-grace, who asked for this to live where the next reader will look rather than in a PR body and a mailbox.
Context
T7.24 of Epic #14560 (map v1.1) — the quality-floor leaf that keeps the design-led surface AT the SSOT bar across the sprint's many hands: pixel-level baselines for the cockpit's core states. Filed under the decomposition sprint (D#14561).
The Problem
Nineteen leaves by many claimants against one design SSOT = drift by a thousand cuts (a wrong rail width here, an off-token color there) that per-leaf review can't reliably catch. The visual bar needs a mechanical guard, scoped to where pixels are the contract.
The Architectural Reality
Playwright screenshot assertions inside the existing custom-config discipline (a named visual config; NEO_TEST_SKIP_CI governs any CI exclusion; baselines committed).
Deterministic-render discipline: fixture roster (no live data in baselines), animations settled (prefers-reduced-motion forced in the harness), fixed viewport set from the #14592-derived breakpoints.
Scope floor: the token demo surface (#14578's consumer), one AgentCard per state, the health bar categories, one chip row, the default shell layout — the states where a pixel diff means a design regression, not content churn.
The Fix
One PR: the visual config + fixture mounts + committed baselines for the floor set + a documented update ritual (a baseline change is a design decision — reviewed as one, per the epic's recorded-decision rule).
Acceptance Criteria
Named visual config runs the floor set against committed baselines (deterministic: fixtures, settled motion, fixed viewports).
A seeded geometry change fails the suite (the guard proven for what this instrument can actually see). Amended 2026-08-15 with measurement — the original read "a seeded off-token color change fails the suite", and that is the wrong instrument. A seeded token change alters 21% of a captured image (53,124 px) and this suite counts zero of it, because the config sets maxDiffPixelRatio: 0.001 but never sets the per-pixel threshold; Playwright's 0.2 default decides nothing differs, so the ratio never gets anything to count. That default is doing its job — it absorbs AA drift so geometry baselines survive as rendered-platform artifacts. Colour correctness belongs to static SCSS analysis, which already exists (check-agentos-theme.mjs: skin parity + token-only consumption, no baselines, no threshold, no platform drift) and does not cover the workstation. Split out so each instrument owns what it can prove.
CI posture explicit (NEO_TEST_SKIP_CI if excluded; never hardcoded skips).
Out of Scope
Interaction/e2e coverage (#14607/#14613) · a11y (T7.25) · per-leaf unit specs. Colour/token correctness — moved to static SCSS analysis; this suite owns geometry. See the amended AC-2 and the two measurement comments on this ticket.
Related
Epic #14560 (parent) · blocked-by #14593/#14594 (the primitives it baselines) · #14592 (viewports) · D#14561.
Live latest-open sweep: fresh this window; no equivalent. A2A sweep: clean. Structure-map gate: N/A — test harness leaf.
tobiu referenced in commit cfabc34 - "feat(agentos): visual-regression baseline harness — deterministic goldens for the design-gate scope floor (#14618) (#15007) on Jul 11, 2026, 2:37 AM
tobiu referenced in commit 76574e2 - "feat(agentos): recompose AgentCard to the evolved-D synthesis anatomy (#15536) (#15565) on Jul 20, 2026, 9:43 PM
tobiu referenced in commit 3e2a6d8 - "feat(build): the theme guard covers the workstation, and the off-token proof lands without pixels (#17205) on Aug 16, 2026, 2:51 AM
tobiu referenced in commit 1cd9d3f - "style(agentos): tab strip indicators and the FM container ground join the token layer (#17543) (#17544) on Aug 22, 2026, 4:36 PM
Context
T7.24 of Epic #14560 (map v1.1) — the quality-floor leaf that keeps the design-led surface AT the SSOT bar across the sprint's many hands: pixel-level baselines for the cockpit's core states. Filed under the decomposition sprint (D#14561).
The Problem
Nineteen leaves by many claimants against one design SSOT = drift by a thousand cuts (a wrong rail width here, an off-token color there) that per-leaf review can't reliably catch. The visual bar needs a mechanical guard, scoped to where pixels are the contract.
The Architectural Reality
NEO_TEST_SKIP_CIgoverns any CI exclusion; baselines committed).prefers-reduced-motionforced in the harness), fixed viewport set from the #14592-derived breakpoints.The Fix
One PR: the visual config + fixture mounts + committed baselines for the floor set + a documented update ritual (a baseline change is a design decision — reviewed as one, per the epic's recorded-decision rule).
Acceptance Criteria
maxDiffPixelRatio: 0.001but never sets the per-pixelthreshold; Playwright's 0.2 default decides nothing differs, so the ratio never gets anything to count. That default is doing its job — it absorbs AA drift so geometry baselines survive as rendered-platform artifacts. Colour correctness belongs to static SCSS analysis, which already exists (check-agentos-theme.mjs: skin parity + token-only consumption, no baselines, no threshold, no platform drift) and does not cover the workstation. Split out so each instrument owns what it can prove.NEO_TEST_SKIP_CIif excluded; never hardcoded skips).Out of Scope
Interaction/e2e coverage (#14607/#14613) · a11y (T7.25) · per-leaf unit specs. Colour/token correctness — moved to static SCSS analysis; this suite owns geometry. See the amended AC-2 and the two measurement comments on this ticket.
Related
Epic #14560 (parent) · blocked-by #14593/#14594 (the primitives it baselines) · #14592 (viewports) · D#14561.
Live latest-open sweep: fresh this window; no equivalent. A2A sweep: clean. Structure-map gate: N/A — test harness leaf.
Origin Session ID: a28f1415-37a4-4a5a-a3e4-b56adf6274ec Retrieval Hint: "FM cockpit visual regression baselines design drift guard"