opencode-swarm 7.196.0 → 7.197.0

package/.opencode/skills/swarm-pr-feedback/SKILL.md

@@ -1,6 +1,5 @@
 ---
 name: swarm-pr-feedback
-audience: swarm-plugin
 description: >
   Ingest and resolve known pull request feedback with skeptical source verification.
   Use when addressing pasted PR feedback, GitHub review comments or threads,
@@ -12,7 +11,9 @@ description: >
   (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.
-swarm-contract-digest: aca3f05b0677
+metadata:
+  audience: swarm-plugin
+  swarm-contract-digest: "a7fade5b1c40"
 ---
 
 # Swarm PR Feedback
@@ -156,36 +157,11 @@ 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.
 
-## Pre-flight: Check Out the PR Branch Locally
-
-Before verifying any claim or making any fix, ensure the PR branch is the working
-tree:
-
-- If `head_ref` is a remote branch that is not checked out locally, fetch it
-  (`git fetch origin <head_ref>`).
-- **Check for parallel work first.** Before checkout, use the repository or
-  runtime's parallel-work check. When the bundled
-  `parallel-work-check` skill exists, it is one conditional implementation to
-  detect concurrent pushes from other agents (for example the repo's
-  auto-review bot following up, a maintainer pushing fixes, or parallel swarm
-  work). If remote has new commits: read `git log local..remote`, evaluate whether the parallel work
-  supersedes your planned fixes, and prefer the parallel work if it's more
-  comprehensive (more tests, better edge coverage, clearer error handling).
-  Abort your rebase, take the remote state, then add minor improvements on top.
+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, call `prepare_pr_workflow_checkout`
-  before binding (Profile A). Omit `paths` to auto-discover and atomically
   preserve every dirty path, including untracked files; pass explicit `paths`
-  only for an exact bounded tracked-file set. It creates an auditable stash
-  receipt containing the original branch/HEAD and a structured
-  `operation: "restore"` recovery instruction. Do not issue `git stash`
-  through shell.
-  Without the controller, surface dirty state to the user or abort the checkout
-  — do not blind-stash.
-- Treat `recovery-required` and `indeterminate` controller results as terminal
-  for the current attempt: report the typed `required_action`, abort/clear any
-  already-active gate, and stop. Only `stashable` permits one preparation call;
-  retry only when the controller explicitly returns `retryable: true`.
 - **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
@@ -193,8 +169,6 @@ tree:
  - Pass the exact `merge_base...head_ref` commit range in every read-only verification or
    explorer/advisory-lane delegation so lane agents can inspect specific revisions
    with `git show` when needed.
-- If no PR reference was provided (a pasted-feedback session on the current branch),
-   confirm the current branch is the intended PR branch before editing.
 - 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
@@ -203,15 +177,6 @@ tree:
   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.
-- The existing constrained tracked-branch and safe `gh pr checkout` pre-bind
-  forms remain supported on every profile after proving the exact SHA and a
-  unique intended remote ref. Never use force, submodule-recursive, or detached
-  `gh pr checkout` variants.
-- Immediately after the first bind and before feedback verification dispatch,
-  prove that `git rev-parse HEAD` equals the authoritative full `pr_head_sha`,
-  `git status --porcelain` is empty, and the current branch tracks the intended
-  PR head remote/branch. A detached exact-head checkout is intake-only; the
-  bind must attach it before feedback dispatch or publication.
 
 When a verification lane result includes `output_ref`, treat `output` as a
 preview and call `retrieve_lane_output` before using it to classify, resolve,
@@ -298,111 +263,12 @@ Build a complete feedback ledger before editing. Include every available source:
 
 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.
 
-### Async advisory verification lanes
-
-After the complete feedback ledger exists and before editing, run independent
-read-only verification lanes. Under Profile A, use
-`dispatch_lanes_async` with `mode: "swarm-pr-feedback:verification"`, the
-complete immutable `feedback_inventory` ID list, the exact current
-`pr_head_sha`, and each lane's exact
-`feedback_item_ids` ownership list for independent read-only verification lanes:
-comment classification, CI/log root-cause inspection, test impact mapping,
-release/docs claim checks, and stale-branch/conflict analysis. Partition the
-ledger so each `FB-###` item is owned by exactly one verification lane and the
-union of lanes covers the entire ledger — no feedback item may be left
-unassigned to a lane; state each lane's owned IDs both structurally and in its
-prompt. The runtime rejects missing, duplicate, overlapping, or unknown item
-ownership and blocks mutation until the verification batch settles. Scale
-the lane count to the ledger size: a 1–3 item round may use a single combined
-lane, while a large multi-round intake may warrant one lane per category above.
+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. Record each returned `batch_id`, then continue only ledger-safe
-architect work: normalize feedback IDs, gather deterministic PR metadata, prepare
-reproduction commands, and plan likely fix groups. Do not edit, close items, or
-mark feedback resolved from running lanes.
-
-Every verification lane must end with one parseable row for each owned item:
-
-```text
-[FEEDBACK-VERIFIED] | FB-### | CONFIRMED/PARTIAL/DISPROVED/PRE_EXISTING/NEEDS_MORE_EVIDENCE/NEEDS_USER_DECISION | evidence
-```
-
-Non-empty prose without this marker contract is not a settled verification
-artifact and cannot unlock mutation.
-
-Before the Verification step can mark any item `CONFIRMED`, `PARTIAL`,
-`DISPROVED`, `PRE_EXISTING`, `NEEDS_MORE_EVIDENCE`, or `NEEDS_USER_DECISION`,
-every open verification batch must be fully settled. Poll with
-`collect_lane_results` (wait omitted or `false`) to process settled lanes
-incrementally — clustering confirmed items and pre-reading files for settled
-findings while ledger-safe work remains — then issue a final
-`collect_lane_results` with `wait: true` per batch once independent work is
-exhausted, to confirm every lane is settled.
-Missing, stale, cancelled, or failed lanes are coverage gaps that must be closed
-before marking any item CONFIRMED/PARTIAL/DISPROVED/PRE_EXISTING. Apply the
-COVERAGE GATE:
-retry failed lanes (max 2) as another
-`swarm-pr-feedback:verification` async batch with the same immutable inventory,
-exact `pr_head_sha`, agent type, prompt, scope, and isolation, or stop and
-surface the lane failure to the user as BLOCKED. Under Profile A, blocking and
-direct-Task fallbacks are rejected because they cannot satisfy the durable
-ownership and head-provenance gate.
-Do not proceed with "blocking verification and record that async advisory lanes
-were unavailable" — record-and-continue is not coverage closure.
-
-Under Profile B, partition the same immutable inventory across fresh read-only
-verification subagents — every `FB-###` item owned by exactly one lane and the
-union of lanes covering the entire ledger — with each prompt stating its owned
-IDs and the exact `pr_head_sha`, and each lane returning one
-`[FEEDBACK-VERIFIED]` row per owned item. Under Profile C, verify the ledger
-in sequential category passes with the same one-row-per-item contract. On
-every profile, no item may be classified until its verification lane or pass
-has settled, and unclosable verification gaps are surfaced as BLOCKED.
-
-### CI matrix cascade check (do this before fixing)
-
-When the PR's `unit` job is a matrix across multiple OSes and downstream jobs
-(`integration`, `smoke`) have `needs: unit`, an OS leg failure blocks the
-entire pipeline. Before triaging, check:
-
-1. Are `integration` or `smoke` jobs in `skipped` or `cancelled` state rather
-   than `failed`? That signals a unit matrix cascade — the unit job failed
-   on one OS leg, blocking the downstream jobs from running on the current
-   HEAD.
-2. If a unit OS leg is the blocker, classify the failure:
-   - **Code issue** — the test itself fails. Reproduce locally; if the
-     test passes locally, the runner is the problem.
-   - **Runner performance** — the test step exceeds the configured timeout.
-     Run all files in the step locally with per-file timing; if cumulative
-     local runtime is <10 min and the runner can't complete in 60+ min, the
-     issue is runner performance. Bump the CI timeout as a stopgap and file
-     a follow-up issue for parallelization. Do not loop bumping the timeout
-     past 90 min without filing the follow-up.
-3. Surface cascade failures to the user explicitly. The downstream jobs'
-   results don't exist; the code's coverage of the current HEAD cannot be
-   confirmed by CI alone.
-
-### PR body claim verification
-
-The `.swarm/evidence/` paths below apply only when the reviewed repository uses
-this plugin's council evidence contract. For any other repository, locate the
-authoritative CI attestation, code-host review record, or repository-declared
-evidence store; the universal rule is that an approval claim needs a real,
-retrievable provenance artifact.
-
-PR body text like "PHASE 2 council APPROVED (5/5, round 2)" or "Final council
-APPROVED" must be backed by an evidence file under `.swarm/evidence/` — phase
-councils write `.swarm/evidence/{phaseNumber}/phase-council.json`; the final
-council writes the flat `.swarm/evidence/final-council.json`. Bot-generated PR
-bodies commonly auto-fill these claims without real review. Before accepting
-such a claim as part of triage:
-
-1. Check whether the corresponding evidence file exists with `verdict:APPROVED`.
-2. If the claim is unsupported, mark the closure ledger item as
-   `NEEDS_MORE_EVIDENCE` rather than `CONFIRMED`. Do not silently drop the
-   claim — it indicates the PR body was generated without a real review.
+trivial round.
 
 ## Feedback Ledger
 
@@ -752,26 +618,7 @@ 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.
 
-### Why gate evidence is not item-scoped
-
-Stage A, Stage B, and closeout evidence invalidate as whole gate batches, not
-per feedback item, and that is a deliberate design decision, not unfinished
-work:
-
-- **No trustworthy item-to-file mapping exists to key invalidation on.** The
-  file scope a caller declares for a feedback item is caller-asserted and
-  only path-sanitized — it is never intersected with the actual changed-file
-  set, and it carries no persisted binding back to feedback item IDs. Keying
-  invalidation on that declaration would let a controller dodge
-  re-verification by under-declaring scope, turning a fail-closed guarantee
-  into a fail-open one (AGENTS.md invariant 9) — the same failure class that
-  already ruled out keying digest invalidation on `git diff --raw` blob OIDs.
-- **The four gate phases are holistic by contract.** Each recorded batch must
-  own every inventory item exactly once and in declared order. Retaining
-  evidence for a subset of items per gate would re-partition that
-  independent-review contract itself, and would need its own
-  collusion/independence analysis before it could be trusted — it is not a
-  drop-in extension of the revision-level retention above.
+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)
 

