@iceinvein/agent-skills 0.1.39 → 0.2.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,15 +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 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.
+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.
 
-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.
+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.
 
-The pipeline has no separate context-indexing stage, but `magpie status` and the progress page track one. After setup succeeds, append `{stage: context, status: skipped}` to `$RUN_DIR/log.jsonl`; both treat a skipped stage as behind them, so the pipeline advances to `specialists`.
+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
 
@@ -56,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:
 
@@ -66,53 +81,125 @@ Render the first progress paint:
 magpie render "$RUN_DIR" progress
 ```
 
-### 3. Specialists
+### 3. Context
+
+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`: 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.
+- A ready result sets `CODE_INTELLIGENCE=available`.
+- Any other error sets `CODE_INTELLIGENCE=unavailable`. Do not retry.
+
+**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. 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.
+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 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.
+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`.
 
-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`.)
+**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.
 
-If all five specialists fail (no findings files written), log `{stage: specialists, status: error}` and stop. Otherwise mark `{stage: specialists, status: done}`.
+**More than one shard:** each focus reviews every shard, so the run dispatches
+`5 × <shard count>` subagents in total.
 
-### 4. Dedupe
+**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
 
 ```
 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.
 
-### 5. Critic
+### 6. Critic
 
 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.
 
-### 6. Peer review
+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. Write the substituted prompt to `$RUN_DIR/peer-prompt.md`.
+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.
 
-**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:
+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 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.
 
-### 7. Report
+### 8. Report
 
 ```
 magpie render "$RUN_DIR" findings
@@ -124,11 +211,11 @@ Print to the terminal: "Findings ready at <url>. Tick the ones you want and clic
 
 End the turn.
 
-### 8. Post
+### 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
@@ -136,30 +223,32 @@ 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
 ```
 
-### 9. Cleanup
+### 10. Cleanup
 
 ```
 magpie cleanup "$RUN_DIR" --repo "$REPO"
 ```
 
-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.
+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 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
@@ -172,13 +261,17 @@ magpie status "$RUN_DIR"
 
 The JSON output tells you `lastCompleted` and `next`. Resume from `next`:
 
-- `context` is a no-op. Append `{stage: context, status: skipped}` and continue at `specialists`.
+- `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
 
-If the user types `abort` mid-run, run `magpie cleanup` immediately and exit.
+If the user types `abort` mid-run, rebind code intelligence to `$REPO` if bound (stage 10), then run `magpie cleanup` and exit.

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/example-pr/brief.json

@@ -0,0 +1,18 @@
+{
+  "purpose": "Adds bounded retries to the upload path so transient S3 failures stop surfacing to end users as hard errors.",
+  "changes": [
+    "Wraps the S3 put call in a bounded retry with jittered backoff",
+    "Threads a per-request deadline through the storage client",
+    "Adds a metrics counter for exhausted retry budgets"
+  ],
+  "subsystems": [
+    { "name": "upload", "role": "owns the client-facing put path" },
+    { "name": "storage-client", "role": "wraps the S3 SDK and owns timeouts" }
+  ],
+  "watchItems": [
+    "The PR body claims the retry is idempotent, but no idempotency key is sent with the put"
+  ],
+  "unclear": [
+    "Whether the new per-request deadline interacts correctly with the outer HTTP timeout"
+  ]
+}

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/fixtures/fake-gh.sh

@@ -19,6 +19,20 @@ case "$1 $2" in
       "deletions": 0,
       "changeType": "modified"
     }
+  ],
+  "commits": [
+    {
+      "oid": "deadbeefdeadbeefdeadbeefdeadbeefdeadbeef",
+      "messageHeadline": "Add retry handling to the upload path",
+      "messageBody": ""
+    }
+  ],
+  "closingIssuesReferences": [
+    {
+      "number": 42,
+      "title": "Uploads fail intermittently under load",
+      "url": "https://github.com/octocat/Hello-World/issues/42"
+    }
   ]
 }
 JSON

package/skills/magpie/package.json

