visual-baseline-gate
/visual-baseline-gate
Wydaje werdykt CI dla regresji wizualnych na podstawie zatwierdzeń recenzenta, blokując zmiany bez podpisu recenzenta innego niż autor.
- Autor
- testland ↗
- Repozytorium
- qa ↗
- Licencja
- MIT
- Ostatnia zmiana repozytorium
- 20.10.2026
Ocena i bezpieczeństwo
- Pliki w paczce
- 3
- Skrypty
- 0
- Komentarze HTML
- 0
- Adresy URL w SKILL.md
- 0
Brak sygnałów. Repozytorium zmienione 20.10.2026, bez odwołań do wycofanych modeli i API.
MIT, otwarta: można używać i zmieniać, z zachowaniem informacji o autorze.
Co robi i kiedy
Wydaje werdykt CI dla regresji wizualnych na podstawie zatwierdzeń recenzenta, blokując zmiany bez podpisu recenzenta innego niż autor.
Oryginalny opis (EN)
Consumes pre-classified visual-diff JSON and a reviewer-signed acceptance log to produce a single go/no-go CI verdict for visual regression. Blocks when intentional baseline changes lack a non-author reviewer sign-off or when regressions are present, and emits the binding gate artifacts - visual-gate.json + visual-gate.md - with fail-closed handling of a missing classifier run and author-cannot-self-approve enforcement, so the pipeline can exit non-zero on BLOCK. Use when the gate's input is pre-classified diff data and the enforcement concern is reviewer approval and a binding CI verdict.
Jak działa
- Overview
- When to use
- How to use
- Inputs
- The gate decision rule
- Author cannot self-approve
- Emitting gate artifacts (the binding CI verdict)
- Worked example
- References
Podgląd SKILL.md
---
name: visual-baseline-gate
description: "Consumes pre-classified visual-diff JSON and a reviewer-signed acceptance log to produce a single go/no-go CI verdict for visual regression. Blocks when intentional baseline changes lack a non-author reviewer sign-off or when regressions are present, and emits the binding gate artifacts - visual-gate.json + visual-gate.md - with fail-closed handling of a missing classifier run and author-cannot-self-approve enforcement, so the pipeline can exit non-zero on BLOCK. Use when the gate's input is pre-classified diff data and the enforcement concern is reviewer approval and a binding CI verdict."
---
# visual-baseline-gate
## Overview
A typical visual-regression CI run produces an engine-specific verdict
(Chromatic exit code, Percy build status, Playwright snapshot pass/fail).
That's not enough for a strict gate, because:
1. Each engine treats "visual changes" differently - Chromatic exits `1`
on changes (review needed), Percy returns success but flags the build
pending, Playwright fails the test outright.
2. **"The author updated baselines and committed them" is not the same
as "a reviewer approved the baseline change."** A `--update-snapshots`
commit is a self-approval; for safety-relevant components it should
require a sign-off.
This skill defines a build-an-X workflow that consumes both the diff
classifier output and an explicit acceptance log to emit a single
go/no-go verdict.
## When to use
- The team uses two or more visual engines and wants one CI gate
(similar in motivation to `data-quality-gate` in the
qa-data-quality plugin, for data quality).
- The team wants to enforce a "reviewer approval" rule on baseline
updates - i.e. a `--update-snapshots` commit by the PR author cannot
self-approve a baseline change to a critical component.
- The team wants the classified visual-diff output to become
CI-blocking rather than advisory.
If the project uses one engine only and trusts engine-native review
(e.g. all changes go through Chromatic UI approval), prefer the
engine's native CI integration - see the matching engine's
"CI integration" section in its SKILL.md.
## How to use
1. **Collect the two inputs** - the pre-classified diff JSON (one record
per snapshot, `category` in intentional | incidental | regression) and
the reviewer-committed `.visual-acceptance.yml` (see Inputs).
2. **Run the gate decision rule** - regression blocks always; intentional
blocks until listed in the acceptance log; incidental warns only (see
The gate decision rule).
3. **Enforce author-cannot-self-approve** - verify the commit that added
`.visual-acceptance.yml` was authored by someone other than the PR
author (see Author cannot self-approve).
4. **Emit the artifact and exit** - write the markdown + JSON summary and
exit non-zero on a no-go verdict so CI halts. The full artifact
template, the runnable CI entrypoint, and the GitHub Actions wiring are
in [references/artifact-and-ci-wiring.md](references/artifact-and-ci-wiring.md).
## Inputs
The gate consumes two inputs:
1. **Classification artifact** - the pre-classified diff JSON, one
record per snapshot:
```json
{
"snapshot": "dashboard-mobile-375",
"engine": "playwright",
"category": "intentional|incidental|regression",
"pattern": "text-truncation|...|null",
"paired_change": true,
"diff_url": "playwright-report/data/dashboard-mobile-375-diff.png"
}
```
2. **Acceptance log** - a YAML file at `.visual-acceptance.yml`
committed by reviewers (NOT the PR author) that explicitly accepts
each intentional baseline change for the current PR:
```yaml
# .visual-acceptance.yml - committed by reviewers in the PR's review pass
pr: 1234
accepted_by: reviewer-handle
accepted_at: 2026-05-04T12:00:00Z
snapshots:
- snapshot: dashboard-mobile-375
reason: "Intentional CTA color change per design spec DS-456"
- snapshot: pricing-tablet-768
reason: "Intentional pricing tier rename"
```
The acceptance file lives in the PR branch; merging the PR records
the acceptance in git history.
## The gate decision rule
```python
def visual_gate(classifications, acceptance_log, *,
require_reviewer_acceptance=True):
accepted = {s["snapshot"] for s in acceptance_log.get("snapshots", [])}
blockers = []
for c in classifications:
if c["category"] == "regression":
blockers.append((c, "regression - blocks unconditionally"))
elif c["category"] == "intentional" and require_reviewer_acceptance:
if c["snapshot"] not in accepted:
blockers.append((c, "intentional - missing reviewer acceptance"))
elif c["category"] == "incidental":
# incidental requires investigation but does NOT block by default
pass
return {
"verdict": "no-go" if blockers else "go",
"blockers": blockers,
"incidentals": [c for c in classifications if c["category"] == "incidental"],
"intentional_accepted": [c for c in classifications
if c["category"] == "intentional"
and c["snapshot"] in accepted],
}
```
Default behavior:
- **regression** -> block (always).
- **intentional** -> block UNTIL listed in `.visual-acceptance.yml`.
- **incidental** -> surface as a warning, do not block.
For low-risk projects, set `require_reviewer_acceptance=False` so
intentional changes pass without explicit acceptance - this collapses
the gate to "block on regressions only."
## Author cannot self-approve
For a stricter gate, validate that the commit adding `.visual-acceptance.yml`
was authored by **someone other than the PR author**:
```bash
ACCEPTANCE_AUTHOR=$(git log --format='%ae' -1 .visual-acceptance.yml)
PR_AUTHOR=$(gh pr view --json author --jq '.author.login + "@..."')
if [[ "$ACCEPTANCE_AUTHOR" == "$PR_AUTHOR" ]]; then
echo "ERROR: PR author cannot self-approve baseline changes"
exit 1
fi
```
This is the visual-regression analog of GitHub's "require approval
from someone other than the last committer" branch protection.
## Emitting gate artifacts (the binding CI verdict)
Applying the decision rule in CI means turning the per-diff judgements into
binding output files the pipeline acts on:
1. **Fail closed on a missing classifier run.** Read
`visual-classifications.json` (written by the classification step, e.g.
`visual-diff-classifier`). If the file is absent or empty, emit `BLOCK`
with reason `classifier-output-missing` and stop - a missing classifier
run is itself a gate failure. Do not attempt to reconstruct
classifications.
2. **Read the acceptance log.** Look for `.visual-acceptance.yml` in the
branch root; if absent, treat all `intentional` diffs as unaccepted.
3. **Apply the decision rule** (previous section). Verdict precedence is
`BLOCK` > `REVIEW` > `OK` - one `BLOCK` overrides any number of `OK`
rows. `incidental` rows surface as `REVIEW`, never silently downgraded
to `OK`; an `incidental` row whose pattern isn't in the conventions'
valid list (anti-aliasing, font-bump, sub-pixel drift per
`visual-baseline-conventions`) is suspect and stays `REVIEW`.
4. **Enforce author-cannot-self-approve.** Compare the acceptance log's
`accepted_by` (and the committing author, next section) against the PR
author; on a match, escalate the verdict to `BLOCK` regardless of other
rows. The gate is read-only on `.visual-acceptance.yml` - only a human
reviewer writes that file.
5. **Don't double-count engine-level signaling.** If the build used
Chromatic without `--exit-zero-on-changes`, the CLI already exited
non-zero on detected changes (exit code `1` = `BUILD_HAS_CHANGES`, per
chromatic.com/docs/ci) - that is engine-level signaling, not a
classifier verdict.
6. **Write `visual-gate.md` + `visual-gate.json` and exit.** `BLOCK` exits
non-zero to halt CI; `REVIEW` and `OK` exit zero, with `REVIEW` posting
the incidentals table as a PR comment for human attention. The full
artifact templates and the GitHub Actions wiring are in
[references/artifact-and-ci-wiring.md](references/artifact-and-ci-wiring.md).
## Worked example
Run the gate on one build. The classification step emitted three
records, and one reviewer committed an acceptance log:
```python
classifications = [
{"snapshot": "dashboard-mobile-375", "engine": "playwright", "category": "regression"},
{"snapshot": "pricing-tablet-768", "engine": "percy", "category": "intentional"},
{"snapshot": "hero-desktop-1280", "engine": "chromatic", "category": "intentional"},
]
acceptance_log = {"snapshots": [{"snapshot": "hero-desktop-1280",
"reason": "Intentional hero copy update per DS-789"}]}
result = visual_gate(classifications, acceptance_log)
```
Walking the rule per record:
| Snapshot | Category | In acceptance log? | Outcome |
|-----------------------|-------------|--------------------|---------|
| dashboard-mobile-375 | regression | n/a | **block** - regressions always block |
| pricing-tablet-768 | intentional | no | **block** - missing reviewer acceptance |
| hero-desktop-1280 | intentional | yes | pass - reviewer signed off |
`result["verdict"]` is `"no-go"` (two blockers), so the CI step exits
non-zero and the merge is held. The gate prints:
```text
# Visual Baseline Gate - verdict: NO-GO
- playwright :: dashboard-mobile-375 :: regression - blocks unconditionally
- percy :: pricing-tablet-768 :: intentional - missing reviewer acceptance
```
To turn this build green, a non-author reviewer either fixes the
`dashboard-mobile-375` regression or, if the diff is actually intended,
adds both snapshots to `.visual-acceptance.yml` and re-runs the gate.
The full markdown + JSON artifact and the CI wiring that surfaces this
output are in
[references/artifact-and-ci-wiring.md](references/artifact-and-ci-wiring.md).
## References
- `percy-visual-regression-testing`
- `chromatic-visual-regression-testing`
- `playwright-snapshots`
- `storybook-visual-regression-testing`
- `visual-baseline-conventions` - the conventions this gate enforces.
- `data-quality-gate` - sibling gate skill for data-quality results, same artifact shape.
Pliki w paczce (3)
- SKILL.md 10 KB
- .tessl-plugin/plugin.json 1 KB
- references/artifact-and-ci-wiring.md 3 KB
Wersje
W bazie nie ma innych skilli o nazwie visual-baseline-gate.
Migawka bazy z 13.11.2026 · wersja paczki 29e5bb3ac84a (skrót SHA-256 całej paczki)
Pobrania w ostatnich 30 dniach: 0 · ranking
Zgłoś problem z tym skillem: szkodliwa treść, błędny opis albo prośba autora o usunięcie.
Podobne skille
- 100review-gate
Przegląda cały diff tylko do odczytu po weryfikacji i przed commitem, bez zmian w kodzie. - 100ae-ltd-visual-regression-forge
Dowodzi bezpieczeństwa zmian w UI na różnych breakpointach przez przepływy bazowe i diff, jako bramka jakości wizualnej przed wydaniem. - 100pr-review
Przegląda pull request lub bieżący diff pod kątem poprawności, dryfu kontraktu, bezpieczeństwa, brakujących testów i progu pokrycia, wydając sklasyfikowane ustalenia i werdykt. - 90code-review
Wydaje werdykt na diff od innego autora, osobno dla specyfikacji, standardów i bezpieczeństwa, zapisując go dla dokładnie tego diffu. - 100agent-flow-reviewer
Ocenia pojedynczy diff w agent-flow jako recenzent tylko do odczytu i zwraca werdykt JSON z uwagami przypisanymi do konkretnych linii kodu. - 100dev-delivery
Orkiestruje dostarczanie kodu: najpierw lista akceptacyjna QA, potem jeden autor implementuje, niezależny przegląd tylko na podstawie diffa, akceptacja fail-closed i poprawki, z równoległymi strumieniami dla zadań wielomodułowych.