package/.opencode/skills/swarm-pr-feedback/references/gate-evidence-scope.md

@@ -0,0 +1,20 @@
+# Why gate evidence is not item-scoped
+
+Stage A, Stage B, and closeout evidence invalidate as whole gate batches, not
+per feedback item, and that is a deliberate design decision, not unfinished
+work:
+
+- **No trustworthy item-to-file mapping exists to key invalidation on.** The
+  file scope a caller declares for a feedback item is caller-asserted and
+  only path-sanitized — it is never intersected with the actual changed-file
+  set, and it carries no persisted binding back to feedback item IDs. Keying
+  invalidation on that declaration would let a controller dodge
+  re-verification by under-declaring scope, turning a fail-closed guarantee
+  into a fail-open one (AGENTS.md invariant 9) — the same failure class that
+  already ruled out keying digest invalidation on `git diff --raw` blob OIDs.
+- **The four gate phases are holistic by contract.** Each recorded batch must
+  own every inventory item exactly once and in declared order. Retaining
+  evidence for a subset of items per gate would re-partition that
+  independent-review contract itself, and would need its own
+  collusion/independence analysis before it could be trusted — it is not a
+  drop-in extension of the revision-level retention above.

package/.opencode/skills/swarm-pr-feedback/references/intake-surfaces.md

