From d5b4531c2289be1b9e4abab6d7c1e56ef69a93fc Mon Sep 17 00:00:00 2001
From: Alex Clarke <alex.j.tusa@gmail.com>
Date: Fri, 11 Sep 2026 14:16:46 -0600
Subject: [PATCH] docs: Added documentation for the new and improved code
 review suite

---
 Agents.md | 86 ++++++++++++++++++++++++++++++++++++++-----------------
 Macros.md |  2 ++
 Skills.md |  3 +-
 3 files changed, 62 insertions(+), 29 deletions(-)

diff --git a/Agents.md b/Agents.md
index 2dac67a..fb816d5 100644
--- a/Agents.md
+++ b/Agents.md
@@ -547,7 +547,7 @@ Claude Code or OpenCode handle complex multi-step tasks.
 
 For a working example of an orchestrator agent that uses sub-agent spawning, see the built-in
 [sisyphus](https://github.com/Dark-Alex-17/coyote/blob/main/assets/agents/sisyphus) agent. For an example of the teammate messaging pattern with parallel sub-agents, 
-see the [code-reviewer](https://github.com/Dark-Alex-17/coyote/blob/main/assets/agents/code-reviewer) agent.
+see the [domain-reviewer](https://github.com/Dark-Alex-17/coyote/blob/main/assets/agents/domain-reviewer) agent.
 
 > **Jobs vs. sub-agents:** sub-agents are for work that needs *reasoning*: they run a full LLM loop. To background a
 > single long-running **tool call** (a build, a test suite, a slow MCP invocation), use the
@@ -726,7 +726,7 @@ agent__check_inbox
 
 Messages are routed through the parent's supervisor. A parent can message its children, and children can message
 their siblings. For a working example of the teammate pattern, see the built-in
-[code-reviewer](https://github.com/Dark-Alex-17/coyote/blob/main/assets/agents/code-reviewer) agent, which spawns file-specific reviewers that share
+[domain-reviewer](https://github.com/Dark-Alex-17/coyote/blob/main/assets/agents/domain-reviewer) agent, which spawns file-specific reviewers that share
 cross-cutting findings with each other.
 
 Sub-agents run by [graph agent nodes](Graph-Agents#agent) can also form per-fan-out teams: set `teammates: true` on the
@@ -828,7 +828,7 @@ otherwise. For the full skills model, including the frontmatter format, validati
 the graph-agent variant, see the [Skills Guide](Skills).
 
 For working examples of agents that use skills heavily, see the bundled
-[`file-reviewer`](https://github.com/Dark-Alex-17/coyote/blob/main/assets/agents/file-reviewer) and [`code-reviewer`](https://github.com/Dark-Alex-17/coyote/blob/main/assets/agents/code-reviewer) agents.
+[`file-reviewer`](https://github.com/Dark-Alex-17/coyote/blob/main/assets/agents/file-reviewer) and [`domain-reviewer`](https://github.com/Dark-Alex-17/coyote/blob/main/assets/agents/domain-reviewer) agents.
 
 ## 10. Auto-Injected Prompts
 
@@ -852,12 +852,16 @@ available; only the auto-injected prompt text is suppressed.
 # Built-In Agents
 Coyote comes packaged with some useful built-in agents:
 
-* `adversary`: An adversarial plan-conformance reviewer. Where `code-reviewer` asks "is this code good?",
-   `adversary` asks "is this the code the plan asked for — all of it, and only it?". Given a diff plus the
-   task/plan's acceptance criteria, it maps every criterion to evidence in the diff and hunts for silently
-   skipped criteria, scope drift, interface substitution, and requirements that never landed ("the dog that
-   didn't bark"), returning a blocking `ADVERSARIAL_REVIEW: CONFORMS`/`DIVERGES` verdict (via the
-   `adversarial-review` skill). The post-implementation counterpart to `oracle`'s pre-implementation
+* `adversary`: A graph-based adversarial plan-conformance reviewer. Where `code-reviewer` asks "is this code good?",
+   `adversary` asks "is this the code the plan asked for? All of it, and only it?". The graph extracts the plan's
+   acceptance criteria into a list and fans out one fresh-context verification branch per criterion, so partial
+   coverage ("checked 8 of 12 and waved the rest through") is structurally impossible. Each verdict passes a
+   deterministic contract gate: `MET` requires evidence including the test proving the behavior (no test means at
+   best `PARTIAL`), malformed output is rejected once then recorded as `PARTIAL` (unproven). Then, a holistic
+   ADDITIVE-only pass hunts what per-criterion checks can't see: absence ("the dog that didn't bark"), scope drift,
+   interface substitution, silently-overridden recorded decisions, and gamed tests. A script computes the blocking
+   `ADVERSARIAL_REVIEW: CONFORMS`/`DIVERGES` verdict: CONFORMS requires every criterion MET with zero holistic
+   complaints, and a missing plan fails closed. The post-implementation counterpart to `oracle`'s pre-implementation
    `plan-review`. Designed to be delegated to by `sisyphus` alongside `code-reviewer` (they cover different
    failure modes: quality vs. conformance).
 * `architecture-reviewer`: An on-demand architecture improvement scout (via the `codebase-design` skill). Scans a
@@ -869,8 +873,8 @@ Coyote comes packaged with some useful built-in agents:
    doc, decomposes it into a quality-gated plan (`gatekeeper` self-containedness gate + `oracle`
    plan-review) and ~1-engineer-day task files (via the `design-session` and `task-tracking` skills,
    tracked on disk in a `plans/` directory), spawns one `sisyphus` per task on a single run branch with a
-   per-task `adversary` conformance check (plus a `probe` usage-pattern check when the task changes
-    consumer-facing surface), and finishes with ONE draft PR, CI checks watched to green,
+   per-task `review-gauntlet` done-gate (forced `adversary` conformance lane, plus `probe` when the task
+   changes consumer-facing surface), and finishes with ONE draft PR, CI checks watched to green,
    plus follow-up task files for every manual action the code can't do for itself. Ends with a
    `whetstone` continuous-improvement pass when the run addressed review feedback from outside its
    own lanes. Supports opt-in
@@ -879,31 +883,47 @@ Coyote comes packaged with some useful built-in agents:
    `other:<label>` via a design-time `librarian` lookup), which flows into every downstream reviewer, with
    an evidence-cited rejection protocol for convention findings.
 * `coder`: An agent to assist you with all your coding tasks
-* `code-reviewer`: A [CodeRabbit](https://coderabbit.ai)-style code reviewer that spawns per-file reviewers using the 
-   teammate messaging pattern and synthesizes their findings into a severity-tagged report. Includes an optional
-   operational-history lane (via the `incident-prior-art` skill): git archaeology on guards the diff deletes or
-   weakens, plus, when the `prior_art_agent` variable names an incident-historian agent, a sweep of your incident
-   record for past outages the change risks reintroducing. Resolves a quality bar (`rigor` + `surfaces`), which
-   are caller-passed, read from the active plan's frontmatter, or detected from the diff, and runs domain linters
-   (tflint/checkov, hadolint, actionlint, kubeconform) once orchestrator-side, routes the matching
-   surface-review skills into each file-reviewer, and folds below-threshold `[convention]` findings into a
-   `## Deferred by quality bar` section per the rigor level (🔴 findings never fold).
+* `code-reviewer`: A [CodeRabbit](https://coderabbit.ai)-style graph-based review orchestrator — the deterministic
+   shell around LLM review judgment. Scripts resolve the diff, the quality bar (`rigor` + `surfaces`: caller-passed,
+   read from the active plan's frontmatter, or detected from the diff), repo conventions, matching review-miss
+   ledger patterns, and repo-history signals (fix/revert clusters plus prior PR review comments on fragile paths);
+   domain linters (tflint, hadolint, actionlint, `buf breaking`) run unconditionally when installed. Changed files
+   are grouped into DOMAIN slices — deterministic proposal, LLM refinement, and an exact-cover gate so no file can
+   be lost — and each slice is reviewed in parallel by a `domain-reviewer` leader with peer messaging between
+   leaders; every leader report passes a completeness gate (mandatory sections present even when clean,
+   reject-and-retry once). A synthesis node with NO verdict authority merges findings, `finding-verifier`
+   re-validates every 🔴/🟡 on an unskippable graph edge, and a SCRIPT computes the rigor folding
+   (below-threshold `[convention]` findings defer; 🔴 never folds) and the `MERGE-READY`/`NEEDS-HUMAN` verdict with
+   deterministic always-human triggers (destructive migrations, auth surface) — the model that wrote the findings
+   never grades its own homework. Optional lanes: operational history (`prior_art_agent`), org context
+   (`org_context_agent`), and a downstream-consumers sweep (`consumers_root`/`github_org`).
 * `demo`: An example agent to use for reference when learning to create your own agents
 * `deep-research`: A graph-based agent designed to perform deep web research 
+* `domain-reviewer`: A domain-slice review leader (used by the `code-reviewer` graph). Where `file-reviewer`
+   reviews one file in isolation, `domain-reviewer` reviews a group of RELATED changed files (e.g. the DB migration
+   plus the queries that use it, the routes plus their handlers, etc.) as one coherent unit: guard symmetry across the
+   slice's sibling paths, literal/enum drift between files, schema↔usage mismatch, and slice-level blast-radius /
+   test-adequacy / removed-guard checks reported even when clean. Small slices are reviewed directly with the full
+   skill stack; larger ones fan out one `file-reviewer` per file with a sibling roster. Leaders run as parallel
+   map branches with teammate messaging armed, so the DB leader can warn the API leader about a renamed column
+   mid-review. Emits a machine-checked report contract ending in `DOMAIN_REVIEW_COMPLETE`.
 * `explore`: An agent designed to help you explore and understand your codebase
-* `file-reviewer`: An agent designed to perform code-review on a single file (used by the `code-reviewer` agent).
+* `file-reviewer`: An agent designed to perform code-review on a single file (used by `domain-reviewer` inside the `code-reviewer` graph).
    Reviews with the `code-review` and `ai-slop-remover` skills, and additionally loads the `transactional-integrity`
    skill when the diff touches state-changing code (e.g. DB writes, transactions, queue/webhook/job handlers, retries, or
    external side effects, etc.) to catch atomicity gaps, read-modify-write races, non-idempotent handlers of at-least-once
    inputs, and dual-writes with no reconciliation. Also loads `logging-discipline` on diffs with operational
-   surface, and, when the orchestrating `code-reviewer`'s surface routing names them, the surface-contract
+   surface, and, when the orchestrator's surface routing names them, the surface-contract
    review skills (`rest-api-review`, `cli-review`, `library-review`, `worker-review`, `iac-review`,
    `migration-review`, `cicd-review`), whose findings carry `[convention]`/`[correctness]` markers used for
    rigor folding and the evidence-cited rejection protocol downstream.
-* `finding-verifier`: A graph-based fact-checker for code-review findings (used by the `code-reviewer` agent).
+* `finding-verifier`: A graph-based fact-checker for code-review findings (wired into the `code-reviewer`
+   graph as an unskippable edge).
    Maps over a review's 🔴/🟡 findings in parallel, fresh context per finding, so the verifier inherits none of
    the reviewer's assumptions, re-reads the cited code, and returns `VERIFIED` (with quoted evidence), `FALSE`
-   (only with proof, e.g. the "missing" guard exists at another path:line), or `UNVERIFIABLE` (kept, marked).
+   (only with proof, e.g. the "missing" guard exists at another path:line), or `UNVERIFIABLE` (kept, marked). Each branch's verdict passes a deterministic contract gate
+   (machine-validated JSON, authoritative id stamped from the finding itself, retry once; malformed output
+   records `UNVERIFIABLE` — a bad branch never sinks the run).
    It never re-judges severity. It only tests whether a claim is true. `code-reviewer` uses the verdicts to
    drop provably-false findings before the final report; dropped findings are tallied, never silently vanished.
 * `gatekeeper`: A plan self-containedness gate (via the `plan-gatekeeping` skill). Audits a plan against
@@ -929,16 +949,28 @@ Coyote comes packaged with some useful built-in agents:
    its tests are deliverables adopted as permanent regression coverage. Designed to be delegated to by
    `sisyphus` and `architect` when a change touches consumer-visible surface.
 * `report-writer`: An agent to polish research findings into clear, citation-preserving final reports
+* `review-gauntlet`: A graph-based "done gate" that runs the whole review stack as ONE spawn. A script derives
+   deterministic change signals (auth surface, dependency/migration/exec changes, consumer-facing surface), an LLM
+   node may ADD lanes but never remove them, and a rules floor guarantees the minimum panel: `code-reviewer`
+   always, `adversary` whenever plan context exists, `security-reviewer` on security-relevant signals, and `probe`
+   when consumer surface changed and a local-run recipe exists. Lanes run in parallel with verdict independence
+   (no teammate messaging between reviewers), each lane's sentinel is machine-parsed (a missing or malformed
+   verdict BLOCKS, it never passes), and a script computes the final `GAUNTLET: PASS`/`BLOCKED` verdict (probe
+   `INCONCLUSIVE` blocks with an environment note, never coerced to pass or fail). The preferred way for
+   `sisyphus` and `architect` to run the review stack.
 * `security-reviewer`: A security analyst for code changes (via the `security-review` skill). Traces untrusted data
    from sources to dangerous sinks (injection, committed secrets, authn/authz gaps, path traversal, SSRF, unsafe
    deserialization, supply chain), then returns a posture-gated `SECURITY_REVIEW: PASS`/`FAIL` verdict. The
    `security_posture` variable (`prototype`/`standard`/`hardened`) sets the blocking threshold so POCs aren't held to
-   production strictness, while Critical findings (leaked credentials, host-endangering code) block in every posture.
+   production strictness, while Critical findings (leaked credentials, host-endangering code) block in every posture. Runs a
+   mechanized pre-pass first (gitleaks/semgrep/dependency audits when already installed) whose hits are leads
+   to trace, never pasted findings.
    Designed to be delegated to by `sisyphus` alongside `code-reviewer` and `adversary`.
 * `sisyphus`: A powerhouse orchestrator agent for writing complex code and acting as a natural language interface for 
    your codebase (similar to ClaudeCode, Gemini CLI, Codex, or OpenCode). Uses sub-agent spawning to delegate to 
-   `explore`, `librarian`, `coder`, `oracle`, `code-reviewer`, `adversary`, `security-reviewer`, `probe`, `step-runner`, and `whetstone`. On 
-   non-trivial work it runs up to four complementary independent review passes: `code-reviewer` for code quality, 
+   `explore`, `librarian`, `coder`, `oracle`, `review-gauntlet`, `code-reviewer`, `adversary`, `security-reviewer`, `probe`, `step-runner`, and `whetstone`. On 
+   non-trivial work it runs the review stack, preferably as ONE `review-gauntlet` spawn (the done gate
+   that machine-parses every lane's verdict), else as up to four individual review passes: `code-reviewer` for code quality, 
    `adversary` for plan conformance, and `security-reviewer` for exploitability when the change touches attack 
    surface, and `probe` for black-box usage-pattern verification when the change touches
    consumer-facing surface. After a run that addressed review feedback from outside its own lanes (humans,
diff --git a/Macros.md b/Macros.md
index 38ad9c7..a804977 100644
--- a/Macros.md
+++ b/Macros.md
@@ -210,6 +210,8 @@ on how to make your own macros, so be sure to check out the [built-in macro defi
 looking for more examples.
 
 * `generate-commit-message` - Generate a Git commit message based on the staged changes in the current directory
+* `record-miss` - Record a code review suite miss into the review miss ledger at `<config_dir>/share/review-misses.md` so that it is not missed
+  on future code review suite runs.
 
 Built-in macros are written to your macros directory on first run and never overwritten afterward, so your edits are
 preserved across Coyote updates. To discard local changes and reinstall the built-in macros from the current Coyote build,
diff --git a/Skills.md b/Skills.md
index be00b19..af14051 100644
--- a/Skills.md
+++ b/Skills.md
@@ -411,10 +411,9 @@ Coyote ships with thirty-five built-in skills, installed automatically on first
 | `verification-gates`  | `execute_command`                                                        | Evidence requirements (diagnostics, builds, tests) before claiming completion. |
 | `plan-authoring`      | `fs_read, fs_grep, fs_glob, fs_ls, fs_cat, fs_write`                     | Author executable high-level plans and per-step implementation plans for phased work; defines the plan repo layout and step-plan schema. |
 | `plan-review`         | `fs_read, fs_grep, fs_glob, fs_ls, fs_cat`                               | Adversarial review of implementation plans against executability, verifiability, and completeness standards. |
-| `adversarial-review`  | `fs_read, fs_grep, fs_glob, fs_cat, fs_ls`                               | Adversarial plan-conformance review of an *implementation* against the plan it should satisfy (skipped criteria, scope drift, interface substitution); verdict `CONFORMS`/`DIVERGES`. Complements `code-review` (quality) and is the post-implementation counterpart to `plan-review`. |
 | `plan-gatekeeping`    | `fs_read, fs_grep, fs_glob, fs_cat, fs_ls`                               | Gatekeep a plan for *self-containedness* before finalization: the "sealed container" test — every implementer question answered inline or via a verified pointer; verdict `PLAN_GATE: SEALED`/`LEAKY` with the missing questions. |
 | `usage-pattern-testing` | `fs_read, fs_cat, fs_grep, fs_glob, fs_ls, fs_write, fs_patch, execute_command` | Black-box verification of a change's consumer-facing surface (HTTP APIs, RPCs, CLIs) against a locally running instance with clean state: run the repo's existing usage suites first (regression check, whatever their format, e.g. Hurl files, curl scripts, collections), then author spec-first tests for the uncovered delta in the repo's suite conventions (tools like Hurl/grpcurl are examples, not requirements); every failure classified BUG / EXPECTED-CHANGE / ENV; verdict `USAGE_PROBE: PASS`/`FAIL`/`INCONCLUSIVE`. The only review gate that tests *behavior* by using the thing, not reading it. |
-| `review-misses`       | none (knowledge-only)                                                    | The review-miss ledger: escaped defects (bugs that survived review and were caught later) recorded as reusable detection patterns in `~/.config/coyote/share/review-misses.md`. Review orchestrators load the skill, read the ledger, and route matching entries to reviewers as first-class checks. The feedback loop that makes the review stack converge instead of plateau. Companion macros: `record-miss` (record one escape) and `mine-review-misses` (batch-mine PR history); `whetstone` also writes entries. |
+| `review-misses`       | none (knowledge-only)                                                    | The review-miss ledger: escaped defects (bugs that survived review and were caught later) recorded as reusable detection patterns in `~/.config/coyote/share/review-misses.md`. Review orchestrators load the skill, read the ledger, and route matching entries to reviewers as first-class checks. The feedback loop that makes the review stack converge instead of plateau. Companion macro: `record-miss` (record one escape); `whetstone` and PR-review-round reconciliation feed a candidates inbox automatically. Promotion into the ledger stays approval-gated. |
 | `design-session`      | `fs_read, fs_grep, fs_glob, fs_ls, fs_cat, fs_write`                     | AI-first design decomposition: ground a design doc in the actual codebase, produce a PLAN file with approach, alternatives, and a ~1-engineer-day task breakdown with measurable acceptance criteria. Includes a quality-bar round declaring `rigor` (poc/prototype/production) and `surfaces`, which calibrate every downstream review gate. |
 | `task-tracking`       | `fs_read, fs_grep, fs_glob, fs_ls, fs_cat, fs_write, fs_patch, fs_mkdir` | File-based task tracking for plan-driven runs: TASK-NNN directory schema (`index.md` + append-only `log.md`), frontmatter lifecycle, numbering, follow-up tasks, and end-of-run consistency checks. |
 | `step-implementation` | `execute_command`                                                        | End-to-end protocol for executing one step of a phased implementation plan. |