Skip to content

ci(website): gate the transcript rows on a 4px grid floor - #19161

Merged
cruisercohen merged 1 commit into
mainfrom
ci/4520-grid-harness-floor
Oct 12, 2026
Merged

cruisercohen merged 1 commit into
mainfrom
ci/4520-grid-harness-floor

Conversation

@cruisercohen

@cruisercohen cruisercohen commented Oct 11, 2026 •

Copy link
Copy Markdown
Contributor

Problem / Motivation

Goal: Every pull request fails when a transcript row's card padding leaves the 4px grid, or when the row harness silently matches zero rows.

The transcript row harness (website/scripts/capture-transcript-row-style.mjs) measures every transcript row against the 4px grid, but no pull request ran it and its 4px verdict was print-only. It has already gone vacuous once: its selector matched zero rows and the run still passed, because every per-row check had nothing to iterate.

Why it matters

A row restyle that breaks the transcript's 4px rhythm merges unnoticed, and a selector drift turns the harness into a check that always passes. Reviewers then trust a guard that is not guarding anything.

Not a goal

  • Enforcing row-to-row pitch or internal edge offsets. Both are off the grid on main for known reasons (see below) and need their own visual pass.
  • A ratchet with stored baselines.
  • Restyling any transcript row.

What changed (motivation → approach → change)

Design call: floor, scoped to what holds on main. Ratchet vs floor was the open question on #4520. This PR takes the floor, which needs no baseline storage and no churn. A frame fails when:

  • zero rows match. This is the vacuous-pass guard. The message names the selector, the candidate count and the gutter class, so a selector drift is easy to find.
  • a row's card padding is off the 4px grid on any side. This is the knob a row restyle actually turns, and it is a computed CSS value, so it reads the same on every machine.
  • a row's box does not start on the column text edge. This check already failed the script before this PR.
  • the page throws an error.

Pitch and internal edges are still printed as a report but are not enforced. Measured on main:

  • Pitches: 84, 32, 40, 82, 56, 44, 92, 46, 129.
  • Every row has off-grid internal edges.

The causes are the ones #4520 names: the 22px chip line box, flex-centred 12-15px glyph boxes, and Markdown prose height. Both measurements also follow the runner's font metrics wherever text wraps or sizes a box. The floor module's docstring records the same boundary next to the code.

Changes:

  • website/scripts/lib/transcript-grid-floor.mjs (new): the pass/fail decision as a pure function (judgeFrame), plus the row selector and grid helpers. This is the same split as the i18n render gate's render-verdict.mjs.
  • capture-transcript-row-style.mjs:
    • Uses that module and exits non-zero on any floor failure.
    • Adds --serve, which starts an in-process Vite dev server on loopback. The production build does not emit capture pages, so this means one command and one shell.
    • The existing two-shell form against a running dev server still works.
    • The zero-row report line no longer crashes on a missing text edge, so the guard's message is the only one printed.
  • ci.yml, e2e job: one new step, nothing else touched.
    • Where. The step runs right before the parallel E2E step, to reuse the Chromium install already in that job. frontend-lint installs no browser.
    • Identity. It is behind the non-root boundary, so it runs as runner through ci-shell like the other test steps. It writes no GitHub file command.
    • What it needs. No gateway, token, network or build. It serves the capture page from source over loopback.
    • Cap. timeout-minutes: 5. Locally the whole run takes about 7 seconds.
    • Why no path filter. The grid also moves with shared CSS (theme tokens, index.css, the Tailwind config), not only with transcript components. A path filter would miss exactly the drift this guards against.

Backwards compatibility

Compatible: the harness keeps its existing invocation and output; it only gains --serve and a non-zero exit on a floor failure, and main holds the floor today.

Removes nothing: the diff adds a module, a test file, a CLI flag and a CI step, and takes no path, key, record or function away.

Tests

  • website/src/test/transcriptGridFloor.test.ts (new), 15 cases: an empty frame (both no candidates and candidates dropped by the gutter filter), each padding side, fractional padding, text-edge offset, page errors, and that pitch and internal edges never fail.
  • Red without the guard: with the zero-row branch removed, the two empty-frame tests fail (2 failed / 13 passed).
  • npx vitest run src/test/transcriptGridFloor.test.ts: 15 passed.
  • eslint (--max-warnings 0) on the touched files: clean. jscpd: 0 clones.
  • The workflow structure tests (test_ci_nonroot_boundary.py and the other ci.yml suites) pass. The only failures are two pytest_split cases that fail identically on main in an environment without that plugin.

Manual verification

End to end, node scripts/capture-transcript-row-style.mjs --serve <dir>:

  • main as-is: exit 0, 15 rows per theme.
  • py-2 changed to py-1.5 on the error card: exit 1, row error-card card padding is off the 4px grid: padTop=6 (off by 2), padBottom=6 (off by 2).
  • row selector changed so it matches nothing: exit 1, ZERO transcript rows matched. Selector [style*="--mc-row-width"] found 0 candidate(s) ....

Screenshots / video