@@ -0,0 +1,107 @@
+# Intake Surfaces detail (async advisory lanes, CI matrix cascade, PR body claim verification)
+
+### Async advisory verification lanes
+
+After the complete feedback ledger exists and before editing, run independent
+read-only verification lanes. Under Profile A, use
+`dispatch_lanes_async` with `mode: "swarm-pr-feedback:verification"`, the
+complete immutable `feedback_inventory` ID list, the exact current
+`pr_head_sha`, and each lane's exact
+`feedback_item_ids` ownership list for independent read-only verification lanes:
+comment classification, CI/log root-cause inspection, test impact mapping,
+release/docs claim checks, and stale-branch/conflict analysis. Partition the
+ledger so each `FB-###` item is owned by exactly one verification lane and the
+union of lanes covers the entire ledger — no feedback item may be left
+unassigned to a lane; state each lane's owned IDs both structurally and in its
+prompt. The runtime rejects missing, duplicate, overlapping, or unknown item
+ownership and blocks mutation until the verification batch settles. Scale
+the lane count to the ledger size: a 1–3 item round may use a single combined
+lane, while a large multi-round intake may warrant one lane per category above.
+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. Record each returned `batch_id`, then continue only ledger-safe
+architect work: normalize feedback IDs, gather deterministic PR metadata, prepare
+reproduction commands, and plan likely fix groups. Do not edit, close items, or
+mark feedback resolved from running lanes.
+
+Every verification lane must end with one parseable row for each owned item:
+
+```text
+[FEEDBACK-VERIFIED] | FB-### | CONFIRMED/PARTIAL/DISPROVED/PRE_EXISTING/NEEDS_MORE_EVIDENCE/NEEDS_USER_DECISION | evidence
+```
+
+Non-empty prose without this marker contract is not a settled verification
+artifact and cannot unlock mutation.
+
+Before the Verification step can mark any item `CONFIRMED`, `PARTIAL`,
+`DISPROVED`, `PRE_EXISTING`, `NEEDS_MORE_EVIDENCE`, or `NEEDS_USER_DECISION`,
+every open verification batch must be fully settled. Poll with
+`collect_lane_results` (wait omitted or `false`) to process settled lanes
+incrementally — clustering confirmed items and pre-reading files for settled
+findings while ledger-safe work remains — then issue a final
+`collect_lane_results` with `wait: true` per batch once independent work is
+exhausted, to confirm every lane is settled.
+Missing, stale, cancelled, or failed lanes are coverage gaps that must be closed
+before marking any item CONFIRMED/PARTIAL/DISPROVED/PRE_EXISTING. Apply the
+COVERAGE GATE:
+retry failed lanes (max 2) as another
+`swarm-pr-feedback:verification` async batch with the same immutable inventory,
+exact `pr_head_sha`, agent type, prompt, scope, and isolation, or stop and
+surface the lane failure to the user as BLOCKED. Under Profile A, blocking and
+direct-Task fallbacks are rejected because they cannot satisfy the durable
+ownership and head-provenance gate.
+Do not proceed with "blocking verification and record that async advisory lanes
+were unavailable" — record-and-continue is not coverage closure.
+
+Under Profile B, partition the same immutable inventory across fresh read-only
+verification subagents — every `FB-###` item owned by exactly one lane and the
+union of lanes covering the entire ledger — with each prompt stating its owned
+IDs and the exact `pr_head_sha`, and each lane returning one
+`[FEEDBACK-VERIFIED]` row per owned item. Under Profile C, verify the ledger
+in sequential category passes with the same one-row-per-item contract. On
+every profile, no item may be classified until its verification lane or pass
+has settled, and unclosable verification gaps are surfaced as BLOCKED.
+
+### CI matrix cascade check (do this before fixing)
+
+When the PR's `unit` job is a matrix across multiple OSes and downstream jobs
+(`integration`, `smoke`) have `needs: unit`, an OS leg failure blocks the
+entire pipeline. Before triaging, check:
+
+1. Are `integration` or `smoke` jobs in `skipped` or `cancelled` state rather
+   than `failed`? That signals a unit matrix cascade — the unit job failed
+   on one OS leg, blocking the downstream jobs from running on the current
+   HEAD.
+2. If a unit OS leg is the blocker, classify the failure:
+   - **Code issue** — the test itself fails. Reproduce locally; if the
+     test passes locally, the runner is the problem.
+   - **Runner performance** — the test step exceeds the configured timeout.
+     Run all files in the step locally with per-file timing; if cumulative
+     local runtime is <10 min and the runner can't complete in 60+ min, the
+     issue is runner performance. Bump the CI timeout as a stopgap and file
+     a follow-up issue for parallelization. Do not loop bumping the timeout
+     past 90 min without filing the follow-up.
+3. Surface cascade failures to the user explicitly. The downstream jobs'
+   results don't exist; the code's coverage of the current HEAD cannot be
+   confirmed by CI alone.
+
+### PR body claim verification
+
+The `.swarm/evidence/` paths below apply only when the reviewed repository uses
+this plugin's council evidence contract. For any other repository, locate the
+authoritative CI attestation, code-host review record, or repository-declared
+evidence store; the universal rule is that an approval claim needs a real,
+retrievable provenance artifact.
+
+PR body text like "PHASE 2 council APPROVED (5/5, round 2)" or "Final council
+APPROVED" must be backed by an evidence file under `.swarm/evidence/` — phase
+councils write `.swarm/evidence/{phaseNumber}/phase-council.json`; the final
+council writes the flat `.swarm/evidence/final-council.json`. Bot-generated PR
+bodies commonly auto-fill these claims without real review. Before accepting
+such a claim as part of triage:
+
+1. Check whether the corresponding evidence file exists with `verdict:APPROVED`.
+2. If the claim is unsupported, mark the closure ledger item as
+   `NEEDS_MORE_EVIDENCE` rather than `CONFIRMED`. Do not silently drop the
+   claim — it indicates the PR body was generated without a real review.

