chore(docs): sweep stale visual-baseline references + queue gate-hardening convoy #135

Merged

varutasu merged 1 commit from chore/sweep-visual-baseline-doc-drift into main

2026-06-12 21:30:34 -04:00

varutasu commented

2026-06-12 21:21:05 -04:00

(Migrated from github.com)

Why

PR #58 (`83a358b`, 2026-06-02) committed the first Linux visual baseline, resolving the `seed-visual-baselines-on-linux` convoy. But the cleanup sweep across the docs that referenced it as "queued / not yet done" never landed. Three files still describe the world as if PR #58 hadn't happened, which makes onboarding any agent (human or AI) into the visual-diff pipeline confusing — they read "no baseline yet" + a Docker-recipe seeding instruction, when the baseline has been on `main` for 10 days.

Surfaced organically while investigating whether `seed-visual-baselines-on-linux` still had work to do. The answer is "no, but the post-resolution sweep does."

What

Pure doc / comment changes. Zero code behavior delta.

File	Before	After
`tests/visual/homepage.spec.ts`	Multi-paragraph "FIRST RUN" + "SEEDING THE BASELINE (post-merge follow-up)" docblock referencing a queued convoy	Current-state docblock referencing PR #58 as the seed origin, with the Linux-only re-seed recipe retained
`playwright.config.js`	"Per Decision 4, we don't commit baselines this convoy" + reference to queued seed convoy	Cross-platform CAUTION about the missing `{platform}` token (still live) with current paths to re-seed
`AGENTS.md` § Visual baselines	"none committed yet. `tests/visual/screenshots/` is intentionally absent..."	Documents the committed baseline at PR #58, both Linux re-seed paths, and the known-staleness window for the current baseline relative to the glass redesign briefs
`AGENTS.md` § Screenshot diff	"First Screenshot diff run after `adopt-playwright-smoke` will fail at the test step because no baseline exists yet"	Documents the current advisory-not-gating posture and points at the new `harden-visual-diff-gate` convoy seed
`.convoys/harden-visual-diff-gate.md` (new)	—	Two-step convoy: (1) re-seed baseline against post-glass-redesign `main`, (2) drop `continue-on-error: true` from `visual-diff.yml`. Captures D1-D3 + R1-R3

What this PR does not do

Does not regenerate the actual `home.png` baseline. That's Step 1 of the new `harden-visual-diff-gate` convoy; doing it here would scope-creep into territory that needs a Linux runner dispatch (CT 111) and operator decision on whether to also add `maxDiffPixelRatio` cushion.
Does not drop `continue-on-error: true` from `visual-diff.yml`. Same reason — flipping that without first re-seeding causes every UI-touching PR to fail against a 10-day-stale reference image.

Test plan

