gauntlet-spec 0.1.1__tar.gz

gauntlet_spec-0.1.1/.claude/settings.json

@@ -0,0 +1,17 @@
+{
+  "_comment": "Gauntlet safety wiring (FR-7.3, plan P2). The PreToolUse hook routes every tool call through the localhost judge via the gauntlet-judge-hook console script (installed on PATH by `uv tool install` / `pipx install`, FR-1.1; `gauntlet init` writes this file, FR-1.2). The hook is safe-by-default: with no GAUNTLET_JUDGE_TOKEN configured it returns `ask` and defers to normal permission handling, so a session without a running judge is never bricked. Under an active gauntlet run the engine sets GAUNTLET_JUDGE_TOKEN/URL/MODE; unattended runs fail closed on a dead judge, interactive sessions fall back to a prompt (review F-004).",
+  "hooks": {
+    "PreToolUse": [
+      {
+        "matcher": "*",
+        "hooks": [
+          {
+            "type": "command",
+            "command": "gauntlet-judge-hook",
+            "timeout": 15
+          }
+        ]
+      }
+    ]
+  }
+}

gauntlet_spec-0.1.1/.codex/hooks.json

@@ -0,0 +1,17 @@
+{
+  "_comment": "Gauntlet safety wiring for Codex (FR-1.2, FR-7.3). The PreToolUse hook routes Codex Bash tool calls through the same localhost judge as Claude Code, via the gauntlet-judge-hook console script (installed on PATH by `uv tool install` / `pipx install`, FR-1.1). NOTE (BOOTSTRAP-NOTES #10, ratified 2026-06-11): `codex exec` does NOT fire PreToolUse hooks on the pinned build (codex-cli 0.139.0) — the hook runtime is app-server/TUI-only. Codex's headless pre-execution control is therefore its SANDBOX (read-only for review steps, workspace-write for build steps), which `.gauntlet/config.yaml` sets per profile. This file is committable and forward-looking: it activates automatically if a future codex build fires exec hooks, at which point `gauntlet doctor` reports the firing change. The exact codex hooks schema is unverified on the pinned build (the hook never fires to exercise it); it mirrors the shared stdin-JSON / exit-code-2 / permissionDecision contract the hook client speaks.",
+  "hooks": {
+    "PreToolUse": [
+      {
+        "matcher": "Bash",
+        "hooks": [
+          {
+            "type": "command",
+            "command": "gauntlet-judge-hook",
+            "timeout": 15
+          }
+        ]
+      }
+    ]
+  }
+}

gauntlet_spec-0.1.1/.gauntlet/config.yaml

@@ -0,0 +1,65 @@
+# Gauntlet run configuration (FR-2.1, plan P3).
+#
+# Agent profiles bind adapter + model + flags; pipeline steps reference them by
+# name (`agent: builder`). Swapping builder/reviewer roles is a YAML edit here or
+# a per-step override — no code change (FR-2.2). The engine builds the actual
+# adapter via the entry-point registry (FR-2.4) and lints flags at load (§8).
+#
+# `gauntlet init` will scaffold this file in P6; it is hand-authored for the
+# bootstrap so the P3 engine has profiles to resolve.
+
+base_branch: main
+branch_prefix: "gauntlet/"
+# Single run-root for plan/transcripts/manifests (BOOTSTRAP-NOTES #2 / #13).
+run_root: runs
+test_command: "uv run pytest"
+
+# On resume of a step killed mid-edit with a dirty worktree (review F-003):
+#   park          -> stop for a human (default; nothing re-run over partial work)
+#   reset_to_base -> back up the partial work to a ref, reset to base, re-run
+interrupted_step: park
+
+agents:
+  builder:
+    adapter: claude-code
+    # Short alias form — the only spelling claude 2.1.172 resolves (pinned;
+    # `claude-opus-latest` 404s, caught live at P5 start, notes #24).
+    model: opus
+    permission_mode: acceptEdits
+    allowed_tools: [Bash, Read, Write, Edit, Grep, Glob]
+    # claude loads the repo's PreToolUse hook only under project setting sources
+    # (pins.yaml); the engine-managed judge cannot gate the builder without it.
+    base_flags: ["--setting-sources", "project"]
+    # A bootstrap implement step is a long-running build; the adapter's 600s
+    # default would halt it mid-phase (FR-3.3 applies, just with a realistic
+    # ceiling — notes #25).
+    step_timeout_s: 5400
+  reviewer:
+    adapter: codex
+    model: gpt-5.5
+    sandbox: read-only        # pure review steps are read-only (FR-9.6)
+  # Cheap-tier models verified live on this machine (P1/P4 contract runs; only
+  # an OpenAI key is present and `claude-haiku-latest` does not resolve via
+  # LiteLLM — see pins.yaml). FR-3.1 tiering: mini for classification, full
+  # model for severity-aware triage escalation (P4, review F-009).
+  triage:
+    adapter: api
+    model: gpt-5-mini
+  escalation:
+    adapter: api
+    model: gpt-5
+  judge_llm:
+    adapter: api
+    model: gpt-5-mini
+
+# Per-agent commit identities (FR-9.7) so git log distinguishes who authored what.
+identities:
+  builder:
+    name: "Gauntlet Builder (claude)"
+    email: "builder@gauntlet.local"
+  reviewer:
+    name: "Gauntlet Reviewer (codex)"
+    email: "reviewer@gauntlet.local"
+  triage:
+    name: "Gauntlet Triage"
+    email: "triage@gauntlet.local"