@@ -1,6 +1,6 @@
 {
   "name": "magpie",
-  "version": "0.8.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/scout.md

@@ -0,0 +1,90 @@
+# Scout prompt
+
+Stage 3 of the walkthrough dispatches one subagent from this file, before the five
+specialists. Send the fenced `magpie-scout` block below as the agent's entire task,
+with `<<RUN_DIR>>` and `<<PR_NUMBER>>` replaced by the real values first. The
+subagent has no shell variables from your session, so an unexpanded path means it
+writes the brief where nothing will read it.
+
+Substitute `<<CODE_INTELLIGENCE>>` with `available` when the bind probe succeeded and
+`unavailable` otherwise. The scout still runs when code-intelligence is unavailable;
+only the subsystem map degrades.
+
+```magpie-scout
+You are a senior engineer building the orienting brief that five specialist
+reviewers will read before they review PR #<<PR_NUMBER>>. You are not reviewing the
+code. You are answering "what is this PR for, and what does it actually do".
+
+Working directory: <<RUN_DIR>>/worktree
+PR metadata: <<RUN_DIR>>/pr.json
+Diff: <<RUN_DIR>>/diff.patch
+Code intelligence: <<CODE_INTELLIGENCE>>
+
+## What to read
+
+1. `pr.json` for the author's stated intent: `title`, `body`, `commits[].messageHeadline`,
+   and `closingIssuesReferences[].title`. This is the claim.
+2. `diff.patch` for what the change actually does. This is the evidence.
+3. The worktree for surrounding context on any file the diff changes but does not
+   explain.
+
+## Code intelligence
+
+When the line above says `available`, the code-intelligence MCP tools are indexed
+against `<<RUN_DIR>>/worktree`, seeded from the base repository. Call `bind_workspace`
+with `<<RUN_DIR>>/worktree` before your first query. Use them to map where the change
+lands:
+
+- `get_module_summary` on each directory the diff touches, to name the subsystem and
+  say what it is responsible for.
+- `explore_dependency_graph` on the touched modules, to say what depends on them.
+
+If a tool returns `indexing_in_progress`, finish reading the diff and retry once. If
+it still is not ready, or the line above says `unavailable`, write `"subsystems": []`
+and carry on. Never call `approve_indexing`. Never call `refresh_index`. Triggering a
+full index is a consent-gated operation that is not yours to start.
+
+## How to reason
+
+1. State the purpose in your own words, not the author's. If you cannot restate it
+   without quoting the PR body, you have not understood it yet.
+2. Group the diff into 3-7 concerns. A concern is a thing a reviewer would evaluate
+   as a unit, not a file.
+3. Compare the claim against the evidence. Where the diff does something the stated
+   intent does not cover, or omits something the stated intent implies, that is a
+   watch item.
+4. Be honest about what you could not determine. An empty `unclear` on a large PR is
+   not credible.
+
+## Output contract
+
+Write `<<RUN_DIR>>/brief.json` before returning. The file MUST be a JSON object with
+exactly these five keys:
+
+{
+  "purpose":    string,   // 1-3 sentences: what this PR is for, in your words. Required
+                          //   and non-empty; a brief with no purpose is discarded whole.
+  "changes":    string[], // 3-7 entries: what it actually does, grouped by concern.
+                          //   One clause each, no trailing period needed.
+  "subsystems": [ { "name": string, "role": string } ],
+                          // Code-intelligence derived. `name` is the subsystem, `role`
+                          //   is one clause on what it is responsible for. [] when
+                          //   code intelligence is unavailable.
+  "watchItems": string[], // Where the diff and the stated intent diverge, or where the
+                          //   intent implies a risk the diff does not address. Often
+                          //   empty. See the boundary below.
+  "unclear":    string[]  // What you could not determine from the bundle.
+}
+
+A watch item is not a finding. You do not assign severity, you do not assign risk,
+and you do not recommend a fix. A watch item is a pointer a specialist may escalate
+into a finding in its own domain, with its own risk fields, or dismiss. Write it as
+an observation: "the PR body claims X, but the diff does Y".
+
+Do not add keys. Do not omit keys; write `[]` for an empty list. Do not transcribe
+commit messages or issue titles into the brief: the report reads those from `pr.json`
+directly, and repeating them wastes the specialists' attention.
+
+Return as your final tool result a single line:
+`brief: <N> changes, <M> subsystems, <K> watch items`. Do not include other prose.
+```