`npm run lint` passes (1 pre-existing warning, unrelated)
No `.js` / `.ts` runtime behavior changed
CI passes on this PR — gates that fire:
- `Lint` ✓
- `Forbidden patterns (8 checks)` ✓
- `Unit tests (vitest)` ✓
- `Convoy metrics gate` — no-op (title prefix is `chore(docs):` not `convoy:`)
- `Screenshot diff` — triggers because `tests/visual/**` is in the path filter; expected to surface a stale-baseline artifact + PR comment (advisory only; doesn't block merge per the `continue-on-error: true` we just documented)
After merge: agents reading the docs no longer get false-positive references to a resolved convoy

PR #58 (`83a358b`) — original baseline seed
PR #18 (`7b6f751`) — `adopt-playwright-smoke` Decision 4 (`continue-on-error` end state)
PR #132 (`f228c09`) — `visual-diff.yml` migration to self-hosted axiom runner
`.convoys/harden-visual-diff-gate.md` (new in this PR) — the actual gate-hardening work

Made with Cursor

## Why PR #58 (\`83a358b\`, 2026-06-02) committed the first Linux visual baseline, resolving the \`seed-visual-baselines-on-linux\` convoy. But the cleanup sweep across the docs that referenced it as "queued / not yet done" never landed. Three files still describe the world as if PR #58 hadn't happened, which makes onboarding any agent (human or AI) into the visual-diff pipeline confusing — they read "no baseline yet" + a Docker-recipe seeding instruction, when the baseline has been on \`main\` for 10 days. Surfaced organically while investigating whether \`seed-visual-baselines-on-linux\` still had work to do. The answer is "no, but the post-resolution sweep does." ## What Pure doc / comment changes. Zero code behavior delta. | File | Before | After | |---|---|---| | \`tests/visual/homepage.spec.ts\` | Multi-paragraph "FIRST RUN" + "SEEDING THE BASELINE (post-merge follow-up)" docblock referencing a queued convoy | Current-state docblock referencing PR #58 as the seed origin, with the Linux-only re-seed recipe retained | | \`playwright.config.js\` | "Per Decision 4, we don't commit baselines this convoy" + reference to queued seed convoy | Cross-platform CAUTION about the missing \`{platform}\` token (still live) with current paths to re-seed | | \`AGENTS.md\` § Visual baselines | "none committed yet. \`tests/visual/__screenshots__/\` is intentionally absent..." | Documents the committed baseline at PR #58, both Linux re-seed paths, and the known-staleness window for the current baseline relative to the glass redesign briefs | | \`AGENTS.md\` § Screenshot diff | "First Screenshot diff run after \`adopt-playwright-smoke\` will fail at the test step because no baseline exists yet" | Documents the current advisory-not-gating posture and points at the new \`harden-visual-diff-gate\` convoy seed | | \`.convoys/harden-visual-diff-gate.md\` *(new)* | — | Two-step convoy: (1) re-seed baseline against post-glass-redesign \`main\`, (2) drop \`continue-on-error: true\` from \`visual-diff.yml\`. Captures D1-D3 + R1-R3 | ## What this PR does **not** do - Does not regenerate the actual \`home.png\` baseline. That's Step 1 of the new \`harden-visual-diff-gate\` convoy; doing it here would scope-creep into territory that needs a Linux runner dispatch (CT 111) and operator decision on whether to also add \`maxDiffPixelRatio\` cushion. - Does not drop \`continue-on-error: true\` from \`visual-diff.yml\`. Same reason — flipping that without first re-seeding causes every UI-touching PR to fail against a 10-day-stale reference image. ## Test plan - [x] \`npm run lint\` passes (1 pre-existing warning, unrelated) - [x] No \`.js\` / \`.ts\` runtime behavior changed - [ ] CI passes on this PR — gates that fire: - \`Lint\` ✓ - \`Forbidden patterns (8 checks)\` ✓ - \`Unit tests (vitest)\` ✓ - \`Convoy metrics gate\` — no-op (title prefix is \`chore(docs):\` not \`convoy:\`) - \`Screenshot diff\` — triggers because \`tests/visual/**\` is in the path filter; expected to surface a stale-baseline artifact + PR comment (advisory only; doesn't block merge per the \`continue-on-error: true\` we just documented) - [ ] After merge: agents reading the docs no longer get false-positive references to a resolved convoy ## Related - PR #58 (\`83a358b\`) — original baseline seed - PR #18 (\`7b6f751\`) — \`adopt-playwright-smoke\` Decision 4 (\`continue-on-error\` end state) - PR #132 (\`f228c09\`) — \`visual-diff.yml\` migration to self-hosted axiom runner - \`.convoys/harden-visual-diff-gate.md\` *(new in this PR)* — the actual gate-hardening work Made with [Cursor](https://cursor.com)

vercel[bot] commented

2026-06-12 21:21:11 -04:00

(Migrated from github.com)

The latest updates on your projects. Learn more about Vercel for GitHub.

Project	Deployment	Actions	Updated (UTC)
tcg-vault	Ready	Preview, Comment	Jun 13, 2026 1:21am

[vc]: #JIwZ4apvw2kH2FUp/H3cw3lvMYPm7BmuANKg3MatB90=:eyJpc01vbm9yZXBvIjp0cnVlLCJ0eXBlIjoiZ2l0aHViIiwicHJvamVjdHMiOlt7Im5hbWUiOiJ0Y2ctdmF1bHQiLCJwcm9qZWN0SWQiOiJwcmpfRjZXOEVvRkd3Y0g3aWVGcnRvRlNlOXdVVkFhNSIsImxpdmVGZWVkYmFjayI6eyJyZXNvbHZlZCI6MCwidW5yZXNvbHZlZCI6MCwidG90YWwiOjAsImxpbmsiOiJ0Y2ctdmF1bHQtZ2l0LWNob3JlLXN3ZWVwLXZpLTRjNTI5NC1yYW5kYWxsLXN0aWxsd2VsbHMtcHJvamVjdHMudmVyY2VsLmFwcCJ9LCJpbnNwZWN0b3JVcmwiOiJodHRwczovL3ZlcmNlbC5jb20vcmFuZGFsbC1zdGlsbHdlbGxzLXByb2plY3RzL3RjZy12YXVsdC8zSHV0RDJKZ1VjU2hlNVBtNTR3aHNDUmdOZFZlIiwicHJldmlld1VybCI6InRjZy12YXVsdC1naXQtY2hvcmUtc3dlZXAtdmktNGM1Mjk0LXJhbmRhbGwtc3RpbGx3ZWxscy1wcm9qZWN0cy52ZXJjZWwuYXBwIiwibmV4dENvbW1pdFN0YXR1cyI6IkRFUExPWUVEIn1dLCJyZXF1ZXN0UmV2aWV3VXJsIjoiaHR0cHM6Ly92ZXJjZWwuY29tL3ZlcmNlbC1hZ2VudC9yZXF1ZXN0LXJldmlldz9vd25lcj1zdHdsLWxhYnMmcmVwbz10Y2ctdmF1bHQmcHI9MTM1In0= The latest updates on your projects. Learn more about [Vercel for GitHub](https://vercel.link/github-learn-more). | Project | Deployment | Actions | Updated (UTC) | | :--- | :----- | :------ | :------ | | [tcg-vault](https://vercel.com/randall-stillwells-projects/tcg-vault) | ![Ready](https://vercel.com/static/status/ready.svg) [Ready](https://vercel.com/randall-stillwells-projects/tcg-vault/3HutD2JgUcShe5Pm54whsCRgNdVe) | [Preview](https://tcg-vault-git-chore-sweep-vi-4c5294-randall-stillwells-projects.vercel.app), [Comment](https://vercel.live/open-feedback/tcg-vault-git-chore-sweep-vi-4c5294-randall-stillwells-projects.vercel.app?via=pr-comment-feedback-link) | Jun 13, 2026 1:21am | <a href="https://vercel.com/vercel-agent/request-review?owner=stwl-labs&repo=tcg-vault&pr=135" rel="noreferrer"><picture><source media="(prefers-color-scheme: dark)" srcset="https://agents-vade-review.vercel.sh/request-review-dark.svg"><source media="(prefers-color-scheme: light)" srcset="https://agents-vade-review.vercel.sh/request-review-light.svg"><img src="https://agents-vade-review.vercel.sh/request-review-light.svg" alt="Request Review"></picture></a>

github-actions[bot] commented

2026-06-12 21:21:28 -04:00

(Migrated from github.com)

Pipeline Health

Build + CI gates

Gate	Status
Vercel build (Preview)	✅ pass
CI: Lint	✅ pass
CI: Schema map fresh	❌ skipped
Preview smoke	✅ pass
Visual diff	✅ pass

Build runs on Vercel; this CI runs lint and schema-map drift only (no duplicate build).

Role reports

Role	Status
Reviewer report	⏳ pending
A11y audit	⏳ pending
Design system audit	⏳ pending

See individual comments above for details. This rollup updates automatically.

## Pipeline Health ### Build + CI gates | Gate | Status | | --- | --- | | Vercel build (Preview) | ✅ pass | | CI: Lint | ✅ pass | | CI: Schema map fresh | ❌ skipped | | Preview smoke | ✅ pass | | Visual diff | ✅ pass | _Build runs on Vercel; this CI runs lint and schema-map drift only (no duplicate build)._ ### Role reports | Role | Status | | --- | --- | | Reviewer report | ⏳ pending | | A11y audit | ⏳ pending | | Design system audit | ⏳ pending | See individual comments above for details. This rollup updates automatically.

github-actions[bot] commented

2026-06-12 21:23:06 -04:00

(Migrated from github.com)

Visual Diff

Screenshots and diffs uploaded as artifacts: view run

If intentional changes: update snapshots locally with npx playwright test --project=visual --update-snapshots and commit.

## Visual Diff Screenshots and diffs uploaded as artifacts: [view run](https://github.com/stwl-labs/tcg-vault/actions/runs/27452294923) If intentional changes: update snapshots locally with `npx playwright test --project=visual --update-snapshots` and commit.