opencode-swarm 7.196.0 → 7.197.0

package/.opencode/skills/swarm-pr-review/references/phase0a-intake.md

@@ -0,0 +1,61 @@
+# Phase 0A signal-intake steps (fetch, classify, merge) and anti-patterns
+
+### Step 1 — Fetch all PR feedback surfaces
+
+The commands below are GitHub examples. On GitLab, Bitbucket, Gerrit, or
+another code host, use the host's API/connector/CLI to enumerate the same full
+surface, including pagination and unresolved-thread state. Host choice never
+reduces the intake ledger.
+
+```bash
+# Issue comments (general PR thread)
+gh api --paginate repos/{owner}/{repo}/issues/{PR_NUMBER}/comments
+
+# Review comments (inline code comments)
+gh api --paginate repos/{owner}/{repo}/pulls/{PR_NUMBER}/comments
+
+# Review summaries (approve/request-changes/comment events)
+gh api --paginate repos/{owner}/{repo}/pulls/{PR_NUMBER}/reviews
+```
+
+`--paginate` requests every REST page. These three calls are gate-allowed as
+written. A literal jq filter passed as one closed double-quoted `gh api --jq`
+argument is also allowed when it needs no backslash-escaped nested double
+quotes; use `gh_evidence` when a portable filter cannot meet that shape. A real
+shell pipeline to `jq` or another command remains blocked. To
+separate bot/automated reviews (Copilot, Codex, CodeRabbit, etc.) from human
+ones, apply the same predicate in context to the JSON already returned above
+— `user.type == "Bot"` or a `user.login` match against
+`bot|copilot|coderabbit|codex` (case-insensitive) — instead of re-fetching
+with a shell-side `--jq` filter. `gh_evidence` with `target: "pr"` and
+`fields: "comments"` is the sanctioned read-only tool path for the same PR
+comment data when a tool call is preferred over a raw shell command. `gh pr
+view --json comments,reviews` is convenience-only because those fields have
+item caps; never use it as the authoritative "all signals" intake.
+
+### Step 2 — Classify each comment
+
+| Category | Action |
+|----------|--------|
+| **Human review with file:line evidence** | Add as candidate finding with `source: existing-review` — still needs reviewer validation |
+| **Bot/automated finding with specific code reference** | Add as candidate finding with `source: bot-review` — high false-positive rate, treat as unverified |
+| **General feedback / style preference** | Add as advisory obligation |
+| **Resolved/outdated comment** | Skip — note in report under "Ingested Resolved Comments" |
+| **Requested changes not yet addressed** | Add as HIGH-priority obligation |
+
+### Step 3 — Merge into review pipeline
+
+All ingested comments become candidate findings or obligations. They follow the
+same Phase 3-8 pipeline as freshly discovered findings. Ingested findings are
+NOT pre-confirmed — they still require independent reviewer validation per the
+Anti-Self-Review Rule.
+
+**Comment-ledger output:**
+```
+[INGESTED] | source | category | file:line (if applicable) | original_author | status: PENDING_VALIDATION / SKIPPED_OUTDATED / ADVISORY
+```
+
+### Anti-patterns
+- ✗ Ignoring bot reviews because "bots produce false positives" — they also catch real issues
+- ✗ Pre-confirming human review comments without independent validation — even senior reviewers make mistakes
+- ✗ Skipping inline review comments and only reading the summary — inline comments contain the evidence

package/.opencode/skills/swarm-pr-review/references/scope-detection.md

