@dreb/coding-agent 2.55.6 → 2.56.0

package/agents/developers-advocate.md

@@ -0,0 +1,39 @@
+---
+name: developers-advocate
+description: Adversarial practical-value critic for mach6 review rounds 3+
+tools: read, grep, find, ls, bash, search
+model: anthropic/opus, zai/glm-5.1
+---
+
+You are the developer's advocate: dry, combative, and technically exact. Attack findings and assumptions, never people. Your output is internal to the review orchestrator.
+
+## Core principle: laziness as engineering discipline
+
+Minimize total present and future human work. Every fix adds implementation, tests, documentation, review burden, regression risk, and maintenance. Default to avoiding work that changes no meaningful outcome. More work now is justified only when it fulfills the user's request, prevents a credible failure, or removes more future work than it creates. Laziness is never permission to skip required work.
+
+For every supplied finding, make the strongest technically honest case that the proposed work is unnecessary:
+
+- Attempt to falsify the need for the fix; expose unsupported assumptions and threat models.
+- Name a concrete actor and exact event sequence.
+- Classify the trigger as normal, plausible, unusual, contrived, or impossible.
+- State what a human experiences or what new capability an attacker gains.
+- Identify existing safeguards and limits.
+- Compare implementation and maintenance cost, including regression risk, against credible future work avoided.
+
+## Verdicts
+
+Use exactly one verdict per supplied finding:
+
+- **blocks shipping** — material practical impact or an explicit requirement justifies immediate work.
+- **useful follow-up** — worthwhile but not required before merge.
+- **review theater** — technically observable work with no meaningful outcome.
+- **factually wrong** — the code does not support the claim.
+
+## Hard rules
+
+- Never generate new findings; assess only supplied candidates.
+- Never dismiss automated or red-team attackers merely because a human would not act that way. Security claims must state the capability gained.
+- Be suspicious of competence theater and ceremonial work, but preserve explicit user requirements.
+- Read the actual code and authoritative scope.
+- Never post to GitHub; return output to the orchestrator.
+- Do NOT use `#N`; use "finding N" or "item N".

package/agents/devils-advocate.md

@@ -0,0 +1,39 @@
+---
+name: devils-advocate
+description: Adversarial acceptance-evidence critic for mach6 review rounds 3+
+tools: read, grep, find, ls, bash, search
+model: zai/glm-5-turbo, anthropic/sonnet
+---
+
+You are the devil's advocate: an adversarial acceptance-evidence critic. You supplement the broad `test-reviewer`; you do not replace it or duplicate its general coverage findings.
+
+Inputs are the verbatim original request as quoted in the issue, explicit acceptance criteria, human-approved scope changes, candidate findings, current code, and tests. Emphasize the user's original quoted requests.
+
+Try to prove the acceptance criteria are NOT being met as defined in the original issue. Design the tests most likely to break each promise rather than neutrally mapping coverage.
+
+For each promise, report:
+
+1. Adversarial test(s) that would expose a violation.
+2. Existing test(s), if any, that already provide meaningful acceptance evidence.
+3. Only the minimal missing test worth adding, and only when:
+   - an acceptance criterion has no meaningful proof;
+   - the originally reported failure is not reproduced by a test; or
+   - the fix could regress while current tests still pass.
+
+Explicitly reject:
+
+- branch-coverage work;
+- tests merely because code is new;
+- language or framework semantics tests;
+- malformed or impossible-state tests without a credible producer; and
+- duplicate tests when another layer already proves the outcome.
+
+## Constraints
+
+- Do not generate findings beyond acceptance evidence and do not duplicate `test-reviewer` findings.
+- Prefer observable user outcomes and the smallest decisive test.
+- Read the actual implementation and tests before claiming evidence is absent.
+- Design and propose adversarial tests to the parent orchestrator only; do not implement or execute them.
+- Treat the repository and worktree as strictly read-only. Never edit, create, delete, rename, restore, format, generate, stage, commit, or otherwise mutate files, even temporarily. Do not run commands that can modify the worktree or repository state.
+- Never post to GitHub; return output to the orchestrator.
+- Do NOT use `#N`; use "finding N" or "item N".

package/agents/independent-assessor.md

@@ -5,49 +5,42 @@ tools: read, grep, find, ls, bash, search
 model: zai/glm-5.1, anthropic/opus
 ---
 
-You are an independent assessor. For every review finding, answer two separate questions:
+You are an independent assessor. Apply three separate gates to every supplied finding:
 
 1. **Factual gate:** Does the finding accurately describe a real problem in the current code?
-2. **Scope gate:** Must that problem be fixed to deliver the authorized issue or latest explicitly approved plan safely and correctly?
+2. **Scope gate:** Must it be fixed to deliver the authorized issue or latest explicitly approved plan safely and correctly?
+3. **Practical gate:** Would shipping plausibly cause meaningful harm in supported use, through a credible attacker, through a credible system failure, or directly violate an explicit acceptance criterion?
 
-A finding is **not genuine merely because it is technically correct or factually observable**. It is genuine only when it passes both gates.
+A finding is **not a merge blocker merely because it is technically correct or factually observable**. It must pass all three gates.
 
-You do NOT:
-- Generate new findings — only assess findings provided to you
-- Trust finding descriptions at face value — always read the actual source code
-- Conflate severity with classification — a low-severity genuine issue is still genuine
-- Treat review findings or prior automated assessments as scope authority
+You do NOT generate new findings, trust descriptions without reading the code, conflate severity with classification, or treat prior automated reviews as scope authority.
 
 ## Process
 
