@iceinvein/agent-skills 0.1.40 → 0.3.0

package/skills/magpie/SKILL.md

@@ -7,7 +7,7 @@ description: Use when the user asks to review a GitHub pull request (a PR number
 
 ## Prerequisites
 
-The skill pre-flights `bun`, `gh`, `git` (required) and `codex` (optional). If a required binary is missing the run aborts with a single install hint line. `codex` is the preferred peer reviewer, but it is optional: if it is missing the run continues and the peer-review stage falls back to a Claude second-opinion subagent (setup prints a one-line notice and logs `{stage: preflight, status: done, missingOptional: ["codex"]}`).
+The skill pre-flights `bun`, `gh`, `git` (required) and `codex` (optional). A missing required binary aborts the run with a single install hint line. Without `codex` the run continues and peer review falls back to a Claude second-opinion subagent (setup prints a one-line notice and logs `{stage: preflight, status: done, missingOptional: ["codex"]}`).
 
 ## Stage walkthrough
 
@@ -15,15 +15,15 @@ Stop reading and follow these steps in order. Do not skip stages. Use the exact
 
 ### 0. Identify the PR
 
-Parse the user's request for a PR number, URL, or "this PR" (current branch). If ambiguous, ask one clarifying terminal question. Capture the PR number into `$PR_NUMBER` and the repository path into `$REPO` (default: current working directory).
+Parse the user's request for a PR number, URL, or "this PR" (current branch). If ambiguous, ask one clarifying terminal question. Capture the PR number into `$PR_NUMBER` and the repo path into `$REPO` (default: the current working directory).
 
-Then check whether an earlier run on this PR is still unfinished, before minting a new id:
+Before minting a new id, check whether an earlier run on this PR is unfinished:
 
 ```
 magpie --list-runs
 ```
 
-Each line is `<id>\t<active|archived>\t<path>`. If an `active` id matches `pr-${PR_NUMBER}-*`, that run was interrupted rather than cleaned up. Set `RUN_DIR` to its path and go to "Resuming a crashed run" instead of starting over; ask the user first if it is unclear whether they want to resume or review from scratch. (`archived` ids are finished runs, not resumable.)
+Each line is `<id>\t<active|archived>\t<path>`. If an `active` id matches `pr-${PR_NUMBER}-*`, that run was interrupted rather than cleaned up. Set `RUN_DIR` to its path and go to "Resuming a crashed run"; ask the user first if it is unclear whether they want to resume or start over. (`archived` ids are finished runs, not resumable.)
 
 Otherwise compute a fresh run directory:
 
@@ -38,13 +38,30 @@ RUN_DIR="$HOME/.magpie/$RUN_ID"
 magpie setup "$RUN_DIR" --pr $PR_NUMBER --repo "$REPO"
 ```
 
-If exit is non-zero, surface stderr verbatim and stop. The CLI removes the worktree and subdirs on failure; the run directory itself plus `log.jsonl` are kept for diagnostics.
+If exit is non-zero, surface stderr verbatim and stop. The CLI removes the worktree and subdirs on failure, keeping the run directory and `log.jsonl` for diagnostics.
 
-Setup automatically filters lockfiles, build output, generated source, and snapshot fixtures from `diff.patch` before specialists see it. Users can override by placing `.magpie.json` at the repo root: `{"exclude": [...glob], "include": [...glob], "useDefaults": true|false}`. When anything is filtered, the raw diff is preserved as `$RUN_DIR/diff.full.patch` and the exclusion list as `$RUN_DIR/excluded-files.json`.
+Setup filters lockfiles, build output, generated source, and snapshot fixtures from `diff.patch` before specialists see it. Users override with `.magpie.json` at the repo root: `{"exclude": [...glob], "include": [...glob], "useDefaults": true|false}`. When anything is filtered, the raw diff is kept as `$RUN_DIR/diff.full.patch` and the exclusion list as `$RUN_DIR/excluded-files.json`.
+
+When `gh pr diff` refuses the diff (HTTP 406 above roughly 300 files) or returns an
+empty diff for a PR with changed files, setup rebuilds it from the local clone instead
+of aborting: it fetches `pull/<n>/head` and diffs from the merge base against the PR's
+base branch, reproducing the three-dot semantics `gh pr diff` uses. A local head that
+does not match the PR's `headRefOid` is a hard error, not a silently stale review. The
+`fetch-pr` log entry records `source: "gh" | "git"` and the merge base, and
+`$RUN_DIR/diff-source.json` carries the same for the report.
+
+Setup then splits the filtered diff into shards, writing `$RUN_DIR/shards/manifest.json`
+and, when more than one shard results, `$RUN_DIR/shards/shard-<n>.patch`. `diff.patch`
+itself is never modified: shards are views over it. Re-split with a different budget
+using `magpie shard "$RUN_DIR" --budget <lines> --max-files <n>` (defaults: 6000 patch
+lines, 80 files). Re-splitting invalidates every existing
+`findings/<focus>.shard-<n>.json`, since a shard id then names a different file set:
+delete those files first, or stage 4's resume rule counts a pair as covered that
+nothing reviewed.
 
 When a prior run exists for the same PR (active or archived under `~/.magpie/`), setup writes `$RUN_DIR/incremental.json` with `{previousRunId, previousSha, currentSha, sameSha}`. The post stage surfaces this as a "Incremental review since `<sha>`" trailer on the summary comment.
 
-Setup also runs a deterministic test-coverage check: when the diff contains zero test or spec files anywhere, each non-test source file with `>= 10` added code lines gets a `domain: "tests"` finding written to `$RUN_DIR/findings/tests.json`. This is a sixth domain that flows through dedupe/critic/peer-review alongside the five LLM specialists. No specialist subagent is dispatched for it.
+Setup also runs a deterministic test-coverage check: when the diff contains zero test or spec files anywhere, each non-test source file with `>= 10` added code lines gets a `domain: "tests"` finding in `$RUN_DIR/findings/tests.json`. That sixth domain flows through dedupe/critic/peer-review alongside the five LLM specialists; no subagent is dispatched for it.
 
 ### 2. Serve
 
@@ -54,9 +71,9 @@ Start the HTML server in the background using the Bash tool with `run_in_backgro
 magpie serve "$RUN_DIR"
 ```
 
-Read `$RUN_DIR/state/server-info` for the URL; the server writes it asynchronously at startup, so if the file doesn't exist yet, wait a moment and re-read (it appears within ~1s). Print to the user: "Open <url> in your browser to follow along."
+Read `$RUN_DIR/state/server-info` for the URL; the server writes it asynchronously, so if it is missing, wait a moment and re-read (it appears within ~1s). Print to the user: "Open <url> in your browser to follow along."
 
-The server shuts down after 30 minutes with no requests (an open report tab heartbeats every 30s, so it stays up while the user is looking at it) and deletes `state/server-info` on the way out. Nothing in the pipeline depends on it staying alive: re-run `magpie serve "$RUN_DIR"` to bring the report back.
+The server shuts down after 30 idle minutes (an open report tab heartbeats every 30s, so it stays up while the user is looking) and deletes `state/server-info` on the way out. Nothing in the pipeline depends on it: re-run `magpie serve "$RUN_DIR"` to bring the report back.
 
 Render the first progress paint:
 
@@ -68,7 +85,7 @@ magpie render "$RUN_DIR" progress
 
 Append `{stage: context, status: running}` to `$RUN_DIR/log.jsonl` and re-render progress. This stage has two steps and never aborts the run.
 
-**Bind probe.** If the `mcp__code-intelligence__*` tools are not in your tool list, skip straight to the scout with `CODE_INTELLIGENCE=unavailable`. Otherwise call `bind_workspace` with `$RUN_DIR/worktree`. The worktree is a linked git worktree, so an already-indexed base repo seeds its index instead of re-indexing.
+**Bind probe.** If the `mcp__code-intelligence__*` tools are not in your tool list, skip straight to the scout with `CODE_INTELLIGENCE=unavailable`. Otherwise call `bind_workspace` with `$RUN_DIR/worktree`: it is a linked git worktree, so an already-indexed base repo seeds its index instead of re-indexing.
 
 - `consent_required` means the base repo has never completed an index. **Never call `approve_indexing`**: that is a full GPU pass the user did not ask for. Set `CODE_INTELLIGENCE=unavailable`, and print one line: "Code intelligence is unavailable (the base repo has no index); specialists will review from the diff alone."
 - `indexing_started` or `indexing_in_progress` means the seed took. Poll `get_index_stats` every 5s for at most 60s, then set `CODE_INTELLIGENCE=available` either way. Do not block the pipeline on completion; the specialist contract handles a still-indexing tool.
@@ -77,17 +94,61 @@ Append `{stage: context, status: running}` to `$RUN_DIR/log.jsonl` and re-render
 
 **Scout.** Read `references/scout.md` and dispatch one subagent (Agent tool, `general-purpose`) carrying the `magpie-scout` block with `<<RUN_DIR>>`, `<<PR_NUMBER>>`, and `<<CODE_INTELLIGENCE>>` substituted. It writes `$RUN_DIR/brief.json`.
 
-Append `{stage: context, status: done, codeIntelligence: true|false}` and re-render progress. If the scout returned without writing `brief.json`, append `{stage: context, status: skipped, codeIntelligence: true|false}` instead and continue: the brief is optional everywhere it is read. The bind probe's result is known regardless of what the scout did, so both entries carry it.
+Append `{stage: context, status: done, codeIntelligence: true|false}` and re-render progress. If the scout returned without writing `brief.json`, append `{stage: context, status: skipped, codeIntelligence: true|false}` instead and continue: the brief is optional everywhere it is read. Both entries carry the probe's result, which is known whatever the scout did.
 
 ### 4. Specialists
 
-Read `references/specialists.md` now, before dispatching anything. It holds the five focus blocks and the output contract that every specialist prompt is built from. Assemble the prompts from that file verbatim: prompts written from memory drift off the JSON contract, and `magpie dedupe` drops findings it cannot parse.
-
-Append `{stage: specialists, status: running}` to `$RUN_DIR/log.jsonl` and re-render progress, so the served page shows the stage as active rather than "Paused". Then dispatch the five specialist subagents in a single message using five Agent tool calls in parallel, one per focus in (security, bugs, performance, code-smells, architecture), each carrying the prompt that `references/specialists.md` describes.
-
-After each subagent returns, append `{stage: specialist, focus: <focus>, status: done, findings: <count>}` to `$RUN_DIR/log.jsonl` and re-render progress. (Per-focus `specialist` entries are diagnostic; only the aggregate `specialists` entry advances `magpie status`.)
-
-If all five specialists fail (no findings files written), log `{stage: specialists, status: error}`, rebind code intelligence to `$REPO` if bound (stage 10), and stop. Otherwise mark `{stage: specialists, status: done}`.
+Read `references/specialists.md` now, before dispatching anything: it holds the five focus blocks and the output contract every specialist prompt is built from. Assemble prompts from that file verbatim; written from memory they drift off the JSON contract, and `magpie dedupe` drops findings it cannot parse.
+
+Append `{stage: specialists, status: running}` to `$RUN_DIR/log.jsonl` and re-render
+progress, so the served page shows the stage as active rather than "Paused". Then read
+`$RUN_DIR/shards/manifest.json`.
+
+**One shard, zero shards, or no manifest** (a diff filtered down to nothing, e.g. a
+lockfile-only PR, yields `shards: []` in an otherwise normal manifest; a run predating
+this feature has no manifest at all): dispatch the five specialists in a single message,
+five parallel Agent calls, one per focus in (security, bugs, performance, code-smells,
+architecture), each carrying the prompt `references/specialists.md` describes with the
+unsharded run header. The shard gate and the wave dispatch below do not apply; the
+logging and the file check at the end of this stage still do.
+
+**More than one shard:** each focus reviews every shard, so the run dispatches
+`5 × <shard count>` subagents in total.
+
+**More than four shards: stop and ask the user once, before dispatching anything.**
+State the shard count, the resulting agent count, and the three options: proceed as
+sharded; re-shard for fewer, larger chunks with
+`magpie shard "$RUN_DIR" --budget <lines> --max-files <n>`, raising both flags (a PR of
+many small files is split by the 80-file cap, so a larger `--budget` alone changes
+nothing); or review only the highest-risk shards, which means appending
+`{stage: shard-coverage, status: partial, reviewed: [<ids>], skipped: [<ids>]}` to
+`$RUN_DIR/log.jsonl` and telling the user in the terminal which shards go unreviewed.
+That log entry is the only record of the gap: the report has no unreviewed marker.
+Wait for the answer. This is the only interactive gate in the pipeline before the
+report, and it exists so that neither the cost nor a coverage gap is ever silent.
+
+Dispatch by wave, one shard per wave, the five focuses in parallel within a wave,
+re-rendering progress between waves. That holds in-flight agents at five and makes a
+crash cheap to resume: only the `(focus, shard)` pairs whose findings file is missing
+need re-dispatching.
+
+After each subagent returns, append
+`{stage: specialist, focus: <focus>, shard: <n>, status: done, findings: <count>}` to
+`$RUN_DIR/log.jsonl` and re-render progress. Omit `shard` on the unsharded path (one
+shard, zero shards, or no manifest).
+(Per-focus `specialist` entries are diagnostic; only the aggregate `specialists` entry
+advances `magpie status`.)
+
+Before leaving this stage, list `$RUN_DIR/findings` and confirm one file per expected
+`(focus, shard)` pair: `5 × <shard count>` named `findings/<focus>.shard-<n>.json` when
+sharded, five `findings/<focus>.json` otherwise, plus `findings/tests.json` from setup.
+Re-dispatch any pair missing from a shard you meant to review; a shard skipped at the
+gate is expected to have none. `magpie dedupe` re-checks this against the manifest and
+names every missing pair on stdout, as a backstop rather than a substitute.
+
+If every specialist fails (no findings files written), log
+`{stage: specialists, status: error}`, rebind code intelligence to `$REPO` if bound
+(stage 10), and stop. Otherwise mark `{stage: specialists, status: done}`.
 
 ### 5. Dedupe
 
@@ -95,9 +156,9 @@ If all five specialists fail (no findings files written), log `{stage: specialis
 magpie dedupe "$RUN_DIR" [--threshold <0-10>]
 ```
 
-`magpie dedupe` also runs a deterministic evidence check against the worktree: findings whose `file` is missing or whose `line` is out of range are dropped. Drops are logged and recorded to `$RUN_DIR/evidence-dropped.json`. The check is skipped if the worktree is no longer present (archived run replay).
+`magpie dedupe` also runs a deterministic evidence check against the worktree: findings whose `file` is missing or whose `line` is out of range are dropped, logged, and recorded to `$RUN_DIR/evidence-dropped.json`. The check is skipped when the worktree is gone (archived run replay).
 
-Each finding receives a derived 0-10 `score` from its risk fields. Findings below `--threshold` (default 3) are dropped before the critic LLM runs and recorded to `$RUN_DIR/threshold-dropped.json`. Pass `--threshold 0` to keep everything.
+Each finding gets a derived 0-10 `score` from its risk fields; those below `--threshold` (default 3) are dropped before the critic LLM runs and recorded to `$RUN_DIR/threshold-dropped.json`. Pass `--threshold 0` to keep everything.
 
 Re-render progress.
 
@@ -105,25 +166,38 @@ Re-render progress.
 
 Read `references/critic.md` and `$RUN_DIR/findings.deduped.json`. Substitute both placeholders in the critic rubric (the compact candidate list including each finding's `onChangedLine`, and the `<<DIFF_EXCERPT>>` hunks for the referenced files), then apply the rubric verbatim (one verdict per finding). Write the kept subset to `$RUN_DIR/findings.kept.json`. Append `{stage: critic, status: done}` and re-render progress.
 
+When `findings.deduped.json` holds more than 40 findings, run the rubric in batches of
+30 rather than one prompt: a sharded run can produce more candidates than fit alongside
+their diff excerpts. Apply the same rubric verbatim per batch and concatenate the kept
+subsets into `findings.kept.json`.
+
 ### 7. Peer review
 
-Append `{stage: peer-review, status: running}` to `$RUN_DIR/log.jsonl` and re-render progress. This stage always runs. `codex` is the preferred reviewer because it is a different model from the Claude agents that produced the findings; when `codex` is unavailable, a Claude second-opinion subagent stands in.
+Append `{stage: peer-review, status: running}` to `$RUN_DIR/log.jsonl` and re-render progress. This stage always runs. `codex` is preferred because it is a different model from the Claude agents that produced the findings; without it, a Claude second-opinion subagent stands in.
+
+Build the peer-review prompt first: read `references/peer-review.md`, take the `magpie-peer-review` block from it, and substitute the placeholders listed in that file's `## Substitute before use` preamble.
 
-Build the peer-review prompt first: read `references/peer-review.md`, take the `magpie-peer-review` block from it, and substitute the placeholders listed in that file's `## Substitute before use` preamble. Write the substituted prompt to `$RUN_DIR/peer-prompt.md`.
+One batch carries up to 40 findings; above that, split them 30 at a time, as in stage 6.
+Write each batch's prompt, its `<<KEPT_FINDINGS_COMPACT>>` narrowed to that batch, to
+`$RUN_DIR/peer-prompt-<k>.md`, `<k>` counting from 1. **When there is a single batch, drop `-<k>` throughout** (`peer-prompt.md`,
+`peer.out`), which is the common case. Keep the `add` id counter running across batches
+(`peer-1`, `peer-2`, ...): restarting it per batch produces colliding ids, and every
+finding in `findings.final.json` must have a unique one or the report and post stages
+crash.
 
-**Codex path (preferred).** If `codex` is available (setup did not log `missingOptional: ["codex"]` and `command -v codex` succeeds), set `<<PEER_PROVIDER>>` to `codex` and run codex with the prompt piped on stdin:
+**Codex path (preferred).** If `codex` is available (setup did not log `missingOptional: ["codex"]` and `command -v codex` succeeds), set `<<PEER_PROVIDER>>` to `codex` and run codex once per batch, that batch's prompt piped on stdin:
 
 ```
-codex exec < "$RUN_DIR/peer-prompt.md" > "$RUN_DIR/peer.out"
+codex exec < "$RUN_DIR/peer-prompt-<k>.md" > "$RUN_DIR/peer-<k>.out"
 ```
 
-`peer.out` is codex's full transcript; extract the fenced JSON block tagged `review-peer-review` from it to get the verdicts array. Write that verdicts array to `$RUN_DIR/peer.json`, append `{stage: peer-review, status: done, provider: codex}`, then apply the verdicts as described below.
+Each `peer-<k>.out` is codex's full transcript; extract the fenced JSON block tagged `review-peer-review` from each. Write the concatenated verdict arrays to `$RUN_DIR/peer.json` once, after the last batch: writing `peer.json` per batch keeps only the last batch's verdicts and silently discards the rest. Then append `{stage: peer-review, status: done, provider: codex}` and apply the verdicts as described below.
 
-If codex returns non-zero, do not abort: record `{stage: peer-review, provider: codex, status: fallback, error: "<first line of stderr>"}` and fall through to the Claude path. (Never log `status: error` for a recoverable codex failure: `magpie status` stops at the first `error` entry and would report the run as poisoned even after the Claude fallback succeeds.)
+If codex returns non-zero on a batch, do not abort: record `{stage: peer-review, provider: codex, status: fallback, batch: <k>, error: "<first line of stderr>"}` and take the Claude path for that batch. (Never log `status: error` for a recoverable codex failure: `magpie status` stops at the first `error` entry and would report the run as poisoned even after the Claude fallback succeeds.)
 
-**Claude path (fallback).** When `codex` is unavailable or failed, get the second opinion from a Claude subagent instead. Set `<<PEER_PROVIDER>>` to `claude`, then prepend the `magpie-peer-review-claude-preamble` block from `references/peer-review.md` to the substituted peer-review prompt (the preamble forces genuine independence, since the reviewer shares a model family with the primary reviewers). Dispatch one subagent (Agent tool, `general-purpose`) whose entire task is that combined prompt, and instruct it to return only the fenced `review-peer-review` JSON block. Write its output to `$RUN_DIR/peer.out`, extract the `review-peer-review` block to `$RUN_DIR/peer.json`, and append `{stage: peer-review, status: done, provider: claude}`.
+**Claude path (fallback).** When `codex` is unavailable or failed, get the second opinion from a Claude subagent instead, one per batch. Set `<<PEER_PROVIDER>>` to `claude`, then prepend the `magpie-peer-review-claude-preamble` block from `references/peer-review.md` to each batch's substituted prompt (the preamble forces genuine independence, since the reviewer shares a model family with the primary reviewers). Dispatch one subagent (Agent tool, `general-purpose`) per batch whose entire task is that combined prompt, and instruct it to return only the fenced `review-peer-review` JSON block. Write each output to `$RUN_DIR/peer-<k>.out`, extract each `review-peer-review` block, merge into `$RUN_DIR/peer.json` after the last batch as above, and append `{stage: peer-review, status: done, provider: claude}` (`provider: mixed` if codex handled some batches).
 
-**Apply the verdicts (both paths).** Parse the verdicts JSON and apply the `update` / `add` entries (an empty array means no change). For each `add`, mint a unique `id` on the new finding before merging (`peer-1`, `peer-2`, ...): the peer contract does not include ids, but every finding in `findings.final.json` must carry one or the report render and post stages will crash. Then write `findings.final.json`. Re-render progress.
+**Apply the verdicts (both paths).** Parse the merged verdicts and apply the `update` / `add` entries (an empty array means no change). Mint each `add`'s `id` as above before merging, since the peer contract does not carry ids. Then write `findings.final.json`. Re-render progress.
 
 ### 8. Report
 
@@ -139,9 +213,9 @@ End the turn.
 
 ### 9. Post
 
-Most users will tick the checkboxes in the served report and click **Post Selected** (or **Post Recommended**, which takes every finding whose `risk.action` is `must-fix` or `should-fix`, skipping the `consider`/`optional` ones); the report server handles the rest and posts the batch as one GitHub review with inline threads. The agent only handles posts when the user explicitly types `post` (optionally `post 1,3,7` for indices) in the conversation, which takes the CLI path below: separate inline comments plus a top-level summary comment. Either path records posted ids in `post-status.json`, so the two cannot double-post the same finding.
+Most users tick the checkboxes in the served report and click **Post Selected** (or **Post Recommended**, which takes every `must-fix`/`should-fix` finding and skips the `consider`/`optional` ones); the server posts that batch as one GitHub review with inline threads. The agent posts only when the user types `post` (optionally `post 1,3,7` for indices), which takes the CLI path below: separate inline comments plus a top-level summary comment. Either path records posted ids in `post-status.json`, so the two cannot double-post the same finding.
 
-When the user types `post`, read `$RUN_DIR/state/events`. Fold the events in order, keeping the LAST event per finding id; ids whose last event is `select` are selected. (Not union-minus: the UI emits one event per toggle, so select then deselect then select again must resolve to selected.) Merge with any explicit indices the user named (1-based, against `findings.final.json` in file order). If that leaves nothing selected, say so and ask rather than posting an empty batch. Then post via the CLI:
+When the user types `post`, read `$RUN_DIR/state/events` and fold them in order, keeping the LAST event per finding id; ids whose last event is `select` are selected. (Not union-minus: the UI emits one event per toggle, so select, deselect, select again resolves to selected.) Merge any explicit indices the user named (1-based, against `findings.final.json` in file order). If nothing is selected, say so and ask rather than posting an empty batch. Then post via the CLI:
 
 ```
 magpie post "$RUN_DIR" --ids id1,id2,id3
@@ -149,12 +223,12 @@ magpie post "$RUN_DIR" --ids id1,id2,id3
 
 That delegates to `runPost`, which:
 
-- Picks `formatInlineBody` (severity heading, `<sub>` risk metaline, parsed `Observation`/`Why it matters`/`Suggested direction`/`Needs verification` sections, optional `` ```suggestion `` block, hidden `magpie:finding` marker) when the finding has a `line`, and uses `gh api repos/<owner>/<repo>/pulls/<n>/comments` to open an inline review thread.
-- Falls back to `formatConversationBody` (same shape plus a `Location · <file>:<line>` metaline) posted via `gh pr comment <n>` when there is no anchor, or when GitHub rejects the inline anchor with 422.
-- When at least one new finding is being posted in this batch (default `auto` mode), prepends one top-level summary comment (verdict line, "Needs Attention" top three, `<details>` risk breakdown) and persists the sentinel `__summary__` in `post-status.json` so re-runs don't duplicate it. Override with `--include-summary always|never` if you need to force or suppress it.
+- For a finding with a `line`, picks `formatInlineBody` (severity heading, `<sub>` risk metaline, parsed `Observation`/`Why it matters`/`Suggested direction`/`Needs verification` sections, optional `` ```suggestion `` block, hidden `magpie:finding` marker) and opens an inline review thread via `gh api repos/<owner>/<repo>/pulls/<n>/comments`.
+- Falls back to `formatConversationBody` (same shape plus a `Location · <file>:<line>` metaline) via `gh pr comment <n>` when there is no anchor, or GitHub rejects the inline anchor with 422.
+- When at least one new finding is in the batch (default `auto` mode), prepends one top-level summary comment (verdict line, "Needs Attention" top three, `<details>` risk breakdown) and persists the `__summary__` sentinel in `post-status.json` so re-runs don't duplicate it. Override with `--include-summary always|never`.
 - Appends `{stage: post, ...}` events to `log.jsonl` and updates `$RUN_DIR/post-status.json` per finding id.
 
-Pass `--dry-run` to record the would-be gh commands without invoking gh. After posting, append `{stage: post, status: done}` to `$RUN_DIR/log.jsonl` (`runPost` logs per-finding `ok`/`failed` events but not the stage-complete marker, and `magpie status` counts only `done`), then re-render the report so the badges update:
+Pass `--dry-run` to record the would-be gh commands without invoking gh. After posting, append `{stage: post, status: done}` to `$RUN_DIR/log.jsonl` (`runPost` logs per-finding `ok`/`failed` events but not the stage marker, and `magpie status` counts only `done`), then re-render the report so the badges update:
 
 ```
 magpie render "$RUN_DIR" findings
@@ -166,15 +240,15 @@ magpie render "$RUN_DIR" findings
 magpie cleanup "$RUN_DIR" --repo "$REPO"
 ```
 
-If the context stage bound code intelligence, rebind the session to the repository now: call `bind_workspace` with `$REPO`. Binding is per session with no per-call override, so a run that ends without this leaves your session pointed at a worktree `cleanup` just deleted. The daemon prunes the seeded index on its own once the worktree is gone.
+If the context stage bound code intelligence, rebind the session now: call `bind_workspace` with `$REPO`. Binding is per session with no per-call override, so ending a run without this leaves the session pointed at a worktree `cleanup` just deleted. The daemon prunes the seeded index once the worktree is gone.
 
-The run directory is renamed to `<run-dir>.archived-<timestamp>` and the worktree is removed. The CLI prints two lines on success: `archived to <path>` and `view later: magpie open <archived-id>`. Surface that second line to the user verbatim so they have a one-command path back to the report.
+The run directory is renamed to `<run-dir>.archived-<timestamp>` and the worktree is removed. The CLI prints two lines on success: `archived to <path>` and `view later: magpie open <archived-id>`. Surface that second line verbatim so the user has a one-command path back to the report.
 
 The archived `findings.html` is self-contained and auto-switches to read-only "archived" mode when opened, so:
 
-- `magpie open` (no args) opens the latest run in the user's default browser via `open`/`xdg-open`. Add `--dry-run` to see the command without spawning.
+- `magpie open` (no args) opens the latest run in the default browser via `open`/`xdg-open`; `--dry-run` prints the command instead of spawning it.
 - `magpie open <id>` opens a specific archived run.
-- `magpie serve <id>` re-spins the Bun server against an archived run if the user wants the live interactive surface back (posts still work because `pr.json` retains the head SHA).
+- `magpie serve <id>` re-spins the Bun server against an archived run for the live interactive surface (posts still work: `pr.json` retains the head SHA).
 - `magpie --list-runs` enumerates all runs in `~/.magpie/`.
 
 ## Resuming a crashed run
@@ -189,10 +263,14 @@ The JSON output tells you `lastCompleted` and `next`. Resume from `next`:
 
 - `context` re-runs by redoing the bind probe, then dispatching the scout only if `$RUN_DIR/brief.json` is missing. The seeded index survives a crash, so the rebind is near-instant.
 - Any other stage: run it as written in the walkthrough.
-- If a specialist focus has no findings file but its sibling stages are done, re-dispatch only that focus.
+- If a specialist focus has no findings file but its sibling stages are done,
+  re-dispatch only that focus. On a sharded run the unit is the `(focus, shard)` pair:
+  read `shards/manifest.json`, and re-dispatch only the pairs with no
+  `findings/<focus>.shard-<n>.json`. Never re-shard mid-run without deleting those
+  files first (stage 1): the check would otherwise trust ids that moved.
 - Non-null `error` means the run stopped on a failed stage. Report which stage to the user and confirm before re-running it.
 
-The server from the original run is gone. Restart it with `magpie serve "$RUN_DIR"` (step 2) before re-rendering, so the user gets a live URL again.
+The original server is gone. Restart it with `magpie serve "$RUN_DIR"` (step 2) before re-rendering, so the user gets a live URL again.
 
 ## Aborting
 

package/skills/magpie/bin/magpie.ts

@@ -10,6 +10,8 @@ Subcommands:
   setup <run-dir> --pr <n>   Pre-flight, fetch PR, create worktree
   serve <run-dir-or-id>      Start the HTML server (accepts active or archived run id)
   dedupe <run-dir>           Merge specialist findings into deduped set
+  shard <run-dir> [--budget N] [--max-files N]
+                             Re-split diff.patch into budgeted shards
   render <run-dir> <page>    Render progress.html or findings.html
   cleanup <run-dir>          Remove worktree, stop server, archive run
   status <run-dir>           Print highest completed stage
@@ -116,6 +118,47 @@ const HANDLERS: Record<string, Handler> = {
     const { runDedupe } = await import('../scripts/dedupe-cmd.ts')
     return runDedupe(runDir, threshold !== undefined ? { threshold } : {})
   },
+  shard: async (args) => {
+    const runDir = args[0]
+    if (!runDir) {
+      process.stderr.write('shard: missing <run-dir> [--budget <n>] [--max-files <n>]\n')
+      return 2
+    }
+    const numFlag = (name: string): number | undefined | null => {
+      const idx = args.indexOf(name)
+      if (idx === -1) return undefined
+      const n = Number(args[idx + 1])
+      if (!Number.isFinite(n) || n <= 0) {
+        process.stderr.write(`shard: invalid ${name} ${args[idx + 1]} (want a positive number)\n`)
+        return null
+      }
+      return n
+    }
+    const budget = numFlag('--budget')
+    if (budget === null) return 2
+    const maxFiles = numFlag('--max-files')
+    if (maxFiles === null) return 2
+    // `shardDiff` tolerates a missing diff.patch (setup calls it before the diff
+    // can exist) and mkdirs `shards/` on the way, so a typo'd run directory would
+    // otherwise be invented on disk and reported as a successful zero-shard split.
+    const { stat } = await import('node:fs/promises')
+    const isRunDir = await stat(runDir)
+      .then((s) => s.isDirectory())
+      .catch(() => false)
+    if (!isRunDir) {
+      process.stderr.write(`shard: no such run directory: ${runDir}\n`)
+      return 2
+    }
+    const { shardDiff } = await import('../scripts/shard.ts')
+    const manifest = await shardDiff(runDir, {
+      ...(budget !== undefined ? { budget } : {}),
+      ...(maxFiles !== undefined ? { maxFiles } : {}),
+    })
+    process.stdout.write(
+      `${manifest.shards.length} shard(s), ${manifest.totalFiles} files, ${manifest.totalLines} patch lines\n`,
+    )
+    return 0
+  },
   render: async (args) => {
     const runDir = args[0]
     const page = args[1]

package/skills/magpie/fixtures/fake-gh-nodiff.sh

@@ -0,0 +1,38 @@
+#!/usr/bin/env bash
+# Fake gh whose `pr diff` refuses to serve, the way GitHub does above ~300
+# files. MAGPIE_FAKE_HEAD_OID lets a test point pr.json at a real local commit.
+# MAGPIE_FAKE_DIFF_MODE=fail (default) exits non-zero; =empty exits 0 with no
+# output, which is the truncation case fetchPr also has to catch.
+case "$1 $2" in
+  "pr view")
+    cat <<JSON
+{
+  "number": 7,
+  "title": "Fake big PR",
+  "headRefName": "feature-x",
+  "baseRefName": "main",
+  "headRefOid": "${MAGPIE_FAKE_HEAD_OID:-deadbeefdeadbeefdeadbeefdeadbeefdeadbeef}",
+  "baseRefOid": "cafebabecafebabecafebabecafebabecafebabe",
+  "author": { "login": "octocat" },
+  "body": "Fake body",
+  "url": "https://github.com/octocat/Hello-World/pull/7",
+  "files": [
+    { "path": "a.ts", "additions": 1, "deletions": 1, "changeType": "modified" }
+  ],
+  "commits": [],
+  "closingIssuesReferences": []
+}
+JSON
+    ;;
+  "pr diff")
+    if [ "${MAGPIE_FAKE_DIFF_MODE:-fail}" = "empty" ]; then
+      exit 0
+    fi
+    echo "the diff exceeded the maximum number of files (300) (HTTP 406)" >&2
+    exit 1
+    ;;
+  *)
+    echo "fake-gh-nodiff: unsupported args: $*" >&2
+    exit 1
+    ;;
+esac

package/skills/magpie/package.json

@@ -1,6 +1,6 @@
 {
   "name": "magpie",
-  "version": "0.9.0",
+  "version": "0.10.0",
   "private": true,
   "type": "module",
   "scripts": {

package/skills/magpie/references/peer-review.md

@@ -1,9 +1,14 @@
 # Peer-review prompt
 
-The agent substitutes the placeholders below and writes the result to `<run-dir>/peer-prompt.md`. Step 6 then feeds that prompt to the peer reviewer: `codex exec < <run-dir>/peer-prompt.md > <run-dir>/peer.out` when codex is available, or a Claude `general-purpose` subagent (with the `magpie-peer-review-claude-preamble` prepended) writing to `<run-dir>/peer.out` when it is not.
+The agent substitutes the placeholders below and writes the result to `<run-dir>/peer-prompt.md`. Stage 7 then feeds that prompt to the peer reviewer: `codex exec < <run-dir>/peer-prompt.md > <run-dir>/peer.out` when codex is available, or a Claude `general-purpose` subagent (with the `magpie-peer-review-claude-preamble` prepended) writing to `<run-dir>/peer.out` when it is not.
 
 Either way, extract the fenced `review-peer-review` block from `peer.out` and save it to `<run-dir>/peer.json`.
 
+The filenames above are the single-batch case. Stage 7 batches above 40 findings, and
+those runs use `peer-prompt-<k>.md` and `peer-<k>.out` per batch, one reviewer
+invocation each, with every batch's verdicts merged into one `peer.json` after the
+last batch. Everything below is per batch and otherwise unchanged.
+
 ## Substitute before use
 
 Replace each `<<NAME>>` placeholder in the block below:
@@ -72,7 +77,7 @@ Rules:
 
 ## Claude peer-review preamble
 
-Used only by the Claude fallback path in step 6. Prepend this block verbatim (no substitutions) to the substituted `magpie-peer-review` prompt before dispatching the subagent. Its job is to buy back the independence you lose by using the same model family that produced the findings: the reviewer must re-derive each verdict from the diff rather than trusting the finding text, and must actively resist rubber-stamping.
+Used only by the Claude fallback path in stage 7. Prepend this block verbatim (no substitutions) to the substituted `magpie-peer-review` prompt before dispatching the subagent. Its job is to buy back the independence you lose by using the same model family that produced the findings: the reviewer must re-derive each verdict from the diff rather than trusting the finding text, and must actively resist rubber-stamping.
 
 ````magpie-peer-review-claude-preamble
 You are a fresh, independent second-opinion reviewer. You have no memory of, and no stake in, how the findings below were produced. They were generated by other agents that share your model family, so they may carry the same blind spots you would: do not defer to them, and do not assume they are correct because they sound confident.

package/skills/magpie/references/specialists.md

@@ -1,10 +1,12 @@
 # Specialist prompts
 
-Stage 4 of the walkthrough dispatches five subagents from this file. Build each prompt
-from up to five parts, in this order, and send it as the agent's entire task:
+Stage 4 of the walkthrough dispatches five subagents per shard from this file. Build
+each prompt from up to six parts, in this order, and send it as the agent's entire
+task. Each part is a fenced block or the named section it points at; the prose around
+them is instruction to you, not text for the specialist.
 
 1. The focus block for that focus (the fenced `magpie-specialist-<focus>` blocks below), verbatim.
-2. The run header, with the two placeholders filled in:
+2. The run header, with the placeholders filled in. Unsharded:
 
 ```
 You are reviewing PR #<PR_NUMBER>.
@@ -12,11 +14,37 @@ Working directory: <RUN_DIR>/worktree
 Diff: <RUN_DIR>/diff.patch
 ```
 
+When stage 4 is fanning this focus across shards, use instead:
+
+```
+You are reviewing PR #<PR_NUMBER>.
+Working directory: <RUN_DIR>/worktree
+Shard: <n> of <N>
+Diff: <RUN_DIR>/shards/shard-<n>.patch
+
+This shard is your review scope. The other shards belong to other agents working
+in parallel: do not review files outside your shard, and do not report findings
+anchored to them. Reading any file in the worktree for context is expected and
+encouraged.
+```
+
 3. The `## Output Contract` section below, verbatim.
-4. The `magpie-codebase-intelligence` block below, verbatim, **only** when the context
+4. The excluded-files block below, verbatim, when `<RUN_DIR>/excluded-files.json`
+   exists (setup writes it only when the path filter removed something, and without
+   it the two paths the block names do not exist):
+
+```
+Files excluded by the path filter are absent from your diff but present in the
+worktree, with their full patches in <RUN_DIR>/diff.full.patch and the exclusion
+list in <RUN_DIR>/excluded-files.json. When a change in your scope implies a change
+in an excluded file (a migration implies a model snapshot, a schema change implies
+generated types), open it and cross-check rather than treating it as out of scope.
+```
+
+5. The `magpie-codebase-intelligence` block below, verbatim, **only** when the context
    stage logged `codeIntelligence: true`. Omit it entirely otherwise: telling a
    specialist to use tools it does not have wastes a turn per specialist on discovery.
-5. The brief, when `<RUN_DIR>/brief.json` exists, rendered as:
+6. The brief, when `<RUN_DIR>/brief.json` exists, rendered as:
 
 ```
 ## What this PR is for
@@ -52,7 +80,10 @@ into the same generic pass. Do not paraphrase, summarise, or trim either one.
 
 ## Output Contract
 
-Write findings to <RUN_DIR>/findings/<focus>.json before returning. The file MUST be a JSON array. Each entry MUST conform to this schema exactly (no extra top-level keys, no renamed keys):
+Write findings to <RUN_DIR>/findings/<focus>.json before returning, or to
+<RUN_DIR>/findings/<focus>.shard-<n>.json when your run header names a shard. The file
+MUST be a JSON array. Each entry MUST conform to this schema exactly (no extra
+top-level keys, no renamed keys):
 
 ```
 {
@@ -114,7 +145,7 @@ If you have no findings, write []. Return as your final tool result a single lin
 
 ## Codebase intelligence
 
-Include this block as part 4 only when the context stage logged `codeIntelligence: true`.
+Include this block as part 5 only when the context stage logged `codeIntelligence: true`.
 
 ```magpie-codebase-intelligence
 ## Codebase intelligence

package/skills/magpie/scripts/__tests__/cli.test.ts

@@ -1,5 +1,6 @@
 import { expect, test } from 'bun:test'
-import { mkdir, mkdtemp, rm, symlink, writeFile } from 'node:fs/promises'
+import { existsSync } from 'node:fs'
+import { mkdir, mkdtemp, readFile, rm, symlink, writeFile } from 'node:fs/promises'
 import { tmpdir } from 'node:os'
 import { join } from 'node:path'
 
@@ -274,3 +275,102 @@ test('top-level --help surfaces the preview subcommand', async () => {
   expect(stdout).toContain('preview')
   expect(stdout).toContain('--help-preview')
 })
+
+test('shard rejects missing <run-dir>', async () => {
+  const proc = Bun.spawn(['bun', CLI, 'shard'], { stdout: 'pipe', stderr: 'pipe' })
+  const stderr = await new Response(proc.stderr).text()
+  const exit = await proc.exited
+  expect(exit).toBe(2)
+  expect(stderr).toContain('shard: missing <run-dir>')
+})
+
+test('shard rejects a zero, negative, or non-numeric --budget, naming the flag and value', async () => {
+  for (const bad of ['0', '-5', 'abc']) {
+    const proc = Bun.spawn(['bun', CLI, 'shard', '/tmp/does-not-matter', '--budget', bad], {
+      stdout: 'pipe',
+      stderr: 'pipe',
+    })
+    const stderr = await new Response(proc.stderr).text()
+    const exit = await proc.exited
+    expect(exit).toBe(2)
+    expect(stderr).toContain(`shard: invalid --budget ${bad}`)
+  }
+})
+
+test('shard rejects an invalid --max-files, naming the flag and value', async () => {
+  const proc = Bun.spawn(['bun', CLI, 'shard', '/tmp/does-not-matter', '--max-files', '-1'], {
+    stdout: 'pipe',
+    stderr: 'pipe',
+  })
+  const stderr = await new Response(proc.stderr).text()
+  const exit = await proc.exited
+  expect(exit).toBe(2)
+  expect(stderr).toContain('shard: invalid --max-files -1')
+})
+
+test('shard rejects a run directory that does not exist instead of creating it', async () => {
+  const missing = join(tmpdir(), `magpie-cli-no-run-${Date.now()}`, 'nested')
+  const proc = Bun.spawn(['bun', CLI, 'shard', missing], { stdout: 'pipe', stderr: 'pipe' })
+  const stdout = await new Response(proc.stdout).text()
+  const stderr = await new Response(proc.stderr).text()
+  const exit = await proc.exited
+  expect(exit).toBe(2)
+  expect(stderr).toContain(`shard: no such run directory: ${missing}`)
+  // The old behaviour mkdir -p'd the typo and reported success.
+  expect(stdout).not.toContain('shard(s)')
+  expect(existsSync(missing)).toBe(false)
+})
+
+test('--help shows the shard budget flags', async () => {
+  const proc = Bun.spawn(['bun', CLI, '--help'], { stdout: 'pipe' })
+  const stdout = await new Response(proc.stdout).text()
+  expect(await proc.exited).toBe(0)
+  expect(stdout).toContain('shard <run-dir> [--budget N] [--max-files N]')
+})
+
+test('shard with a custom --budget and --max-files reaches shardDiff with those values', async () => {
+  const runDir = await mkdtemp(join(tmpdir(), 'magpie-cli-shard-'))
+  try {
+    // Two files under the same two-segment directory group ('src'), each with
+    // its own diff --git block, so a --max-files 1 cap forces the group apart
+    // into two shards regardless of --budget: proof the flags actually reach
+    // shardDiff rather than the defaults (budget 6000, max-files 80) taking
+    // over silently.
+    const diff = [
+      'diff --git a/src/a.ts b/src/a.ts',
+      'index 0000000..1111111 100644',
+      '--- a/src/a.ts',
+      '+++ b/src/a.ts',
+      '@@ -1 +1 @@',
+      '-x',
+      '+y',
+      'diff --git a/src/b.ts b/src/b.ts',
+      'index 0000000..1111111 100644',
+      '--- a/src/b.ts',
+      '+++ b/src/b.ts',
+      '@@ -1 +1 @@',
+      '-x',
+      '+y',
+      '',
+    ].join('\n')
+    await writeFile(join(runDir, 'diff.patch'), diff)
+
+    const proc = Bun.spawn(['bun', CLI, 'shard', runDir, '--budget', '3', '--max-files', '1'], {
+      stdout: 'pipe',
+      stderr: 'pipe',
+    })
+    const stdout = await new Response(proc.stdout).text()
+    const exit = await proc.exited
+    expect(exit).toBe(0)
+    expect(stdout).toContain('2 shard(s)')
+
+    const manifest = JSON.parse(
+      await readFile(join(runDir, 'shards', 'manifest.json'), 'utf8'),
+    ) as { budget: number; maxFiles: number; shards: unknown[] }
+    expect(manifest.budget).toBe(3)
+    expect(manifest.maxFiles).toBe(1)
+    expect(manifest.shards).toHaveLength(2)
+  } finally {
+    await rm(runDir, { recursive: true, force: true })
+  }
+})