🛡️ Gauntlet Loop — Bounded Multi-Agent Quality Improvement Loop

A deterministic, bounded quality improvement loop that eliminates infinite token burns, self-grading delusions, and regression churn. Deploys an unyielding, 4-role protocol (Freeze → Build → Fresh Critic → Automated Gate → Integrator) with hard mathematically enforced termination boundaries, OWASP security header verification, and multi-viewport visual regression gates.

Modes

Every invocation resolves to exactly one mode. Load only the matched reference:

When to Use

Trigger Conditions

Execute this skill when:

1. Multi-Round Code/Doc Refinement: A complex task requires iterative quality improvement across multiple passes.
2. Preventing Self-Grading Delusion: The builder agent must NOT evaluate its own output; an isolated Fresh Critic must score the work against frozen criteria.
3. Web Application Hardening Gate: Iterating on web apps, frontend templates, or API servers requiring strict security headers (CSP, HSTS) and responsive viewport checks (375px, 768px, 1280px).
4. Hard Stop Boundaries Required: Guarding against runaway agent loops where changes oscillate or degrade previous passes.
5. Mission-Critical Delivery: High-stakes deliverables requiring an ironclad ACCEPTANCE_PACKET.md.

Anti-Triggers

Do NOT use this skill when:

• The task is a trivial one-liner fix or typo correction (use direct editing).
• The task is exploratory research without a concrete deliverable (use research subagent).
• Task dependencies are heavily coupled and unsplit (run coupling-router first).

Quick Reference

The 4 Gauntlet Roles & Blind Reference Bar

┌─────────────────┐       ┌─────────────────┐       ┌─────────────────────────────┐       ┌─────────────────┐
│     BUILDER     │ ────▶ │  FRESH CRITIC   │ ────▶ │       AUTOMATED GATE        │ ────▶ │   INTEGRATOR    │
│ Minimal, clean  │       │ Blind audit vs  │       │ Tests, types, secret scans, │       │ Merges ONLY the │
│ diff candidate  │       │ NAMED REAL BAR  │       │ security headers & viewports│       │ #1 largest fix  │
└─────────────────┘       └─────────────────┘       └─────────────────────────────┘       └─────────────────┘

🎯 "The Bar is the Whole Trick" Doctrine

The loop only produces quality if the thing it compares against is real:

• Named: A specific entity, not an abstract category ("Nike's running landing page", not "modern athletic sites").
• Fetchable: The critic can obtain the raw reality (live URL screenshot, published article, test suite).
• Comparable: Both artifacts can sit side-by-side so a judge can pick a winner.

Stop Conditions Matrix

Right-sized change verification (tiers — do not over/under-check)

Match the check depth to the change's blast radius before committing, so small edits don't burn tokens and risky ones don't slip (keeper: 99rebels/regression-guard):

This is a checkpoint, not a controller — it surfaces findings for the agent/user to decide, and it runs after the change before the full test suite. Most changes are Tier 1 (80%+).

Web Application Automated Gate Checklist

When evaluating web endpoints or frontend components:

• Security Headers (OWASP): CSP, HSTS, X-Frame-Options: DENY, X-Content-Type-Options: nosniff, Referrer-Policy: strict-origin-when-cross-origin.
• Responsive Viewports: Tested at 375px (mobile), 768px (tablet), 1280px (desktop) for zero horizontal scrollbar overflow (scrollWidth === innerWidth).
• CMS-Cohesion & Hardcoded Copy Gate: When CMS/page builder is detected, ensure all editable marketing copy and customizable styles live inside CMS collections/globals/tokens. Hardcoded text blocks (>60 chars) or inline CSS bypassing tokens must be flagged (bun anti-drift.ts --scan-cms-cohesion).
• Verified Deploy Gate: Before marking any web delivery task complete, verify the preview/staging URL returns HTTP 200 without runtime fatal exceptions (bun anti-drift.ts --verify-deploy <url>).

Procedure

Option A: Autonomous Multi-Role Execution Loop

Step 1 — Set the Real Bar & Freeze the Job Contract (GAUNTLET_JOB_CONTRACT.md)

1. Intake triage ratchet (superpowers/brainstorming S1): classify the job aloud as spike (throwaway probe), bounded (fixed-scope fix), or architectural (structural change). Complexity upgrades the path, never downgrades it. Human-approval gate before ANY code on every path — freeze the contract first, build never.
2. Name the Bar: If the user supplied a reference, use it. If not, offer 2 or 3 candidate bars (one line each) and wait for their pick.
3. Lock Contract: Record in workspace root:
   • Goal: Precise, measurable objective statement.
   • Concrete Bar: Named fetchable reference artifact.
   • Acceptance Criteria: 3–5 binary checkboxes + OWASP security headers + responsive viewports.
   • Automated Proof Commands: Pinned commands (bun test, tsc --noEmit, SecretScan.ts, curl header audits).
   • Iteration Budget: Max rounds (default 3, hard ceiling 5).