Why no screenshot: the diff changes a capture script, a pure verdict module, a unit test and a CI step, and no rendered component or style.

Related Issues

Closes #4520

Checklist

  • At most two commits (one is the norm), with a Conventional Commits title (feat|fix|docs|style|refactor|perf|test|chore|ci|build|revert: ...)
  • Existing tests pass and new tests added for new functionality
  • Self-review completed; code follows project style guidelines
  • Documentation updated (if applicable)
  • No secrets, credentials, or internal references in the diff

Contribution License Agreement

Contributions are accepted under the project's Apache-2.0 license; see the Licensing section of CONTRIBUTING.md.

@github-actions github-actions Bot added the readiness: checking Automated validation is still running label Oct 11, 2026
@github-actions

github-actions Bot commented Oct 11, 2026 •

Copy link
Copy Markdown
Contributor

UX Review (Opus 5.5) — ✅ PASS

UX-level review of f07d5009302c117d8ba80bbd7a5ca604a56ac9b0 — updated in place on each push. A BLOCK verdict blocks PR readiness; PASS/CONCERNS are advisory.

UX-Verdict: PASS

Nothing to check.

[UX-REVIEWED] f07d500

Description read

[DESCRIPTION-READ] af458d0351f714c4bf393e6ab5a636a0b7c3025801c8f3721dd97cb0f420f67e

That sha256 names everything this verdict read: the PR description, plus the 3 evidence file(s) the workflow collected from it and handed this review. It covers that evidence because the media strip replaces every attachment URL with the same placeholder, so an edit swapping one attachment for another would leave the description's captured text identical while what this review judged changed. Recompute it with .github/scripts/pr-description-capture.sh over the same inputs; if it differs, the description or that evidence changed after this verdict was formed and any finding drawn from either is unproven.

@github-actions

github-actions Bot commented Oct 11, 2026 •

Copy link
Copy Markdown
Contributor

Design Review (Opus 5.5) — ✅ PASS

Design-level review of f07d5009302c117d8ba80bbd7a5ca604a56ac9b0 — updated in place on each push. A BLOCK verdict blocks PR readiness; PASS/CONCERNS are advisory.

Design-Verdict: PASS

Check that this PR's first e2e run passes the new step on the CI runner. The "main holds the floor" claim has only been measured locally.

[DESIGN-REVIEWED] f07d500

Description read

[DESCRIPTION-READ] 98452959848e800797c03581055c30f795ef227e5cdc8b3e75d88c7acd8af399

That sha256 names everything this verdict read: the PR description, plus the 1 evidence file(s) the workflow collected from it and handed this review. It covers that evidence because the media strip replaces every attachment URL with the same placeholder, so an edit swapping one attachment for another would leave the description's captured text identical while what this review judged changed. Recompute it with .github/scripts/pr-description-capture.sh over the same inputs; if it differs, the description or that evidence changed after this verdict was formed and any finding drawn from either is unproven.

@github-actions

github-actions Bot commented Oct 11, 2026 •

Copy link
Copy Markdown
Contributor

GPT 6.1 Review — ✅ no blocking findings

GPT 6.1 completed its review of f07d5009302c117d8ba80bbd7a5ca604a56ac9b0 and found no blocking issues.

This comment is updated in place on each push.

Review details

No findings.
[GPT-REVIEWED] f07d500

False positive or not applicable? A repository writer can comment:
/ai-review override gpt f07d5009302c117d8ba80bbd7a5ca604a56ac9b0: <one-sentence reason>

@github-actions

github-actions Bot commented Oct 11, 2026 •

Copy link
Copy Markdown
Contributor

First Principles Review (Opus 5.5) — ✅ PASS

Premise-level review of f07d5009302c117d8ba80bbd7a5ca604a56ac9b0 — why this exists and whether the shipped surface is the smallest honest version. Updated in place on each push. A BLOCK verdict blocks PR readiness; PASS/CONCERNS are advisory.

First-Principles-Verdict: PASS

The new step goes before the parallel E2E step, so if the floor fails, E2E is skipped for that run. Confirm that ordering is acceptable.

What this change ships

Inventory (6 items) — 6 justified

Intent: make every pull request fail when a transcript row's card padding leaves the 4px grid, or when the row harness matches zero rows. This is an ADDITION (a CI gate) that closes #4520.

  1. Every PR now runs the transcript row harness in the e2e job and fails on a floor violation — justified
  2. A row whose card padding is off the 4px grid now fails the harness (it was only printed before) — justified
  3. The pass/fail decision moved into scripts/lib/transcript-grid-floor.mjs (judgeFrame) so it can be unit-tested without a browser — justified
  4. A new --serve flag starts an in-process Vite dev server on loopback, so the run needs one shell — justified
  5. The zero-row report line no longer crashes when the text edge is missing, so only the guard's message prints — justified
  6. A new unit test file with 15 cases, including two empty-frame tests that fail with the guard removed — justified

[FIRST-PRINCIPLES-REVIEWED] f07d500

Description read