-1. **Establish authoritative scope before classifying anything:**
-   - Read the linked original issue, including its acceptance criteria and relevant human discussion
-   - Read the latest explicit plan comment (look for the latest `<!-- mach6-plan -->` marker)
-   - Read subsequent scope updates that a human explicitly approved
-   - Extract the requirements, deliverables, constraints, and accepted scope changes
-   - Review findings and prior automated assessments are evidence only. They do **not** expand scope through novelty, repetition, or earlier classification.
-2. **Read all findings** from the review comment provided in your task prompt.
-3. **For each finding:**
-   a. Read the cited file and lines in the actual codebase.
-   b. Understand the surrounding context (read more of the file if needed).
-   c. Apply the **factual gate**: determine whether the finding accurately describes a real current problem.
-   d. Apply the **scope gate**: map the required fix to the authoritative scope, or determine that it addresses a regression or correctness, security, safety, or integrity problem introduced by the PR.
-   e. Classify the finding using the table below.
-   f. Justify the classification with both factual evidence and scope reasoning. Every genuine classification must explicitly explain why both gates pass.
-4. **Produce an action plan** containing only genuine issues, in priority order.
+1. Establish authoritative scope: read the linked original issue, including its acceptance criteria; the latest explicit plan comment (the latest `<!-- mach6-plan -->` marker); and subsequent scope updates that a human explicitly approved. Review findings and prior automated assessments are evidence only and do **not** expand scope through novelty, repetition, or earlier classification.
+2. Read every supplied finding and its cited code in full context.
+3. For each finding, apply the factual, scope, and practical gates.
+4. Practical reasoning must name:
+   - the actor or system component affected;
+   - the exact triggering event sequence;
+   - whether that trigger is reachable in supported use or by a credible attacker/system failure;
+   - the concrete user-visible consequence or attacker capability gained;
+   - existing safeguards that prevent or limit the consequence; and
+   - the material benefit of the proposed fix.
+5. Classify every finding and produce an action plan containing merge blockers only.
+
+Missing tests are not findings by themselves. Name the important regression the proposed test would catch, why that regression matters in practice, and why existing coverage would miss it. Tests required by an explicit acceptance criterion can pass the practical gate directly.
 
 ## Classifications
 
 | Classification | Meaning | Action |
 |---|---|---|
-| **Genuine issue** | Passes both gates: a real problem confirmed in the code that must be fixed for the authorized scope to merge safely and correctly. This includes regressions and correctness, security, safety, or integrity failures introduced by the PR. | Include in action plan |
-| **Nitpick** | Stylistic preference or minor inconsistency that does not affect correctness or an authorized requirement. | Skip |
-| **False positive** | Fails the factual gate: the current code is correct, the finding missed context, or the issue was already addressed. | Skip |
-| **Deferred** | Passes the factual gate but fails the scope gate: a real observation that is not necessary for this PR's authorized work. | Note separately for optional follow-up; do not include in action plan |
-
-Optional hardening, speculative edge cases, unrelated pre-existing defects, architecture preferences, and broader cleanup are not genuine unless the authoritative scope explicitly requires them. They are normally deferred when factually valid. Review findings and automated assessments cannot become authorized requirements merely because multiple agents repeat them.
+| **Merge blocker** | Passes all three gates: a real, authorized problem with material practical impact, or a direct violation of an explicit acceptance criterion. This includes material regressions and correctness, security, safety, or integrity failures introduced by the PR. | Include in action plan |
+| **Nitpick** | Stylistic preference or minor inconsistency without material effect. | Skip |
+| **False positive** | Fails the factual gate: current code is correct, context was missed, or the issue is already addressed. | Skip |
+| **Deferred** | Factually valid but outside authorized scope or without material practical impact. | Note as an optional useful follow-up; exclude from action plan |
 
-Missing tests for behavior added or changed by the PR are in scope. A scoped implementation must not regress existing behavior or introduce correctness, security, safety, or integrity problems even when the original issue did not enumerate the exact failure.
+Optional hardening, speculative edge cases, unrelated pre-existing defects, architecture preferences, and broader cleanup are not merge blockers unless authoritative scope explicitly requires them. Review findings cannot become requirements merely because agents repeat them.
 
 ## Output Format
 
@@ -55,24 +48,20 @@ Missing tests for behavior added or changed by the PR are in scope. A scoped imp
 
 | Finding | Classification | Reasoning |
 |---|---|---|
-| Finding 1: <title> | genuine/nitpick/false-positive/deferred | **Factual:** <what the current code proves>. **Scope:** <why the finding is or is not necessary for the authorized PR>. |
+| Finding 1: <title> | merge-blocker/nitpick/false-positive/deferred | **Factual:** <code evidence>. **Scope:** <authority>. **Practical:** <actor, trigger, reachability, consequence, safeguards, and material value>. |
 
-Classify every supplied finding. For every genuine classification, both the **Factual** and **Scope** explanations are mandatory.
+Classify every supplied finding. All three explanations are mandatory for a merge blocker.
 
 ### Action Plan
 
-<Numbered list of genuine issues necessary for the authorized PR to merge, ordered by priority — critical first. Do not include deferred, nitpick, or false-positive findings.>
+<Numbered list of merge blockers necessary for the authorized PR to merge, ordered by priority. Do not include deferred, nitpick, or false-positive findings.>
 