Step 2 — Round Execution Loop (with Blind A/B Critique)

Round N (N = 1..max_rounds):
  1. BUILD: Builder produces candidate patch based strictly on previous round critic feedback.
      - **Fresh worker per task (superpowers/subagent-driven-development S3)**: spawn a fresh worker per round/task with the brief file as the single source — never paste prior-round history. Per-task review against spec + quality.
      - **Fix-loop cap with escalation (S3)**: hard cap 5 rounds; rounds 4–5 escalate (stronger model / narrower scope) and any further failure escalates to human with ledger receipt. **Ledger over memory**: `ITERATION_LEDGER.md` is the source of truth (compaction-proof) — rulings recorded there, not carried in context.
      - **Evidence baseline pre-step (#35)**: before producing a fix, run the target test/command to capture its RED (failing) state. A fix may not enter the loop without this baseline on record — the loop later proves the fix turned it green.
      - **High-certainty sweep gate (#34)**: when working from an issue/finding list, deep-review each candidate first, then touch ONLY small, high-certainty bugs with a clear root cause. Refuse large or uncertain changes as out of scope — note them in the ledger and return, don't burn the round on guesswork.
      - **Sweep autonomy ladder (lane A #7 brooks-sweep)**: safe changes (typos, formatting, isolated renames, pinned-dependency bumps with green gate) auto-apply; risky changes (API/signature, migrations, security headers, cross-file refactors) require explicit confirm-first. Read-only audit stays excluded from auto-apply.
  2. AUDIT (Blind A/B): Spawn isolated Fresh Critic subagent with NO memory of builder reasoning.
      - Strip labels from candidate and bar.
      - Put candidate next to the bar blind; judge which is better and name the single biggest remaining gap.
      - **Root-cause-before-fix (superpowers/systematic-debugging S5)**: no fix scores above 5 on Correctness without a named root cause (Symptom→Source chain); symptom-only patches are rejected feedback, not progress. **3 failed fixes → question architecture**: three rounds failing on the same root cause stops the fix loop — escalate to an architecture question instead of burning rounds 4–5 on the same shape.
      - **Second-model review gate + refusal routing (lane A #12 gbrain-cross-modal-review)**: on high-stakes rounds, route the blind critique to a second model; on critic refusal, silently switch reviewer (log the switch in the ledger) rather than stalling the loop.
      - **Metric honesty** (source: `addyosmani/agent-skills` agents `web-performance-auditor`): never fabricate a measurement — unmeasured = `not measured`, lab ≠ field.
      - **No-persona-spawns** (source: `addyosmani/agent-skills` agents rule): the critic never delegates to sub-reviewers; orchestration belongs to the loop caller.
      - **Prove-It** (H12 test-engineer rule): already landed as the TDD iron law above (S4) — cited, not duplicated.
      - **Adversarial reviewer** (source: lane H1 #7 `doubt-driven-development`): prompt critic to disprove, not confirm; evidence = ARTIFACT+CONTRACT only, never CLAIM; non-triviality gate (5 criteria); CLAIM→EXTRACT→DOUBT→RECONCILE→STOP with 3-cycle cap, then STOP/escalate.
      - Score 0.0–10.0 across: Correctness (40%), Minimal Diff (25%), Edge Cases (20%), Architecture (15%).
  3. GATE: Run automated proof suite AND integrity checks AND Web App Security & Visual Gate:
      - **TDD iron law — Automated Gate clause (superpowers/tdd S4)**: watch the test FAIL first or it proves nothing; code written before its failing test is deleted and the round restarts. Evidence (RED receipt) before claim, every round.
      - **Discover-the-Stack-First preamble** (source: `addyosmani/agent-skills` `test-driven-development`): read package.json/wrappers/framework/conventions/CI before the first test; focused-test command in the loop, full suite before completion; never assume `npm test`.
      - **Testing-patterns bar** (source: `addyosmani/agent-skills` `references/testing-patterns`): AAA structure, names `[unit]-[behavior]-[condition]`, mock-at-boundaries-only matrix (mock DB/HTTP/FS/clock; never mock internals or pure functions), and the 8-row anti-pattern table. JS/TS syntax illustrative — principles portable across stacks.
      - **Test-bloat gate (#33)**: every generated or altered test must be non-vacuous and independently valuable — it must be capable of failing on the defect class it guards and must assert something the other tests don't. Strip assertions that can never fire and near-duplicate asserts added to inflate coverage; a screen of smoke asserts inflates line-and-assert counts, not proof.
     - Check 5 mandatory security headers (CSP, HSTS, X-Frame-Options, X-Content-Type-Options, Referrer-Policy).
     - Check 3 responsive viewports (375px, 768px, 1280px) for zero horizontal overflow.
     - **Quality-bar regression check**: scan the round's diff for a lowered bar — new suppression directives, skipped or deleted tests, weakened assertions, thresholds edited down. Any of these zeroes the round score (0.0): a build that passes because the bar was lowered is a regression, not a pass.
     - **Fail-closed eval check**: confirm the proof suite contains at least one test that CAN fail on the defect class the round claims to fix. If nothing in the suite could have caught the defect, a green run proves nothing — the round does not pass until a capable test exists (write it, watch it fail on the pre-fix state).
     - Any test failure, missing critical security header, visual overflow, quality-bar regression, or failed fail-closed check zeroes the round score (0.0).
  4. RECORD: Append round metrics, header receipts, viewport outcomes, and finding counts (new findings vs fixed findings this round) to ITERATION_LEDGER.md — the ledger is the convergence instrument: when new findings outnumber fixed findings two rounds running, the loop is diverging, not converging — stop and escalate instead of burning the remaining budget. **Deduplicate by root cause before counting**: if a finding from a previous round reappears (even under new phrasing), it is NOT a new finding — it is an unfinished one and counts against convergence, not for it.
      - **Tech-debt roadmap (#32)**: after each bounded loop, write the fixed/refused findings into a durable TECHNICAL_DEBT.md (workspace `.agents/artifacts/`) — root cause, file, ref and one-line fix — so improvement stays stateful across sessions and checkpoints survive the loop ending. This roadmap is the persistent backlog, distinct from the per-run convergence ledger.
      - **Tech-debt sprint mode (lane A #8 tech-debt-sprint)**: when the contract scopes a debt sprint, run inventory taxonomy first (TODOs, outdated deps, missing tests, god objects) → fix smells → remove dead code → harden review pass. Each phase logs into the ledger; refused items land in TECHNICAL_DEBT.md.
  5. DECIDE: Evaluate Stop Conditions Matrix.

Step 3 — Integrator Gate

The Integrator agent NEVER merges bulk diffs. It isolates and applies only the single highest-impact delta that directly improved the score, preserving all previously verified baselines.

Step 4 — Acceptance Packet Synthesis (ACCEPTANCE_PACKET.md)

Upon reaching success termination, compile the final artifact:

• Summary of rounds executed and score trajectory ($R_1 \rightarrow R_N$).
• Verbatim execution receipts of automated proof commands, security headers, and viewport checks.
• Verified diff summary and signature.

Option B: Gauntlet Prompt Synthesizer Mode

When the user asks to "make a gauntlet prompt" or "loop until it beats X", craft ONE short, paste-ready prompt (120–180 words):

1. Set the Bar: Name a concrete, fetchable reference.
2. Break into Pieces: Smallest judgeable components.
3. Blind Critic Directive: Fresh critic puts output next to the bar blind with labels stripped and names the #1 biggest gap.
4. Offer to Run: Append flat line: I can run this here.

Pitfalls

• Self-Grading Bias: Never allow the builder subagent to evaluate its own work. The critic MUST run in an isolated conversation context.
• Overlooking Security Headers: Shipping web apps or APIs with missing CSP or HSTS headers.
• Horizontal Scroll Blowout: Failing to audit the 375px mobile viewport for layout blowouts.
• Diff Bloat Across Iterations: Reject candidates that expand the diff surface by $>30%$ without a proportional score increase.
• Ignoring Score Plateau: If round 2 scores 7.5 and round 3 scores 7.4, STOP immediately. Do not attempt round 4.
• Lowered-Bar Green: Passing the gate by suppressing, skipping, or weakening checks in the same diff — the gate measures the artifact, not the artifact's ability to evade measurement.
• Vacuous Green: Accepting a green proof suite that contains no test capable of failing on the round's defect class — an unevaluatable claim is not a pass; add the capable test first.

Verification

Before declaring gauntlet completion:

1. GAUNTLET_JOB_CONTRACT.md exists with frozen acceptance criteria.
2. ITERATION_LEDGER.md logs every round with objective critic score breakdown.
3. All automated proof commands exit with return code 0.
4. Web applications pass security header audit (CSP, HSTS, X-Frame-Options, X-Content-Type-Options, Referrer-Policy).
5. Multi-viewport visual check passes at 375px, 768px, and 1280px with zero horizontal overflow.
6. ACCEPTANCE_PACKET.md is generated with final verification receipts.
7. CMS-Cohesion audit passes when a CMS or visual page builder is present.
8. Live deployment preview is verified with HTTP 200 response receipt.