gauntlet_spec-0.1.1/.gauntlet/pins.yaml

@@ -0,0 +1,185 @@
+# Doctor pin file (FR-1.5 groundwork, plan P1).
+# Records the installed CLI versions and the exact flags the P1 contract
+# suite verified against them (uv run pytest -m integration, 2026-06-10,
+# 9/9 passed). Written from what the installed CLIs actually do — where
+# observed behavior differs from the PRD/prompt, this file and a
+# BOOTSTRAP-NOTES.md entry win.
+verified_date: "2026-06-10"
+clis:
+  claude:
+    version: "2.1.172"
+    verified_flags:
+      - flag: "-p --output-format json (prompt via stdin)"
+        verified: >-
+          Single result object on stdout with result, session_id,
+          total_cost_usd, structured_output, and usage
+          {input_tokens, output_tokens, cache_read_input_tokens, ...}.
+      - flag: "--output-format stream-json"
+        verified: >-
+          JSONL events (system/init with session_id, assistant turns, final
+          result). Requires --verbose in -p mode.
+      - flag: "--resume <session-id>"
+        verified: >-
+          Continues the recorded session in -p mode; prior-turn content
+          (codeword) recalled.
+      - flag: "--model haiku"
+        verified: "Model alias resolves; used for all smoke traffic."
+      - flag: "--model opus"
+        verified: >-
+          P5 start: short alias resolves (modelUsage reports claude-opus-4-8).
+          The long form `claude-opus-latest` is REJECTED with an in-band 404
+          result (is_error=true, exit 1) — the builder profile must use the
+          short alias. Caught live by the first engine-driven builder step;
+          evidence preserved by the P4 failure-path transcripts (F-007).
+      - flag: '--tools ""'
+        verified: "Empty string disables all built-in tools (tool-less smoke)."
+      - flag: "--json-schema <inline-json>"
+        verified: >-
+          Native structured output: conforming object surfaced in the result
+          event's structured_output field (PRD assumed best-effort JSON for
+          claude — positive divergence, see BOOTSTRAP-NOTES #9).
+      - flag: "--permission-mode acceptEdits + --allowedTools/--tools Write"
+        verified: >-
+          Write tool ran unprompted in a disposable fixture repo; file
+          created with expected content.
+      - flag: "PreToolUse hook via .claude/settings.json (--setting-sources project)"
+        verified: >-
+          P2: fires in `claude -p` for Bash tool calls. Payload carries
+          {session_id, cwd, hook_event_name, tool_name, tool_input{command},
+          tool_use_id, permission_mode}. Emitting hookSpecificOutput
+          permissionDecision=deny blocks the tool PRE-execution and surfaces
+          the reason to the agent (verified end-to-end: denied echo never
+          produced its output). permissionDecision=allow proceeds;
+          unreachable+interactive falls back to a normal prompt (no deadlock).
+    notes:
+      - >-
+        Cost IS reported (total_cost_usd) on this install, so the tokens-only
+        degraded path (PRD §12 Q3) is claude's fallback, not its default.
+      - >-
+        Permission-bypass flags observed in --help (--dangerously-skip-permissions,
+        --allow-dangerously-skip-permissions, --bare which skips hooks,
+        --permission-mode bypassPermissions) are rejected by the config lint.
+      - >-
+        P3: no --max-turns flag on claude 2.1.172 (`claude --help` has no
+        turn/limit option), and `codex exec` has no turn cap either. The engine
+        therefore rejects `max_turns` at pipeline load (review F-006); the
+        working per-step halts are timeout_s and budget_usd (FR-3.3).
+  codex:
+    version: "codex-cli 0.139.0"
+    verified_flags:
+      - flag: "exec --json (prompt via stdin with '-')"
+        verified: >-
+          JSONL events on stdout: thread.started{thread_id}, turn.started,
+          item.completed{item.type=agent_message, text}, turn.completed
+          {usage: input_tokens, cached_input_tokens, output_tokens,
+          reasoning_output_tokens}.
+      - flag: "exec --output-schema <file>"
+        verified: >-
+          Final agent message conformed to the schema; parsed and validated
+          first try (consistent with the plan-cycle-r1 capture).
+      - flag: "exec --output-schema (P4 live review path, strict-mode rules)"
+        verified: >-
+          P4: the schema is enforced server-side under OpenAI strict mode —
+          a schema whose `required` omits any declared property is rejected
+          with HTTP 400 before the model runs (exit 1). "Optional" fields
+          must be spelled required-but-nullable (type ["string","null"]);
+          `pattern` constraints were removed from the normative schemas to
+          stay inside the strict subset. With schemas/findings.json in that
+          form, the live adversarial_cycle contract test round-tripped:
+          review findings validated, fix-round commit, diff-scoped confirm
+          verdicts validated (tests/integration/test_cycle_contract.py).
+      - flag: "--output-last-message <file>"
+        verified: >-
+          Long form live-verified: file written with the final agent message
+          text (fresh exec and resume). The -o short alias is observed in
+          --help only, not exercised by the contract suite.
+      - flag: "-s read-only / -s workspace-write"
+        verified: >-
+          read-only used for all review/smoke runs; workspace-write created a
+          file in a disposable fixture repo.
+      - flag: "exec resume <session-id>"
+        verified: >-
+          Live contract tests: plain resume recalled prior-turn content
+          (codeword), and resume + --output-schema + --output-last-message
+          returned conforming JSON (the combination P4's confirm pass relies
+          on). resume accepts --json/--output-schema/--output-last-message
+          but NOT --sandbox/-s (help-surface assertion test) — the sandbox
+          must be pinned via -c sandbox_mode="..." on resume.
+    notes:
+      - >-
+        --full-auto does NOT exist on `codex exec` 0.139.0 (PRD §4.1/plan
+        mention it): exec is already non-interactive; the sandbox flag alone
+        governs write access. Verified by a help-surface assertion test, not
+        a live run. See BOOTSTRAP-NOTES #9.
+      - >-
+        Cost is never reported in the event stream — tokens-only degraded
+        path (PRD §12 Q3) is codex's normal mode.
+      - >-
+        Bypass flags observed in --help (--dangerously-bypass-approvals-and-sandbox,
+        --dangerously-bypass-hook-trust, -s danger-full-access) are rejected
+        by the config lint.
+      - >-
+        P2 HOOK FINDING (deviation, ratified by John 2026-06-11): `codex exec`
+        does NOT fire PreToolUse hooks on 0.139.0 — verified against project
+        `.codex/hooks.json`, user `~/.codex/hooks.json`, `[features].hooks=true`
+        (globally stable+true), and even `--dangerously-bypass-hook-trust`. The
+        hook runtime (hooks/list, hook trust review) is app-server/TUI-only.
+        Codex's pre-execution control is therefore its SANDBOX, verified live:
+        `-s read-only` blocks all writes; `-s workspace-write` confines writes
+        to the workspace + system temp (TMPDIR/`/tmp` are writable by design),
+        and refuses writes to `$HOME`. The codex hook client is wired but inert
+        on this build; it activates automatically if a future codex fires exec
+        hooks. FR-7's "100% blocked pre-execution + audit" is met via claude;
+        codex is sandbox-sourced (coarser, no per-command judge audit). See
+        BOOTSTRAP-NOTES #10.
+  api_models:
+    version: "litellm (P4 verification, 2026-06-11)"
+    verified_flags:
+      - flag: "gpt-5-mini via LiteLLM (triage/judge_llm cheap tier)"
+        verified: >-
+          P4: live completion + cost reporting work with the present OpenAI
+          key (~$0.00015 per short call). Ran the full 36-finding triage
+          accuracy harness: 94.4% verdict agreement, blocking 9/9, zero
+          unescalated blocking→reject misses (report at
+          runs/gauntlet-bootstrap/manual/p4-triage-accuracy.md).
+      - flag: "gpt-5 via LiteLLM (escalation tier, review F-009)"
+        verified: "P4: live completion + cost reporting (~9x mini's price)."
+    notes:
+      - >-
+        `claude-haiku-latest` (the previous configured triage model) does NOT
+        resolve via LiteLLM, and no Anthropic key is present in this
+        environment — the profile could never have run here. Swapped to the
+        verified models above; BOOTSTRAP-NOTES #19.
+  judge:
+    version: "gauntlet P2 (this repo)"
+    verified_flags:
+      - flag: "fast-path decision latency (FR-7.2 target p50 < 150 ms)"
+        verified: >-
+          Server-side policy fast-path p50 ≈ 2.4 ms (in-process timing in the
+          judge audit log), far under the 150 ms target. Measured over the
+          live red-team + benign hook runs in test_judge_live.py.
+      - flag: "FR-7 red-team acceptance (claude path)"
+        verified: >-
+          25/25 dangerous commands denied through the real gauntlet-judge-hook
+          binary against a live judge (exit 2, audit deny). Benign suite
+          fast-path allow rate 100% (≥ 90% required). End-to-end claude block
+          proven via a deny-policy sentinel.
+      - flag: "P3 engine-managed judge lifecycle + live agent_task gating"
+        verified: >-
+          `gauntlet run` starts the judge (python -m gauntlet judge serve),
+          injects per-run GAUNTLET_JUDGE_{TOKEN,URL,MODE,RUN_ID} + per-step
+          GAUNTLET_STEP_ID, and stops it on exit (no env leakage). A real
+          agent_task->shell->commit pipeline ran through the live judge: the
+          builder's `echo` tool call was gated by the PreToolUse hook and
+          audited as fast-path ALLOW with the run/step ids attributed. REQUIRES
+          the claude builder profile to pass `--setting-sources project`
+          (base_flags) — without it claude does not load the repo hook and the
+          agent runs UNGATED. In-repo writes (`Write` tool / `echo > f`) are not
+          a fast-path allow; they escalate to the judge_llm rung and fail-closed
+          to deny when no classifier is configured (BOOTSTRAP-NOTES #16).
+    notes:
+      - >-
+        Judge binds 127.0.0.1 only and rejects callers without the per-run
+        X-Gauntlet-Token (§8). LLM classifier rung + fail-closed verified by
+        unit tests; the live latency/acceptance numbers above are from the P2
+        contract run.

gauntlet_spec-0.1.1/.github/workflows/release.yml

@@ -0,0 +1,52 @@
+name: Release to PyPI
+
+# Publishes gauntlet-spec to PyPI when a version tag is pushed (e.g. v0.1.1).
+# Uses PyPI Trusted Publishing (OIDC) — no API token stored as a secret.
+# One-time setup on PyPI: add a trusted publisher for this repo pointing at
+# workflow `release.yml` and environment `pypi`.
+
+on:
+  push:
+    tags:
+      - "v*"
+
+permissions:
+  contents: read
+
+jobs:
+  build:
+    name: Build distribution
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - name: Install uv
+        uses: astral-sh/setup-uv@v5
+      - name: Build sdist and wheel
+        run: uv build
+      - name: Verify tag matches package version
+        run: |
+          TAG="${GITHUB_REF_NAME#v}"
+          PKG=$(grep -m1 '^version = ' pyproject.toml | sed -E 's/version = "(.*)"/\1/')
+          if [ "$TAG" != "$PKG" ]; then
+            echo "::error::Tag v$TAG does not match pyproject version $PKG"
+            exit 1
+          fi
+      - uses: actions/upload-artifact@v4
+        with:
+          name: dist
+          path: dist/
+
+  publish:
+    name: Publish to PyPI
+    needs: build
+    runs-on: ubuntu-latest
+    environment: pypi
+    permissions:
+      id-token: write  # required for Trusted Publishing
+    steps:
+      - uses: actions/download-artifact@v4
+        with:
+          name: dist
+          path: dist/
+      - name: Publish
+        uses: pypa/gh-action-pypi-publish@release/v1

gauntlet_spec-0.1.1/.gitignore

@@ -0,0 +1,18 @@
+# Python
+__pycache__/
+*.pyc
+.venv/
+.pytest_cache/
+*.egg-info/
+dist/
+
+# IDE / editor / OS
+.idea/
+.vscode/
+.DS_Store
+
+# P2 judge contract-test audit artifact
+.gauntlet/test-judge-audit.jsonl
+
+# Engine live-run pointers are bookkeeping, never commit payload (notes #13/#22)
+runs/*/active-run.txt

gauntlet_spec-0.1.1/AGENTS.md

@@ -0,0 +1,266 @@
+# AGENTS.md — Gauntlet
+
+This file is read by every Codex session in this repository, whether
+you are **building Gauntlet**, **running as the `builder` agent inside a
+Gauntlet pipeline**, or **acting as the `reviewer` agent**. Read it fully
+before doing anything. The section headers tell you which parts apply to you.
+
+---
+
+## 1. What this project is (always read)
+
+Gauntlet is an adversarial multi-agent development harness. It orchestrates
+a pipeline of: human-authored PRD → adversarial review loop → implementation
+plan → adversarial review loop → phased implementation, where each phase ends
+in a commit and goes through an adversarial review loop before the next phase
+begins. The spec is `PRD-gauntlet.md`. When in doubt, the PRD wins.
+
+**The central invariant:** the worktree is clean and committed at every point
+where control passes to a reviewer. This is not a style preference — it is
+what makes review diffs meaningful, mutation detection possible, and confirm
+passes cheap.
+
+---
+
+## 2. Guiding principles (always read)
+
+These are the values the project will measure implementation against. When a
+decision isn't covered by the PRD, use these to reason toward an answer.
+
+**Determinism over cleverness.** The orchestrator is a state machine. Prefer
+boring, explicit, resumable logic over elegant abstractions that are hard to
+inspect mid-run. A run that survives `kill -9` and resumes correctly is worth
+more than clean code that can't.
+
+**Fail closed.** Every external call — judge service, agent CLI, API adapter —
+defaults to deny/halt on timeout, parse error, or unexpected exit code. A
+stuck run is recoverable. A run that silently continues past a failed safety
+gate is not.
+
+**Separation of concerns between agents.** The builder implements. The
+reviewer reviews. Neither should be asked to do the other's job in the same
+step. When you are the builder, you do not pre-emptively review your own
+work in the same turn; that's the reviewer's job and it will happen.
+
+**Data over inference.** Persist everything — manifests, transcripts, triage
+verdicts, judge decisions, agent identities on commits. Future you, debugging
+a failed run, should never have to infer what happened.
+
+**Process fidelity is part of the deliverable.** When you are building
+Gauntlet, the quality of the process you follow (commit discipline, review
+handoff, triage rigor) is as observable as the code quality. The bootstrap
+is a dogfood run; treat it that way.
+
+**Approved artifacts change only through their own loop and gate.** Do not
+amend an artifact that a human has approved (PRD, plan) because a later phase
+found it incomplete. Halt and surface the conflict. Humans ratify; agents
+propose.
+
+---
+
+## 3. When you are building Gauntlet (bootstrap / development work)
+
+### Branch discipline
+All work goes on `gauntlet/bootstrap` (during bootstrap) or a
+`gauntlet/<slug>` branch thereafter. Never push to or commit directly on the
+base branch.
+
+### Phase discipline
+The implementation plan (`runs/gauntlet/plan.md`) defines phases. Work one
+phase at a time. At the end of each phase:
+
+1. All tests pass (`uv run pytest` — failing tests are a hard stop).
+2. Commit with the enforced format:
+   - Line 1: `PN: <imperative summary, ≤72 chars>`
+   - Blank line
+   - Body: what changed, why, which PRD assumption this phase validates,
+     relevant FR refs, any explicit deferrals to later phases.
+3. Surface the commit SHA and invite the review handoff. Do not continue.
+
+Fix commits use: `PN.x: Address review — <short summary>` with a body that
+lists each addressed finding by ID, the triage verdict, and what changed.
+Declined findings appear in the body as explicitly declined with the triage
+reasoning — declining with a recorded reason is part of the audit trail.
+
+### Tests are the guardrail
+The test suite only grows. Never delete or skip a passing test to make a
+phase pass. If a test is wrong, fix the test in a separate commit with
+justification.
+
+Integration tests that require live CLI credentials are marked
+`@pytest.mark.integration`. CI runs `pytest -m "not integration"`. You run
+the integration suite locally before every review handoff.
+
+### What to decide vs. what to ask
+**Decide yourself:** module layout, library choices within the constraints in
+`BOOTSTRAP-PROMPT.md`, prompt wording, schema field names consistent with
+PRD §7, test structure.
+
+**Stop and ask:** plan deviations, anything requiring credentials or global
+machine state changes, FR conflicts, anything that would amend an already-
+approved artifact, the gate after every phase.
+
+### Safety rules for your own session
+- Never use `--dangerously-skip-permissions` or equivalent bypass flags.
+  This disables the PreToolUse hooks. The hooks are the safety layer.
+- Never force-push or rewrite history on any branch other than the active
+  PRD branch (and only with explicit human instruction there).
+- Never read credential files outside this repository tree.
+- After P2, the judge service hooks your own session. Do not attempt to
+  work around a deny decision; surface it and ask.
+
+### The self-hosting switchover
+After P4 (pipeline engine + adversarial cycle + logger): switch to running
+subsequent phases through `gauntlet run`. Manual process execution from P5
+onward is a bug. Record any gap that forced you to fall back to manual in
+`BOOTSTRAP-NOTES.md`.
+
+---
+
+## 4. When you are the `builder` agent inside a Gauntlet pipeline
+
+You receive a phase prompt referencing the approved PRD and the approved
+implementation plan. Your job in that phase is defined by the plan. Scope
+is everything.
+
+### Your scope
+- Implement exactly what the current phase specifies, per the plan.
+- Write or extend tests to cover the phase's deliverables. Tests pass before
+  you signal completion.
+- Do not implement work belonging to a later phase, even if it seems easy or
+  obviously needed. Record the temptation as a deferral note in the commit
+  body; do not act on it.
+
+### Signaling completion
+When the phase is done and tests pass, signal completion clearly:
+```
+PHASE COMPLETE
+Phase: <PN — title>
+SHA: <commit sha>
+Tests: <N passed, 0 failed>
+Deferrals: <list any scope items pushed to later phases>
+```
+Do not perform the review. Do not pre-critique your own work. The reviewer
+will do that.
+
+### If you discover a plan or PRD conflict
+Stop. Do not proceed. Report:
+```
+UPSTREAM CONFLICT
+Phase: <PN>
+Conflict: <what the plan/PRD says vs. what implementation reveals>
+Options: <what you see as the paths forward>
+```
+The human will resolve it. This is FR-10.4; it is not optional.
+
+---
+
+## 5. When you are the `reviewer` agent inside a Gauntlet pipeline
+
+You are an adversarial reviewer. Your job is to find problems, not to be
+polite. The builder's feelings are not a consideration; shipping broken or
+incomplete work is.
+
+### Review stance
+Be skeptical of everything. The builder had context you don't. Use that
+asymmetry: if something is unclear to you as a reader, it is a finding,
+regardless of whether the author's intent was clear.
+
+### What you are reviewing against
+Always review against three references, in priority order:
+1. The approved `prd.md` — is the spec fully implemented?
+2. The approved `plan.md`, current phase — did the phase deliver what it said?
+3. The guiding principles in §2 of this file — were they followed?
+
+Findings that don't trace to one of these three are likely bikeshedding.
+Label them honestly as such in your `severity` field.
+
+### Output format
+Return findings as structured JSON matching `schemas/findings.json`. Every
+finding must have: `id`, `severity` (blocking/major/minor/nit), `category`,
+`location` (file and line/section), `claim`, `evidence`. Optional:
+`suggested_fix`.
+
+Do not editorialize outside the JSON. The triage agent reads your output
+programmatically.
+
+### On the confirm pass
+You receive: the commit-range diff (pre-fix SHA to post-fix SHA) and your
+prior findings with triage verdicts. For each finding, return:
+```
+{ "finding_id": "F-001", "verdict": "resolved | partially_resolved |
+  unresolved | regression_introduced", "notes": "..." }
+```
+You are checking whether the diff addressed your concern — not re-reviewing
+the whole phase. Scope yourself to the diff.
+
+### Read-only contract
+You do not modify files. You do not run commands that have side effects. If
+your adapter configuration allows write tools and you are tempted to use them:
+write a finding instead, with a suggested_fix. Any worktree mutation by a
+reviewer is a process violation and will be detected.
+
+---
+
+## 6. Stack and project layout (all agents)
+
+```
+src/gauntlet/
+  cli.py          # typer CLI entrypoint
+  engine/         # pipeline state machine, step types, manifest
+  adapters/       # ClaudeCodeAdapter, CodexAdapter, ApiAdapter (LiteLLM)
+  judge/          # FastAPI judge service, policy engine
+  logging/        # transcript logger (md + jsonl)
+  config.py       # pydantic config/schema models
+pipelines/        # YAML pipeline definitions
+prompts/          # versioned prompt templates (data, not code)
+schemas/          # JSON schemas for structured agent outputs
+policy.yaml       # judge fast-path allow/deny rules
+runs/             # per-PRD run artifacts (committable)
+tests/
+  unit/
+  integration/    # requires live CLI creds; pytest -m integration
+BOOTSTRAP-NOTES.md  # process pain points recorded during bootstrap
+PRD-gauntlet.md     # the spec
+```
+
+**Key dependencies:** Python 3.10+, `uv`, `typer`, `pydantic`, `fastapi`,
+`uvicorn`, `litellm`. No heavier orchestration frameworks. The orchestrator
+is thin by design.
+
+**Run tests:** `uv run pytest` (unit only) / `uv run pytest -m integration`
+
+**Install locally:** `uv tool install -e .` or `pipx install -e .`
+
+**Check environment:** `gauntlet doctor`
+
+---
+
+## 7. Commit message format (reference)
+
+```
+PN: Imperative summary of what this phase delivers (≤72 chars)
+
+What changed and why. This is not a restatement of the diff; it is the
+reasoning behind the change. Include:
+- Which PRD assumption this phase validates
+- Relevant FR numbers (e.g. "implements FR-3.3, FR-7.2")
+- Any explicit deferrals: "Deferred to P4: retry logic on ApiAdapter"
+
+For fix commits (PN.x):
+- F-001 [legitimate]: <what was wrong> → <what changed>
+- F-002 [bikeshedding/declined]: <reviewer's concern> — declined because
+  <triage reasoning>
+- F-003 [premature_optimization/declined]: <reviewer's concern> — deferred
+  to post-v1, tracked in FUTURE.md
+```
+
+---
+
+## 8. Files you must not modify without explicit human instruction
+
+- `PRD-gauntlet.md` — the spec; changes require a new PRD revision process
+- Any file in `runs/*/` that represents an approved artifact (`prd.md`,
+  `plan.md`, and manifest entries marked `status: approved`)
+- `policy.yaml` — judge rules; changes go through the retro proposal process
+- `CHANGELOG.md` in `prompts/` — append only, never rewrite history