[DESCRIPTION-READ] 8fe884d7178cf2857de782d973f1e1c8d9a1fb314ac3c1a9692703124bb9058b

That sha256 names the PR description this verdict read. Recompute it with .github/scripts/pr-description-capture.sh; if it differs, the description changed after this verdict was formed and any finding drawn from the description is unproven.

@github-actions

github-actions Bot commented Oct 11, 2026 •

Copy link
Copy Markdown
Contributor

Opus 5.5 Review — ✅ no blocking findings

Reviewed f07d5009302c117d8ba80bbd7a5ca604a56ac9b0 — this comment is updated in place on each push.

Review details

No findings.

[OPUS-REVIEWED] f07d500

Verdict parsed from the review's SHA-scoped output markers for commit f07d5009302c117d8ba80bbd7a5ca604a56ac9b0.

False positive or not applicable? A repository writer can comment:
/ai-review override fable f07d5009302c117d8ba80bbd7a5ca604a56ac9b0: <one-sentence reason>

@cruisercohen
cruisercohen marked this pull request as ready for review October 11, 2026 17:38
@cruisercohen
cruisercohen requested review from a team and KiroCrewCaptain as code owners October 11, 2026 17:38
@cruisercohen
cruisercohen enabled auto-merge (squash) October 11, 2026 17:38
@github-actions github-actions Bot added readiness: passed Eligible automated validation passed for the current revision and removed readiness: checking Automated validation is still running labels Oct 11, 2026
@bolichen97

Copy link
Copy Markdown
Contributor

Maintainer read (bolichen97): the code is clean and the new step ran green on CI ("Transcript rows hold the 4px grid floor (asserting harness)" in the E2E job). Since this is a new gate on every PR with no path filter, and the branch is ~146 commits behind, please rebase onto current main so the step runs green once on today's main before it lands. I will approve the rebased head.

Posted by an AI assistant at bolichen97's request, after a read-only review of this head.

@cruisercohen
cruisercohen force-pushed the ci/4520-grid-harness-floor branch from eeb7e37 to 683a2b0 Compare October 12, 2026 07:03
@github-actions github-actions Bot added readiness: checking Automated validation is still running and removed readiness: passed Eligible automated validation passed for the current revision labels Oct 12, 2026
The transcript row harness measured padding, pitch and every internal
edge, but nothing ran it on a pull request, and its 4px verdict was
print-only.

Move the pass/fail decision into scripts/lib/transcript-grid-floor.mjs:
a frame fails when its row selector matches zero rows (the message names
the selector, candidate count and gutter class), when a row's card
padding is off the 4px grid on any side, when a row leaves the column
text edge, or on a page error. Pitch and internal edges stay a printed
report: both are off the grid on main for known reasons and follow the
runner's font metrics.

Give the harness a --serve mode that starts an in-process Vite dev
server on loopback, since the production build does not emit capture
pages, and run it in the E2E job after the Chromium install, behind the
non-root boundary.

Closes #4520
@cruisercohen
cruisercohen force-pushed the ci/4520-grid-harness-floor branch from 683a2b0 to f07d500 Compare October 12, 2026 07:55
@github-actions github-actions Bot added readiness: passed Eligible automated validation passed for the current revision and removed readiness: checking Automated validation is still running labels Oct 12, 2026
@cruisercohen

Copy link
Copy Markdown
Contributor Author

@bolichen97 Rebased onto current main (0a47021090). Both rebases were clean with no conflicts, and the change is identical to the reviewed commit; there is no code change.

On the new head f07d500930, the E2E job's "Transcript rows hold the 4px grid floor (asserting harness)" step passed, every check is green, and readiness passed. The first rebase head picked up two reds that were already failing on main at the time (the wait-discipline ratchet and the FilePathMenu in-app tests). I rebased a second time after their fixes (#19329, #19288) merged, with no change to the content.

@iamwhatever iamwhatever left a comment

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

The transcript row harness measured the 4px grid but never failed, and it once passed while matching zero rows. This PR moves the verdict into a pure judgeFrame. A frame fails on zero rows, padding off the grid on any side, a row off the column text edge, or a page error. The PR adds a --serve mode and runs the harness in CI's E2E job. I checked that the probe really records padTop/padRight/padBottom/padLeft as parsed floats, so the floor reads real values, not undefined. The in-process Vite server binds only to 127.0.0.1 and is closed after the run. I confirmed the new step ran and passed in the "E2E (stub ACP backend, offline)" job on f07d500. The unit tests cover every failure branch, including the empty-frame guard. Pitch and internal edges stay report-only, for reasons the PR states. All lanes are PASS and checks are green. — crew-pr-reviewer (deep re-check)

@cruisercohen
cruisercohen merged commit d99c585 into main Oct 12, 2026
102 checks passed
@cruisercohen
cruisercohen deleted the ci/4520-grid-harness-floor branch October 12, 2026 17:08
@github-actions github-actions Bot removed the readiness: passed Eligible automated validation passed for the current revision label Oct 12, 2026
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

Wire the transcript 4px-grid harness into CI (ratchet or floor — needs a call)

3 participants