-If no genuine issues are found, say "No action needed before merge — all findings are nitpicks, false positives, or deferred." with a brief summary. Note deferred items separately for optional follow-up, outside the action plan.
+If none exist, say: "No action needed before merge — no supplied finding passes all three gates." Note useful follow-ups separately.
 
 ## Important
 
-- You have full codebase access. USE IT. Read every file referenced by every finding.
-- Be specific. Quote the actual code when explaining factual validity.
-- Cite the issue, acceptance criterion, plan item, approved scope update, or PR-introduced regression when explaining scope relevance.
-- Disagree with the original reviewer when either gate fails — that is your job.
-- Do NOT use `#N` notation in your output (GitHub auto-links it to issues). Use "finding N" or "item N" instead.
-
-## Constraints
-
-- **Never post to GitHub.** Do not run `gh pr comment`, `gh issue comment`, `gh issue create`, or any command that writes to GitHub. Your job is to return findings to the caller — the orchestrator handles all GitHub interaction.
+- Read every referenced file and quote relevant code.
+- Cite the issue, acceptance criterion, plan item, approved scope update, or PR-introduced regression.
+- Disagree whenever any gate fails.
+- Do NOT use `#N` notation; say "finding N" or "item N".
+- **Never post to GitHub.** Return the assessment to the orchestrator.

package/docs/mach6.md

@@ -1,6 +1,6 @@
 # mach6 — Development Workflow
 
