# Integration Test Verify Loop > [Testing] Use when you need to drive an integration-test suite to fully green — each round runs /integration-test-verify (whole system by default, or the target named in the prompt), and on ANY failure combines /debug-investigate + /integration-test-review (report-only) to adjudicate the fault (test wrong · test not optimal · source wrong), then /fix to resolve it at the owning layer, then /changes-review on that round's fix diff, then re-runs a FRESH full verify — looping until the whole suite passes its 2-consecutive-green-runs gate with zero failures. - Skill: `duc01226/integration-test-verify-loop-2` (Agent Skill) - Install (CLI): `npx skillmds@latest add duc01226/integration-test-verify-loop-2` - Raw SKILL.md: https://api.skillmd.com/api/skills/duc01226/integration-test-verify-loop-2/raw - Safety review: pending - Works with: Claude Code, Claude.ai, OpenAI Codex - Category: AI & ML, Integrations & APIs - Author: duc01226 (https://skillmd.com/u/duc01226) - Updated: 2026-09-22 - Page: https://skillmd.com/skills/duc01226/integration-test-verify-loop-2 --- > Codex compatibility note: > > - Invoke repository skills with `$skill-name` in Codex; this mirrored copy rewrites legacy Claude `/skill-name` references. > - Task tracker mandate: BEFORE executing any workflow or skill step, create/update task tracking for all steps and keep it synchronized as progress changes. > - User-question prompts mean to ask the user directly in Codex. > - Ignore Claude-specific mode-switch instructions when they appear. > - Strict execution contract: when a user explicitly invokes a skill, execute that skill protocol as written. > - Subagent authorization: when a skill is user-invoked or AI-detected and its protocol requires subagents, that skill activation authorizes use of the required `spawn_agent` subagent(s) for that task. > - Do not skip, reorder, or merge protocol steps unless the user explicitly approves the deviation first. > - For workflow skills, execute each listed child-skill step explicitly and report step-by-step evidence. > - If a required step/tool cannot run in this environment, stop and ask the user before adapting. ## Codex Project-Reference Loading (No Hooks) Codex uses static project-reference loading instead of runtime-injected project docs. When coding, planning, debugging, testing, or reviewing, open project docs explicitly using this routing. **Always read:** - `docs/project-config.json` (project-specific paths, commands, modules, and workflow/test settings) - `docs/project-reference/docs-index-reference.md` (routes to the full `docs/project-reference/*` catalog) - `docs/project-reference/lessons.md` (always-on guardrails and anti-patterns) **Missing/stale context route:** If `docs/project-config.json`, the docs index, `lessons.md`, `CLAUDE.md`, `AGENTS.md`, or any task-required reference doc is missing or stale, auto-run `$project-init` or the narrow setup route (`$project-config`, `$docs-init`, `$scan-all`, `$scan --target=`, `$claude-md-init`) before ordinary project-specific work. If Codex mirrors or `AGENTS.md` are missing/stale, ask the user to run `$sync-codex`; do not auto-run it. **Situation-based docs:** - Project structure/architecture/tech-stack/deployment/setup (any layer — backend, frontend, or infra): `project-structure-reference.md` - Backend/CQRS/API/domain/entity changes: `backend-patterns-reference.md`, `domain-entities-reference.md` - Frontend/UI/styling/design-system: `frontend-patterns-reference.md`, `scss-styling-guide.md`, `design-system/README.md` - Spec authoring, `docs/specs/` pathing, or TC format: `feature-spec-reference.md`, `spec-system-reference.md`, `spec-principles.md` - Behavior/public-contract changes or spec-test-code sync: `workflow-spec-test-code-cycle-reference.md` plus the spec docs above - Derived spec indexes/ERDs/reimplementation guides: `spec-system-reference.md` and source Feature Specs under `docs/specs/` - Integration test implementation/review: `integration-test-reference.md` - E2E test implementation/review: `e2e-test-reference.md` - Code review/audit work: `code-review-rules.md` plus domain docs above based on changed files Do not read all docs blindly. Start from `docs-index-reference.md`, then open only relevant files for the task. > **[BLOCKING]** Execute skill steps in declared order. NEVER skip, reorder, or merge steps without explicit user approval. > **[BLOCKING]** Before each step or sub-skill call, update task tracking: set `in_progress` when step starts, set `completed` when step ends. > **[BLOCKING]** Every completed/skipped step MUST include brief evidence or explicit skip reason. > **[BLOCKING]** If Task tools are unavailable, create and maintain an equivalent step-by-step plan tracker with the same status transitions. ## Quick Summary **Goal:** Drive an integration-test suite to **fully green** by pairing `$integration-test-verify` with a combined fault-adjudication + `$fix` half in a recursive loop — each round runs a FRESH full `$integration-test-verify` over `{scope}` (**the WHOLE system by default**, or the target named in the prompt), and on ANY failure runs `$debug-investigate` **and** `$integration-test-review` (report-only) together to decide _who is at fault_, then `$fix` at the owning layer — stopping only when a fresh full verify passes its **2-consecutive-green-runs-without-DB-reset** gate with **zero failed tests**, proven by actual runner output. **Summary:** - **Each round = verify (find) + adjudicate (diagnose) + `$fix` (resolve) + `$changes-review` (prove the fix is sound).** `$integration-test-verify` reports pass/fail but must not own the fix; the adjudication pair decides _test-wrong vs test-not-optimal vs source-wrong_; `$fix` lands the change; `$changes-review` code-reviews that change before the next round. A round is incomplete until all four have run (or the verify returned zero failures). - **Steps (in order):** (0) resolve `{scope}` + Goal Contract → (0b) bind the convergence loop (protocol loop primary + optional `/goal` accelerator) → (1) round loop { snapshot → run `$integration-test-verify` INLINE over `{scope}` → **on failure:** `$debug-investigate` + `$integration-test-review` report-only → emit ONE Fault Verdict per failure → `$fix` at the owning layer → **CONDITIONAL `$changes-review` on the round's fix diff when any fix landed** → Round Integrity Check → log iteration } → (2) converge on a zero-failure fresh verify OR escalate → (3) terminal spec/doc sync + recap. - **Every fix gets code-reviewed in the round that lands it.** Whenever a round applies ANY fix — source, test, scenario, or spec — that round runs `$changes-review` (report-only, INLINE) over the round's fix diff; validated findings fold back into the SAME round's fix set. No fix applied → skipped with a recorded reason. — why: a green test cannot see a wrong-layer fix, a broken invariant elsewhere, or a security/performance regression. - **Default scope is the WHOLE SYSTEM.** With no target in the prompt, `{scope}` = **every** discovered integration-test project (`testProjectPattern` glob > `testProjects` list) — NOT the git-changed subset. The loop passes `{scope}` to `$integration-test-verify` **explicitly** so it never falls through to its change-scoped default (`integration-test-verify/SKILL.md:132,159`). - **Convergence:** stop ONLY when a **fresh full** `$integration-test-verify` over the CURRENT (post-fix) code reports **zero failed tests across 2 consecutive runs without a DB reset**, with real runner output — never a stale green predating the last fix. - **Inline invariant:** run `$integration-test-verify`, `$debug-investigate`, and `$integration-test-review` via the skill invocation, NEVER the `spawn_agent` tool. `$debug-investigate` requires its `$why-review` gate **in the same session/main agent** (`debug-investigate/SKILL.md:34`), and `$integration-test-review` self-binds its own fix + re-review obligations — a sub-agent cannot own or carry either back to this loop. Their OWN internal fan-outs (verify's `integration-tester` per-project sub-agents, `integration-test-review`'s phase agents) stay sub-agents by their own design, so context stays bounded. - **No fake green — Round Integrity Check:** a round converges only if the executed test count did **not shrink** and the skipped count did **not grow** versus the prior round. Deleting, skipping, or narrowing tests is a REGRESSION, never convergence. - **Bounded:** round cap default 3; failing count not shrinking across 2 rounds, or cap hit with failures still open → **STOP & escalate** by asking the user directly. Increasing failures → STOP (fixes regressing). Environment/infrastructure fault → **BLOCKED**, escalate immediately — never loop against an unhealthy system. **Why this skill exists (READ FIRST — it is the whole justification):** the obligation to loop already exists as **prose scattered across three skills**, with no mechanism behind it. `$integration-test-verify` says _"After fixing → re-run the full 2-run verify sequence"_ (`integration-test-verify/SKILL.md:238`) and its `SYNC:integration-test-execution-discipline` §5 says _"Loop until the whole suite is green"_ (`:404`) — but there is **no round cap, no Goal Contract, no shrinking-failures gate, and no escalation path**, so an agent that fixes one test and reports success is not violating anything mechanical. Worse, the fix half is **triple-owned and undefined**: `$integration-test-review` fixes tests and re-reviews itself (P5–P8), `$fix --target=test` runs its own unbounded _"if tests fail, repeat from step 2"_ (`fix/SKILL.md:218`), and verify's own failure protocol says fix-and-re-run (`:232-238`) — three overlapping loops that can double-fix the same failure or each assume another owns it. This skill makes the loop a **bounded, evidence-gated convergence contract with one owner**: verify FINDS, the `$debug-investigate` + `$integration-test-review` pair ADJUDICATES fault, `$fix` RESOLVES, and a fresh full verify RE-PROVES — with a Round Integrity Check so the suite can never go "green" by losing tests. Without it, "tests failed, then something fixed them" ships on a single green run over a hand-picked subset. **Workflow:** resolve `{scope}` (whole system by default) + Goal Contract → bind the convergence loop → **round loop** { run `$integration-test-verify` INLINE → on failure run `$debug-investigate` + `$integration-test-review` report-only → emit Fault Verdict → `$fix` at owning layer → conditional `$changes-review` on the round's fix diff → Round Integrity Check → log iteration } → converge when a fresh full verify is 2/2 green with zero failures → terminal `$spec [mode=sync]` + `$docs-update` + recap. **Key Rules:** - **Each round pairs verify (find) + adjudicate (diagnose) + `$fix` (resolve) + `$changes-review` (review the fix).** Never skip the adjudication half and jump straight to a fix — an unadjudicated failure gets "fixed" by whatever is nearest, which is almost always the assertion. - **CONDITIONAL `$changes-review` every round that lands a fix.** Working tree changed vs the round's snapshot → run `$changes-review` INLINE, report-only, scoped to the round's fix diff; validate its findings and fold them into the SAME round's fix set; unfixable validated findings → STOP & escalate. Working tree unchanged → skip with a recorded reason. NEVER let a round's fixes reach the next round un-reviewed. - **Default `{scope}` = the WHOLE system**; a target named in the prompt narrows it. Pass `{scope}` to `$integration-test-verify` EXPLICITLY every round — never let it fall back to git auto-detect. - **MUST run INLINE via the skill invocation — NEVER dispatch `$integration-test-verify`, `$debug-investigate`, `$integration-test-review`, or `$changes-review` as a sub-agent** (their in-session gates are lost). Their internal fan-outs remain sub-agents by their own design. - **`$integration-test-review` runs REPORT-ONLY.** It performs its 8-gate review and STOPS before its P5 fix / P6 re-review / P7 build-and-run — the loop owns fixing and re-running. If it cannot be constrained and self-fixes anyway, treat that as this round's fix half and skip the `$fix` step for that round — never double-fix. - **One written Fault Verdict per failure BEFORE any edit** — `TEST-WRONG` · `TEST-NOT-OPTIMAL` · `SOURCE-WRONG` · `ENVIRONMENT-BLOCKED` · `AMBIGUOUS` — with `file:line` evidence and confidence. `AMBIGUOUS` → ask the user directly, never a silent pick. - **NEVER force green.** No weakened or removed assertions, no skip annotations, no widened assertion timeouts, no retries around a failing assertion, no repository-hacked domain data, no narrowed scope. Fix the SCENARIO (an ARRANGE barrier on a real observable) or the product defect. - **Convergence = a fresh full verify over the post-fix code, 2/2 green, zero failures, real runner output, Round Integrity Check passed.** All five, or it is not converged. - **Round cap (default 3)**; failures not shrinking across 2 rounds, increasing, or cap hit with failures open → **STOP & escalate** by asking the user directly. `ENVIRONMENT-BLOCKED` → escalate immediately; never loop against an unhealthy system. --- ## First Principle — Convergence, Not Motion > A round that changes the code is progress **only if** the next fresh verify has fewer failing tests. > The loop exists to reach a fixed point (a whole suite that is green twice in a row), not to keep editing until something passes. > If the failing count stops shrinking, that is a signal to **escalate**, not to spin another round. > And a suite that got greener by having fewer tests did not converge — it regressed. --- ## Step 0 — Resolve Verification Scope + Goal Contract (FIRST ACTION) 1. **Read `docs/project-config.json` → `integrationTestVerify`** before anything else (the same config `$integration-test-verify` obeys, `integration-test-verify/SKILL.md:74-92`). You need `quickRunCommand`, `testProjectPattern`, `testProjects`, `systemCheckCommand`, `startupScript`, and `referenceDocs` to resolve scope and to read the project's integration-test reference docs. 2. **Resolve `{scope}` — WHOLE SYSTEM by default:** | Prompt | `{scope}` | | ------------------------------------ | -------------------------------------------------------------------------------------------------------------------------------------------- | | **No target named** (default) | **Every** integration-test project discoverable via `testProjectPattern` glob > `testProjects` list. The WHOLE system. | | Names a suite/project/module/feature | Only the test projects covering that target, resolved from the same config; state which projects the target maps to and how you resolved it. | | Names a diff/branch/PR | The test projects covering that change set — this is the ONLY case where change-scoping is correct, and it must be explicit in the prompt. | > **NEVER let `$integration-test-verify` resolve scope by itself.** Its Step 3 priority ends in git auto-detect and _"Only run projects relevant to the current change"_ (`integration-test-verify/SKILL.md:132,159`) — correct when it is a workflow step after an edit, WRONG as this loop's default. Pass `{scope}` explicitly in the invocation every round. — why: a loop that silently verifies only the changed subset reports "all green" for a system it never ran. 3. **Record `{scope}` as a stable string** (the resolved project list). The scope is FIXED for the whole loop — it never narrows as rounds progress. If a fix legitimately ADDS a test project, widen `{scope}` and say so in the Iteration Log; narrowing it is forbidden. 4. **Resolve/create the Goal Contract** per `SYNC:goal-contract-satisfaction-loop` (`plans/goals/{YYMMDD-HHmm}-{slug}/goal.md`, template `.claude/templates/goal-contract-template.md`). Its single **required** Success Criterion: > _A fresh full `$integration-test-verify` over `{scope}` reports **zero failed tests** across **2 consecutive runs without a DB reset**, evidenced by actual test-runner output (Passed/Failed/Skipped counts), with no test deleted, skipped, or weakened to get there._ Record in **Constraints**: `{scope}` (the project list), the round cap (default 3), the baseline executed/skipped test counts once round 1 reports them, and `quickRunCommand`. ## Step 0b — Bind the Convergence Loop (protocol-first; `/goal` is an optional accelerator) The convergence loop is bound by TWO layers. The **protocol loop (Steps 1–2) is the BINDING mechanism** and MUST be self-driven by you, the running agent, on every host — with or without any command or hook. The **`/goal` command is an OPTIONAL accelerator** layered on top; it is never the primary mechanism, and its absence NEVER weakens the loop. This mirrors the project rule that hooks/trackers are accelerators only — correctness must not depend on them. **1. Protocol loop — ALWAYS binding (hook/command-independent).** You are personally responsible for not stopping until the loop converges or bounded-escalates. This binds Claude, Codex, and Copilot equally, whether or not `/goal` exists: > Repeatedly run `$integration-test-verify` INLINE over `{scope}` (passed explicitly, never re-derived). After each run, if ANY test failed, adjudicate every failure with `$debug-investigate` + `$integration-test-review` (report-only) into ONE Fault Verdict, apply the fix via `$fix` at the owning layer, then re-run a FRESH full `$integration-test-verify` over `{scope}`. Do NOT stop while the last verify still reported a failing test. Converge ONLY when a fresh full verify reports zero failures across 2 consecutive runs without a DB reset AND the Round Integrity Check passes (executed test count not shrunk, skipped count not grown). Cap at `{N=5}` rounds; if the failing count does not shrink across 2 consecutive rounds, failures increase, the cap is hit with failures still open, or any failure is ENVIRONMENT-BLOCKED → STOP and escalate by asking the user directly. Never loop open-ended, and NEVER reach green by weakening, skipping, deleting, or de-scoping a test. Treat this as a standing obligation you re-read at every Step 2 checkpoint — NOT a one-time note you can rationalize away after the first fix cycle. The Goal Contract's required Success Criterion (Step 0) is its durable, host-independent record. **2. `/goal` command — invoke as an accelerator WHEN AVAILABLE.** If a `/goal` command exists and you are permitted to run it in this environment, ALSO invoke it (a real tool/command call, NOT a paraphrase, NOT a Goal Contract file substituted for it) with the SAME condition, so a session Stop hook mechanically enforces the loop: ``` /goal integration-test green convergence loop: repeatedly run $integration-test-verify INLINE over {scope} (passed explicitly). If any test failed → adjudicate each failure with $debug-investigate + $integration-test-review (report-only) into one Fault Verdict, fix via $fix at the owning layer, and run another round. If a fresh full verify reports zero failures across 2 consecutive runs without DB reset AND executed test count has not shrunk and skipped count has not grown → CONVERGED, run the terminal $spec [mode=sync] + $docs-update and clear the gate. Do NOT stop while the last verify still reported a failing test. Cap at {N=5} rounds; if the failing count does not shrink across 2 consecutive rounds, failures increase, the cap is hit with failures open, or a failure is ENVIRONMENT-BLOCKED → STOP and escalate by asking the user directly. Never loop open-ended; never reach green by weakening, skipping, deleting, or de-scoping a test. ``` The `/goal` Stop hook blocks stopping until the condition holds and auto-clears when met — do not tell the user to clear it. **If `/goal` is unavailable, unregistered, or not permitted** (e.g. Codex/Copilot, or a Claude run without the command): DO NOT error, DO NOT block, and DO NOT invent a stand-in gate. Record ONE line in the Goal Contract — `/goal accelerator unavailable — loop bound by protocol (Steps 1–2) + this Goal Contract` — and proceed. The protocol loop above plus the Goal Contract are the same gate, enforced by discipline instead of a hook. > **Nested gates (by design, safe):** each inner `$debug-investigate` self-binds its own `$why-review` validation gate that clears when its root cause is validated, and `$integration-test-review` runs REPORT-ONLY so its P5 fix / P6 re-review loop is deferred to this caller — no inner fix gate is installed. THIS outer loop owns the single convergence gate. All self-clear on satisfaction — no orphaned gate. Do NOT tell the user to clear any of them. ## Step 1 — Round Loop (verify → adjudicate → fix → review → integrity-check → log) Each round couples four halves — **verify to find, adjudicate to diagnose, fix to resolve, `$changes-review` to prove the fix itself is sound.** For each round `R` (starting at 1), do ALL of: 1. **Snapshot before:** record the working-tree fingerprint — `git status --porcelain` + `git diff --stat`. This is the fixes-applied baseline for the round and the objective backstop for convergence detection (Step 2). 2. **Run `$integration-test-verify` INLINE** via the skill invocation (NEVER the `spawn_agent` tool), passing `{scope}` **explicitly** so it skips its own scope derivation. It runs its full contract: system check → the named projects → the **2-consecutive-green-runs-without-DB-reset** gate → a report with real Passed/Failed/Skipped counts and failing test names. Let it fan out its own `integration-tester` sub-agents per isolated project (its design, `integration-test-verify/SKILL.md:188-206`) — that fan-out is bounded and correct. **Tell it explicitly that this run IS a round of this loop**, so it returns its counts + failing names to this loop instead of recommending `$workflow-integration-test-green` as a next step — why: that recommendation is correct for a standalone verify but circular here, and would restart the loop that is already running. 3. **Record the round's counts:** executed, passed, failed, skipped — per project and total, from **actual runner output**. These feed the Round Integrity Check (1.8) and the shrinking-failures gate (Step 2). No output = no counts = no claim. 4. **If failures = 0** and the 2-run gate was green → this round converged; go to Step 2 (no adjudication or fix half needed). 5. **If failures > 0 — ADJUDICATE (the combined half). Run BOTH, INLINE, in this order, per failure or per failure cluster:** **(a) `$debug-investigate`** — trace the failure end-to-start to the defect's owning layer, producing a `file:line` root cause with a confidence score, validated through its own `$why-review` gate. It is investigation-ONLY — it never patches (`debug-investigate/SKILL.md:22`). **(b) `$integration-test-review` — REPORT-ONLY** — scoped to the failing tests **and the production code they exercise**. Its 8 gates supply the test-side verdict: G1 assertion value (mutation probe), G2 data state, G3 repeatability, G4 domain logic (does the test assert only what the handler writes?), G5 spec traceability, G6 three-way sync, G7 change coverage, G8 scenario fidelity. **Direct it to STOP after its findings report** — no P5 fix, no P6 re-review, no P7 build-and-run; this loop owns fixing and re-running. **Combine (a) + (b) into ONE written Fault Verdict per failure, BEFORE any edit:** | Verdict | Meaning | Evidence required | Resolution | | ----------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | **TEST-WRONG** | The test encodes a stale or incorrect assertion, setup, or expectation that contradicts intended behavior | The governing spec (§3 AC / §4 BR / §5 invariant / §8 TC) or the handler source shows the production behavior is correct and the test is not (`file:line`) | Fix the test at its root. NEVER weaken an assertion, add a skip, or relax a timeout. | | **TEST-NOT-OPTIMAL** | The test is directionally right but mis-specified — unrealistic scenario, compressed actor pacing, blind sleep, missing ARRANGE barrier, shared-state repeatability defect, smoke-only or DI-resolution-only assertion | The failing G3/G8 gate plus the ARRANGE block read as a production trace (`file:line`) | Repair the SCENARIO — add an ARRANGE-phase settle barrier polling a real observable, unique data per run, real use-case setup. NEVER a widened assertion timeout or a retry around the assertion. | | **SOURCE-WRONG** | Production code violates the spec's intended behavior or a clear invariant | `$debug-investigate`'s traced root cause at the invariant-owning layer (`file:line`, confidence ≥60%) | Fix the source at the **lowest owning layer** (Entity > Service > Handler), never the crash site. **Keep or strengthen** the test that caught it, and route the changed source into `$changes-review` before declaring PASS (`integration-test-verify/SKILL.md:294`). | | **ENVIRONMENT-BLOCKED** | Infrastructure, services, containers, or data fixtures are not ready — the system, not the code, is failing | The `systemCheckCommand` output or the runner error naming the unavailable dependency | **STOP the loop and escalate.** Point the user at `startupScript`. NEVER change a test because the system was down (`integration-test-verify/SKILL.md:296`). | | **AMBIGUOUS** | Intended behavior is unclear — no spec covers it, the spec is silent, or spec and code disagree with no tiebreaker | State exactly what is undetermined and which artifacts you checked | **ask the user directly before editing either side.** NEVER silently pick source or test just to make the suite pass. | **Intermittent failures (red in one run of the 2-run gate, green in the other) use the three-way flake adjudication instead** — (a) unrealistic scenario / compressed pacing, (b) harness topology amplification, (c) genuine product race — per `integration-test-verify/SKILL.md:298-316`. Record the verdict with evidence BEFORE any change; do NOT file (c) until (a) and (b) are ruled out. 6. **Run `$fix` on the adjudicated verdicts** (failures > 0 only) — this is the half the loop owns. Resolve each at its owning layer, routed by verdict: `SOURCE-WRONG` → `$fix` (its `--target` routing) or a direct edit at the lowest invariant-owning layer, then `$prove-fix`; `TEST-WRONG` / `TEST-NOT-OPTIMAL` → repair the test or scenario at its root; a missing §8 TC surfaced by G5/G7 → `$spec [mode=tests]`; a spec divergence → adjudicate per `SYNC:spec-drift-adjudication` (`$spec [update]` for SPEC-STALE, a BLOCKING fix for CODE-WRONG). Fix ONLY adjudicated verdicts — never an unadjudicated guess. > **If `$integration-test-review` could not be constrained to report-only and already applied its P5 fixes**, treat those as this round's fix half (detect fixes-applied against the 1.1 snapshot) and SKIP this step for that round — never double-fix the same failure. 7. **CONDITIONAL — run `$changes-review` on the round's fix diff, when (and only when) the round applied ANY fix.** Compare the working tree against the 1.1 snapshot: unchanged → SKIP this sub-step and record `No fix applied this round — $changes-review skipped`. Changed → run it, every round, on every round's fixes. - **Scope = the round's fix diff**, not the whole branch: exactly the files this round changed since the 1.1 snapshot (source fixes, test fixes, scenario repairs, spec/TC edits alike). — why: the round's own changes are the only thing the prior rounds' reviews have not already seen. - **Run it INLINE via the skill invocation, REPORT-ONLY** — its full dimensional review, then STOP before its Phase 7 self-fix / Phase 7.5 holistic / Phase 8 docs-update (the documented `$workflow-review-changes` boundary where the caller owns fixing, `changes-review/SKILL.md:52,204`). NEVER dispatch it as a sub-agent — it self-binds its own review-loop obligations, which a sub-agent cannot own or carry back (`changes-review-loop/SKILL.md:37`). Its own Phase 0.7 dimensional reviewers stay sub-agents by its design. - **Validate, then fold the surviving findings into THIS round's fix set** — run `$why-review --validate-findings` over its report and apply every VALIDATED finding at its owning layer, exactly as in 1.6. The next round's fresh full verify is what re-proves them, so the test loop stays the single convergence engine — do NOT open a nested review→fix loop here. - **Unfixable validated findings → STOP & escalate** by asking the user directly (Step 2). A round that leaves a validated review finding open has not finished, even if its tests went green. - **This subsumes the `SOURCE-WRONG` per-verdict routing** in 1.5: that verdict already demands the changed source reach `$changes-review` before PASS (`integration-test-verify/SKILL.md:294`). Running it once per round over the whole fix diff satisfies that obligation AND extends it to test-side and spec-side fixes — do not run it twice for the same diff. — why: the loop's own convergence signal is "the tests went green", and a fix that greens a test can still be wrong in every way a test cannot see — wrong layer, broken invariant elsewhere, dead code, a leaked domain concept, a security or performance regression. Without a per-round review, every fix this loop lands ships un-code-reviewed on the strength of a green suite alone. 8. **Round Integrity Check (no fake green) — BLOCKING before the round can count as progress.** Compare this round's counts (1.3) against the prior round's: | Signal | Meaning | Action | | ------------------------------------------ | --------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------- | | Executed test count **decreased** | Tests were deleted, renamed out of discovery, filtered out, or the scope narrowed | **REGRESSION → STOP & escalate.** Restore the tests. A smaller suite is not a greener suite. | | Skipped count **increased** | A failure was hidden behind a skip annotation | **REGRESSION → STOP & escalate.** Remove the skip and adjudicate the failure properly. | | `{scope}` project list **shrank** | The loop de-scoped its way to green | **REGRESSION → STOP & escalate.** `{scope}` is fixed (Step 0.3). | | Counts stable or grown, failures shrinking | Genuine progress | Continue to Step 2. | — why: unlike a review loop, a test loop has a cheap fake exit — remove what fails. This check is the only thing standing between "converged" and "quietly deleted the hard tests". 9. **Append an Iteration Log entry** to the Goal Contract: round number, per-project executed/passed/failed/skipped counts, the failing test names, each Fault Verdict with its `file:line` evidence and confidence, the fixes applied (`file:line`), the `$changes-review` verdict for the round's fix diff (or the explicit skip reason when no fix landed), the Round Integrity Check result, and remaining gaps. ## Step 2 — Convergence & Escalation Gate Evaluate after every round: | Condition | Action | | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------ | | Fresh full `$integration-test-verify` over `{scope}` reported **zero failures across 2 consecutive runs without a DB reset**, AND the Round Integrity Check passed, AND the working tree is unchanged by that final verify pass | **CONVERGED** → mark the required criterion PASS in the Goal Satisfaction matrix (attaching the runner output) → clear the `/goal` gate → go to Step 3. | | Failures > 0 AND round `< N` AND the failing count shrank vs the prior round AND integrity held | Apply the adjudicated fixes (Step 1.6), then run round `R+1` (fresh full re-verify over the SAME `{scope}`). | | Failing count did **not shrink** across 2 consecutive rounds (same/increasing count) | **STOP & escalate** by asking the user directly — a non-converging loop is a signal, not a reason to spin. | | Round cap `N` hit with failures still open | **STOP & escalate** by asking the user directly — report the still-failing tests with their Fault Verdicts; do not silently continue. | | Any failure adjudicated **ENVIRONMENT-BLOCKED** | **STOP & escalate immediately** — mark the criterion BLOCKED with a user-facing reason and point at `startupScript`. Never loop against an unhealthy system. | | Any failure adjudicated **AMBIGUOUS** | **PAUSE and ask the user directly** before the fix — resume the loop with the user's answer. | | Round Integrity Check failed (tests lost, skips added, scope narrowed) | **STOP & escalate** — restore the lost coverage first; this is a regression, not progress. | | The round's `$changes-review` (1.7) left **validated findings unfixed** | **STOP & escalate** by asking the user directly — a green suite does not clear an open, validated review finding on the fix that greened it. | > **Increasing failures = STOP.** If round `R` has MORE failing tests than round `R-1`, the fixes are regressing the system — STOP and escalate immediately. Never trade one green test for two new red ones across rounds. ## Step 3 — Terminal Spec/Doc Sync + Recap 1. **Terminal sync (MANDATORY once converged, when running STANDALONE).** The loop deferred all downstream sync while it churned, so close it now, in order: - **`$spec [mode=sync]`** — reconcile §8 TCs ↔ the executing test code; update every `CoveredBy` field for tests the loop changed or added. - **`$docs-update`** — update impacted docs: the integration-test reference doc, feature-doc evidence fields, and version history if coverage changed materially. > **When this skill runs as a step inside a workflow that already declares `$spec [mode=sync]`, `$scan --target=integration-tests`, and `$docs-update`** (e.g. `workflow-integration-test-green`), SKIP this sub-step and let the workflow own it — say so explicitly in the recap. — why: running the same sync twice churns the same files and hides which pass actually made the change. 2. **Recap.** Emit a concise convergence recap: rounds run, the shrinking failing-count sequence, each round's Fault Verdicts and the fixes applied, the final zero-failure runner output (both runs), the Round Integrity Check trail (executed/skipped counts per round), and the Goal Satisfaction matrix (required criterion PASS). Point to each round's report under `plans/reports/` and the Goal Contract Iteration Log. Do NOT commit or push unless the user explicitly asks. --- ## Convergence Detection — Why Five Conditions A round converges ONLY when **all five** hold. Each closes a distinct way a test loop lies to itself: 1. **Fresh verify over the post-fix code** — a green report from a run that predates the last fix proves nothing about that fix. Every applied fix invalidates the prior verdict; re-run, never reuse. 2. **Zero failed tests** — not "only known failures left", not "the important ones pass". A single red test is an unconverged loop. 3. **2 consecutive green runs without a DB reset** — the gate `$integration-test-verify` already owns (`integration-test-verify/SKILL.md:44,169`). One green run hides order-dependent and state-leak flakiness, which is exactly what a fix cycle tends to introduce. 4. **Real runner output** — Passed/Failed/Skipped counts and names. "Looks like it passed" is theater (`integration-test-verify/SKILL.md:339`). 5. **Round Integrity Check passed** — the executed count did not shrink, the skipped count did not grow, `{scope}` did not narrow. This is the condition the other four cannot see: a suite can satisfy 1–4 perfectly by having quietly lost the tests that failed. **Working-tree-unchanged backstop:** the c …(truncated)