package/.opencode/skills/swarm-pr-feedback/references/preflight-checkout.md

@@ -0,0 +1,67 @@
+# Pre-flight PR branch checkout
+
+## Pre-flight: Check Out the PR Branch Locally
+
+Before verifying any claim or making any fix, ensure the PR branch is the working
+tree:
+
+- If `head_ref` is a remote branch that is not checked out locally, fetch it
+  (`git fetch origin <head_ref>`).
+- **Check for parallel work first.** Before checkout, use the repository or
+  runtime's parallel-work check. When the bundled
+  `parallel-work-check` skill exists, it is one conditional implementation to
+  detect concurrent pushes from other agents (for example the repo's
+  auto-review bot following up, a maintainer pushing fixes, or parallel swarm
+  work). If remote has new commits: read `git log local..remote`, evaluate whether the parallel work
+  supersedes your planned fixes, and prefer the parallel work if it's more
+  comprehensive (more tests, better edge coverage, clearer error handling).
+  Abort your rebase, take the remote state, then add minor improvements on top.
+- Verify the working tree is clean first (`git status --porcelain`). If any
+  tracked or untracked changes exist, call `prepare_pr_workflow_checkout`
+  before binding (Profile A). Omit `paths` to auto-discover and atomically
+  preserve every dirty path, including untracked files; pass explicit `paths`
+  only for an exact bounded tracked-file set. It creates an auditable stash
+  receipt containing the original branch/HEAD and a structured
+  `operation: "restore"` recovery instruction. Do not issue `git stash`
+  through shell.
+  Without the controller, surface dirty state to the user or abort the checkout
+  — do not blind-stash.
+- Treat `recovery-required` and `indeterminate` controller results as terminal
+  for the current attempt: report the typed `required_action`, abort/clear any
+  already-active gate, and stop. Only `stashable` permits one preparation call;
+  retry only when the controller explicitly returns `retryable: true`.
+- **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
+  exact `merge_base...head_ref` range for diff-scoped inspection.
+ - Pass the exact `merge_base...head_ref` commit range in every read-only verification or
+   explorer/advisory-lane delegation so lane agents can inspect specific revisions
+   with `git show` when needed.
+- If no PR reference was provided (a pasted-feedback session on the current branch),
+   confirm the current branch is the intended PR branch before editing.
+- 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.
+- The existing constrained tracked-branch and safe `gh pr checkout` pre-bind
+  forms remain supported on every profile after proving the exact SHA and a
+  unique intended remote ref. Never use force, submodule-recursive, or detached
+  `gh pr checkout` variants.
+- Immediately after the first bind and before feedback verification dispatch,
+  prove that `git rev-parse HEAD` equals the authoritative full `pr_head_sha`,
+  `git status --porcelain` is empty, and the current branch tracks the intended
+  PR head remote/branch. A detached exact-head checkout is intake-only; the
+  bind must attach it before feedback dispatch or publication.
+
+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.)