@@ -0,0 +1,103 @@
+# Scope Detection, pre-flight git ref availability, and shell rules under the PR_REVIEW gate
+
+### Shell rules under the PR_REVIEW gate
+
+The gate accepts one command per tool call — never compose commands with
+`&&`, `;`, shell pipelines, redirects (`>`, `>>`, `<`), or `$(...)`/`` ` ``
+substitution. The only literal-pipe exception is inside one closed
+double-quoted `gh api --jq` argument with no backslash-escaped nested double
+quotes; that escape is ambiguous under `cmd.exe`. The exception does not
+permit an outer pipeline or any other control syntax.
+A single leading `cd <dir> &&` prefix and a trailing `2>&1` suffix are
+tolerated, but only on read-only commands. State-transition verbs — `git
+fetch`, `git checkout`, `git switch`, `git branch`, and `gh pr checkout` —
+must always run bare: no `cd` prefix, no `2>&1` suffix.
+
+Allowed read-only `git` subcommands: `status`, `log`, `show`, `diff`,
+`rev-parse`, `merge-base`, `ls-files`, `grep`, `blame`, `cat-file`,
+`for-each-ref`, `branch --list` (listing only — mutation flags are blocked),
+`remote -v`, and `config --get`.
+
+Prefer tools over raw shell for state that a single read-only command cannot
+cover cleanly:
+
+- `pr_workflow_status` — observe local HEAD, branch, dirty-file state,
+  remotes, and gate state in one read-only call.
+- `gh_evidence` — bounded PR/issue/run metadata without a shell round-trip.
+- If `gh` is not installed, the web fetch tool against the equivalent
+  `api.github.com` REST URL is the degraded read-only path.
+
+
+Determine review scope using this priority:
+
+1. explicit user-provided PR URL, PR number, commit, branch, or file scope,
+2. current feature branch diff vs the remote-tracking base ref (`origin/main`,
+   `origin/master`; a local `main`/`master` only as a last resort — it is only as
+   fresh as the last fetch and yields a different merge base),
+3. staged changes,
+4. latest commit,
+5. user-specified files or directories.
+
+Record:
+
+- base ref,
+- head ref,
+- commit range,
+- changed files,
+- deleted files,
+- generated files,
+- lockfiles,
+- test files,
+- docs/config/schema files,
+- whether the working tree is dirty.
+
+If scope cannot be determined, review the narrowest safe scope available and state the limitation.
+
+### Pre-flight git ref availability
+
+Before launching explorers (Phase 3), perform this exact standalone sequence:
+
+1. Resolve and retain the authoritative full `pr_head_sha` from PR metadata.
+2. Verify the working tree is clean with `git status --porcelain`. If it is
+   dirty at all — tracked changes, untracked files, or both — call
+   `prepare_pr_workflow_checkout` (Profile A). The tool supports
+   self-discovery: call it with no `paths` argument to auto-discover and
+   preserve every dirty path in one step, including untracked files; an
+   already-clean tree returns a no-op (nothing is stashed, no receipt is
+   written). Pass explicit `paths` only when you already have the exact,
+   bounded list of dirty tracked files and want the older exact-match
+   contract. Without the controller (Profiles B/C), do not blind-stash over
+   dirty state: surface tracked changes to the user, or abort. Do not issue
+   `git stash` through shell.
+   Treat the controller's Git-state result as final for this attempt: `clean`
+   proceeds, `stashable` permits exactly one checkout-preparation call, and
+   `recovery-required` or `indeterminate` means report the typed
+   `required_action`, abort/clear any already-active gate, and stop. Retry only
+   when the controller explicitly returns `retryable: true`; never fight an
+   unmerged index or in-progress Git operation with repeated stash attempts.
+3. Fetch the PR head as one standalone command, for example
+   `git fetch origin refs/pull/<N>/head`. Do not compose fetch and checkout.
+3a. Fetch the base branch as its own standalone command, for example
+   `git fetch origin main`. Skipping this is the single most common cause of a
+   rejected dispatch: the merge base is recomputed against `base_ref`, and a
+   local `main`/`refs/heads/main` that was never refreshed resolves to a
+   different commit than `origin/main` for the same `base_sha`.
+4. Prove the full commit exists locally with two portable standalone commands:
+   `git rev-parse --verify <full_pr_head_sha>^0`, then
+   `git cat-file -t <full_pr_head_sha>`. The second command must print
+   `commit`. This avoids shell/wrapper parsing differences around the
+   `^{commit}` suffix on Windows.
+5. Check out the exact PR filesystem with
+   `git switch --detach <full_pr_head_sha>`. Do not use `--track FETCH_HEAD`:
+   `FETCH_HEAD` is not a remote-tracking branch.
+6. Confirm `git rev-parse HEAD` equals the full `pr_head_sha`, bind that exact
+   head (Profile A: through the first PR-review controller call; Profiles B/C:
+   record it at the top of the findings ledger and repeat it in every lane
+   prompt), and finish this before dispatching explorer lanes.
+
+Explorer agents read files from the working tree, not from git history. Passing
+the commit range in a prompt cannot substitute for this checkout because
+`Read` / `Glob` / `Grep` operate on the filesystem.
+- Explicitly pass the verified merge-base range (`base_sha...pr_head_sha`) in every explorer delegation so explorers inspect exactly the bound PR diff. Include `base_ref` only as the live ref used to recompute `base_sha`; do not substitute a two-dot branch-tip range.
+
+If refs cannot be fetched or checked out, state the limitation in the context pack.

package/.opencode/skills/swarm-pr-review/references/writeback-phases.md

@@ -0,0 +1,68 @@
+# Phase 10 Metrics and Knowledge Writeback / Phase 11 Post-Fix Re-verification
+
+## Phase 10: Metrics and Knowledge Writeback
+
+At the end of the review, include review quality metrics in the final report's
+validation provenance. Persist them only through an invoked evidence tool and
+record the exact `.swarm/evidence/` path returned by that tool; if no invoked
+tool supports metrics (including all of Profiles B/C), state `NOT PERSISTED —
+no metrics evidence writer` and keep the metrics block in the final report and
+session ledger rather than naming a nonexistent command or path.
+
+Record:
+
+- raw candidates by base lane,
+- raw candidates by micro-lane,
+- deterministic tool candidates,
+- reviewer-confirmed findings,
+- reviewer-disproved findings,
+- reviewer-unverified findings,
+- critic-upheld findings,
+- critic-downgraded findings,
+- critic-disproved findings,
+- final reported findings,
+- suppressed non-actionable candidates,
+- recurring false-positive patterns,
+- commands or probes used,
+- token/time cost if available,
+- accepted/fixed findings when known.
+
+Knowledge writeback rules:
+
+- Write back only validated true positives or validated false-positive patterns.
+- Include file patterns, invariant, evidence, and why it was confirmed/disproved.
+- Mark repo-specific lessons as project-tier unless there is strong evidence they generalize.
+- Never promote quarantined or unvalidated knowledge to hive-tier.
+- Never store secrets, private tokens, or raw sensitive logs.
+
+---
+
+## Phase 11: Post-Fix Re-verification
+
+When the PR author pushes fixes after a review, perform a targeted re-verification before updating the verdict.
+
+### Re-verification scope
+
+Only re-verify findings the author claims to have fixed. Do not re-run the full review pipeline.
+
+### Re-verification steps
+
+1. For each finding the author claims fixed:
+   a. Read the changed file(s) from the updated branch at the specific lines referenced in the original finding.
+   b. Verify the fix addresses the root cause, not just the symptom.
+   c. Check that the fix does not introduce a new issue in the same area.
+2. Run CI checks on the updated branch to confirm no regressions.
+3. For findings the author did not address, carry forward the original finding with unchanged status.
+
+### Re-verification output
+
+```
+[REVERIFIED] | finding_id | FIXED / PARTIALLY_FIXED / NOT_FIXED / NEW_ISSUE | evidence | updated_severity
+```
+
+- `FIXED`: the root cause is resolved and no new issue introduced.
+- `PARTIALLY_FIXED`: the root cause is partially addressed or a residual concern remains.
+- `NOT_FIXED`: the root cause persists unchanged.
+- `NEW_ISSUE`: the fix introduced a new problem at the same location.
+
+Update the verdict only after re-verifying all previously blocking findings.

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

@@ -1,13 +1,14 @@
 ---
 name: swarm-pr-subscribe
-audience: swarm-plugin
 description: >
   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 <pr-activity> wake message or
   [pr-monitor:...] advisory arrives for a subscribed PR. Owns event triage
   (fix / ask / skip), bounded-retry escalation, and terminal-state cleanup.
-swarm-contract-digest: 1f679751e34e
+metadata:
+  audience: swarm-plugin
+  swarm-contract-digest: 1f679751e34e
 ---
 
 # Swarm PR Subscribe

package/.opencode/skills/swarm-resume/SKILL.md

@@ -1,8 +1,9 @@
 ---
 name: swarm-resume
-audience: swarm-plugin
 description: >
   Full execution protocol for MODE: RESUME -- continuing an existing approved plan safely from current state.
+metadata:
+  audience: swarm-plugin
 ---
 
 # Resume Protocol

package/.opencode/skills/test-file-split/SKILL.md

@@ -1,7 +1,8 @@
 ---
 name: test-file-split
-audience: swarm-plugin
 description: Protocol for splitting test files that approach or exceed the FR-006 500-line limit (enforced in CI by scripts/check-test-file-cap.ts as a diff-scoped ratchet). Covers describe-block extraction, shared helper management, pure-function extraction, mock isolation verification, and cascading-split detection. Load when a test file approaches or exceeds 500 lines.
+metadata:
+  audience: swarm-plugin
 ---
 
 # Test File Split Protocol (FR-006)

package/.opencode/skills/worktree-retry-cleanup/SKILL.md

@@ -1,7 +1,8 @@
 ---
 name: worktree-retry-cleanup
-audience: swarm-plugin
 description: 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).
+metadata:
+  audience: swarm-plugin
 ---
 
 # Worktree Retry Cleanup