@soleur/opencode 0.0.0-stage → 3.354.2

package/skills/test-fix-loop/SKILL.md

@@ -0,0 +1,159 @@
+---
+name: test-fix-loop
+description: "This skill should be used when autonomously iterating on test failures: runs the suite, diagnoses, applies minimal fixes, re-runs with checkpoint commit isolation until all tests pass."
+---
+
+<!-- Inspired by mattpocock/skills/skills/engineering/diagnosing-bugs/SKILL.md (MIT, Copyright (c) 2026 Matt Pocock). -->
+<!-- soleur-cloud-mode:start -->
+**Cloud Mode (Devin):** before pipeline work run `bash "${CLAUDE_PLUGIN_ROOT}/scripts/cloud-detect.sh"`. If `CLAUDE_PLUGIN_ROOT` is unset (cloud exec shells do not export it), resolve the root by IDENTITY, never by script basename: for `d` in `"$HOME/.local/share/devin/cli/plugins/cache"` and `/opt/.devin/plugins`, skip unless `[ -d "$d" ]`, then `MANIFEST="$(find "$d" -path '*/.claude-plugin/plugin.json' -exec grep -l '"name"[[:space:]]*:[[:space:]]*"soleur"' {} + 2>/dev/null | head -1)"`, `ROOT="${MANIFEST%/.claude-plugin/plugin.json}"` — one resolution, two consumers: `$ROOT/scripts/cloud-detect.sh` and `$ROOT/scripts/precommit-guard.sh`. (Shape check, not authentication: a planted `{"name":"soleur"}` dir passes — ADR-179 A11.) `local` or `not-local:no-devin-env` proceeds normally; any other `not-local:<reason>` applies `<plugin-root>/devin/INSTRUCTIONS.md` §Cloud Mode: emit the `--banner`, fan out sequentially with `Reviewed-Coverage: sequential-fallback` disclosure (never claim an independent review ran), `message_user` ack before any secrets read or production mutation, and run `precommit-guard.sh` before any `git commit` — hooks do not fire in cloud.
+<!-- soleur-cloud-mode:end -->
+
+<!-- grok-harness-invoke:start -->
+**Grok Build (`plugins/soleur/lib/harness.ts` `invokeSkill()`):** Read this SKILL.md in this process and run it to completion. A one-segment `soleur:<name>` in this document names a SKILL — on Grok Build, Read `plugins/soleur/skills/<name>/SKILL.md` in this process; it is not a nested tool_use. A multi-segment id such as `soleur:<domain>:<name>` names an AGENT: spawn it, never Read it, and on Grok Build spawn_subagent takes the id with its colons replaced by hyphens (`agentIdToGrokSubagentType`). **Claude Code:** Skill tool for a skill (`soleur:<name>`), Task tool with `subagent_type` for an agent. Forbidden is executing a subset, not the Read.
+<!-- grok-harness-invoke:end -->
+
+# Test-Fix Loop
+
+Autonomous test-fix iteration loop. Run the test suite, diagnose failures, apply fixes to implementation code, and re-run until all tests pass or a termination condition is met. This is a recovery mechanism for unexpected failures -- not a replacement for RED/GREEN/REFACTOR (use `atdd-developer` for TDD discipline).
+
+## When to Use
+
+- After implementation produces unexpected test failures in unrelated modules
+- When `soleur:work` GREEN phase fails and manual diagnosis is tedious
+- To batch-fix multiple test failures across a codebase
+- NOT for writing new tests (use `atdd-developer`)
+- NOT for linting, type-checking, or non-test failures
+
+## Phase 0: Detect and Confirm
+
+### Detect Test Runner
+
+Auto-detect the test command from project files in priority order:
+
+1. `CLAUDE.md` -- explicit test command (highest priority)
+2. `package.json` -- `scripts.test` field
+3. `Cargo.toml` -- `cargo test`
+4. `Makefile` / `Justfile` -- `test` target
+5. `Gemfile` / `Rakefile` -- `bundle exec rake test` or `bin/rails test`
+6. `pyproject.toml` -- `pytest`
+7. `go.mod` -- `go test ./...`
+
+If `$ARGUMENTS` contains `--cmd` or `--max` flags, extract values directly: `--cmd '<command>'` sets the test command and `--max N` the iteration cap; when either is present it wins over the number/command heuristics below (a red-capable command from `soleur:reproduce-bug` usually contains digits). Optional flag: `--max` (iterations, default 5). When the caller is `soleur:reproduce-bug`, `--cmd` is its Phase 8 red-capable command, already committed in its Phase 9 — the loop iterates on the user's symptom, not on a proxy. `--max` and `--max-fix-rounds` are the same ceiling — feed it to `bash "${CLAUDE_PLUGIN_ROOT}/scripts/pipeline-tally.sh" init --max-fix-rounds N` ONLY when explicitly provided: the default-5 must never ratchet down a pipeline-set cap (#9403) — and the tally's own ratchet guard refuses a lower argv cap against a persisted one without `--reset`.
+Otherwise: if `$ARGUMENTS` contains a custom test command, use it instead of auto-detection; if it contains a number, use it as max iterations (default: 5).
+If no runner is detected, the plugin gate is the entry point — `bash "${CLAUDE_PLUGIN_ROOT}/scripts/affected-tests.sh"` detects the stack (nx/turbo, JS/TS, Python, Go), reads `.soleur-test-gate.json` overrides, and refuses loudly rather than improvising a command; a repo with a capability-positive [scripts/test-all.sh](../../../../scripts/test-all.sh) is delegated to instead. Precedence to know: a committed `test_command` in that config runs FIRST — before delegation or adapters — so read it before assuming a stack's own selector applies. If the gate reports `no-stack`/`toolchain-missing` (rc 4) or `no-tests` (rc 7), ask the user for the test command.
+
+### Require Clean Working Tree
+
+Run `git status --porcelain`. If output is non-empty, STOP and tell the user to commit their changes first.
+
+### Pre-flight Confirmation
+
+<decision_gate>
+**API budget.** Each iteration of this loop consumes one main-model turn (parse failures → cluster → fix → re-run) against the Anthropic API key in your Claude Code session. The `max iterations` cap (default 5, configurable via `$ARGUMENTS`) is the only cost ceiling — a runaway against a perpetually-flaky test command or an infinite-regression chain runs up to the cap before terminating. Soleur does not bill or proxy these calls — Anthropic does, against the key in your session. The Soleur LICENSE (BSL 1.1) disclaims warranty for runtime cost; you operate this loop against your own budget.
+
+Show the user: detected test command, max iterations, current branch.
+Get one confirmation before starting the loop. This is the only approval gate --
+no per-iteration approval.
+</decision_gate>
+
+## Phase 1: Test-Fix Loop
+
+Record the current commit SHA as `<initial-sha>` before entering the loop. This is the rollback target if the loop terminates on failure after multiple iterations.
+
+Pipeline tally (#9403): `bash "${CLAUDE_PLUGIN_ROOT}/scripts/pipeline-tally.sh" init` (merge-safe — the resolved `--max` lands via `--max-fix-rounds`). Before EACH iteration's fix attempt: `VERDICT="$(bash "${CLAUDE_PLUGIN_ROOT}/scripts/pipeline-tally.sh" gate fix_rounds)"` — `STOP` → write `knowledge-base/project/specs/<feature>/session-state.md` (`status: budget-capped` + `budget-capped: fix_rounds=<count>/<cap>` + resume prompt) and exit cleanly without reset (a capped run preserves its commits; the iteration table's `Max iterations` row still governs its own cap). `WARN`/`OK` → continue and `bash "${CLAUDE_PLUGIN_ROOT}/scripts/pipeline-tally.sh" incr fix_rounds` once per iteration. `UNKNOWN` → continue (caps unenforced — ship renders `cap-unenforced`).
+
+Run the initial test suite and **capture its exit code** (`rc`) — the verdict is `rc`, not the parsed output. Exit with "All tests already pass. Nothing to fix." only when `rc` is 0. A run that exits non-zero while parsing to zero failures is not a pass: this repo's `test-all.sh` exits 3 when zero suites failed and at least one was terminated with a signal-shaped status, rendered `[KILLED]` rather than `[FAIL]` (see its `EXIT CONTRACT` block). Handle that through the *Suite terminated* row in §2 — never by entering the loop and never by reporting success.
+
+For each iteration (up to max iterations):
+
+### 1. Parse Failures
+
+Extract failure summaries from test output: test name and error message only (one line each). Discard full stack traces and passing test output to minimize context consumption.
+
+Distinguish build/compilation errors from test failures. If the suite fails to compile, treat the entire build error as a single cluster and fix the compilation issue first.
+
+Count `^[KILLED]` lines separately from failures, and record both alongside `rc`. A terminated suite emits no assertion output, so it parses to zero failures and produces zero clusters: "non-zero `rc`, nothing parseable" is a real shape, and it is *unresolved coverage*, not an empty failure set. Never let it fall through to "all tests pass".
+
+**Flake screen — the failure set §2's delta rows and §3's clustering read is the POST-SCREEN set.** For each test in this run's failure set that is not already quarantined — keyed by file + test name (the same `it()` title in two files is two entries, not one flake) — re-run that test alone on the unchanged code via the runner's filter flag (`vitest -t`, `pytest -k`, `go test -run`, `bun test -t` / `--test-name-pattern`; when the runner cannot filter, one suite-level re-run answers the same question by absence). **A pass on that re-run — same code, no fix applied — is a flake signature.** A re-run that itself errors or times out is NOT a pass: the failure stays on the fix path. Mixed sets compose per-test — passers quarantine, failers proceed to §3. The screen never runs on a `^[KILLED]` / `rc` 3 suite (the *Suite terminated* row owns those — ADR-177) nor on build/compile errors (no single test to isolate). Per quarantined test, three acts:
+
+- **Quarantine it** — remove it from the failure set driving fix/cluster bookkeeping and from every later delta count: a test quarantined in iteration N stays quarantined for the run, never counts toward "fixed", and never trips *Circular fix*. It consumes no fix-round tally (no fix was attempted).
+- **File it** — when a GitHub remote and `gh` exist: ensure the label first (`gh label create flaky --color FBCA04 --description "Intermittently-failing test" 2>/dev/null || true` — the create self-heals on a repo lacking the label and never rewrites an existing one), then dedupe on a sentinel, not the title: `gh issue list --state open --label flaky --json number,body` and match `<!-- soleur:flake test="<file>::<name>" -->` in the bodies, commenting on the existing tracker rather than filing a duplicate (the sentinel-dedup arm of `check-red-on-main.sh`; an `in:title "…"` phrase breaks on a test name carrying `"` or search-significant punctuation and silently misses the tracker it exists to find). On a miss, `gh issue create` titled `flake: <test> — <signature>` with `--label flaky`, body carrying the sentinel line, the pass-on-retry signature, the runner command, and a pointer to [determinism-checklist.md](./references/determinism-checklist.md). With no `gh`/remote the quarantine is report-only and the report says so.
+- **Report it** — a `Quarantined flakes:` block in the Diagnostic Report naming each test + its issue. Once quarantined, a later re-failure is noted in the report and the filed issue, not re-entered for fixing; if the flake was first observed in an iteration after this loop's first fix commit, or the flaked test exercises files this branch's diff touched, flag **possible diff-interaction** — a diff-introduced flake passes the screen by construction, and a path intersection against the loop's commits can never fire (the loop never edits test files), so timing and exercised-surface are the only honest signals. Quarantine must never launder a real regression this branch caused. Quarantine never edits, skips, or deletes a test file.
+
+### 2. Check Termination Conditions
+
+Before attempting fixes, check whether to stop. Rows are checked top to bottom; the first match wins.
+
+**The count driving every delta row below is `failures + killed` on the post-screen set (the §1 flake screen's quarantines never enter it), and a suite that is KILLED in either of the two iterations being compared is excluded from the delta rather than counted as fixed.** A failures-only count is arithmetically unsafe here: a suite that FAILED in iteration N and is KILLED in N+1 lowers it, which reads as a fabricated improvement; when the same suite completes again in N+2 the count jumps back, which reads as **Regression** and would `git reset --hard HEAD` over real fixes on the strength of a signal artifact.
+
+| Condition | Detection | Action |
+|-----------|-----------|--------|
+| Suite terminated (unresolved) | Any `^[KILLED]` line in the output, or runner `rc` 3 | Do NOT stage, do NOT report success, do NOT reset. Re-run that suite alone; if it is KILLED again, STOP and report UNRESOLVED naming the suite |
+| All tests pass | `rc` 0 (zero failures **and** zero killed) | Run the probe grep from §4 first (on output, remove the probes and re-run the suite); when it is silent, stage fixes with `git add -A`, report success |
+| All failures screened out | Post-screen failure set empty while `rc` non-zero **and ≥1 test was quarantined this run** — every parsed failure passed its isolated re-run (a zero-failure parse with non-zero `rc` is NOT this row: nothing screened is nothing proven, and it falls through to the rows below) | Run the same probe grep as the row above; when silent, `git add -A` and report `SUCCESS (N quarantined — issues #…)` — never NON_CONVERGENCE or MAX_ITERATIONS on an all-flake set |
+| Max iterations | iteration == limit | `git reset --hard <initial-sha>` (revert all iterations), report |
+| Regression | Failure count increased vs previous iteration | `git reset --hard HEAD` (discard uncommitted fixes), report |
+| Circular fix | Failure name set matches any prior iteration | `git reset --hard <initial-sha>` (revert all iterations), report |
+| Non-convergence | Failure count unchanged for 2 consecutive iterations | `git reset --hard <initial-sha>` (revert all iterations), report |
+| Build error persists | Same compilation error after fix attempt | `git reset --hard <initial-sha>` (revert all iterations), report |
+
+If a termination condition triggers, skip to the Diagnostic Report.
+
+### 3. Cluster and Diagnose
+
+Cluster failures by file or module (max 5 groups, sorted by failure count descending). If more than 5 modules fail, take the top 5 and note the skipped modules.
+
+For each cluster, apply the diagnostic-first rule:
+
+- Read the failing test to understand expected behavior
+- Read the implementation code referenced by the error
+- Identify the root cause before proposing a fix
+
+### 4. Checkpoint and Fix
+
+<critical_sequence>
+Commit the current working tree as a rollback checkpoint before applying fixes. Skip on iteration 1 if the tree is clean -- `<initial-sha>` already serves as the rollback point.
+
+Before the checkpoint commit run `git grep -niE --untracked '\[DEBUG-[0-9a-f]{4}\]' -- ':/' ':(top,exclude)knowledge-base/**/*.md'`; it must print nothing (top-anchored: the whole repo from whatever cwd the suite needs). On output, remove the probes and re-run the suite before committing -- a probe removal is not a fix and never checkpoints as one (ADR-230). Then `git ls-files --others --exclude-standard | grep -iE '\.(har|webm|mp4|mov|dmp|core)$'` -- also nothing: a captured artifact from `soleur:reproduce-bug` Phase 2 option 3 must never be swept up by the `git add -A` below.
+
+    git add -A && git commit -m "test-fix-loop: checkpoint iteration N"
+
+Apply fixes to implementation code only. NEVER modify test files, add skip annotations, delete tests, or weaken assertions.
+
+Re-run the full test suite after applying fixes.
+
+Evaluate the result (same `failures + killed` count and the same row order as §2):
+
+- Any `^[KILLED]` line or `rc` 3: do NOT stage, do NOT report success, do NOT reset — take the *Suite terminated* row
+- All pass (`rc` 0): run the same probe grep and the artifact grep; on output, remove the probes / the artifact, re-run the suite, and stage only when both are silent and `rc` is still 0. Then `git add -A`, report success, STOP
+- Failures decreased: continue to next iteration (fixes stay in working tree; the next iteration's checkpoint commits them)
+- Regression: `git reset --hard HEAD` (discard uncommitted fixes, return to checkpoint), STOP
+- Circular or non-convergence: `git reset --hard <initial-sha>` (revert ALL iterations), STOP
+- Max iterations reached: `git reset --hard <initial-sha>` (revert ALL iterations), STOP
+</critical_sequence>
+
+## Diagnostic Report
+
+On termination (success or failure), write a report to stdout:
+
+- **Result**: SUCCESS, REGRESSION, CIRCULAR, MAX_ITERATIONS, NON_CONVERGENCE, or UNRESOLVED
+- **Iterations completed**: N out of max
+- **Termination reason**: one-line explanation
+- **Iteration history**: failure count per iteration with delta
+- **Remaining failures**: test name and error message for each (if not success)
+- **Quarantined flakes**: one line per quarantined test — name + filed issue (or `report-only` when no `gh`/remote); a SUCCESS with quarantines renders `SUCCESS (N quarantined — issues #…)`, never a bare green
+- **Fixes applied**: files modified and what changed (last iteration)
+- **Recommendation**: what the user should investigate next (if not success). CIRCULAR or NON_CONVERGENCE on one cluster is an architecture signal, not a fix signal: recommend `soleur:engineering:review:legacy-code-expert` for that cluster's seams and characterization tests before another loop. Likewise when a fix landed but no existing test asserts the behaviour it changed -- this loop never writes tests, so name the agent that should. On NON_CONVERGENCE or MAX_ITERATIONS, name the remaining failures as load-only flake candidates to review against [determinism-checklist.md](./references/determinism-checklist.md) — the isolated re-run under-detects the contention class (fails only under suite load), so the honest answer there is determinism work on the test, not retry.
+
+On success, fixes are staged but NOT committed. Commit through `soleur:ship`, which runs review. A manual commit stays an option and does not skip review: merge stays review-gated (`rf-never-skip-qa-review-before-merging`).
+
+## Key Principles
+
+- Diagnose before fixing -- never guess at the root cause
+- Fix implementation code only -- tests define the contract
+- Truncate aggressively -- failure summaries only, no full stack traces
+- Fail safe -- checkpoint commit before every fix attempt, revert on regression
+- Exit early -- stop as soon as the trajectory indicates non-convergence
+- Stage, do not commit -- respect the Workflow Completion Protocol
+- Probes are not fixes -- a `[DEBUG-<hex4>]` line never checkpoints or stages (ADR-230)
+- Pass-on-retry is a flake to quarantine, not a fix to report

package/skills/test-fix-loop/references/determinism-checklist.md

@@ -0,0 +1,154 @@
+# Determinism checklist for test suites
+
+A suite an agent can trust is *deterministic*: same code, same inputs, same
+result — on any machine, under any load. A suite that is not teaches the
+worst lesson a fix loop can learn: retry until green. A failure that
+disappears on the next run of *unchanged* code was never fixed — it was
+nondeterministic, and it will be back.
+
+This reference is shared by three consumers: `test-fix-loop` applies its
+signatures and quarantine protocol inside the loop,
+`soleur:engineering:review:test-design-reviewer` cites its axes when
+scoring a test's Repeatable property, and `qa` lands
+its flake-vs-regression discrimination here for the follow-through fix.
+
+## Flake signatures
+
+Name the shape before fixing it — each signature routes to a different
+axis below.
+
+- **Pass-on-retry.** The test fails inside the suite and passes when the
+  same test is re-run in isolation on *unchanged* code — no fix applied.
+  This is the signature the loop's quarantine screen detects: one isolated
+  re-run per newly-failed test, keyed by file + test name (the same `it()`
+  title in two files is two entries, not one flake). A retry that itself
+  errors or times out is NOT a pass — the failure stays on the fix path.
+- **Order-dependence.** Passes alone, fails in the suite (or the inverse)
+  — shared mutable state, leaked globals, an unfrozen clock or leaked env
+  var left over from a sibling test.
+- **Environment-dependence.** Green locally and on branch CI, red on
+  merge-group or shared-runner runs — the issue #10649 shape: a
+  timing-sensitive suite that only fails under load it never sees in
+  isolation. Isolated re-runs under-detect this class; the honest fix is
+  determinism work on the test, not another retry.
+
+## The quarantine protocol
+
+For each test the screen marks pass-on-retry:
+
+1. **Isolate** — re-run the one test in isolation via the runner's filter
+   flag (`vitest -t`, `pytest -k`, `go test -run`, `bun test -t` /
+   `--test-name-pattern`). When the runner cannot filter, one suite-level
+   re-run of unchanged code answers the same question by absence.
+2. **File** — when the repo has a GitHub remote and `gh` is available,
+   file `flake: <test> — <signature>`. Ensure the `flaky` label first
+   (`gh label create` with `|| true` — self-heals on a repo that lacks
+   it and never rewrites an existing one), then dedupe on a sentinel,
+   not the title: `gh issue list --state open --label flaky --json
+   number,body` and match `<!-- soleur:flake test="<file>::<name>" -->`
+   in the bodies — comment on the existing tracker instead of filing a
+   duplicate (the sentinel-dedup arm of `check-red-on-main.sh` in this
+   repo; an `in:title "…"` phrase breaks on a test name carrying `"` or
+   search-significant punctuation). The issue body carries the sentinel
+   line, the pass-on-retry signature, the runner command, and a pointer
+   to this checklist; apply `--label flaky` on create or via
+   `gh issue edit`. With no `gh`/remote, the quarantine is report-only
+   and says so.
+3. **Track** — the quarantined set is run-scoped: excluded from the
+   failure set driving fix/cluster bookkeeping and the delta counts,
+   never counted as fixed, never re-entered on a later re-failure (the
+   re-failure is noted in the report and the filed issue instead). It
+   consumes no fix-round tally — no fix was attempted.
+4. **Un-quarantine** — a flake tracker that stays open forever trains the
+   label to be ignored. Convention: auto-close the issue on the next
+   green run of the same suite, mirroring the auto-close-stale arm of
+   `scheduled-integration-suites.yml` (one green run closes it — "a
+   transient flake leaves a permanently open issue and trains the label
+   to be ignored"). A repo with no scheduled re-runner keeps the tracker
+   until a later loop or a human observes green.
+
+Quarantine is bookkeeping + tracker + report — it never edits, skips, or
+deletes a test file, and a quarantined failure never counts toward
+"fixed" nor trips a circular-fix verdict.
+
+## The determinism checklist
+
+When a filed flake or a flaky-shaped new test needs a root cause, walk
+the axes — most flakes resolve to exactly one.
+
+### Seeds — make randomness reproducible
+
+An unseeded RNG is a test that fails on inputs nobody can replay. Seed
+every random source the test touches (`faker.seed(123)`, a stubbed or
+injected `Math.random`, synthesized fixtures over live UUID factories).
+Property-based runners already print their seed — log it in the failure
+line so a red run is reproducible verbatim. (Unseeded-RNG substring
+collisions are a measured class: rename the fixture rather than regexing
+around it.)
+
+### Clocks — freeze time
+
+A test that reads wall-clock time is nondeterministic by construction.
+Freeze the clock the harness provides (`vi.useFakeTimers` +
+`vi.setSystemTime`, `timekeeper`, `freezegun`), and never assert exact
+equality on a measured quantity — bound it (`-le`, `expect.poll`, a
+range); a real clock can tick between the before and after reads.
+Cross-service tests need the same skew discipline at both ends: a
+timestamp written by one clock and compared by another drifts.
+
+### Network — controlled, fail-loud
+
+Real network inside a unit test is a flake farm: latency, DNS, rate
+limits, vendor brownouts. Stub the seam — and make the stub fail LOUD on
+an unexpected request (an allowlist router that 500s on anything
+unregistered), not return a default that silently passes. DOM emulators
+ship real network adapters (happy-dom's `fetch`/`WebSocket` reach the
+wire): the blockade is what turns "no network" from an intention into a
+property.
+
+### State isolation — no residue between tests
+
+Every test leaves the world as it found it: fresh fixture state per test
+(`beforeEach`, not a `beforeAll` that mutates), no shared files, no
+leaked env vars or globals, no singleton carried into the next case. A
+describe-level row or a mutated module registry is an order-dependence
+signature waiting for a scheduler to expose it.
+
+### Output terseness — quiet on green, loud on red
+
+Chatty suites bury the failure line in noise. Run the runner quiet
+(`--reporter=dot`, `-q`, the runner's quiet flag) and keep failure output
+terse (test name + error, not a stack dump). Terseness is a correctness
+property for consumers, not a style one: the loop's parse-failures step
+reads only the summary, and any `| tail` / pipefail chain reads the last
+line — only a terse summary makes that line the verdict.
+
+### Contention / ordering — load boundaries
+
+The signature an isolated re-run structurally cannot see: a test that
+fails only under suite load — parallel workers racing a fixed port, a
+tmpfs watchdog, a file lock, a `sleep`-gated resource. The issue #10649
+shape: green in isolation and on branch CI, red in merge-group runs
+carrying unrelated diffs. Disciplines: allocate ports and tmpdirs per
+worker, never fixed; wait on real signals (poll the port or lock, never
+`sleep`); keep watchdog budgets per-test, not per-run. A contention
+flake can carry two mechanisms at once (an intra-test wait budget AND a
+cold-import cost): triage to mechanism, never bump a timeout. For this
+class an isolated re-run answers pass-on-retry honestly — and the fix is
+the determinism work itself, not the retry.
+
+## Using this checklist
+
+- `test-fix-loop`: the §1 quarantine screen applies the signatures and
+  protocol above; a filed flake's issue body points here for the fix
+  work.
+- `soleur:engineering:review:test-design-reviewer`: a new test carrying
+  flake-signal sources (unseeded RNG, wall-clock reads, real network,
+  shared mutable state, nondeterministic output) with no determinism
+  control is a Repeatable WARN — cite the axis.
+- `qa` and humans: the flake-vs-regression discriminator lands here for
+  the "what makes it deterministic" remediation.
+
+Source: Addy Osmani, [Agentic Verification](https://addyo.substack.com/p/agentic-verification)
+("fast and deterministic" — a suite an agent can trust must be both; a
+pass on retry is a flake to isolate, not a fix to report).