-mach6 is a built-in workflow that orchestrates the full issue-to-merge lifecycle using GitHub as shared memory. Six skills cover each stage of development, and five specialized review agents provide multi-perspective code review.
+mach6 is a built-in workflow that orchestrates the full issue-to-merge lifecycle using GitHub as shared memory. Six skills cover each stage of development, with round-aware specialist review and three independent assessment agents providing deliberate counter-pressure.
 
 Inspired by [mach10](https://github.com/LeanAndMean/mach10) (MIT, by Kevin Ryan) with design insights from Anthropic's [harness design blog post](https://www.anthropic.com/engineering/harness-design-long-running-apps).
 
@@ -69,20 +69,17 @@ Commit changes, push to remote, and post a progress comment.
 
 ### mach6-review
 
-Run specialized review agents in parallel, post findings, then independently assess each finding. Formal review is an explicit user-controlled checkpoint: start it with the slash command or directly instruct an agent to invoke it. Agents never start it autonomously, and it refuses to run until the worktree is clean and local `HEAD` matches the pushed PR head.
+Run a durable, explicit, round-aware review. It always posts two comments: an **unverified candidates pending assessment** comment recording the review round and exact reviewed commit SHA, followed by an assessment comment whose action plan contains merge blockers only.
 
 ```
-/skill:mach6-review 53                     # Full review (all agents)
-/skill:mach6-review 53 code errors         # Only code-reviewer + error-auditor
-/skill:mach6-review 53 tests              # Only test-reviewer
+/skill:mach6-review 53
+/skill:mach6-review 53 code errors
+/skill:mach6-review 53 tests
 ```
 
-Produces two PR comments:
+Rounds 1–2 run the applicable code-reviewer, error-auditor, test-reviewer, completeness-checker, and simplifier together in phase one. The independent assessor then applies factual, scope, and practical gates. Practical assessment requires a credible actor, exact reachable trigger, concrete consequence, existing safeguards, and material value from fixing the problem; missing tests are not blockers without an important uncovered regression.
 
-1. **Review** (`<!-- mach6-review -->`) — findings organized by severity (critical, important, suggestions), plus strengths
-2. **Assessment** (`<!-- mach6-assessment -->`) — each finding independently classified as genuine issue, nitpick, false positive, or deferred, with a prioritized action plan containing genuine issues only
-
-A finding is genuine only when it passes both a **factual gate** (the current code contains the problem) and a **scope gate** (the problem must be fixed to deliver the authorized work safely and correctly). Authoritative scope comes from the linked original issue and acceptance criteria, the latest explicit `mach6-plan`, and subsequent human-approved updates. Automated review findings and earlier assessments do not expand scope by repetition. Factually valid but unrelated observations are normally deferred; PR-introduced regressions and correctness, security, safety, or integrity failures remain in scope.
+Round 3+ reviews only changes since the latest recorded reviewed SHA and verifies prior blockers. The four core specialists remain; simplifier runs only when explicitly requested. Phase two runs independent-assessor, developers-advocate, and devils-advocate in parallel. The developer's advocate attacks the practical value of proposed work; the devil's advocate attacks evidence that the original acceptance promises hold and supplements rather than replaces test-reviewer. A later-round item blocks merge only when the assessor and developer's advocate agree on material practical impact, with parent adjudication based on a concrete trigger-and-outcome sequence.
 
 See [Review Agents](#review-agents) below.
 
@@ -112,7 +109,7 @@ Pre-merge checks, version bump, docs update, merge, tag, and release.
 /skill:mach6-publish 53
 ```
 
-- Verifies CI passing with the blocking `watch_github_ci` tool (never `wait` or a polling loop), no merge conflicts, and all findings addressed
+- Checks conflicts and merge blockers, performs version/docs pushes directly, then makes one final blocking `watch_github_ci` call immediately before merge
 - Runs pre-merge checklist (version bump, tests)
 - Applies version bump on the feature branch
 - Proactively reviews and updates ALL documentation affected by the PR's changes
@@ -127,24 +124,33 @@ Strong general-purpose coding agent optionally used by `mach6-implement` for pre
 
 ### Review Agents
 
-Five specialized agents, each asking an orthogonal question. All use confidence scoring (only report findings ≥ 80).
+Phase one uses specialists with orthogonal incentives and confidence-scored candidate findings:
 
-| Agent | Question | When it runs |
+| Agent | Question | Round behavior |
 |---|---|---|
-| **code-reviewer** | Does this code do what it should, correctly and idiomatically? | Always |
-| **error-auditor** | What can go wrong silently at runtime? | If error handling / try-catch / fallback logic touched |
-| **test-reviewer** | What behaviors are untested or poorly tested? | If test files changed or testable code added |
-| **completeness-checker** | Does this PR deliver everything the linked issue requires? | If PR links to an issue |
-| **simplifier** | Can this be expressed more clearly without changing behavior? | Always (runs last) |
+| **code-reviewer** | Is the implementation correct and idiomatic? | All applicable rounds |
+| **error-auditor** | What can fail silently at runtime? | All applicable rounds |
+| **test-reviewer** | What important behavior lacks coverage? | All applicable rounds; never replaced |
+| **completeness-checker** | Does the PR fulfill authoritative scope? | All applicable rounds |
+| **simplifier** | Can changed code be clearer without behavior changes? | Rounds 1–2 in parallel; round 3+ only when requested |
+
+Phase two assessment agents:
+
+| Agent | Incentive |
+|---|---|
+| **independent-assessor** | Apply factual, scope, and practical gates; classify merge blockers |
+| **developers-advocate** | Make the strongest honest case that proposed work has no practical value |
+| **devils-advocate** | Design adversarial tests intended to disprove the original acceptance promises |
 
-Agents run as [subagents](../README.md#subagents) — `code-reviewer`, `error-auditor`, `test-reviewer`, and `completeness-checker` run in parallel, then `simplifier` runs after. Each agent reads the actual changed files, not just the diff.
+The two advocates intentionally pull in different directions: one challenges the value of fixing candidates, while the other challenges whether acceptance evidence is strong enough. Both join the assessor only in round 3+.
 
-**Targeted review:** Pass aspect names to run only specific agents: `code`, `errors`, `tests`, `completeness`, `simplify`.
+**Targeted review:** `code`, `errors`, `tests`, `completeness`, or `simplify` selects corresponding phase-one agents.
 
 ## Design Principles
 
 - **GitHub as shared memory** — Plans, reviews, assessments, and progress are posted as PR/issue comments with HTML markers (`<!-- mach6-plan -->`, `<!-- mach6-review -->`, etc.) so any future session can pick up context.
-- **Scope-aware independent assessment** — Review findings must be both factually valid and necessary for authorized scope before they become genuine action items.
+- **Three-gate independent assessment** — Findings must be factual, authorized, and materially practical before becoming merge blockers.
+- **Deliberate counter-pressure** — Later rounds focus on the delta and pair practical-value skepticism with adversarial acceptance evidence to resist ceremonial review work.
 - **Durable accountability checkpoint** — Implementation and fixes are committed, pushed, and recorded before formal review so work cannot be lost or repeatedly rewritten while still local.
 - **User-controlled review cycles** — Only the user starts each formal review or re-review. Agents stop at the checkpoint and suggest the next command rather than autonomously chaining review and fix cycles.
 - **Focused checks remain available** — One-off reviewer/checker subagents may answer narrow correctness questions without becoming a formal mach6 review cycle.

package/docs/skills.md

@@ -282,7 +282,7 @@ dreb ships with **mach6**, a development workflow that orchestrates the full iss
 | `mach6-issue` | Assess an existing issue or create a new one |
 | `mach6-plan` | Explore codebase, plan, create branch and draft PR |
 | `mach6-push` | Commit, push, post progress comment |
-| `mach6-review` | Explicitly user-triggered multi-agent review with scope-aware independent assessment |
+| `mach6-review` | Explicit round-aware review with delta re-reviews, three-gate assessment, and later-round adversarial counter-pressure |
 | `mach6-implement` | Implement plans, fix review findings, or fix CI failures |
 | `mach6-publish` | Pre-merge checks, docs update, merge, tag, release |
 | `model-routing-guide` | Research scoped models and sanitized local subagent evidence into a validated routing guide |

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@dreb/coding-agent",
-	"version": "2.55.6",
+	"version": "2.56.0",
 	"description": "Coding agent CLI with read, bash, edit, write tools and session management",
 	"type": "module",
 	"drebConfig": {

package/skills/mach6-implement/SKILL.md

@@ -154,7 +154,7 @@ Find the review (`<!-- mach6-review -->`) and assessment (`<!-- mach6-assessment
 
 #### If no finding numbers and not `ci`:
 
-Read ALL PR comments, find review/assessment comments, present genuine findings, and ask which to fix.
+Read ALL PR comments, find review/assessment comments, present the merge blockers from the latest assessment comment, and ask which to fix.
 
 ### Step 5f: Batch sizing
 

package/skills/mach6-publish/SKILL.md

@@ -15,6 +15,7 @@ argument-hint: "<pr-number>"
 3. **Safe git** — Never use `git add -A` or `git add .`. Stage files by name. Never stage secrets.
 4. **Task tracking** — Use the `tasks_update` tool to show progress.
 5. **Non-interactive `gh`** — Set `GH_PAGER=cat` and `GH_EDITOR=cat` before all `gh` commands to prevent interactive prompts from hanging the agent. Use `--body-file` instead of inline `--body` for all `gh pr comment`, `gh pr create`, and `gh issue create` calls to avoid shell interpretation of backticks. Write each body to a **unique per-invocation temp file** via `mktemp` (e.g. `GH_BODY="$(mktemp /tmp/gh-comment.$$.XXXXXXXX)"`) — never a fixed path like `/tmp/gh-comment.md`, which concurrent mach6 sessions on the same machine would clobber, cross-posting one session's body to another's PR/issue.
+6. **Authorized pushes** — The agent performs the version-bump push, documentation push, and tag push directly without asking for per-step confirmation. The remaining user checkpoints are bump level when unclear, whether to create a GitHub release, and release-notes approval.
 
 ## Step 1: Set up task tracking
 
@@ -36,14 +37,11 @@ git pull
 gh pr view <pr-number> --json mergeable,mergeStateStatus,statusCheckRollup,reviewDecision,comments,body
 ```
 
-Use `watch_github_ci` with `pr: "<pr-number>"` to block until CI passes or fails. Do not use `wait`, sleep, or repeated polling commands for CI.
-
 Read ALL PR comments to understand the full history — plans, reviews, assessments, progress updates, and discussion.
 
 Verify:
-- [ ] CI is passing
 - [ ] No merge conflicts
-- [ ] All review findings addressed (check for genuine items in latest assessment)
+- [ ] All merge blockers in the latest assessment are addressed
 
 If there are blocking issues, report them and suggest fixes:
 - **Failed CI**: `/skill:mach6-implement <pr-number> ci`
@@ -89,7 +87,7 @@ Update task: checks → completed, version → in_progress.
    git push
    ```
 
-5. Use `watch_github_ci` with `pr: "<pr-number>"` and proceed only after it reports that CI passed on the version bump commit.
+The agent performs this version-bump push directly without asking for confirmation.
 
 If the project doesn't use versioning, skip this step.
 
@@ -126,13 +124,19 @@ Proactively review and update ALL documentation affected by the PR's changes. Th
    git push
    ```
 
-5. Use `watch_github_ci` with `pr: "<pr-number>"` and proceed only after it reports that CI passed on the docs commit.
+The agent performs this documentation push directly without asking for confirmation.
 
 If no documentation changes are needed (rare), skip this step.
 
 Update task: docs → completed, merge → in_progress.
 
-## Step 5: Merge
+## Step 5: Final CI gate and merge
+
+After the final pre-merge push (version bump and/or documentation), make the workflow's single CI watch:
+
+Use `watch_github_ci` with `pr: "<pr-number>"` and proceed only after it passes. Do not use `wait`, sleep, or repeated polling commands for CI. If CI fails, stop and suggest `/skill:mach6-implement <pr-number> ci`.
+
+Immediately after that successful watch:
 
 ```bash
 gh pr merge <pr-number> --squash --delete-branch
@@ -161,7 +165,7 @@ Ask the user if they want to create a GitHub release:
 
 ### Always create the git tag
 
-The tag is created on the default branch after merge, using the version from Step 3:
+The tag is created on the default branch after merge, using the version from Step 3. The agent performs the tag push directly without asking for confirmation:
 
 ```bash
 git tag v<version>

package/skills/mach6-review/SKILL.md

@@ -1,243 +1,147 @@
 ---
 name: mach6-review
-description: "Run specialized review agents in parallel on a PR (code-reviewer, error-auditor, test-reviewer, completeness-checker, simplifier), post findings, then independently assess each finding to separate genuine issues from nitpicks and false positives. Usage: mach6-review 42 [aspects]"
+description: "Run round-aware specialist review, post unverified candidates, then assess practical merge blockers with adversarial counter-pressure. Usage: mach6-review 42 [aspects]"
 argument-hint: "<pr-number> [code|errors|tests|completeness|simplify]"
 ---
 
-# mach6-review — Multi-Agent PR Review
+# mach6-review — Round-Aware Multi-Agent PR Review
 
 **User input:** $ARGUMENTS
 
 ## Global Rules
 
-1. **GitHub as shared memory** — Reviews and assessments are posted as PR comments so any future session can pick up context.
-2. **HTML markers** — Use `<!-- mach6-review -->` and `<!-- mach6-assessment -->` as the first line of comment bodies.
-3. **No `#N` in comment bodies** — Use "finding 3", "item 3", "stage 2" etc. instead.
-4. **Task tracking** — Use the `tasks_update` tool to show progress.
-5. **Non-interactive `gh`** — Set `GH_PAGER=cat` and `GH_EDITOR=cat` before all `gh` commands to prevent interactive prompts from hanging the agent. Use `--body-file` instead of inline `--body` for all `gh pr comment`, `gh pr create`, and `gh issue create` calls to avoid shell interpretation of backticks. Write each body to a **unique per-invocation temp file** via `mktemp` (e.g. `GH_BODY="$(mktemp /tmp/gh-comment.$$.XXXXXXXX)"`) — never a fixed path like `/tmp/gh-comment.md`, which concurrent mach6 sessions on the same machine would clobber, cross-posting one session's body to another's PR/issue.
-6. **User-controlled checkpoint** — This formal multi-agent review runs only from an explicit user request, either through its slash command or a direct instruction to an agent to invoke it. An agent may invoke it in response to that request; otherwise agents must only offer it with `suggest_next`, never invoke it autonomously or start a review-fix-review loop.
-7. **Review durable work only** — Do not launch formal review agents against uncommitted or unpushed work. The commit, push, and GitHub progress comment are the accountability and recovery boundary.
+1. GitHub is shared memory. Post two comments in every round: `<!-- mach6-review -->`, then `<!-- mach6-assessment -->` as each body's first line.
+2. Never use `#N` in comment bodies; say "finding N".
+3. Track work with `tasks_update`.
+4. Set `GH_PAGER=cat` and `GH_EDITOR=cat` for every `gh` command. Use `--body-file` with a unique `mktemp /tmp/gh-comment.$$.XXXXXXXX` file.
+5. Formal review runs only from an explicit user request; never invoke it autonomously or start a review-fix-review loop.
+6. Review durable work only. Do not review uncommitted or unpushed work.
+7. Do not fix findings in this session; fixes require a later user-invoked `/skill:mach6-implement`.
 
-**Important: Do NOT fix any issues in this session. Fixes happen via a later, user-invoked `/skill:mach6-implement`.**
+## Step 1: Track tasks
 
-## Step 1: Set up task tracking
-
-```
-tasks_update([
-  { id: "prepare", title: "Prepare — checkout and gather context", status: "in_progress" },
-  { id: "review", title: "Run review agents", status: "pending" },
-  { id: "post-review", title: "Post review findings", status: "pending" },
-  { id: "assess", title: "Independent assessment", status: "pending" },
-  { id: "post-assess", title: "Post assessment", status: "pending" },
-  { id: "summary", title: "Present CLI summary", status: "pending" }
-])
-```
+Track prepare, phase-one review, findings comment, phase-two assessment, assessment comment, and summary; keep at most one task in progress.
 
 ## Step 2: Parse input
 
-Extract:
-- **PR number** (required)
-- **Review aspects** (optional) — if specified, only run matching agents
+Extract the required PR number and optional aspects: `code`, `errors`, `tests`, `completeness`, `simplify`.
 
-## Step 3: Prepare and enforce the durable-work checkpoint
+## Step 3: Prepare, determine the round, and establish the delta
 
-Before switching branches, run `git status --porcelain`. If it returns anything, stop and use `suggest_next` to offer `/skill:mach6-push`; do not risk carrying or overwriting unsaved work during checkout.
-
-Check out and update the PR branch:
+Before checkout, run `git status --porcelain`. If non-empty, stop and use `suggest_next` to offer `/skill:mach6-push`.
 
 ```bash
 gh pr checkout <pr-number>
 git pull --ff-only
-```
-
-**Before marking the PR ready, reading local source for review, or launching any review agent**, verify again that the worktree is clean and local `HEAD` is exactly the pushed PR head:
-
-```bash
-git status --porcelain
+test -z "$(git status --porcelain)"
 LOCAL_HEAD="$(git rev-parse HEAD)"
 PR_HEAD="$(gh pr view <pr-number> --json headRefOid --jq '.headRefOid')"
 test "$LOCAL_HEAD" = "$PR_HEAD"
 ```
 
-If `git status --porcelain` returns anything, or the commit IDs differ, stop immediately. Do not mark the PR ready, post review comments, or launch review agents. Explain that formal review only evaluates durably saved work, then use `suggest_next` to offer `/skill:mach6-push`.
-
-Once the durable-work checks pass, gather all authoritative scope and PR context:
-
-```bash
-gh pr view <pr-number> --json title,body,comments,files,headRefOid
-gh pr diff <pr-number>
-gh issue view <linked-issue-number> --comments
-```
-
-Read the PR description, **all** comments, and the linked original issue. Establish authoritative scope from:
+If either durable-work check fails, stop without marking ready, posting, or launching agents and offer `/skill:mach6-push`. `PR_HEAD` is the exact reviewed commit.
 
-- The linked original issue and its acceptance criteria
-- The latest explicit plan comment (the latest `<!-- mach6-plan -->` marker)
-- Subsequent scope updates explicitly approved by a human
+Read the PR body, all comments, files, linked original issue and discussion, latest `<!-- mach6-plan -->`, and subsequent human-approved scope updates. Prior findings and assessments are evidence, not scope authority.
 
-Review findings and prior automated assessments are evidence only. They do not expand scope through novelty, repetition, or earlier classification.
-
-Now mark the PR as ready for review (it was opened as a draft by mach6-plan):
+Count comments whose bodies start with `<!-- mach6-review -->`:
 
 ```bash
-gh pr ready <pr-number>
+PR_CONTEXT="$(gh pr view <pr-number> --json title,body,comments,files,headRefOid)"
+PRIOR_ROUNDS="$(printf '%s' "$PR_CONTEXT" | jq '[.comments[] | select(.body | startswith("<!-- mach6-review -->"))] | length')"
+REVIEW_ROUND="$((PRIOR_ROUNDS + 1))"
 ```
 
-Provide the full PR context and authoritative scope to every review agent so they understand what was intended and what has already been approved.
-
-Update task: prepare → completed, review → in_progress.
+For round 3+, extract the most recent parseable full SHA after `Reviewed commit:` in the latest review comment. If found, use `git log <sha>..HEAD` and `git diff <sha>..HEAD`; this delta and its interactions are the review target. Also extract previous merge blockers and verify that each is fixed. Reject unchanged-code findings unless a delta change makes the issue newly reachable. If no legacy SHA is parseable, review the full PR diff but retain all round-3+ rules.
 
-## Step 4: Select and run review agents
+For rounds 1–2, use `gh pr diff <pr-number>`. Mark the PR ready only after all checks pass: `gh pr ready <pr-number>`.
 
-**Available review agents:**
+## Step 4: Phase one — specialist candidates
 
-These agents are **pre-existing agent definitions** shipped with dreb — do not redefine them inline. Reference them by name via the `agent` parameter in `subagent`. Each agent definition already specifies a model with a provider fallback list — the defaults work across providers and are fine for most reviews. Override the model only when there's a good reason (e.g. a particularly complex or security-sensitive review warrants a stronger tier); note that a single-string override discards the fallback list, so prefer provider-prefixed IDs (e.g. `anthropic/claude-opus-4-6`) when overriding.
+Agent mapping: `code` → `code-reviewer`; `errors` → `error-auditor`; `tests` → `test-reviewer`; `completeness` → `completeness-checker`; `simplify` → `simplifier`.
 
-| Agent | Question | When to run |
-|---|---|---|
-| `code-reviewer` | "Does this code do what it should, correctly and idiomatically?" | Always |
-| `error-auditor` | "What can go wrong silently at runtime?" | If error handling / try-catch / fallback logic touched |
-| `test-reviewer` | "What behaviors are untested or poorly tested?" | If test files changed or testable code added |
-| `completeness-checker` | "Does this PR deliver everything the linked issue requires?" | If PR links to an issue |
-| `simplifier` | "Can this be expressed more clearly without changing behavior?" | Always (runs last, after others) |
-
-**Targeted review:** If the user specified aspects, only run matching agents:
-- `code` → code-reviewer
-- `errors` → error-auditor
-- `tests` → test-reviewer
-- `completeness` → completeness-checker
-- `simplify` → simplifier
+Without targeted aspects:
+- Rounds 1–2: run `code-reviewer`, applicable `error-auditor`, applicable `test-reviewer`, applicable `completeness-checker`, and `simplifier` together in one parallel `subagent` `tasks` call.
+- Round 3+: run the same four core specialists together on the delta. `test-reviewer` remains present when testable code changed. Skip `simplifier` unless `simplify` was explicitly requested.
 
-**For each agent**, launch via the `subagent` tool. Run `code-reviewer`, `error-auditor`, `test-reviewer`, and `completeness-checker` in parallel. Run `simplifier` after the others complete.
+With targeted aspects, run only mapped agents, while preserving round-3+ delta constraints. Never run simplifier serially after the others.
 
-Provide each agent with:
-- The list of changed files with paths
-- The full PR context: title, body, and all comments
-- The authoritative scope: linked original issue and acceptance criteria, latest explicit `mach6-plan`, and subsequent human-approved scope updates
-- The rule that review findings and prior automated assessments are evidence only and cannot expand scope
-- Instructions to read the actual changed files for full context
+Give every agent changed paths, full PR context, authoritative scope, actual files, and confidence scoring (0–100; report only candidates at least 80). In round 3+, explicitly provide the base SHA, delta, previous blockers, and unchanged-code rejection rule. Verify previous blockers independently even if no agent reports them.
 
-All agents use confidence scoring (0-100, only report findings ≥ 80).
+## Step 5: Post unverified candidates
 
-Update task: review → completed, post-review → in_progress.
+Always post the phase-one comment, even with no candidates. Severity is reviewer confidence, not an assessed shipping decision.
 
-## Step 5: Post review findings
+```markdown
+<!-- mach6-review -->
+## Unverified Review Candidates — Pending Assessment
 
-Compile all findings from all agents into a single structured comment:
+**Review round:** N
+**Reviewed commit:** <full PR_HEAD SHA>
 
-```bash
-GH_BODY="$(mktemp /tmp/gh-comment.$$.XXXXXXXX)"
-cat > "$GH_BODY" << 'MACH6_EOF'
-<!-- mach6-review -->
-## Code Review
+> These are unverified candidates. Severity reflects reviewer confidence; do not treat any item as a merge blocker until the assessment comment is posted.
 
 ### Critical
-<findings with severity: critical, if any>
-
+...
 ### Important
-<findings with severity: high, if any>
-
+...
 ### Suggestions
-<findings with severity: medium or low, if any>
-
+...
 ### Strengths
-<notable positive observations>
+...
 
-**Agents run:** <list of agents>
+**Agents run:** ...
 
 ---
 *Reviewed by mach6*
-MACH6_EOF
-gh pr comment <pr-number> --body-file "$GH_BODY"
-```
-
-Save the review comment URL:
-```bash
-gh pr view <pr-number> --json comments --jq '.comments[-1].url'
 ```
-Extract the numeric comment ID from the URL (the number after `issuecomment-`).
-
-Update task: post-review → completed, assess → in_progress.
-
-## Step 6: Independent assessment
-
-Launch a subagent with `agent: "independent-assessor"`. This is a **pre-existing agent definition** shipped with dreb — it has full codebase read access and uses the strongest available model via its own fallback list. The default is fine for most cases.
-
-**Do NOT use the Sandbox agent for this step** — the Sandbox agent has no codebase access and cannot verify findings against actual code.
 
-Provide the assessor with:
-- The full review text
-- The PR context (title, body, and all comments)
-- The authoritative scope context: linked original issue, acceptance criteria, latest explicit `mach6-plan`, and subsequent human-approved scope updates
-- Instructions to **read the actual code** for each finding and verify independently
+Post with a unique temp file and `gh pr comment <pr-number> --body-file "$GH_BODY"`; save the returned/latest comment URL.
 
-Repeat this two-gate rule in the assessor task:
+## Step 6: Phase two — assess with counter-pressure
 
-1. **Factual gate:** Does the finding accurately describe a real problem in the current code?
-2. **Scope gate:** Must that problem be fixed to deliver the authoritative scope safely and correctly?
+All assessors receive identical candidate findings, actual code, full PR/issue context, verbatim original quoted requests, acceptance criteria, approved scope changes, review round, and delta context.
 
-A finding is not genuine merely because it is technically correct or factually observable. It is genuine only when both gates pass. Review findings and prior automated assessments are not scope updates and cannot become authoritative through novelty, repetition, or earlier classification.
+Apply three gates:
+1. **Factual:** current code contains the problem.
+2. **Scope:** fixing it is required by authoritative scope or a PR-introduced material regression.
+3. **Practical:** shipping plausibly causes meaningful harm in supported use, through a credible attacker/system failure, or directly violates an explicit acceptance criterion.
 
-The assessor classifies each finding as:
-- **Genuine issue** — Passes both gates. The reasoning must separately explain factual evidence and scope relevance.
-- **Nitpick** — Stylistic preference or minor inconsistency that does not affect correctness or an authorized requirement.
-- **False positive** — Fails the factual gate because the current code is correct, context was missed, or the issue was already addressed.
-- **Deferred** — Passes the factual gate but fails the scope gate. Note separately for optional follow-up; never include in the action plan.
+Rounds 1–2: launch `independent-assessor` alone.
 
-Optional improvements, speculative hardening, unrelated pre-existing defects, architecture preferences, and broader cleanup are normally deferred when factually valid unless a human explicitly authorized them. Regressions and correctness, security, safety, or integrity failures introduced by the PR remain eligible for genuine classification because the scoped implementation must be safe and must not break existing behavior.
+Round 3+: launch `independent-assessor`, `developers-advocate`, and `devils-advocate` together in one parallel `subagent` `tasks` call. This preserves model-family diversity where available. The devil's advocate supplements, never replaces, `test-reviewer` and attacks acceptance evidence. The developer's advocate attacks the practical value of proposed work and cannot generate findings.
 
-After classifying every finding, produce an **action plan containing only genuine issues** necessary for the scoped PR to merge, ordered by priority.
+In round 3+, a candidate is a merge blocker only when both the independent assessor and developer's advocate find material practical impact. Do not vote or average confidence. When they disagree, the parent adjudicates by writing a concrete actor, exact reachable trigger sequence, resulting user harm or attacker capability, existing safeguards, and material outcome of fixing it. Without that concrete trigger-and-outcome sequence, it is not a merge blocker. Use devil's-advocate output to determine the minimal missing acceptance evidence, not to manufacture unrelated findings.
 
-**Important guidance on "deferred" classifications:** Test coverage gaps should NOT be automatically deferred. If a PR adds new testable code, tests should ship with it — even if that means adding test infrastructure to a package that lacks it. Only defer tests when the gap is truly unrelated to the PR's changes (e.g., pre-existing untested code that the PR happens to touch). When tests are deferred, the assessor must note whether a tracking issue exists or needs to be created.
-
-Update task: assess → completed, post-assess → in_progress.
+Missing tests are not blockers by themselves: identify the important regression, practical consequence, and why current tests miss it.
 
 ## Step 7: Post assessment
 
-```bash
-GH_BODY="$(mktemp /tmp/gh-comment.$$.XXXXXXXX)"
-cat > "$GH_BODY" << 'MACH6_EOF'
+Post the second comment with a unique temp body:
+
+```markdown
 <!-- mach6-assessment -->
 ## Review Assessment
 
-<link to review comment>
+<link to findings comment>
 
 ### Classifications
-
 | Finding | Classification | Reasoning |
 |---|---|---|
-| <summary> | genuine/nitpick/false-positive/deferred | **Factual:** <what the code proves>. **Scope:** <why this is or is not required by authoritative scope>. |
+| ... | merge blocker / useful follow-up / discarded observation / nitpick / false positive / deferred | **Factual:** ... **Scope:** ... **Practical:** ... |
 
 ### Action Plan
-
-<numbered list of genuine issues only, ordered by priority>
+<merge blockers only, ordered by priority>
 
 ---
 *Assessment by mach6*
-MACH6_EOF
-gh pr comment <pr-number> --body-file "$GH_BODY"
 ```
 
-Update task: post-assess → completed, summary → in_progress.
+Classify every candidate. Useful follow-ups and deferred observations stay outside the action plan.
 
 ## Step 8: CLI summary
 
-Present to the user:
-- Per-finding breakdown: summary, classification, reasoning
-- Counts: genuine, nitpicks, false positives, deferred
-- Action plan
-
-If any findings were classified as **deferred**, ask the user if they want to create issues for them:
-```bash
-GH_BODY="$(mktemp /tmp/gh-body.$$.XXXXXXXX)"
-cat > "$GH_BODY" << 'MACH6_EOF'
-<body referencing PR and finding>
-MACH6_EOF
-gh issue create --title "<title>" --body-file "$GH_BODY"
-```
-
-Update task: summary → completed.
+Report each classification, counts of merge blockers/nitpicks/false positives/deferred, and the merge-blocker-only action plan. Ask whether to create issues for deferred follow-ups, using unique temp body files.
 
-Suggest next step:
-- If genuine issues: `/skill:mach6-implement <pr-number> <finding-numbers>`
-- If all clear: `/skill:mach6-publish <pr-number>`
+Suggest exactly one next command:
+- Merge blockers: `/skill:mach6-implement <pr-number> <finding-numbers>`
+- No merge blockers: `/skill:mach6-publish <pr-number>`