Swarm PR Feedback
Use this skill to close known PR feedback. This is not a fresh broad PR review.
Repository-specific bot names and examples below are illustrative; substitute the repo's actual bot and branch-state surfaces when they differ.
swarm-pr-review discovers new findings; swarm-pr-feedback ingests existing
feedback surfaces, verifies each claim, clusters related problems, fixes confirmed
issues, validates the branch, and reports closure status for every item.
Mandatory gate contract. Stage A (structural pre-checks) and Stage B (reviewer + test_engineer) gates and the reviewer + critic closeout gate are MANDATORY for any change made as part of this process. No fix lands, no closure ledger row is marked FIXED, and no PR is published until all three gates pass on the current diff. There is no speed, efficiency, or time exception. See "Mandatory Gates" below for the full protocol.
When the work starts from a prior Profile-A swarm-pr-review run, use the exact
user command /swarm pr-feedback <PR_URL> continue from .swarm/pr-review/<run_id>/feedback-handoff.json. The controller validates the
terminal review and artifact before atomically creating an unbound feedback
gate; the artifact alone is not write authorization. Profiles B/C ingest their
task-workspace handoff directly before triage.
Carry forward the original review finding IDs, classifications, reviewer/critic
provenance, and any operational blockers instead of renumbering them as new
discoveries.
Feedback closure is not the end of the PR lifecycle. On a PR, the default run is
references/drive-to-merge.md: gates → dispositions → CI green → merge (explicit
authorization only) → monitor → retro + memory closeout; "fixes only" stops early. With
pr_monitor.enabled, post-closure events (a new bot round, a CI change, fresh
review activity) are triaged under ../swarm-pr-subscribe/SKILL.md and route
back into this discipline when they need fixes.
Multi-Round Bot Reviews (Iterative Pattern)
When the repo uses an auto-review bot that posts a new review comment after
every push to the PR branch, identify that bot from the repository contract
and apply this pattern (for example hermes-pr-review in this repo). Expect N
rounds of review for N pushes, and budget for it.
Round N+1 deltas vs Round N:
- Fresh
FB-###ledger IDs for new findings (do not reuse IDs from earlier rounds) - Findings from prior rounds that remain unfixed will reappear with the same evidence
- Findings you marked DISPROVED with new evidence may reappear if the bot disagrees
- New findings may be introduced that the prior round did not see (the bot's read scope is the new commit, not the full diff history)
Operating principles for multi-round triage:
- Continue the ledger, do not start over. Append to the same
FB-###counter across rounds. Track each finding's state per round (open, fixed, disproved, awaiting-decision, repeated). - Carry forward unresolved items. Findings you marked
PARTIALorNEEDS_USER_DECISIONin round N will still be open in round N+1. The closure ledger should show their evolution (e.g., "PARTIAL round 1 → CONFIRMED round 2 after evidence collected"). - Apply the 3-strikes evidence-escalation rule. When the same finding is raised 3+ times across rounds, re-run source verification with a fresh reviewer context and surface the disagreement explicitly. Add a defense-in-depth change only when that fresh verification proves the change is correct, preserves the real invariant, and adds meaningful protection. Repetition, time, token cost, and reviewer persistence are never substitutes for evidence. Document any parent-vs-inner relationship inline so future readers see the rationale. Do not add the repeated suggestion: If it would add incorrect or misleading code about existing guards — e.g., an outer guard that already exists at an inner scope and whose addition would imply the inner guard is absent, a type narrowing that masks a real error class, or a check whose presence asserts a false invariant — do not add the change. A wrong fix embedded in the code is harder to remove than a repeated rebuttal in a comment thread. When the repeated finding is misleading about existing guards, apply item 6's "surface to user" path instead of 3-strikes; otherwise the 3-strikes rule applies.
- Verify bot fix-direction suggestions against actual file structure. Bots read files linearly and can miss parent-block guards. For any "add an X check" suggestion, read the surrounding function/block to confirm the check is genuinely missing or already exists at a higher scope.
- Each round produces its own closure ledger as a PR comment. Prefix with "Round N" so the bot and reviewers can see progression. Maintain a running summary table at the end of each comment showing totals across rounds (confirmed+fixed / disproved / partial / awaiting-decision).
- Stop the cycle deliberately. If a finding is disproved with code evidence 3+ times and the bot keeps re-raising it, leave the comment, post the closure ledger with the cumulative evidence, and surface the disagreement to the user rather than continuing to push fixes. The user can resolve persistent reviewer-AI disagreement.
Why this matters: Without the multi-round pattern, each round looks like "start over, re-triage everything." With it, the rounds become incremental: each round's work is bounded by new findings + carried-forward items only. This matches how the bot actually behaves and avoids wasted cycles.
Bot and Security Claim Verification
Before trusting automated review findings (SAST bots, security scanners, AI reviewers), apply the verification protocol in references/bot-claim-verification.md. Key principle: every bot claim is unverified until you reproduce the exact finding against the current HEAD with the exact tool and rule it names.
Operating Stance
Treat every review comment, CI failure, bot summary, PR body claim, and pasted note as a claim until source evidence proves it. Do not silently drop, defer, or mark items out of scope. Ask the user only for product or scope decisions that cannot be proven from the PR, repo, or explicit instructions.
Do not run a fresh broad PR review while addressing existing feedback. Inspect adjacent code only as needed to verify reachability, dependencies, shared root causes, regression risk, or sibling changes required by a confirmed item.
GitHub review-thread resolution is user-controlled. Do not resolve or mark review threads resolved unless the user explicitly instructs you to do so.
Do not act on review-discovered findings from a prior swarm-pr-review run
unless the user has explicitly approved the transition into swarm-pr-feedback.
The handoff artifact is triage input, not standing authorization to change code.
Runtime Capability Profiles
This skill runs on any agent harness. Detect the active profile from the
actual tool list before triage — the same three profiles defined in
../swarm-pr-review/SKILL.md (Runtime Capability Profiles):
- Profile A — mechanical PR-feedback controller. The plugin's tools are
present in this session:
dispatch_lanes_async,collect_lane_results,retrieve_lane_output,prepare_pr_feedback_scope,run_pr_feedback_stage_a,complete_pr_workflow. The controller's fail-closed accounting (immutable inventory, ordered gate lanes, content digests, arming, bound push) is authoritative; bypassing it — direct subagent calls, blocking dispatch, prose verdicts — is BLOCKED while it is active. - Profile B — native parallel subagents, no controller. Run the same
intake → verify → fix → gate → publish discipline using your harness's
subagent tool for verification lanes and gate roles; you maintain the
ledger, the ownership partition, and the digest accounting yourself in
session/task workspace files (never under
.swarm/, which belongs to the plugin runtime). - Profile C — single context, no subagents. Same discipline as strictly separated sequential passes that re-derive rather than restate earlier reasoning, plus explicit disclosure in the closure ledger that gate independence was procedural.
Controller-tool absence is NOT a blocker; Profiles B and C are first-class execution paths. BLOCKED is reserved for bypassing an active controller and for verification or coverage gaps that stay unclosable after bounded retries.
Detailed reference material moved to .opencode/skills/swarm-pr-feedback/references/preflight-checkout.md (issue #2907 progressive-disclosure budget).
- Verify the working tree is clean first (
git status --porcelain). If any tracked or untracked changes exist, callprepare_pr_workflow_checkoutpreserve every dirty path, including untracked files; pass explicitpaths - Check out the head branch locally before dispatching feedback lanes. Feedback verification reads the working-tree
filesystem (
Read/Glob/Grep), and fixes must land on the PR branch — without a checkout you would verify and patch the base branch's code instead. Record the exactmerge_base...head_refrange for diff-scoped inspection. - Pass the exact
merge_base...head_refcommit range in every read-only verification or explorer/advisory-lane delegation so lane agents can inspect specific revisions withgit showwhen needed. - A detached checkout at the authoritative full PR head is a valid pre-bind intake state. On the first Profile-A bind, the controller attaches it only when Git reports exactly one safe candidate: an existing local branch at that SHA whose upstream is an exact remote ref at the same SHA, or one exact remote-tracking ref. It never guesses a remote/name boundary. Zero candidates, multiple candidates, a linked-worktree-owned local branch, or an existing mismatched upstream fails closed without publishing the bind. Retry is idempotent if switching succeeded but state persistence failed.
When a verification lane result includes output_ref, treat output as a
preview and call retrieve_lane_output before using it to classify, resolve,
disprove, or group feedback items. If the result is output_degraded,
transcript_incomplete, or truncated without a usable ref, keep the affected
ledger items as NEEDS_MORE_EVIDENCE or re-dispatch a narrower read-only lane.
(Profile A. On Profiles B/C, read each verification subagent's or pass's full
report directly — a truncated or summary-only report is a preview, not
verification evidence, and keeps its items open the same way.)
Pre-flight: Restart Inventory (Profiles B/C)
After a session restart mid-round, record a four-bucket inventory in the
task-gates artifact before dispatching: reusable artifacts / stale approvals
(gate verdicts bound to pre-restart digests need re-verification) / dead
agent ids (SendMessage fails; never retry or wait) / fresh-dispatch work
(every in-flight lane needs a new standalone packet). Full protocol:
references/restart-inventory.md.
Pre-flight: Dirty Worktree Handling
Before staging any files for the PR commit, check the working tree state:
The problem: git add -A stages every uncommitted change in the working tree,
including pre-existing changes from other branches or prior work.
The check: Run git status --porcelain first. If output is non-empty, identify
which files are PR-related vs pre-existing uncommitted changes.
The rule: Never stage with git add -A, git add ., or any glob form —
stage exact paths with the -- separator, each already inside the
PR changed set (the gate refuses every other form):
git add -- src/foo.ts tests/foo.test.ts
Batch Collection (mandatory before any fix)
When the runtime provides a CI-failure-batching workflow, load it before
proceeding. The bundled ci-failure-batching skill is one conditional
implementation; otherwise apply the host-neutral complete-ledger protocol
below.
For the detailed 6-step batch collection protocol, read file:.swarm/bundled-skills/ci-failure-batching/SKILL.md. The steps below are a summary:
gh pr checks <number> --json name,bucket,state,linkto collect all check results- Filter to
bucket == "fail"orbucket == "cancel" gh run view <id> --log-failedfor each failing run- Group failures by root cause before fixing
Rule: The complete failure ledger must be collected before any modification is proposed. Verifying the ledger is complete is a prerequisite for the Fix Planning step.
Pre-flight: Scope Discipline
When the plugin's mechanical controller is available, every coder Task must be
preceded by prepare_pr_feedback_scope({ task_id, files }). The controller is
available only after the immutable feedback-verification lanes have settled and
binds the exact file set to the current feedback revision, parent session, and
next matching Task call. The coder prompt must use the same numeric task_id,
contain matching FILE: directives, and include a literal ACCEPTANCE: line.
Once a Task consumes that scope, its task_id is immutable for the current
feedback revision. Any retry must prepare and dispatch a fresh nested numeric
task identity (for example 1.1.1), never re-declare the consumed ID.
Do not create a synthetic save_plan merely to authorize feedback work, and do
not use declare_scope; those tools belong to the normal implementation-plan
lifecycle. There is no one-file or single-function carve-out from the dedicated
PR-feedback scope controller.
In runtimes without this controller, use the native scope mechanism. If none exists, put exact allowed files and non-goals in the delegation and verify the resulting diff mechanically. Never bypass an available scope controller merely to reduce ceremony.
Intake Surfaces
Build a complete feedback ledger before editing. Include every available source:
- validated findings and operational blockers handed off from
swarm-pr-review, - pasted user or reviewer feedback,
- GitHub review threads, inline review comments, and review summaries,
- PR issue comments and requested-changes reviews,
- CI/check failures, check annotations, and relevant logs,
- mergeability, conflicts, base drift, and stale PR branch state,
- local validation failures,
- PR body checkboxes, test-plan claims, linked issues, and acceptance criteria,
- commit history and bot/app commits on the PR branch.
If a source is unavailable, retry with alternative access paths. If unavailable after retry, the source is a coverage gap that must be reported to the user — do not silently "record that limitation" and proceed as if the source doesn't matter.
Detailed reference material moved to .opencode/skills/swarm-pr-feedback/references/intake-surfaces.md (issue #2907 progressive-disclosure budget).
Cap each dispatch_lanes_async batch at 8 lanes (MAX_LANES); if the ledger
needs more than 8 verification lanes, dispatch in sequential batches and settle
each batch's COVERAGE GATE before the next — do not over-spawn lanes for a
trivial round.
Feedback Ledger
Normalize each item before triage:
FB-001 | source | author/tool | status: UNTRIAGED | location | claim | raw link/quote | depends_on
Rules:
- Preserve prior
F-###,CI-###,CONFLICT-###,STALE-###, and similar IDs from a review handoff when they already exist. Only mint freshFB-###IDs for new feedback discovered after the handoff. - Preserve reviewer/critic provenance from the handoff artifact so the closure ledger can show which items were review-validated before fix work began.
- Preserve exact reviewer wording or log summary when practical.
- Split compound comments into separate ledger items only when they require different evidence or fixes.
- Keep duplicate symptoms linked to one root cause rather than deleting them.
- Include conflicts, stale branch state, obsolete older-head CI,
generated-output (
dist/) drift, and other CI failures as first-class ledger items. - Use explicit IDs for non-review feedback when useful, for example
CONFLICT-001for merge/base drift andCI-001for check failures, so PR bodies can show exactly how operational blockers were closed. Seereferences/operational-gotchas.md(## Contract addendum (2026-10-12)) for the body-claim-audit, probe-hygiene, and stable-obligation/coverage-diff ledger rules.
Mandatory: integrate all PR comments with feedback or findings before branch validation (Stage A)
Before branch validation (Stage A) can begin, every PR comment that contains feedback
or findings MUST be integrated into the total feedback ledger as a
FB-### item. This is a hard requirement, not a best-effort step.
What counts as feedback/findings (and what does not) is enumerated in
references/intake-surfaces.md (## What counts as feedback or findings).
Rules:
- No finding may be addressed outside the ledger. If you fix something a
reviewer mentioned, the corresponding
FB-###item MUST be in the ledger before the fix. If you skip the fix, theFB-###item MUST be in the ledger with aDISPROVED,PRE_EXISTING,NEEDS_MORE_EVIDENCE, orNEEDS_USER_DECISIONstatus before branch validation (Stage A) can begin. - Status semantics for unaddressed items:
CONFIRMEDandPARTIALitems must be addressed (fixed or disproved) before branch validation (Stage A) can begin. ACONFIRMEDitem that is left unaddressed is a regression against the review.DISPROVED,PRE_EXISTING,NEEDS_MORE_EVIDENCE, andNEEDS_USER_DECISIONitems may remain open at branch-validation (Stage A) time, but each must be explicitly justified in the closure ledger.
- The closure ledger at the end of the run must account for every
FB-###item with a final status (fixed / disproved / pre-existing / needs user decision / needs more evidence); each PRE_EXISTING, NEEDS_MORE_EVIDENCE, or NEEDS_USER_DECISION item also gets one disposition (ABSORB / FILE / RECORD / ASK) perreferences/followup-dispositions.md; DISPROVED items need none. - Comments from the latest bot round take precedence over earlier rounds
for the same finding; the earlier-round
FB-###item is updated with the new evidence rather than a new item being created. - Multi-round pattern continues to apply (see "Multi-Round Bot Reviews"
section): new bot-round findings get new
FB-###items; prior items carry forward with the new evidence. - Re-fetch at every round boundary (#3607). Intake is not one-time:
re-fetch issue comments, inline review comments, and reviews at the start of
every fix round and again before the closeout gate — a critic NEEDS_REVISION
restart counts as a fix round. The fetch is a RECORDED obligation: append a
fetch receipt (surfaces, comment ids, timestamp) to the findings ledger at
every boundary. Commands, bot markers, field evidence:
references/intake-surfaces.md(## Round-boundary re-fetch).
Rationale: the closure summary is the only artifact the user/maintainer reads to confirm the PR is ready to merge; a review comment fixed or skipped without a ledger item is invisible there, so the PR ships with unreviewed feedback.
Verification
Classify every ledger item before fixing:
| Status | Meaning |
|---|---|
CONFIRMED |
The issue is real, reachable or structurally proven, and introduced or exposed by the PR. |
PARTIAL |
The comment points at a real concern, but the framing, severity, or requested fix is incomplete. |
DISPROVED |
Source, tests, or execution context prove the claim is false, unreachable, or already mitigated. |
PRE_EXISTING |
The issue exists on the base branch and is not materially worsened by the PR. |
NEEDS_MORE_EVIDENCE |
The claim (e.g., "council APPROVED") is unsupported by stored evidence (e.g., a missing or failed .swarm/evidence/ artifact); more information is required before triage. |
NEEDS_USER_DECISION |
The item requires a product, UX, compatibility, or scope choice that cannot be inferred. |
Verification checklist:
- Read the referenced file and surrounding code.
- Check caller context, reachability, feature flags, schema validation, guards, state-machine rules, and permission boundaries.
- Determine whether the issue is PR-introduced, pre-existing, or unresolved.
- Check related tests and whether a failing/proposed test would prove the item.
- Check whether multiple feedback items share one root cause.
DI seam migration validation
When the repository uses _internals seam / mock.module() patterns, apply the validation protocol in references/operational-gotchas.md.
Fix Planning
Cluster ledger items by root cause before coding. Fix in this order unless a user instruction or dependency requires otherwise:
- Merge conflicts, stale branch state, and base drift.
- Deterministic CI, build, typecheck, formatting, and test failures.
- Confirmed correctness, security, data-loss, persistence, git/write-safety, and permission issues.
- Test gaps needed to prove confirmed fixes.
- Docs, release notes, PR body, and migration guidance.
- Reviewer communication and closure summaries.
For each cluster, record:
ROOT-001 | ledger items: FB-001, FB-004 | files | fix approach | tests | docs | risk
Do not make scope decisions yourself. If the right fix depends on product intent
or compatibility policy, mark the item NEEDS_USER_DECISION and ask.
Implementation Rules
- Patch only confirmed or partial items, plus required tests/docs.
- Do not implement speculative cleanup while feedback remains unclosed.
- Never ship unwired code. Any new command, tool, skill, config, docs surface, or generated artifact must be fully registered and validated.
- Never defer work or declare it out of scope without explicit user instruction; route every unfixed item through
references/followup-dispositions.md(RECORD is a visible closure, never a silent drop). - Keep invalid or disproved findings in the closure ledger with the evidence.
- For CI failures, verify the failing job belongs to the current PR head before treating it as current evidence.
- For generated output or dist failures, inspect the failing log before rebuilding and commit regenerated files only when the PR touches the source surface.
- When
mainhas a merge queue enabled, do not rebase or force-push a PR only becausemainadvanced. Once required checks and review are green, queue the PR and let the merge queue perform final current-base validation. Still resolve real merge conflicts and SHA-dependent review threads before queuing.
Conditional runtime/host gotchas
For portability gotchas (plan identity, stale gate evidence, PowerShell comment posting, same-file batching), read references/operational-gotchas.md.
Mandatory Gates
Stage A and Stage B gates and the reviewer + critic closeout gate are
MANDATORY for any change made as part of the PR-feedback process. No fix
lands, no closure ledger row is marked FIXED, and no PR is published until all
three gates pass on the current diff. This section uses the repository's
established Stage A/B meaning: Stage A = pre_check_batch-equivalent structural
pre-checks; Stage B = reviewer + test_engineer per-task gates (consistent
with execute, plan, specify, brainstorm, docs/swarm-briefing.md, and
docs/council/README.md).
Mechanical controller contract (Profile A). Prose acknowledgements, direct Task calls,
blocking dispatch, reused conversations, and free-form APPROVE/PASS text do
not satisfy these gates while the controller is active. The durable controller requires this exact sequence on
one content digest:
Controller authority follows the parent/child session ancestry. Coder and nested child tool calls inherit the parent feedback gate; delegation never grants early commit, push, remote-write, checkout, or protected-evidence authority.
run_pr_feedback_stage_awith array-form commands for every concrete workspace/category/source build, typecheck, and lint/format obligation mechanically discovered from the repository's manifests, configs, scripts, or bounded.pr-validation.jsoncontract, plus exact["git", "diff", "--check"]. A category with no repository-local signal is not invented merely to reach a fixed command count. Add one required proof command: use the exact failing CI/test reproduction when the immutable inventory includes a defect or CI/test failure; otherwise add a repo-appropriate targeted regression/test command that exercises the changed behavior. The tool executes the commands; naming a category without executing it is not evidence. The controller binds that reproduction receipt to the complete immutable feedback inventory, so no feedback item can reach Stage B with an unrelated or unowned Stage A receipt.- One
dispatch_lanes_asynclane withmode: "swarm-pr-feedback:stage-b-reviewer",workflow_lane: "stage-b-reviewer", every immutablefeedback_item_ids, andmax_concurrent: 1. - After that lane settles positively, one fresh
test_engineerlane withmode: "swarm-pr-feedback:stage-b-test", matchingworkflow_lane, the complete inventory, andmax_concurrent: 1. - After Stage B settles, one separate fresh reviewer lane with
mode: "swarm-pr-feedback:closeout-reviewer", then one separate fresh critic lane withmode: "swarm-pr-feedback:closeout-critic". Each owns the complete inventory and usesmax_concurrent: 1.
Every gate lane emits exactly one fully populated row per feedback ID:
[STAGE-B-REVIEW] | FB-001 | APPROVE|NEEDS_REVISION|BLOCKED | evidence
[STAGE-B-TEST] | FB-001 | PASS|FAIL|BLOCKED | evidence
[CLOSEOUT-REVIEW] | FB-001 | APPROVE|NEEDS_REVISION|BLOCKED | evidence
[CLOSEOUT-CRITIC] | FB-001 | APPROVE|NEEDS_REVISION|BLOCKED | evidence
Only exact positive verdict fields pass — APPROVE (or its accepted spelling
APPROVED on the three review/critic markers) for review/critic rows, exact
PASS for test rows; anything else fails. A sentence containing “not APPROVE,” a
header without item rows, duplicate rows, missing IDs, degraded/truncated
artifacts, wrong roles, stale content digests, parallel or out-of-order phases,
and reused pre-edit approvals all fail closed. Any content change after Stage A
invalidates Stage A and every later gate; restart at step 1. For an in-scope edit whose moved digest triggers the incomplete-ownership block, re-dispatch swarm-pr-feedback:verification on the edited tree (new batch_id, same lane ids) to re-settle coverage; further coder writes need a fresh scope (new task_id), then re-run Stage A and the ordered gates. See
"Re-recording Stage A on an unchanged revision" below for the one retention exception, which applies only when the revision digest itself did not change. Publication tools
and git commit/git push remain blocked until all four ordered lane phases
settle on the Stage-A digest. After they settle, only one standalone git commit
command may create the reviewed commit; push and remote publication remain
blocked until that exact commit is armed. The first completion requires a clean
index/worktree and a non-merge direct child commit whose sole parent is the
immutable intake head, so multiple commits, merge commits,
amend/non-descendant histories,
--allow-empty, and partially committed reviewed content fail closed. There is no speed, efficiency, token, or time exception.
Verified no-change terminal (issue #2131 C1). When the ENTIRE immutable
inventory is verified as a no-change outcome — every FB-### item classified
DISPROVED, PRE_EXISTING, NEEDS_MORE_EVIDENCE, or NEEDS_USER_DECISION
in the settled verification lanes — a correct workflow needs NO content commit.
After every ordered gate settles, call complete_pr_workflow with the intake
pr_head_sha while HEAD still equals that intake head and the tree is clean:
it returns verified-no-change and clears the gate terminally (nothing to
publish; an empty or --allow-empty commit is still forbidden). Any item
classified CONFIRMED/PARTIAL requires the ordinary exactly-one-reviewed-
commit path above.
Base-sync/rebind (issue #2131 C2). When base drift or merge conflicts force
a merge/rebase, the repaired history is no longer a direct child of the intake
head and the ordinary publication path can never be satisfied. Do NOT abort
ad-hoc: finish the repair, fetch the new authoritative PR head, check it out,
then call rebind_pr_feedback_head with the new full PR head SHA. It moves the
immutable intake head to the new head, preserves the immutable inventory, and
invalidates every ancestry-bound receipt (Stage A, verification, ordered
gates) — re-run the entire mechanical ladder on the new ancestry. It refuses a
no-op rebind, refuses while publication is armed, and refuses while lanes are
in flight.
Without the controller (Profiles B/C). The same gates run in the same
order with the same one-row-per-feedback-ID verdict contracts; what changes is
the executor. Stage A: run the repository's discovered build, typecheck, and
lint/format obligations, exact git diff --check, and one targeted
reproduction/regression command yourself, recording each command and its
output as a receipt in the ledger; track the content digest manually (for
example git rev-parse HEAD plus a working-tree diff hash) so stale receipts
are detectable, and re-run the whole set after any content change. Stage B:
one fresh reviewer subagent, then one fresh test-engineer-role subagent
(Profile B), or two strictly separated re-derivation passes (Profile C);
each test-engineer verdict must NAME its discriminating probe (mutant /
source surgery / executed pre-fix failure, with the observed failure mode) —
a green suite alone is test theater and does not settle the item. Closeout:
a separate fresh reviewer, then a separate fresh critic, per the swarm
closeout contract. Emit the same [STAGE-B-REVIEW], [STAGE-B-TEST],
[CLOSEOUT-REVIEW], and [CLOSEOUT-CRITIC] rows, record the verdicts in the
session task-gates artifact, and disclose Profile C's procedural independence
in the closure ledger. Any edit after a gate verdict invalidates that verdict
and every later one; restart at Stage A.
If a gate failure is suspected pre-existing, prove it on the base branch or
label it UNVERIFIED. Do not call the branch green while required checks are
non-green.
Stage A — structural pre-checks (mandatory before Stage B)
Run for every changed surface. No "where relevant" — every PR-feedback change runs these; if a surface is genuinely untouched, state that explicitly rather than skipping silently.
- the repository's actual build validation for the changed surface — must succeed when that surface participates in a build,
- the repository's actual typecheck/static-analysis validation for the changed surface — must pass when such a check exists,
- the repository's actual lint/format validation for the changed surface — must pass when such a check exists,
git diff --check— no whitespace or merge-marker errors.- one proof command is mandatory on every run:
- use the exact failing CI/test command when a ledger item is rooted in a defect or CI/test failure; the reproduction must fail on the pre-fix tree and pass after the fix.
- otherwise run a repo-appropriate targeted regression/test command that exercises the changed behavior and passes on the post-fix tree.
Execute these through run_pr_feedback_stage_a when available. Its bounded
array-form commands are not arbitrary shell escape hatches: diff-check and a
targeted reproduction are unconditional, every mechanically discovered
workspace/category/source obligation is also required, and each command must
match its declared build/typecheck/lint/diff-check/reproduction intent. Multiple
commands in one category are mandatory when polyglot or monorepo discovery
produces multiple obligations; use the exact working_directory and
obligation_id for each. Every obligation ID gets exactly one independently
executed receipt; identical commands remain separate only when distinct
repository sources mechanically require them. The
reproduction command must name at least one exact test, package, path, or
regression selector in targets. Invoke recognized validators and test runners
directly. Standard contained ./gradlew and ./mvnw wrappers are supported. A
repository with a custom validator can declare its exact array-form command in a
bounded .pr-validation.json version-1 contract that is byte-identical to
the immutable base_ref/base_sha merge-base copy and reference the exact
contract path/id. A contract added or changed by the PR never authorizes a
command. When that trusted contract replaces an otherwise opaque named
package script, the controller preserves the contract identity on the discovered
obligation and receipt, requires non-empty execution evidence, and permits only
an exact inspected npm, pnpm, yarn, or Bun script selection. Unsupported
workspace-glob semantics fail closed rather than silently omitting a workspace.
Arbitrary opaque scripts and unverified package-script names remain non-proof
because a name such as test or build can hide a no-op. A
reproduction must also return non-empty machine-observable runner output.
The reproduction check also supplies one feedback_targets row per immutable
feedback ID, in inventory order: exact feedback_item_id, one executed target,
concrete expected_behavior, and a typed proof_kind (defect, metadata,
source-proof, conflict, ci, or user-decision). Missing, duplicate,
invented, target-less, or kind-less mappings block Stage B; the controller
persists that exact per-item mapping. This is a STRUCTURAL mapping with a typed
proof kind — it proves each item maps to a target the executed command actually
selects, not that the target is causally decisive for that item; the Stage B
reviewer lane owns that judgement (issue #2131 C4).
No-op/help/list/dry-run,
fix/update, package publication/deployment, Git mutation, remote client,
shell/eval/wrapper, and credentialed publication surfaces fail closed. The
controller snapshots the content revision plus HEAD, index, refs, upstream, and
Git config before and after every command (including failures/timeouts); any
mutation invalidates Stage A and prevents later commands from becoming proof.
The Stage A response carries per-check summaries (category, command, exit code,
duration) rather than inline stdout/stderr. On failure it also carries a bounded
tail of the failing check and a full_output_ref for retrieving the complete
output via retrieve_summary; if that persistence fails, the failing check's
full stdout/stderr is inlined instead so evidence is never lost. A successful
run persists nothing — there is no failure evidence to recover, and the
per-check summaries are the useful record.
Re-recording Stage A on an unchanged revision
Re-recording Stage A always requires a fresh, complete receipt set on the current revision digest — that part is unconditional. What happens to the already-recorded Stage B and closeout gate batches depends on whether the revision digest itself changed. If the digest is unchanged from the prior Stage A record and the newly declared applicable obligations/categories are equal to or a superset of the prior declaration, the already-approved independent gate batches are retained: re-recording Stage A to add a previously-missed obligation, or to re-attest the same set, does not by itself discard Stage B and closeout work that already passed on that revision. A narrower obligation set than the prior declaration, or any actual digest change, still wipes every recorded gate batch and un-arms publication exactly as before — a controller cannot narrow what it declares in order to dodge re-verification.
Detailed reference material moved to .opencode/skills/swarm-pr-feedback/references/gate-evidence-scope.md (issue #2907 progressive-disclosure budget).
Stage B — reviewer + test_engineer (mandatory after Stage A passes)
Two independent agents on the Stage-A-green diff, run in order: reviewer first, then test_engineer. The reviewer validates the fixes before the test_engineer writes falsification probes against them; running them in parallel risks the test_engineer pinning a not-yet-approved fix shape.
- reviewer — independent (fresh context, not the implementer, not a continued conversation). Validates each fix on the current diff against the feedback item it closes. Verdict per item: APPROVE / NEEDS_REVISION / BLOCKED.
- test_engineer — independently designs and runs the falsification probe or
regression test that proves each fix resolves its item (tests for changed
behavior or newly covered gaps). The structured gate lane is read-only: if a
missing test must be authored, return
FAILwith the exact requested probe so implementation can add it before the sequence restarts. Verdict per item: PASS / FAIL / BLOCKED.
Address every NEEDS_REVISION / BLOCKED / FAIL, then restart at Stage A on the current diff. When implementation authors or modifies test files requested by the test_engineer, the content-digest controller invalidates all earlier receipts automatically. Stage A must be green over the full Stage-B-inclusive diff before a new Stage B reviewer and test engineer run.
Closeout gate — reviewer + critic (mandatory after Stage B)
A separate reviewer + critic pair on the Stage-B-approved diff. This is the
swarm closeout contract (see ../swarm/SKILL.md "Mandatory implementation
closeout gate"); because this skill edits code, docs, release notes, or skill files it applies in full — Stage B
alone does not satisfy it.
- independent reviewer (fresh context, separate from the Stage B reviewer) → APPROVE / NEEDS_REVISION / BLOCKED per item; a delta approval is invalid while unreviewed external feedback exists on the PR (#3607).
- final critic (separate fresh context, not a continued conversation with
the reviewer, dispatched after the reviewer returns APPROVE) → APPROVE /
NEEDS_REVISION / BLOCKED per item. The critic challenges: is every feedback
item actually resolved — including items posted after the ledger was built
(it fetches all three surfaces fresh — issue comments, inline review
comments, and reviews, see
references/intake-surfaces.md— and reconciles each external finding against the ledger, #3607)? Any requirement drift, weak evidence, missing sibling-file checks, stale approvals, anything unwired or deferred?
Address every NEEDS_REVISION / BLOCKED item, re-review with the reviewer if the
critic surfaces correctness issues, then re-critic. Any edit after the
reviewer's or critic's approval invalidates that approval — re-run the
affected gate on the current diff before publishing. Before dispatching the
final critic, record the closure ledger in the durable session task-gates
artifact (bound to the reviewed head SHA and fetch time); the critic
reconciles it against its own fresh fetch — an input to verify, never a
substitute for the fetch (#3607). Publish the ledger as a PR comment only
after the reviewed commit is pushed and the remote head verified: under
Profile A the gate blocks PR comments until all four phases settle and
complete_pr_workflow arms the push; the B/C invariants likewise forbid
comment/body writes before the verified push. Open the same task-gates
artifact at ROUND START — before any PR_FEEDBACK gate binding or after the
verification lanes settle (the gate blocks writes in between) — and append
every reviewer/critic verdict (with HEAD/diff) as it lands, so compaction or
handoff re-enters from disk. (ZC
…(truncated)