[{"data":1,"prerenderedAt":-1},["ShallowReactive",2],{"skill:01M732CF6HHMVM2VHC4Q199PQ4":3,"skill-same:01M732CF6HHMVM2VHC4Q199PQ4":47},{"skillNo":4,"name":5,"nameZh":6,"description":7,"descriptionZh":6,"repositoryFullName":8,"ownerLogin":9,"ownerAvatarUrl":10,"ownerAccountNo":11,"ownerDisplayName":12,"repositoryNo":13,"starsCount":14,"licenseSpdxId":15,"licenseFileUrl":6,"sourceHtmlUrl":16,"categories":17,"keywords":18,"publishedAt":19,"linkOnly":20,"markdownContent":21,"markdownBody":22,"frontMatter":23,"refName":24,"commitSha":25,"skillDirectory":26,"forksCount":27,"repositoryHtmlUrl":28,"repositoryHomepageUrl":6,"ownerHtmlUrl":29,"ownerBlogUrl":30,"ownerDescription":31,"updatedAt":32,"install":33,"resources":46},"01M732CF6HHMVM2VHC4Q199PQ4","swarm-pr-feedback",null,"Ingest and resolve known pull request feedback with skeptical source verification. Use when addressing pasted PR feedback, GitHub review comments or threads, requested changes, CI\u002Fcheck failures, merge conflicts, stale PR branches, or PR follow-up work that must close all known issues without dropping findings. Supports multi-round bot reviews (the repository's bot posts a new review after every push) via the iterative pattern documented in the body. 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.","djimit\u002Fdjimitflo","djimit","https:\u002F\u002Favatars.githubusercontent.com\u002Fu\u002F19958832?v=4","01M7327CH792DZPFZPYAEFPRXT","Dutch Dim","01M7327CHWPSXT9AWE4MPWCX9Q",2,"MIT","https:\u002F\u002Fgithub.com\u002Fdjimit\u002Fdjimitflo\u002Fblob\u002Fmain\u002F.opencode\u002Fskills\u002Fswarm-pr-feedback\u002FSKILL.md",[],[],"2026-11-11 15:11:14",false,"---\nname: swarm-pr-feedback\ndescription: >\n  Ingest and resolve known pull request feedback with skeptical source verification.\n  Use when addressing pasted PR feedback, GitHub review comments or threads,\n  requested changes, CI\u002Fcheck failures, merge conflicts, stale PR branches, or\n  PR follow-up work that must close all known issues without dropping findings.\n  Supports multi-round bot reviews (the repository's bot posts a new review\n  after every push) via the iterative pattern documented in the body. Stage A\n  (structural pre-checks) and Stage B (reviewer + test_engineer) gates and the\n  reviewer + critic closeout gate are MANDATORY for any change made as part of\n  this process.\n---\n\n# Swarm PR Feedback\n\nUse this skill to close known PR feedback. This is not a fresh broad PR review.\n`swarm-pr-review` discovers new findings; `swarm-pr-feedback` ingests existing\nfeedback surfaces, verifies each claim, clusters related problems, fixes confirmed\nissues, validates the branch, and reports closure status for every item.\n\n**Mandatory gate contract.** Stage A (structural pre-checks) and Stage B\n(reviewer + test_engineer) gates and the reviewer + critic closeout gate are\nMANDATORY for any change made as part of this process. No fix lands, no closure\nledger row is marked FIXED, and no PR is published until all three gates pass on\nthe current diff. See \"Mandatory Gates\" below for the full protocol.\n\nWhen the work starts from a prior `swarm-pr-review` run, ingest the review's\nhandoff artifact (for example\n`.swarm\u002Fpr-review\u002F\u003Crun_id>\u002Ffeedback-handoff.md` or `.json`) before triage.\nCarry forward the original review finding IDs, classifications, reviewer\u002Fcritic\nprovenance, and any operational blockers instead of renumbering them as new\ndiscoveries.\n\nFeedback closure is not the end of the PR lifecycle: when PR monitoring is\nenabled (`pr_monitor.enabled`), the PR remains subscribed and monitored under\n`..\u002Fswarm-pr-subscribe\u002FSKILL.md` until it is merged or closed. Events that\narrive after closure (a new bot round, a CI change, fresh review activity) are\ntriaged through that skill and route back into this discipline when they need\nfixes.\n\n## Multi-Round Bot Reviews (Iterative Pattern)\n\nThe repository's bot reviewer (`hermes-pr-review` \u002F Qwen3.6 + Gemma-4 dual-model)\nposts a new review comment after **every push** to the PR branch, not just the\nfinal state. Expect N rounds of review for N pushes, and budget for it.\n\n**Round N+1 deltas vs Round N:**\n- Fresh `FB-###` ledger IDs for new findings (do not reuse IDs from earlier rounds)\n- Findings from prior rounds that remain unfixed will reappear with the same evidence\n- Findings you marked DISPROVED with new evidence may reappear if the bot disagrees\n- New findings may be introduced that the prior round did not see (the bot's read scope\n  is the new commit, not the full diff history)\n\n**Operating principles for multi-round triage:**\n\n1. **Continue the ledger, do not start over.** Append to the same `FB-###` counter\n   across rounds. Track each finding's state per round (open, fixed, disproved,\n   awaiting-decision, repeated).\n2. **Carry forward unresolved items.** Findings you marked `PARTIAL` or `NEEDS_USER_DECISION`\n   in round N will still be open in round N+1. The closure ledger should show their\n   evolution (e.g., \"PARTIAL round 1 → CONFIRMED round 2 after evidence collected\").\n3. **Apply the 3-strikes-then-defense-in-depth rule.** When the same finding is\n   raised 3+ times across rounds, prefer to add the suggested code change with a\n   defense-in-depth rationale comment rather than continue to debate. One extra\n   condition is cheap; per-round debate is expensive. Document the parent-vs-inner\n   relationship inline so future readers see the rationale.\n   **When not to apply 3-strikes:** If the suggested fix would add incorrect,\n   misleading, or redundant code — e.g., an outer guard that already exists at an\n   inner scope and whose addition would imply the inner guard is absent, a type\n   narrowing that masks a real error class, or a check whose presence asserts a\n   false invariant — do not add the change. A wrong fix embedded in the code is\n   harder to remove than a repeated rebuttal in a comment thread. Apply item 6's\n   \"surface to user\" path instead, with the cumulative evidence that the fix\n   direction is incorrect.\n4. **Verify bot fix-direction suggestions against actual file structure.** Bots\n   read files linearly and can miss parent-block guards. For any \"add an X check\"\n   suggestion, read the surrounding function\u002Fblock to confirm the check is genuinely\n   missing or already exists at a higher scope.\n5. **Each round produces its own closure ledger as a PR comment.** Prefix with\n   \"Round N\" so the bot and reviewers can see progression. Maintain a running\n   summary table at the end of each comment showing totals across rounds\n   (confirmed+fixed \u002F disproved \u002F partial \u002F awaiting-decision).\n6. **Stop the cycle deliberately.** If a finding is disproved with code evidence 3+\n   times and the bot keeps re-raising it, leave the comment, post the closure\n   ledger with the cumulative evidence, and surface the disagreement to the user\n   rather than continuing to push fixes. The user can resolve persistent\n   reviewer-AI disagreement.\n\n**Why this matters:** Without the multi-round pattern, each round looks like\n\"start over, re-triage everything.\" With it, the rounds become incremental:\neach round's work is bounded by new findings + carried-forward items only.\nThis matches how the bot actually behaves and avoids wasted cycles.\n\n### Bot Review Verification Traps\n\nWhen a bot or pasted review cites a code fact, verify the fact against the\ncurrent branch before editing:\n\n- **Import\u002Fexport claims:** Check the exact import path used by the changed file.\n  A symbol may be missing from an internal submodule but correctly exported by the\n  public barrel the tests or runtime actually import.\n- **Line numbers:** Treat bot line references as approximate after any follow-up\n  push or local edit. Re-locate the symbol or block with `rg` before patching.\n- **Ordering claims:** If the concern is about rule precedence, add or run a\n  direct precedence test that would fail under the wrong ordering; comments alone\n  are not enough.\n- **Disproved findings:** Do not change unrelated code to satisfy a false claim.\n  Keep the finding in the closure ledger with the source or test evidence that\n  disproves it.\n- **Cache\u002Fstate claims:** Test both relevant state orders when the behavior\n  depends on cache priming, singleton state, or prior calls.\n\n### Automated Security Finding Verification\n\nAutomated security bots (e.g., hermes-pr-review, CodeRabbit, Gemini) frequently\nproduce findings rated CRITICAL or HIGH that are false positives. In a recent\nPR review cycle, 7\u002F7 bot security findings were false positives upon source\nverification. Before acting on any bot security finding, perform these\nsource-level checks:\n\n1. **`child_process.exec` vs `RegExp.exec`**: SAST rules pattern-match on\n   `.exec(` and cannot distinguish `child_process.exec(userInput)` (real\n   injection risk) from `\u002F^pattern$\u002F.exec(str)` (safe regex test). Read the\n   actual line to determine which `.exec` is called.\n\n2. **Schema validation already present**: Bots may flag \"missing type\n   validation\" without checking the Zod schema. Search for the field name in\n   `src\u002Fconfig\u002Fschema.ts` — `z.number().int()`, `z.string().min()`, etc. are\n   runtime validators that run before the code path the bot reviewed.\n\n3. **`Object.assign` mutation claims**: Bots may claim `Object.assign` mutates\n   the source object. Check whether the call is `Object.assign(target, source)`\n   (mutates target) vs `Object.assign({}, source)` or a manual copy loop into a\n   new `{}` (creates a new object, source is safe). Read the actual assignment.\n\n4. **Path containment for system-generated paths**: Bots may flag \"path\n   traversal\" on file paths. Check whether the path is user-controlled (real\n   risk) or system-generated from `provisionWorktree`, `mkdtempSync`, or\n   similar (no user input reaches the path). Trace the variable's origin.\n\n5. **Value validation vs key validation**: Bots may suggest validating env var\n   *values* for shell injection characters. Check whether the value is passed\n   through a sandbox executor that escapes arguments (e.g., `wrapCommand`\n   which returns a shell-quoted \u002F `psStringEscape`-escaped string for the\n   `bunSpawn` array-form argv to consume). Value validation would break\n   legitimate env vars (PATH with `;`, URLs with `$`); escaping is the\n   sandbox's job — see `engineering-conventions` § \"Sandbox env overrides\"\n   for the full escape contract.\n\n6. **Deduplication for independent resources**: Bots may suggest deduplicating\n   cache redirects or env var entries. Check whether the entries map to\n   independent keys (different env var names) — independent keys cannot\n   \"collide\" and deduplication is nonsensical.\n\n**Rule:** For any bot finding rated CRITICAL or HIGH, read the actual source\nline AND its surrounding context (parent function, schema definition, type\nannotations) before accepting the finding. If the finding is disproved, record\nit in the closure ledger with the specific source evidence that disproves it.\n\n## Operating Stance\n\nTreat every review comment, CI failure, bot summary, PR body claim, and pasted note\nas a claim until source evidence proves it. Do not silently drop, defer, or mark\nitems out of scope. Ask the user only for product or scope decisions that cannot\nbe proven from the PR, repo, or explicit instructions.\n\nDo not run a fresh broad PR review while addressing existing feedback. Inspect\nadjacent code only as needed to verify reachability, dependencies, shared root\ncauses, regression risk, or sibling changes required by a confirmed item.\n\nGitHub review-thread resolution is user-controlled. Do not resolve or mark review\nthreads resolved unless the user explicitly instructs you to do so.\n\nDo not act on review-discovered findings from a prior `swarm-pr-review` run\nunless the user has explicitly approved the transition into `swarm-pr-feedback`.\nThe handoff artifact is triage input, not standing authorization to change code.\n\n## Pre-flight: Check Out the PR Branch Locally\n\nBefore verifying any claim or making any fix, ensure the PR branch is the working\ntree:\n\n- If `head_ref` is a remote branch that is not checked out locally, fetch it\n  (`git fetch origin \u003Chead_ref>`).\n- **Check for parallel work first.** Before checkout, run the\n  [`parallel-work-check`](..\u002Fgenerated\u002Fparallel-work-check\u002FSKILL.md) protocol to\n  detect concurrent pushes from other agents (e.g., `hermes-pr-review` bot\n  following up, maintainer pushing fixes, parallel swarm work). If remote has new\n  commits: read `git log local..remote`, evaluate whether the parallel work\n  supersedes your planned fixes, and prefer the parallel work if it's more\n  comprehensive (more tests, better edge coverage, clearer error handling).\n  Abort your rebase, take the remote state, then add minor improvements on top.\n- Verify the working tree is clean first (`git status --porcelain`). If uncommitted\n  changes exist, stash them or abort to prevent data loss.\n- **Check out the head branch locally.** Feedback verification reads the working-tree\n  filesystem (`Read`\u002F`Glob`\u002F`Grep`), and fixes must land on the PR branch — without a\n  checkout you would verify and patch the base branch's code instead. Record the\n  `base_ref..head_ref` range for diff-scoped inspection.\n - Pass the `base_ref..head_ref` commit range in every read-only verification or\n   explorer\u002Fadvisory-lane delegation so lane agents can inspect specific revisions\n   with `git show` when needed.\n- If no PR reference was provided (a pasted-feedback session on the current branch),\n   confirm the current branch is the intended PR branch before editing.\n\nWhen a verification lane result includes `output_ref`, treat `output` as a\npreview and call `retrieve_lane_output` before using it to classify, resolve,\ndisprove, or group feedback items. If the result is `output_degraded`,\n`transcript_incomplete`, or truncated without a usable ref, keep the affected\nledger items as `NEEDS_MORE_EVIDENCE` or re-dispatch a narrower read-only lane.\n\n## Pre-flight: Dirty Worktree Handling\n\nBefore staging any files for the PR commit, check the working tree state:\n\n**The problem:** `git add -A` stages every uncommitted change in the working tree,\nincluding pre-existing changes from other branches or prior work. This was hit twice\nin one session during PR #1472 review, producing a 59-file commit instead of the\nintended 2-file targeted fix.\n\n**The check:** Run `git status --porcelain` first. If output is non-empty, identify\nwhich files are PR-related vs pre-existing uncommitted changes.\n\n**The rule:** Stage files explicitly by path when the working tree contains files\nunrelated to the PR. For example:\n\n```bash\ngit add src\u002Ffoo.ts tests\u002Ffoo.test.ts\n```\n\nNever use `git add -A` when the working tree has pre-existing changes from other\nbranches or prior work sessions.\n\n*Reference: Caught during PR #1472 Round 1 closure.*\n\n## Pre-flight: Scope Discipline\n\n`declare_scope({ taskId, files })` enforces that the delegated coder agent may only modify the declared files. The enforcement requires an active `.swarm\u002Fplan.json` — calling `declare_scope` in a feedback-closure run (which does not go through `save_plan`) rejects with \"No plan found.\"\n\n**When to use `declare_scope` (preferred):** any feedback round that touches 2+ files, OR any feedback round where the file scope is not 100% obvious from the prompt. Before delegating, save a minimal plan via `save_plan` with a single phase containing the feedback-closure tasks, then call `declare_scope` per task with the exact file list.\n\n**Carve-out for direct Task delegation:** 1-file, single-function changes where the file path appears verbatim in the coder's prompt may use direct `Task(subagent_type=\"paid_coder\", ...)` delegation without `declare_scope`. This is a narrow exception; the orchestrator is responsible for verifying the scope is unambiguous.\n\n**Anti-pattern:** do not use `Task` delegation for multi-file feedback fixes just to skip `save_plan` — the loss of scope discipline is not worth the saved ceremony.\n\n## Intake Surfaces\n\nBuild a complete feedback ledger before editing. Include every available source:\n\n- validated findings and operational blockers handed off from `swarm-pr-review`,\n- pasted user or reviewer feedback,\n- GitHub review threads, inline review comments, and review summaries,\n- PR issue comments and requested-changes reviews,\n- CI\u002Fcheck failures, check annotations, and relevant logs,\n- mergeability, conflicts, base drift, and stale PR branch state,\n- local validation failures,\n- PR body checkboxes, test-plan claims, linked issues, and acceptance criteria,\n- commit history and bot\u002Fapp commits on the PR branch.\n\nIf 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.\n\n### Async advisory verification lanes\n\nAfter the complete feedback ledger exists and before editing, use\n`dispatch_lanes_async` when available for independent read-only verification lanes:\ncomment classification, CI\u002Flog root-cause inspection, test impact mapping,\nrelease\u002Fdocs claim checks, and stale-branch\u002Fconflict analysis. Partition the\nledger so each `FB-###` item is owned by exactly one verification lane and the\nunion of lanes covers the entire ledger — no feedback item may be left\nunassigned to a lane; state each lane's owned `FB-###` range in its prompt. Scale\nthe lane count to the ledger size: a 1–3 item round may use a single combined\nlane, while a large multi-round intake may warrant one lane per category above.\nCap each `dispatch_lanes_async` batch at 8 lanes (`MAX_LANES`); if the ledger\nneeds more than 8 verification lanes, dispatch in sequential batches and settle\neach batch's COVERAGE GATE before the next — do not over-spawn lanes for a\ntrivial round. Record each returned `batch_id`, then continue only ledger-safe\narchitect work: normalize feedback IDs, gather deterministic PR metadata, prepare\nreproduction commands, and plan likely fix groups. Do not edit, close items, or\nmark feedback resolved from running lanes.\n\nBefore the Verification step can mark any item `RESOLVED`, `DISPROVED`,\n`PRE_EXISTING`, `NEEDS_MORE_EVIDENCE`, or `NEEDS_USER_DECISION`, every open\nverification batch must be fully settled. Poll with `collect_lane_results` (wait\nomitted or `false`) to process settled lanes incrementally — clustering confirmed\nitems and pre-reading files for settled findings while ledger-safe work remains —\nthen issue a final `collect_lane_results` with `wait: true` per batch once\nindependent work is exhausted, to confirm every lane is settled.\nMissing, stale, cancelled, or failed lanes are coverage gaps that must be closed\nbefore marking any item RESOLVED\u002FDISPROVED\u002FPRE_EXISTING. Apply the COVERAGE GATE:\nretry failed lanes (max 2), deploy a verified equivalent alternative (same agent\ntype, same prompt, same scope, same isolation, with Task-tool dispatch as the\nfinal fallback when lane tools do not work), or stop and surface the lane failure\nto the user as BLOCKED.\nDo not proceed with \"blocking verification and record that async advisory lanes\nwere unavailable\" — record-and-continue is not coverage closure.\n\n### CI matrix cascade check (do this before fixing)\n\nWhen the PR's `unit` job is a matrix across multiple OSes and downstream jobs\n(`integration`, `smoke`) have `needs: unit`, an OS leg failure blocks the\nentire pipeline. Before triaging, check:\n\n1. Are `integration` or `smoke` jobs in `skipped` or `cancelled` state rather\n   than `failed`? That signals a unit matrix cascade — the unit job failed\n   on one OS leg, blocking the downstream jobs from running on the current\n   HEAD.\n2. If a unit OS leg is the blocker, classify the failure:\n   - **Code issue** — the test itself fails. Reproduce locally; if the\n     test passes locally, the runner is the problem.\n   - **Runner performance** — the test step exceeds the configured timeout.\n     Run all files in the step locally with per-file timing; if cumulative\n     local runtime is \u003C10 min and the runner can't complete in 60+ min, the\n     issue is runner performance. Bump the CI timeout as a stopgap and file\n     a follow-up issue for parallelization. Do not loop bumping the timeout\n     past 90 min without filing the follow-up.\n3. Surface cascade failures to the user explicitly. The downstream jobs'\n   results don't exist; the code's coverage of the current HEAD cannot be\n   confirmed by CI alone.\n\n### PR body claim verification\n\nPR body text like \"PHASE 2 council APPROVED (5\u002F5, round 2)\" or \"Final council\nAPPROVED\" must be backed by an evidence file in `.swarm\u002Fevidence\u002F`\n(typically `phase-council.json` or `final-council.json`). Bot-generated PR\nbodies commonly auto-fill these claims without real review. Before accepting\nsuch a claim as part of triage:\n\n1. Check whether the corresponding evidence file exists with `verdict:APPROVED`.\n2. If the claim is unsupported, mark the closure ledger item as\n   `NEEDS_MORE_EVIDENCE` rather than `CONFIRMED`. Do not silently drop the\n   claim — it indicates the PR body was generated without a real review.\n\n## Feedback Ledger\n\nNormalize each item before triage:\n\n```text\nFB-001 | source | author\u002Ftool | status: UNTRIAGED | location | claim | raw link\u002Fquote | depends_on\n```\n\nRules:\n\n- Preserve prior `F-###`, `CI-###`, `CONFLICT-###`, `STALE-###`, and similar\n  IDs from a review handoff when they already exist. Only mint fresh `FB-###`\n  IDs for new feedback discovered after the handoff.\n- Preserve reviewer\u002Fcritic provenance from the handoff artifact so the closure\n  ledger can show which items were review-validated before fix work began.\n- Preserve exact reviewer wording or log summary when practical.\n- Split compound comments into separate ledger items only when they require\n  different evidence or fixes.\n- Keep duplicate symptoms linked to one root cause rather than deleting them.\n- Include conflicts, stale branch state, obsolete older-head CI,\n  generated-output (`dist\u002F`) drift, and other CI failures as first-class ledger\n  items.\n- Use explicit IDs for non-review feedback when useful, for example\n  `CONFLICT-001` for merge\u002Fbase drift and `CI-001` for check failures, so PR\n  bodies can show exactly how operational blockers were closed.\n\n### Mandatory: integrate all PR comments with feedback or findings before validation\n\n**Before the Verification step begins, every PR comment that contains feedback\nor findings MUST be integrated into the total feedback ledger as a\n`FB-###` item.** This is a hard requirement, not a best-effort step.\n\nWhat counts as \"feedback or findings\":\n- A reviewer request for a code change (\"please rename this\", \"add a test for\n  X\", \"this should call `_internals.foo`\")\n- A reviewer claim about correctness, security, or style (\"this is\n  incorrect\", \"X will leak\")\n- A bot reviewer's findings table entries\n- A CI failure with a specific file:line root cause\n- A reviewer question that implies a code change is needed (\"why is this\n  static?\")\n- PR review summaries or aggregate comments\n\nWhat does NOT count (and is therefore not required to be a ledger item):\n- Pure acknowledgements (\"LGTM\", \"looks good\")\n- PR-level metadata changes (title, label, milestone)\n- Force-push acknowledgements\n\nRules:\n- **No finding may be addressed outside the ledger.** If you fix something a\n  reviewer mentioned, the corresponding `FB-###` item MUST be in the ledger\n  before the fix. If you skip the fix, the `FB-###` item MUST be in the\n  ledger with a `DISPROVED`, `PRE_EXISTING`, `NEEDS_MORE_EVIDENCE`, or\n  `NEEDS_USER_DECISION` status before validation can begin.\n- **Status semantics for unaddressed items:**\n  - `CONFIRMED` and `PARTIAL` items must be addressed (fixed or\n    disproved) before validation can begin. A `CONFIRMED` item that is\n    left unaddressed is a regression against the review.\n  - `DISPROVED`, `PRE_EXISTING`, `NEEDS_MORE_EVIDENCE`, and\n    `NEEDS_USER_DECISION` items may remain open at validation time, but\n    each must be explicitly justified in the closure ledger.\n- **The closure ledger at the end of the run must account for every `FB-###`\n  item** with a final status (fixed \u002F disproved \u002F pre-existing \u002F needs user\n  decision \u002F needs more evidence).\n- **Comments from the latest bot round take precedence over earlier rounds**\n  for the same finding; the earlier-round `FB-###` item is updated with the\n  new evidence rather than a new item being created.\n- **Multi-round pattern continues to apply** (see \"Multi-Round Bot Reviews\"\n  section). A new bot round adds new `FB-###` items for findings that\n  weren't in the prior round; the prior round's items are carried forward\n  and updated with the new evidence.\n\nRationale: silently addressing a review comment without a corresponding\nledger item means the closure summary at the end of the run cannot\ndemonstrate that every review comment was considered. The closure summary\nis the only artifact the user\u002Fmaintainer reads to confirm the PR is ready\nto merge. Missing items in the ledger = missing items in the closure = a\nPR that ships with unreviewed feedback.\n\n## Verification\n\nClassify every ledger item before fixing:\n\n| Status | Meaning |\n|---|---|\n| `CONFIRMED` | The issue is real, reachable or structurally proven, and introduced or exposed by the PR. |\n| `PARTIAL` | The comment points at a real concern, but the framing, severity, or requested fix is incomplete. |\n| `DISPROVED` | Source, tests, or execution context prove the claim is false, unreachable, or already mitigated. |\n| `PRE_EXISTING` | The issue exists on the base branch and is not materially worsened by the PR. |\n| `NEEDS_MORE_EVIDENCE` | The claim (e.g., \"council APPROVED\") is unsupported by stored evidence (e.g., a missing or failed `.swarm\u002Fevidence\u002F` artifact); more information is required before triage. |\n| `NEEDS_USER_DECISION` | The item requires a product, UX, compatibility, or scope choice that cannot be inferred. |\n\nVerification checklist:\n\n- Read the referenced file and surrounding code.\n- Check caller context, reachability, feature flags, schema validation, guards,\n  state-machine rules, and permission boundaries.\n- Determine whether the issue is PR-introduced, pre-existing, or unresolved.\n- Check related tests and whether a failing\u002Fproposed test would prove the item.\n- Check whether multiple feedback items share one root cause.\n\n### DI seam migration validation\n\nWhen a test file mutates a DI seam object (e.g., `_internals.foo = mock`),\nverify that the production source reads from the seam at call time. A common\nanti-pattern: the test mutates the seam object, but the production code\nimports the named function (`import { foo } from '.\u002Fmodule'`) which is bound\nat module load. The seam mutation has no effect on the named reference,\nso the test fails even though the seam object's `foo === mock`.\n\nVerification: open the source file and grep for call sites. If you see\n`import { foo } from '...'` followed by `foo(...)` in the production code,\nand the test does `_internals.foo = mock`, the test will fail. The fix is\nto change the production code to call `_internals.foo(...)` (or equivalent\nactive-seam pattern) so the seam mutation is read at call time.\n\nIf only a few call sites exist, fix them in the source. If many call sites\nexist, consider whether the migration should use `mock.module()` instead,\nwhich replaces the entire module object (including the named export\nreference).\n\n## Fix Planning\n\nCluster ledger items by root cause before coding. Fix in this order unless a user\ninstruction or dependency requires otherwise:\n\n1. Merge conflicts, stale branch state, and base drift.\n2. Deterministic CI, build, typecheck, formatting, and test failures.\n3. Confirmed correctness, security, data-loss, persistence, git\u002Fwrite-safety, and\n   permission issues.\n4. Test gaps needed to prove confirmed fixes.\n5. Docs, release notes, PR body, and migration guidance.\n6. Reviewer communication and closure summaries.\n\nFor each cluster, record:\n\n```text\nROOT-001 | ledger items: FB-001, FB-004 | files | fix approach | tests | docs | risk\n```\n\nDo not make scope decisions yourself. If the right fix depends on product intent\nor compatibility policy, mark the item `NEEDS_USER_DECISION` and ask.\n\n## Implementation Rules\n\n- Patch only confirmed or partial items, plus required tests\u002Fdocs.\n- Do not implement speculative cleanup while feedback remains unclosed.\n- Never ship unwired code. Any new command, tool, skill, config, docs surface, or\n  generated artifact must be fully registered and validated.\n- Never defer work or declare it out of scope without explicit user instruction.\n- Keep invalid or disproved findings in the closure ledger with the evidence.\n- For CI failures, verify the failing job belongs to the current PR head before\n  treating it as current evidence.\n- For generated output or dist failures, inspect the failing log before rebuilding\n  and commit regenerated files only when the PR touches the source surface.\n- When `main` has a merge queue enabled, do not rebase or force-push a PR only\n  because `main` advanced. Once required checks and review are green, queue the PR\n  and let the merge queue perform final current-base validation. Still resolve real\n  merge conflicts and SHA-dependent review threads before queuing.\n\n## Mandatory Gates\n\n**Stage A and Stage B gates and the reviewer + critic closeout gate are\nMANDATORY for any change made as part of the PR-feedback process.** No fix\nlands, no closure ledger row is marked FIXED, and no PR is published until all\nthree gates pass on the current diff. This section uses the repository's\nestablished Stage A\u002FB meaning: Stage A = `pre_check_batch`-equivalent structural\npre-checks; Stage B = `reviewer` + `test_engineer` per-task gates (consistent\nwith `execute`, `plan`, `specify`, `brainstorm`, `docs\u002Fswarm-briefing.md`, and\n`docs\u002Fcouncil\u002FREADME.md`).\n\nIf a gate failure is suspected pre-existing, prove it on the base branch or\nlabel it `UNVERIFIED`. Do not call the branch green while required checks are\nnon-green.\n\n### Stage A — structural pre-checks (mandatory before Stage B)\n\nRun for every changed surface. No \"where relevant\" — every PR-feedback change\nruns these; if a surface is genuinely untouched, state that explicitly rather\nthan skipping silently.\n\n- `bun run build` (or the repository's build command) — must succeed.\n- typecheck — must pass.\n- lint\u002Fformat (e.g. `biome ci .`) — must pass.\n- `git diff --check` — no whitespace or merge-marker errors.\n- exact failing CI\u002Ftest command reproduced locally when a ledger item is rooted\n  in a CI\u002Ftest failure — the reproduction must fail on the pre-fix tree and pass\n  after the fix.\n\n### Stage B — reviewer + test_engineer (mandatory after Stage A passes)\n\nTwo independent agents on the Stage-A-green diff:\n\n- **reviewer** — independent (fresh context, not the implementer, not a continued\n  conversation). Validates each fix on the current diff against the feedback\n  item it closes. Verdict per item: APPROVE \u002F NEEDS_REVISION \u002F BLOCKED.\n- **test_engineer** — writes and runs the falsification probe or regression test\n  that proves each fix actually resolves its item (tests for changed behavior or\n  newly covered gaps). Verdict per item: PASS \u002F FAIL \u002F BLOCKED.\n\nAddress every NEEDS_REVISION \u002F BLOCKED \u002F FAIL, then re-run the affected agent on\nthe current diff.\n\n### Closeout gate — reviewer + critic (mandatory after Stage B)\n\nA *separate* reviewer + critic pair on the Stage-B-approved diff. This is the\nswarm closeout contract (see `..\u002Fswarm\u002FSKILL.md` \"Mandatory implementation\ncloseout gate\"); because this skill edits code, docs, release notes, or skill files it applies in full — Stage B\nalone does not satisfy it.\n\n- **independent reviewer** (fresh context, separate from the Stage B reviewer)\n  → APPROVE \u002F NEEDS_REVISION \u002F BLOCKED per item.\n- **final critic** (separate fresh context, not a continued conversation with\n  the reviewer, dispatched after the reviewer returns APPROVE) → APPROVE \u002F\n  NEEDS_REVISION \u002F BLOCKED per item. The critic challenges: is every original\n  feedback item actually resolved? Any requirement drift, weak evidence, missing\n  sibling-file checks, stale approvals, anything unwired or silently deferred?\n\nAddress every NEEDS_REVISION \u002F BLOCKED item, re-review with the reviewer if the\ncritic surfaces correctness issues, then re-critic. **Any edit after the\nreviewer's or critic's approval invalidates that approval** — re-run the\naffected gate on the current diff before publishing.\n\nRecord both closeout verdicts (reviewer + critic, with HEAD\u002Fdiff) in\n`.claude\u002Fsession\u002Ftasks\u002F\u003Cslug>\u002Fgates.md` per the `durable-session-state` skill\n(`.swarm\u002F` is the plugin's runtime state — never write task artifacts there).\n\n### Post-publish verification (mandatory after the PR is pushed)\n\nThese checks run after the fix lands on the remote — they are NOT Stage A\npre-checks and must not be folded into Stage A.\n\n- PR metadata checks after push: head SHA, check status,\n  mergeability\u002Fconflicts, and unresolved feedback state.\n- After conflict fixes, verify remote mergeability is clean (`MERGEABLE` \u002F\n  `CLEAN`), not only that local conflict markers disappeared.\n- For current-head CI, prefer run-level details when PR checks look stale:\n  `gh run view \u003Crun-id> --json headSha,status,conclusion,jobs,url`.\n\n## Publishing And Communication\n\nAfter fixes, update the PR body or comment with a closure ledger:\n\n```text\nFB-001 | fixed | commit\u002Ftest evidence\nFB-002 | disproved | code evidence\nFB-003 | pre-existing | base-branch evidence\nFB-004 | needs user decision | decision required\nFB-005 | needs more evidence | .swarm\u002Fevidence\u002Fphase-council.json missing\nCONFLICT-001 | fixed | remote mergeability is MERGEABLE\u002FCLEAN\nCI-001 | fixed | current-head check\u002Frun evidence\n```\n\nDo not resolve GitHub review threads unless explicitly instructed. If instructed,\nresolve only threads whose ledger item is fixed or disproved on the pushed PR\nhead, and record the exact evidence used.\n\n## Final Output\n\nReport:\n\n- intake sources checked and unavailable sources,\n- ledger counts by status,\n- root-cause clusters fixed,\n- tests and commands run,\n- unresolved user decisions,\n- CI\u002Fmergeability state,\n- whether review-thread resolution was skipped or explicitly performed.\n\nEnd with a complete ledger mapping every original item to its outcome.\n","# Swarm PR Feedback\n\nUse this skill to close known PR feedback. This is not a fresh broad PR review.\n`swarm-pr-review` discovers new findings; `swarm-pr-feedback` ingests existing\nfeedback surfaces, verifies each claim, clusters related problems, fixes confirmed\nissues, validates the branch, and reports closure status for every item.\n\n**Mandatory gate contract.** Stage A (structural pre-checks) and Stage B\n(reviewer + test_engineer) gates and the reviewer + critic closeout gate are\nMANDATORY for any change made as part of this process. No fix lands, no closure\nledger row is marked FIXED, and no PR is published until all three gates pass on\nthe current diff. See \"Mandatory Gates\" below for the full protocol.\n\nWhen the work starts from a prior `swarm-pr-review` run, ingest the review's\nhandoff artifact (for example\n`.swarm\u002Fpr-review\u002F\u003Crun_id>\u002Ffeedback-handoff.md` or `.json`) before triage.\nCarry forward the original review finding IDs, classifications, reviewer\u002Fcritic\nprovenance, and any operational blockers instead of renumbering them as new\ndiscoveries.\n\nFeedback closure is not the end of the PR lifecycle: when PR monitoring is\nenabled (`pr_monitor.enabled`), the PR remains subscribed and monitored under\n`..\u002Fswarm-pr-subscribe\u002FSKILL.md` until it is merged or closed. Events that\narrive after closure (a new bot round, a CI change, fresh review activity) are\ntriaged through that skill and route back into this discipline when they need\nfixes.\n\n## Multi-Round Bot Reviews (Iterative Pattern)\n\nThe repository's bot reviewer (`hermes-pr-review` \u002F Qwen3.6 + Gemma-4 dual-model)\nposts a new review comment after **every push** to the PR branch, not just the\nfinal state. Expect N rounds of review for N pushes, and budget for it.\n\n**Round N+1 deltas vs Round N:**\n- Fresh `FB-###` ledger IDs for new findings (do not reuse IDs from earlier rounds)\n- Findings from prior rounds that remain unfixed will reappear with the same evidence\n- Findings you marked DISPROVED with new evidence may reappear if the bot disagrees\n- New findings may be introduced that the prior round did not see (the bot's read scope\n  is the new commit, not the full diff history)\n\n**Operating principles for multi-round triage:**\n\n1. **Continue the ledger, do not start over.** Append to the same `FB-###` counter\n   across rounds. Track each finding's state per round (open, fixed, disproved,\n   awaiting-decision, repeated).\n2. **Carry forward unresolved items.** Findings you marked `PARTIAL` or `NEEDS_USER_DECISION`\n   in round N will still be open in round N+1. The closure ledger should show their\n   evolution (e.g., \"PARTIAL round 1 → CONFIRMED round 2 after evidence collected\").\n3. **Apply the 3-strikes-then-defense-in-depth rule.** When the same finding is\n   raised 3+ times across rounds, prefer to add the suggested code change with a\n   defense-in-depth rationale comment rather than continue to debate. One extra\n   condition is cheap; per-round debate is expensive. Document the parent-vs-inner\n   relationship inline so future readers see the rationale.\n   **When not to apply 3-strikes:** If the suggested fix would add incorrect,\n   misleading, or redundant code — e.g., an outer guard that already exists at an\n   inner scope and whose addition would imply the inner guard is absent, a type\n   narrowing that masks a real error class, or a check whose presence asserts a\n   false invariant — do not add the change. A wrong fix embedded in the code is\n   harder to remove than a repeated rebuttal in a comment thread. Apply item 6's\n   \"surface to user\" path instead, with the cumulative evidence that the fix\n   direction is incorrect.\n4. **Verify bot fix-direction suggestions against actual file structure.** Bots\n   read files linearly and can miss parent-block guards. For any \"add an X check\"\n   suggestion, read the surrounding function\u002Fblock to confirm the check is genuinely\n   missing or already exists at a higher scope.\n5. **Each round produces its own closure ledger as a PR comment.** Prefix with\n   \"Round N\" so the bot and reviewers can see progression. Maintain a running\n   summary table at the end of each comment showing totals across rounds\n   (confirmed+fixed \u002F disproved \u002F partial \u002F awaiting-decision).\n6. **Stop the cycle deliberately.** If a finding is disproved with code evidence 3+\n   times and the bot keeps re-raising it, leave the comment, post the closure\n   ledger with the cumulative evidence, and surface the disagreement to the user\n   rather than continuing to push fixes. The user can resolve persistent\n   reviewer-AI disagreement.\n\n**Why this matters:** Without the multi-round pattern, each round looks like\n\"start over, re-triage everything.\" With it, the rounds become incremental:\neach round's work is bounded by new findings + carried-forward items only.\nThis matches how the bot actually behaves and avoids wasted cycles.\n\n### Bot Review Verification Traps\n\nWhen a bot or pasted review cites a code fact, verify the fact against the\ncurrent branch before editing:\n\n- **Import\u002Fexport claims:** Check the exact import path used by the changed file.\n  A symbol may be missing from an internal submodule but correctly exported by the\n  public barrel the tests or runtime actually import.\n- **Line numbers:** Treat bot line references as approximate after any follow-up\n  push or local edit. Re-locate the symbol or block with `rg` before patching.\n- **Ordering claims:** If the concern is about rule precedence, add or run a\n  direct precedence test that would fail under the wrong ordering; comments alone\n  are not enough.\n- **Disproved findings:** Do not change unrelated code to satisfy a false claim.\n  Keep the finding in the closure ledger with the source or test evidence that\n  disproves it.\n- **Cache\u002Fstate claims:** Test both relevant state orders when the behavior\n  depends on cache priming, singleton state, or prior calls.\n\n### Automated Security Finding Verification\n\nAutomated security bots (e.g., hermes-pr-review, CodeRabbit, Gemini) frequently\nproduce findings rated CRITICAL or HIGH that are false positives. In a recent\nPR review cycle, 7\u002F7 bot security findings were false positives upon source\nverification. Before acting on any bot security finding, perform these\nsource-level checks:\n\n1. **`child_process.exec` vs `RegExp.exec`**: SAST rules pattern-match on\n   `.exec(` and cannot distinguish `child_process.exec(userInput)` (real\n   injection risk) from `\u002F^pattern$\u002F.exec(str)` (safe regex test). Read the\n   actual line to determine which `.exec` is called.\n\n2. **Schema validation already present**: Bots may flag \"missing type\n   validation\" without checking the Zod schema. Search for the field name in\n   `src\u002Fconfig\u002Fschema.ts` — `z.number().int()`, `z.string().min()`, etc. are\n   runtime validators that run before the code path the bot reviewed.\n\n3. **`Object.assign` mutation claims**: Bots may claim `Object.assign` mutates\n   the source object. Check whether the call is `Object.assign(target, source)`\n   (mutates target) vs `Object.assign({}, source)` or a manual copy loop into a\n   new `{}` (creates a new object, source is safe). Read the actual assignment.\n\n4. **Path containment for system-generated paths**: Bots may flag \"path\n   traversal\" on file paths. Check whether the path is user-controlled (real\n   risk) or system-generated from `provisionWorktree`, `mkdtempSync`, or\n   similar (no user input reaches the path). Trace the variable's origin.\n\n5. **Value validation vs key validation**: Bots may suggest validating env var\n   *values* for shell injection characters. Check whether the value is passed\n   through a sandbox executor that escapes arguments (e.g., `wrapCommand`\n   which returns a shell-quoted \u002F `psStringEscape`-escaped string for the\n   `bunSpawn` array-form argv to consume). Value validation would break\n   legitimate env vars (PATH with `;`, URLs with `$`); escaping is the\n   sandbox's job — see `engineering-conventions` § \"Sandbox env overrides\"\n   for the full escape contract.\n\n6. **Deduplication for independent resources**: Bots may suggest deduplicating\n   cache redirects or env var entries. Check whether the entries map to\n   independent keys (different env var names) — independent keys cannot\n   \"collide\" and deduplication is nonsensical.\n\n**Rule:** For any bot finding rated CRITICAL or HIGH, read the actual source\nline AND its surrounding context (parent function, schema definition, type\nannotations) before accepting the finding. If the finding is disproved, record\nit in the closure ledger with the specific source evidence that disproves it.\n\n## Operating Stance\n\nTreat every review comment, CI failure, bot summary, PR body claim, and pasted note\nas a claim until source evidence proves it. Do not silently drop, defer, or mark\nitems out of scope. Ask the user only for product or scope decisions that cannot\nbe proven from the PR, repo, or explicit instructions.\n\nDo not run a fresh broad PR review while addressing existing feedback. Inspect\nadjacent code only as needed to verify reachability, dependencies, shared root\ncauses, regression risk, or sibling changes required by a confirmed item.\n\nGitHub review-thread resolution is user-controlled. Do not resolve or mark review\nthreads resolved unless the user explicitly instructs you to do so.\n\nDo not act on review-discovered findings from a prior `swarm-pr-review` run\nunless the user has explicitly approved the transition into `swarm-pr-feedback`.\nThe handoff artifact is triage input, not standing authorization to change code.\n\n## Pre-flight: Check Out the PR Branch Locally\n\nBefore verifying any claim or making any fix, ensure the PR branch is the working\ntree:\n\n- If `head_ref` is a remote branch that is not checked out locally, fetch it\n  (`git fetch origin \u003Chead_ref>`).\n- **Check for parallel work first.** Before checkout, run the\n  [`parallel-work-check`](..\u002Fgenerated\u002Fparallel-work-check\u002FSKILL.md) protocol to\n  detect concurrent pushes from other agents (e.g., `hermes-pr-review` bot\n  following up, maintainer pushing fixes, parallel swarm work). If remote has new\n  commits: read `git log local..remote`, evaluate whether the parallel work\n  supersedes your planned fixes, and prefer the parallel work if it's more\n  comprehensive (more tests, better edge coverage, clearer error handling).\n  Abort your rebase, take the remote state, then add minor improvements on top.\n- Verify the working tree is clean first (`git status --porcelain`). If uncommitted\n  changes exist, stash them or abort to prevent data loss.\n- **Check out the head branch locally.** Feedback verification reads the working-tree\n  filesystem (`Read`\u002F`Glob`\u002F`Grep`), and fixes must land on the PR branch — without a\n  checkout you would verify and patch the base branch's code instead. Record the\n  `base_ref..head_ref` range for diff-scoped inspection.\n - Pass the `base_ref..head_ref` commit range in every read-only verification or\n   explorer\u002Fadvisory-lane delegation so lane agents can inspect specific revisions\n   with `git show` when needed.\n- If no PR reference was provided (a pasted-feedback session on the current branch),\n   confirm the current branch is the intended PR branch before editing.\n\nWhen a verification lane result includes `output_ref`, treat `output` as a\npreview and call `retrieve_lane_output` before using it to classify, resolve,\ndisprove, or group feedback items. If the result is `output_degraded`,\n`transcript_incomplete`, or truncated without a usable ref, keep the affected\nledger items as `NEEDS_MORE_EVIDENCE` or re-dispatch a narrower read-only lane.\n\n## Pre-flight: Dirty Worktree Handling\n\nBefore staging any files for the PR commit, check the working tree state:\n\n**The problem:** `git add -A` stages every uncommitted change in the working tree,\nincluding pre-existing changes from other branches or prior work. This was hit twice\nin one session during PR #1472 review, producing a 59-file commit instead of the\nintended 2-file targeted fix.\n\n**The check:** Run `git status --porcelain` first. If output is non-empty, identify\nwhich files are PR-related vs pre-existing uncommitted changes.\n\n**The rule:** Stage files explicitly by path when the working tree contains files\nunrelated to the PR. For example:\n\n```bash\ngit add src\u002Ffoo.ts tests\u002Ffoo.test.ts\n```\n\nNever use `git add -A` when the working tree has pre-existing changes from other\nbranches or prior work sessions.\n\n*Reference: Caught during PR #1472 Round 1 closure.*\n\n## Pre-flight: Scope Discipline\n\n`declare_scope({ taskId, files })` enforces that the delegated coder agent may only modify the declared files. The enforcement requires an active `.swarm\u002Fplan.json` — calling `declare_scope` in a feedback-closure run (which does not go through `save_plan`) rejects with \"No plan found.\"\n\n**When to use `declare_scope` (preferred):** any feedback round that touches 2+ files, OR any feedback round where the file scope is not 100% obvious from the prompt. Before delegating, save a minimal plan via `save_plan` with a single phase containing the feedback-closure tasks, then call `declare_scope` per task with the exact file list.\n\n**Carve-out for direct Task delegation:** 1-file, single-function changes where the file path appears verbatim in the coder's prompt may use direct `Task(subagent_type=\"paid_coder\", ...)` delegation without `declare_scope`. This is a narrow exception; the orchestrator is responsible for verifying the scope is unambiguous.\n\n**Anti-pattern:** do not use `Task` delegation for multi-file feedback fixes just to skip `save_plan` — the loss of scope discipline is not worth the saved ceremony.\n\n## Intake Surfaces\n\nBuild a complete feedback ledger before editing. Include every available source:\n\n- validated findings and operational blockers handed off from `swarm-pr-review`,\n- pasted user or reviewer feedback,\n- GitHub review threads, inline review comments, and review summaries,\n- PR issue comments and requested-changes reviews,\n- CI\u002Fcheck failures, check annotations, and relevant logs,\n- mergeability, conflicts, base drift, and stale PR branch state,\n- local validation failures,\n- PR body checkboxes, test-plan claims, linked issues, and acceptance criteria,\n- commit history and bot\u002Fapp commits on the PR branch.\n\nIf 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.\n\n### Async advisory verification lanes\n\nAfter the complete feedback ledger exists and before editing, use\n`dispatch_lanes_async` when available for independent read-only verification lanes:\ncomment classification, CI\u002Flog root-cause inspection, test impact mapping,\nrelease\u002Fdocs claim checks, and stale-branch\u002Fconflict analysis. Partition the\nledger so each `FB-###` item is owned by exactly one verification lane and the\nunion of lanes covers the entire ledger — no feedback item may be left\nunassigned to a lane; state each lane's owned `FB-###` range in its prompt. Scale\nthe lane count to the ledger size: a 1–3 item round may use a single combined\nlane, while a large multi-round intake may warrant one lane per category above.\nCap each `dispatch_lanes_async` batch at 8 lanes (`MAX_LANES`); if the ledger\nneeds more than 8 verification lanes, dispatch in sequential batches and settle\neach batch's COVERAGE GATE before the next — do not over-spawn lanes for a\ntrivial round. Record each returned `batch_id`, then continue only ledger-safe\narchitect work: normalize feedback IDs, gather deterministic PR metadata, prepare\nreproduction commands, and plan likely fix groups. Do not edit, close items, or\nmark feedback resolved from running lanes.\n\nBefore the Verification step can mark any item `RESOLVED`, `DISPROVED`,\n`PRE_EXISTING`, `NEEDS_MORE_EVIDENCE`, or `NEEDS_USER_DECISION`, every open\nverification batch must be fully settled. Poll with `collect_lane_results` (wait\nomitted or `false`) to process settled lanes incrementally — clustering confirmed\nitems and pre-reading files for settled findings while ledger-safe work remains —\nthen issue a final `collect_lane_results` with `wait: true` per batch once\nindependent work is exhausted, to confirm every lane is settled.\nMissing, stale, cancelled, or failed lanes are coverage gaps that must be closed\nbefore marking any item RESOLVED\u002FDISPROVED\u002FPRE_EXISTING. Apply the COVERAGE GATE:\nretry failed lanes (max 2), deploy a verified equivalent alternative (same agent\ntype, same prompt, same scope, same isolation, with Task-tool dispatch as the\nfinal fallback when lane tools do not work), or stop and surface the lane failure\nto the user as BLOCKED.\nDo not proceed with \"blocking verification and record that async advisory lanes\nwere unavailable\" — record-and-continue is not coverage closure.\n\n### CI matrix cascade check (do this before fixing)\n\nWhen the PR's `unit` job is a matrix across multiple OSes and downstream jobs\n(`integration`, `smoke`) have `needs: unit`, an OS leg failure blocks the\nentire pipeline. Before triaging, check:\n\n1. Are `integration` or `smoke` jobs in `skipped` or `cancelled` state rather\n   than `failed`? That signals a unit matrix cascade — the unit job failed\n   on one OS leg, blocking the downstream jobs from running on the current\n   HEAD.\n2. If a unit OS leg is the blocker, classify the failure:\n   - **Code issue** — the test itself fails. Reproduce locally; if the\n     test passes locally, the runner is the problem.\n   - **Runner performance** — the test step exceeds the configured timeout.\n     Run all files in the step locally with per-file timing; if cumulative\n     local runtime is \u003C10 min and the runner can't complete in 60+ min, the\n     issue is runner performance. Bump the CI timeout as a stopgap and file\n     a follow-up issue for parallelization. Do not loop bumping the timeout\n     past 90 min without filing the follow-up.\n3. Surface cascade failures to the user explicitly. The downstream jobs'\n   results don't exist; the code's coverage of the current HEAD cannot be\n   confirmed by CI alone.\n\n### PR body claim verification\n\nPR body text like \"PHASE 2 council APPROVED (5\u002F5, round 2)\" or \"Final council\nAPPROVED\" must be backed by an evidence file in `.swarm\u002Fevidence\u002F`\n(typically `phase-council.json` or `final-council.json`). Bot-generated PR\nbodies commonly auto-fill these claims without real review. Before accepting\nsuch a claim as part of triage:\n\n1. Check whether the corresponding evidence file exists with `verdict:APPROVED`.\n2. If the claim is unsupported, mark the closure ledger item as\n   `NEEDS_MORE_EVIDENCE` rather than `CONFIRMED`. Do not silently drop the\n   claim — it indicates the PR body was generated without a real review.\n\n## Feedback Ledger\n\nNormalize each item before triage:\n\n```text\nFB-001 | source | author\u002Ftool | status: UNTRIAGED | location | claim | raw link\u002Fquote | depends_on\n```\n\nRules:\n\n- Preserve prior `F-###`, `CI-###`, `CONFLICT-###`, `STALE-###`, and similar\n  IDs from a review handoff when they already exist. Only mint fresh `FB-###`\n  IDs for new feedback discovered after the handoff.\n- Preserve reviewer\u002Fcritic provenance from the handoff artifact so the closure\n  ledger can show which items were review-validated before fix work began.\n- Preserve exact reviewer wording or log summary when practical.\n- Split compound comments into separate ledger items only when they require\n  different evidence or fixes.\n- Keep duplicate symptoms linked to one root cause rather than deleting them.\n- Include conflicts, stale branch state, obsolete older-head CI,\n  generated-output (`dist\u002F`) drift, and other CI failures as first-class ledger\n  items.\n- Use explicit IDs for non-review feedback when useful, for example\n  `CONFLICT-001` for merge\u002Fbase drift and `CI-001` for check failures, so PR\n  bodies can show exactly how operational blockers were closed.\n\n### Mandatory: integrate all PR comments with feedback or findings before validation\n\n**Before the Verification step begins, every PR comment that contains feedback\nor findings MUST be integrated into the total feedback ledger as a\n`FB-###` item.** This is a hard requirement, not a best-effort step.\n\nWhat counts as \"feedback or findings\":\n- A reviewer request for a code change (\"please rename this\", \"add a test for\n  X\", \"this should call `_internals.foo`\")\n- A reviewer claim about correctness, security, or style (\"this is\n  incorrect\", \"X will leak\")\n- A bot reviewer's findings table entries\n- A CI failure with a specific file:line root cause\n- A reviewer question that implies a code change is needed (\"why is this\n  static?\")\n- PR review summaries or aggregate comments\n\nWhat does NOT count (and is therefore not required to be a ledger item):\n- Pure acknowledgements (\"LGTM\", \"looks good\")\n- PR-level metadata changes (title, label, milestone)\n- Force-push acknowledgements\n\nRules:\n- **No finding may be addressed outside the ledger.** If you fix something a\n  reviewer mentioned, the corresponding `FB-###` item MUST be in the ledger\n  before the fix. If you skip the fix, the `FB-###` item MUST be in the\n  ledger with a `DISPROVED`, `PRE_EXISTING`, `NEEDS_MORE_EVIDENCE`, or\n  `NEEDS_USER_DECISION` status before validation can begin.\n- **Status semantics for unaddressed items:**\n  - `CONFIRMED` and `PARTIAL` items must be addressed (fixed or\n    disproved) before validation can begin. A `CONFIRMED` item that is\n    left unaddressed is a regression against the review.\n  - `DISPROVED`, `PRE_EXISTING`, `NEEDS_MORE_EVIDENCE`, and\n    `NEEDS_USER_DECISION` items may remain open at validation time, but\n    each must be explicitly justified in the closure ledger.\n- **The closure ledger at the end of the run must account for every `FB-###`\n  item** with a final status (fixed \u002F disproved \u002F pre-existing \u002F needs user\n  decision \u002F needs more evidence).\n- **Comments from the latest bot round take precedence over earlier rounds**\n  for the same finding; the earlier-round `FB-###` item is updated with the\n  new evidence rather than a new item being created.\n- **Multi-round pattern continues to apply** (see \"Multi-Round Bot Reviews\"\n  section). A new bot round adds new `FB-###` items for findings that\n  weren't in the prior round; the prior round's items are carried forward\n  and updated with the new evidence.\n\nRationale: silently addressing a review comment without a corresponding\nledger item means the closure summary at the end of the run cannot\ndemonstrate that every review comment was considered. The closure summary\nis the only artifact the user\u002Fmaintainer reads to confirm the PR is ready\nto merge. Missing items in the ledger = missing items in the closure = a\nPR that ships with unreviewed feedback.\n\n## Verification\n\nClassify every ledger item before fixing:\n\n| Status | Meaning |\n|---|---|\n| `CONFIRMED` | The issue is real, reachable or structurally proven, and introduced or exposed by the PR. |\n| `PARTIAL` | The comment points at a real concern, but the framing, severity, or requested fix is incomplete. |\n| `DISPROVED` | Source, tests, or execution context prove the claim is false, unreachable, or already mitigated. |\n| `PRE_EXISTING` | The issue exists on the base branch and is not materially worsened by the PR. |\n| `NEEDS_MORE_EVIDENCE` | The claim (e.g., \"council APPROVED\") is unsupported by stored evidence (e.g., a missing or failed `.swarm\u002Fevidence\u002F` artifact); more information is required before triage. |\n| `NEEDS_USER_DECISION` | The item requires a product, UX, compatibility, or scope choice that cannot be inferred. |\n\nVerification checklist:\n\n- Read the referenced file and surrounding code.\n- Check caller context, reachability, feature flags, schema validation, guards,\n  state-machine rules, and permission boundaries.\n- Determine whether the issue is PR-introduced, pre-existing, or unresolved.\n- Check related tests and whether a failing\u002Fproposed test would prove the item.\n- Check whether multiple feedback items share one root cause.\n\n### DI seam migration validation\n\nWhen a test file mutates a DI seam object (e.g., `_internals.foo = mock`),\nverify that the production source reads from the seam at call time. A common\nanti-pattern: the test mutates the seam object, but the production code\nimports the named function (`import { foo } from '.\u002Fmodule'`) which is bound\nat module load. The seam mutation has no effect on the named reference,\nso the test fails even though the seam object's `foo === mock`.\n\nVerification: open the source file and grep for call sites. If you see\n`import { foo } from '...'` followed by `foo(...)` in the production code,\nand the test does `_internals.foo = mock`, the test will fail. The fix is\nto change the production code to call `_internals.foo(...)` (or equivalent\nactive-seam pattern) so the seam mutation is read at call time.\n\nIf only a few call sites exist, fix them in the source. If many call sites\nexist, consider whether the migration should use `mock.module()` instead,\nwhich replaces the entire module object (including the named export\nreference).\n\n## Fix Planning\n\nCluster ledger items by root cause before coding. Fix in this order unless a user\ninstruction or dependency requires otherwise:\n\n1. Merge conflicts, stale branch state, and base drift.\n2. Deterministic CI, build, typecheck, formatting, and test failures.\n3. Confirmed correctness, security, data-loss, persistence, git\u002Fwrite-safety, and\n   permission issues.\n4. Test gaps needed to prove confirmed fixes.\n5. Docs, release notes, PR body, and migration guidance.\n6. Reviewer communication and closure summaries.\n\nFor each cluster, record:\n\n```text\nROOT-001 | ledger items: FB-001, FB-004 | files | fix approach | tests | docs | risk\n```\n\nDo not make scope decisions yourself. If the right fix depends on product intent\nor compatibility policy, mark the item `NEEDS_USER_DECISION` and ask.\n\n## Implementation Rules\n\n- Patch only confirmed or partial items, plus required tests\u002Fdocs.\n- Do not implement speculative cleanup while feedback remains unclosed.\n- Never ship unwired code. Any new command, tool, skill, config, docs surface, or\n  generated artifact must be fully registered and validated.\n- Never defer work or declare it out of scope without explicit user instruction.\n- Keep invalid or disproved findings in the closure ledger with the evidence.\n- For CI failures, verify the failing job belongs to the current PR head before\n  treating it as current evidence.\n- For generated output or dist failures, inspect the failing log before rebuilding\n  and commit regenerated files only when the PR touches the source surface.\n- When `main` has a merge queue enabled, do not rebase or force-push a PR only\n  because `main` advanced. Once required checks and review are green, queue the PR\n  and let the merge queue perform final current-base validation. Still resolve real\n  merge conflicts and SHA-dependent review threads before queuing.\n\n## Mandatory Gates\n\n**Stage A and Stage B gates and the reviewer + critic closeout gate are\nMANDATORY for any change made as part of the PR-feedback process.** No fix\nlands, no closure ledger row is marked FIXED, and no PR is published until all\nthree gates pass on the current diff. This section uses the repository's\nestablished Stage A\u002FB meaning: Stage A = `pre_check_batch`-equivalent structural\npre-checks; Stage B = `reviewer` + `test_engineer` per-task gates (consistent\nwith `execute`, `plan`, `specify`, `brainstorm`, `docs\u002Fswarm-briefing.md`, and\n`docs\u002Fcouncil\u002FREADME.md`).\n\nIf a gate failure is suspected pre-existing, prove it on the base branch or\nlabel it `UNVERIFIED`. Do not call the branch green while required checks are\nnon-green.\n\n### Stage A — structural pre-checks (mandatory before Stage B)\n\nRun for every changed surface. No \"where relevant\" — every PR-feedback change\nruns these; if a surface is genuinely untouched, state that explicitly rather\nthan skipping silently.\n\n- `bun run build` (or the repository's build command) — must succeed.\n- typecheck — must pass.\n- lint\u002Fformat (e.g. `biome ci .`) — must pass.\n- `git diff --check` — no whitespace or merge-marker errors.\n- exact failing CI\u002Ftest command reproduced locally when a ledger item is rooted\n  in a CI\u002Ftest failure — the reproduction must fail on the pre-fix tree and pass\n  after the fix.\n\n### Stage B — reviewer + test_engineer (mandatory after Stage A passes)\n\nTwo independent agents on the Stage-A-green diff:\n\n- **reviewer** — independent (fresh context, not the implementer, not a continued\n  conversation). Validates each fix on the current diff against the feedback\n  item it closes. Verdict per item: APPROVE \u002F NEEDS_REVISION \u002F BLOCKED.\n- **test_engineer** — writes and runs the falsification probe or regression test\n  that proves each fix actually resolves its item (tests for changed behavior or\n  newly covered gaps). Verdict per item: PASS \u002F FAIL \u002F BLOCKED.\n\nAddress every NEEDS_REVISION \u002F BLOCKED \u002F FAIL, then re-run the affected agent on\nthe current diff.\n\n### Closeout gate — reviewer + critic (mandatory after Stage B)\n\nA *separate* reviewer + critic pair on the Stage-B-approved diff. This is the\nswarm closeout contract (see `..\u002Fswarm\u002FSKILL.md` \"Mandatory implementation\ncloseout gate\"); because this skill edits code, docs, release notes, or skill files it applies in full — Stage B\nalone does not satisfy it.\n\n- **independent reviewer** (fresh context, separate from the Stage B reviewer)\n  → APPROVE \u002F NEEDS_REVISION \u002F BLOCKED per item.\n- **final critic** (separate fresh context, not a continued conversation with\n  the reviewer, dispatched after the reviewer returns APPROVE) → APPROVE \u002F\n  NEEDS_REVISION \u002F BLOCKED per item. The critic challenges: is every original\n  feedback item actually resolved? Any requirement drift, weak evidence, missing\n  sibling-file checks, stale approvals, anything unwired or silently deferred?\n\nAddress every NEEDS_REVISION \u002F BLOCKED item, re-review with the reviewer if the\ncritic surfaces correctness issues, then re-critic. **Any edit after the\nreviewer's or critic's approval invalidates that approval** — re-run the\naffected gate on the current diff before publishing.\n\nRecord both closeout verdicts (reviewer + critic, with HEAD\u002Fdiff) in\n`.claude\u002Fsession\u002Ftasks\u002F\u003Cslug>\u002Fgates.md` per the `durable-session-state` skill\n(`.swarm\u002F` is the plugin's runtime state — never write task artifacts there).\n\n### Post-publish verification (mandatory after the PR is pushed)\n\nThese checks run after the fix lands on the remote — they are NOT Stage A\npre-checks and must not be folded into Stage A.\n\n- PR metadata checks after push: head SHA, check status,\n  mergeability\u002Fconflicts, and unresolved feedback state.\n- After conflict fixes, verify remote mergeability is clean (`MERGEABLE` \u002F\n  `CLEAN`), not only that local conflict markers disappeared.\n- For current-head CI, prefer run-level details when PR checks look stale:\n  `gh run view \u003Crun-id> --json headSha,status,conclusion,jobs,url`.\n\n## Publishing And Communication\n\nAfter fixes, update the PR body or comment with a closure ledger:\n\n```text\nFB-001 | fixed | commit\u002Ftest evidence\nFB-002 | disproved | code evidence\nFB-003 | pre-existing | base-branch evidence\nFB-004 | needs user decision | decision required\nFB-005 | needs more evidence | .swarm\u002Fevidence\u002Fphase-council.json missing\nCONFLICT-001 | fixed | remote mergeability is MERGEABLE\u002FCLEAN\nCI-001 | fixed | current-head check\u002Frun evidence\n```\n\nDo not resolve GitHub review threads unless explicitly instructed. If instructed,\nresolve only threads whose ledger item is fixed or disproved on the pushed PR\nhead, and record the exact evidence used.\n\n## Final Output\n\nReport:\n\n- intake sources checked and unavailable sources,\n- ledger counts by status,\n- root-cause clusters fixed,\n- tests and commands run,\n- unresolved user decisions,\n- CI\u002Fmergeability state,\n- whether review-thread resolution was skipped or explicitly performed.\n\nEnd with a complete ledger mapping every original item to its outcome.\n",{"name":5,"description":7},"main","1667541871a3a917f9e544e5584ef06a544a119d",".opencode\u002Fskills\u002Fswarm-pr-feedback",0,"https:\u002F\u002Fgithub.com\u002Fdjimit\u002Fdjimitflo","https:\u002F\u002Fgithub.com\u002Fdjimit","https:\u002F\u002Fdjimit.nl\u002F","About me\r\n\r\nI’m Dennis a strategic IT advisor specializing in cloud, cybersecurity, privacy, AI, and enterprise architecture. ","2026-11-15 04:42:36",{"source":8,"skillName":5,"commands":34,"prompt":44,"zipAvailable":45},[35,38,41],{"tool":36,"command":37},"npx","npx skills add djimit\u002Fdjimitflo --skill swarm-pr-feedback",{"tool":39,"command":40},"bunx","bunx skills add djimit\u002Fdjimitflo --skill swarm-pr-feedback",{"tool":42,"command":43},"pnpm","pnpm dlx skills add djimit\u002Fdjimitflo --skill swarm-pr-feedback","安装技能，技能地址：https:\u002F\u002Fgithub.com\u002Fdjimit\u002Fdjimitflo\u002Fblob\u002Fmain\u002F.opencode\u002Fskills\u002Fswarm-pr-feedback\u002FSKILL.md",true,[],[48,55,62,69,76,83],{"skillNo":49,"name":50,"nameZh":6,"description":51,"descriptionZh":6,"repositoryFullName":8,"ownerLogin":9,"ownerAvatarUrl":10,"ownerAccountNo":11,"ownerDisplayName":12,"repositoryNo":13,"starsCount":14,"licenseSpdxId":15,"licenseFileUrl":6,"sourceHtmlUrl":52,"categories":53,"keywords":54,"publishedAt":19},"01M732DRW7MHQP9VTJ5JSBMWC3","provider-step-usage-v1-0-0","Sum measured OpenCode step_finish token totals with replay deduplication and fail-closed validation.","https:\u002F\u002Fgithub.com\u002Fdjimit\u002Fdjimitflo\u002Fblob\u002Fmain\u002Fskills\u002Fprovider-step-usage-v1-0-0\u002FSKILL.md",[],[],{"skillNo":56,"name":57,"nameZh":6,"description":58,"descriptionZh":6,"repositoryFullName":8,"ownerLogin":9,"ownerAvatarUrl":10,"ownerAccountNo":11,"ownerDisplayName":12,"repositoryNo":13,"starsCount":14,"licenseSpdxId":15,"licenseFileUrl":6,"sourceHtmlUrl":59,"categories":60,"keywords":61,"publishedAt":19},"01M732DKXHWZ1P99ZDNA4PX7BV","writing-tests","Guidelines for writing, organizing, and maintaining tests in the opencode-swarm repository. Covers framework rules (bun:test), mock isolation, CI pipeline structure, file placement, and anti-patterns that break cross-platform CI. Load this skill before writing or modifying any test file.","https:\u002F\u002Fgithub.com\u002Fdjimit\u002Fdjimitflo\u002Fblob\u002Fmain\u002F.opencode\u002Fskills\u002Fwriting-tests\u002FSKILL.md",[],[],{"skillNo":63,"name":64,"nameZh":6,"description":65,"descriptionZh":6,"repositoryFullName":8,"ownerLogin":9,"ownerAvatarUrl":10,"ownerAccountNo":11,"ownerDisplayName":12,"repositoryNo":13,"starsCount":14,"licenseSpdxId":15,"licenseFileUrl":6,"sourceHtmlUrl":66,"categories":67,"keywords":68,"publishedAt":19},"01M732DCEG1R9S45A68T5WR2T7","worktree-retry-cleanup","Protocol for cleaning parallel-coder worktree lanes before retry. Triggered before re-dispatching any task that already has a lane (completed, denied, cancelled, or failed).","https:\u002F\u002Fgithub.com\u002Fdjimit\u002Fdjimitflo\u002Fblob\u002Fmain\u002F.opencode\u002Fskills\u002Fworktree-retry-cleanup\u002FSKILL.md",[],[],{"skillNo":70,"name":71,"nameZh":6,"description":72,"descriptionZh":6,"repositoryFullName":8,"ownerLogin":9,"ownerAvatarUrl":10,"ownerAccountNo":11,"ownerDisplayName":12,"repositoryNo":13,"starsCount":14,"licenseSpdxId":15,"licenseFileUrl":6,"sourceHtmlUrl":73,"categories":74,"keywords":75,"publishedAt":19},"01M732D8KYWE5RHJ1AA76F70K7","swarm","Cross-agent swarm-mode behavior model — a higher-rigor workflow using parallel investigation, independent reviewer validation, and critic challenge, plus the mandatory implementation closeout gate. Runtime adapters (.claude, .agents) add execution-specific notes and command wiring.","https:\u002F\u002Fgithub.com\u002Fdjimit\u002Fdjimitflo\u002Fblob\u002Fmain\u002F.opencode\u002Fskills\u002Fswarm\u002FSKILL.md",[],[],{"skillNo":77,"name":78,"nameZh":6,"description":79,"descriptionZh":6,"repositoryFullName":8,"ownerLogin":9,"ownerAvatarUrl":10,"ownerAccountNo":11,"ownerDisplayName":12,"repositoryNo":13,"starsCount":14,"licenseSpdxId":15,"licenseFileUrl":6,"sourceHtmlUrl":80,"categories":81,"keywords":82,"publishedAt":19},"01M732D232XCMYP3XYKEAQC3YT","swarm-pr-subscribe","Monitor a pull request after creation and act autonomously on pushed PR activity. Use when subscribing to a PR after opening it, when asked to watch, babysit, or autofix a PR until merge, or when a \u003Cpr-activity> wake message or [pr-monitor:...] advisory arrives for a subscribed PR. Owns event triage (fix \u002F ask \u002F skip), bounded-retry escalation, and terminal-state cleanup.","https:\u002F\u002Fgithub.com\u002Fdjimit\u002Fdjimitflo\u002Fblob\u002Fmain\u002F.opencode\u002Fskills\u002Fswarm-pr-subscribe\u002FSKILL.md",[],[],{"skillNo":84,"name":85,"nameZh":6,"description":86,"descriptionZh":6,"repositoryFullName":8,"ownerLogin":9,"ownerAvatarUrl":10,"ownerAccountNo":11,"ownerDisplayName":12,"repositoryNo":13,"starsCount":14,"licenseSpdxId":15,"licenseFileUrl":6,"sourceHtmlUrl":87,"categories":88,"keywords":89,"publishedAt":19},"01M732CVKJ4QEN83DQ30EYG75A","swarm-pr-review","Run a graph-guided, tool-augmented Swarm PR review using context packing, parallel exploration, triggered plugin micro-lanes, independent reviewer validation, critic challenge, and metrics writeback. Use for deep pull request review with low false-positive tolerance and high recall.","https:\u002F\u002Fgithub.com\u002Fdjimit\u002Fdjimitflo\u002Fblob\u002Fmain\u002F.opencode\u002Fskills\u002Fswarm-pr-review\u002FSKILL.md",[],[]]