@iceinvein/agent-skills 0.1.40 → 0.2.0

package/README.md

@@ -24,6 +24,12 @@ Auto-detects Claude Code, Cursor, Codex, or Gemini CLI. Use `--tool claude` to t
 
 ## Skills
 
+### Migration
+
+| Skill | What it does |
+|-------|--------------|
+| **migrate** | Walks a legacy codebase through probe, enumerate, seam, extract, parity, and queue: measured surface coverage, an empirically derived capability seam, cited requirements, a parity plan, and a batch decision queue. Bundles a Bun CLI that enforces the coverage arithmetic and phase ordering instead of trusting it. |
+
 ### Code Architecture
 
 Skills that analyze how code is structured: module boundaries, coupling, complexity, contracts, and evolution over time.
@@ -91,6 +97,14 @@ Skills for producing job application materials that read like a human wrote them
 | **cover-letter-rewrite** | Reviser | Audit-driven targeted rewrite of an existing letter. Focus modes: humanize, align, tighten, structure, tone. Preserves voice where it already works. |
 | **cover-letter-persona** | Voice profile | Reusable writing personas using the NNGroup 4-dimension tone framework (funny-serious, formal-casual, respectful-irreverent, enthusiastic-matter-of-fact) adapted for professional correspondence. |
 
+### Workflow
+
+Skills that shape how work gets done rather than analyzing code.
+
+| Skill | What it does |
+|-------|--------------|
+| **sluice** | Routes work by change shape into four channels (`bypass`, `fast`, `main`, `deep`) and applies only the rules each channel needs, so a one-line fix does not pay the cost of a multi-subsystem build. Six rules live as one-liners in the router; the full treatment sits in references read only on friction. Claude Code only. Conflicts with the superpowers plugin, which requires its own fixed pipeline up front for anything that adds to or changes what the software does, not just code edits; disable superpowers before installing. |
+
 ### Orchestration
 
 Skills that compose the other audit skills into higher-level workflows.
@@ -145,11 +159,13 @@ To pin to the current version, do nothing: skills are not auto-updated. `update`
 
 ## Activation Modes (Claude Code)
 
-Some skills (like `terse`) support activation modes. Pick one at install time:
+Some skills (like `terse` and `sluice`) support activation modes. Pick one at install time:
 
-- **session** (default): invoke the skill manually with `/<skill>` each session
+- **session**: invoke the skill manually with `/<skill>` each session
 - **global**: auto-activate every Claude Code session via a `SessionStart` hook in `.claude/settings.json`
 
+Each skill declares its own default: `terse` defaults to session, `sluice` defaults to global because a router that is not always on does not route.
+
 If a skill declares activation support and you're installing for Claude Code interactively, the CLI prompts you. Use `--activation session` or `--activation global` for scripted installs. `remove` strips the hook cleanly; `update` preserves your choice across version bumps.
 
 ## Supported Tools

package/dist/cli/index.js

@@ -423,8 +423,10 @@ function runScript(scriptPath, cwd) {
   });
   return { ok: result.exitCode === 0, code: result.exitCode ?? 1 };
 }
-function matchesSkillDirective(command, skillName) {
-  return command.includes(`Activate ${skillName} skill`);
+function matchesSkillDirective(hook, skillName) {
+  if (hook.skill !== undefined)
+    return hook.skill === skillName;
+  return hook.command.includes(`Activate ${skillName} skill`);
 }
 async function wireSessionStartHook(settingsPath, skillName, directive) {
   let settings = {};
@@ -438,12 +440,12 @@ async function wireSessionStartHook(settingsPath, skillName, directive) {
   const command = `echo '${directive}'`;
   for (const group of settings.hooks.SessionStart) {
     for (const hook of group.hooks ?? []) {
-      if (matchesSkillDirective(hook.command, skillName))
+      if (matchesSkillDirective(hook, skillName))
         return;
     }
   }
   settings.hooks.SessionStart.push({
-    hooks: [{ type: "command", command }]
+    hooks: [{ type: "command", command, skill: skillName }]
   });
   mkdirSync(dirname(settingsPath), { recursive: true });
   await Bun.write(settingsPath, JSON.stringify(settings, null, 2) + `
@@ -457,7 +459,7 @@ async function unwireSessionStartHook(settingsPath, skillName) {
   if (!sessionStart)
     return;
   const filteredGroups = sessionStart.map((group) => ({
-    hooks: (group.hooks ?? []).filter((h) => !matchesSkillDirective(h.command, skillName))
+    hooks: (group.hooks ?? []).filter((h) => !matchesSkillDirective(h, skillName))
   })).filter((group) => group.hooks.length > 0);
   if (filteredGroups.length === 0) {
     delete settings.hooks.SessionStart;
@@ -865,6 +867,10 @@ async function installSkill(cwd, manifest, files, targetTools, activation) {
   return { ok: true, installed, skipped };
 }
 
+// src/cli/commands/remove.ts
+import { existsSync as existsSync6, statSync as statSync2, unlinkSync as unlinkSync4, rmSync as rmSync4 } from "node:fs";
+import { basename, join as join7 } from "node:path";
+
 // src/cli/github.ts
 var REPO2 = "iceinvein/agent-skills";
 var BRANCH2 = "master";
@@ -969,6 +975,28 @@ function resolveBundlePaths2(entries, bundle) {
 }
 
 // src/cli/commands/remove.ts
+var SHARED_CONFIG_FILES = new Set([
+  ".claude/settings.json",
+  ".claude/settings.local.json",
+  ".cursor/mcp.json",
+  ".gemini/settings.json"
+]);
+function isSharedConfigFile(relPath) {
+  if (SHARED_CONFIG_FILES.has(relPath))
+    return true;
+  const parts = relPath.split("/");
+  const name = basename(relPath);
+  const isConfigName = name === "settings.json" || name === "settings.local.json" || name === "mcp.json";
+  return parts.length === 2 && parts[0].startsWith(".") && isConfigName;
+}
+function removeFileOrDir(fullPath) {
+  const stat = statSync2(fullPath);
+  if (stat.isDirectory()) {
+    rmSync4(fullPath, { recursive: true, force: true });
+  } else {
+    unlinkSync4(fullPath);
+  }
+}
 async function removeSkill(cwd, skillName) {
   const lockfile = await readLockfile(cwd);
   const entry = lockfile.skills[skillName];
@@ -993,18 +1021,28 @@ async function removeSkill(cwd, skillName) {
       });
       await adapter.remove(cwd, manifestResult.manifest, toolFiles);
     }
-  } else {
-    const { unlinkSync: unlinkSync4, existsSync: existsSync6 } = await import("node:fs");
-    const { join: join7 } = await import("node:path");
-    for (const file of entry.files) {
-      const fullPath = join7(cwd, file);
-      if (existsSync6(fullPath)) {
-        unlinkSync4(fullPath);
+    await removeSkillFromLockfile(cwd, skillName);
+    return { ok: true, removed: entry.files };
+  }
+  const removed = [];
+  const warnings = [];
+  for (const file of entry.files) {
+    if (isSharedConfigFile(file)) {
+      const fullPath2 = join7(cwd, file);
+      if (existsSync6(fullPath2)) {
+        await unwireSessionStartHook(fullPath2, skillName);
       }
+      warnings.push(`Manifest unavailable (${manifestResult.error}). Left '${file}' in place, only removing '${skillName}'s SessionStart hook from it; any MCP server entries it owns were not touched.`);
+      continue;
     }
+    const fullPath = join7(cwd, file);
+    if (!existsSync6(fullPath))
+      continue;
+    removeFileOrDir(fullPath);
+    removed.push(file);
   }
   await removeSkillFromLockfile(cwd, skillName);
-  return { ok: true, removed: entry.files };
+  return { ok: true, removed, ...warnings.length > 0 ? { warnings } : {} };
 }
 
 // src/cli/commands/list.ts
@@ -1026,6 +1064,30 @@ async function infoSkill(skillName) {
 }
 
 // src/cli/commands/remove.ts
+import { existsSync as existsSync7, statSync as statSync3, unlinkSync as unlinkSync5, rmSync as rmSync5 } from "node:fs";
+import { basename as basename2, join as join8 } from "node:path";
+var SHARED_CONFIG_FILES2 = new Set([
+  ".claude/settings.json",
+  ".claude/settings.local.json",
+  ".cursor/mcp.json",
+  ".gemini/settings.json"
+]);
+function isSharedConfigFile2(relPath) {
+  if (SHARED_CONFIG_FILES2.has(relPath))
+    return true;
+  const parts = relPath.split("/");
+  const name = basename2(relPath);
+  const isConfigName = name === "settings.json" || name === "settings.local.json" || name === "mcp.json";
+  return parts.length === 2 && parts[0].startsWith(".") && isConfigName;
+}
+function removeFileOrDir2(fullPath) {
+  const stat = statSync3(fullPath);
+  if (stat.isDirectory()) {
+    rmSync5(fullPath, { recursive: true, force: true });
+  } else {
+    unlinkSync5(fullPath);
+  }
+}
 async function removeSkill2(cwd, skillName) {
   const lockfile = await readLockfile(cwd);
   const entry = lockfile.skills[skillName];
@@ -1050,18 +1112,28 @@ async function removeSkill2(cwd, skillName) {
       });
       await adapter.remove(cwd, manifestResult.manifest, toolFiles);
     }
-  } else {
-    const { unlinkSync: unlinkSync4, existsSync: existsSync6 } = await import("node:fs");
-    const { join: join7 } = await import("node:path");
-    for (const file of entry.files) {
-      const fullPath = join7(cwd, file);
-      if (existsSync6(fullPath)) {
-        unlinkSync4(fullPath);
+    await removeSkillFromLockfile(cwd, skillName);
+    return { ok: true, removed: entry.files };
+  }
+  const removed = [];
+  const warnings = [];
+  for (const file of entry.files) {
+    if (isSharedConfigFile2(file)) {
+      const fullPath2 = join8(cwd, file);
+      if (existsSync7(fullPath2)) {
+        await unwireSessionStartHook(fullPath2, skillName);
       }
+      warnings.push(`Manifest unavailable (${manifestResult.error}). Left '${file}' in place, only removing '${skillName}'s SessionStart hook from it; any MCP server entries it owns were not touched.`);
+      continue;
     }
+    const fullPath = join8(cwd, file);
+    if (!existsSync7(fullPath))
+      continue;
+    removeFileOrDir2(fullPath);
+    removed.push(file);
   }
   await removeSkillFromLockfile(cwd, skillName);
-  return { ok: true, removed: entry.files };
+  return { ok: true, removed, ...warnings.length > 0 ? { warnings } : {} };
 }
 
 // src/cli/commands/install.ts
@@ -1131,7 +1203,7 @@ async function updateAllSkills(cwd) {
 }
 
 // src/cli/commands/bump.ts
-import { join as join7 } from "node:path";
+import { join as join9 } from "node:path";
 
 // src/cli/semver.ts
 function bumpVersion(current, level) {
@@ -1152,7 +1224,7 @@ function bumpVersion(current, level) {
 
 // src/cli/commands/bump.ts
 async function bumpSkill(repoRoot, skillName, level) {
-  const manifestPath = join7(repoRoot, "skills", skillName, "skill.json");
+  const manifestPath = join9(repoRoot, "skills", skillName, "skill.json");
   const file = Bun.file(manifestPath);
   if (!await file.exists()) {
     return { ok: false, error: `Skill '${skillName}' not found at skills/${skillName}/skill.json` };
@@ -1223,7 +1295,7 @@ async function bumpAllChanged(repoRoot, level, dryRun) {
     if (skillVersionChanged(repoRoot, skillName, tag))
       continue;
     if (dryRun) {
-      const manifestPath = join7(repoRoot, "skills", skillName, "skill.json");
+      const manifestPath = join9(repoRoot, "skills", skillName, "skill.json");
       const file = Bun.file(manifestPath);
       if (!await file.exists())
         continue;
@@ -1279,10 +1351,10 @@ async function checkForUpdates(cwd) {
 }
 
 // src/cli/lockfile.ts
-import { join as join8 } from "node:path";
+import { join as join10 } from "node:path";
 var LOCKFILE_NAME2 = ".agent-skills.lock";
 async function readLockfile2(cwd) {
-  const path = join8(cwd, LOCKFILE_NAME2);
+  const path = join10(cwd, LOCKFILE_NAME2);
   const file = Bun.file(path);
   if (!await file.exists()) {
     return { skills: {} };
@@ -3162,7 +3234,7 @@ async function pickActivation(skillName, modes) {
 
 // src/cli/index.ts
 import { mkdirSync as mkdirSync4 } from "fs";
-import { join as join9 } from "path";
+import { join as join11 } from "path";
 import { homedir } from "os";
 async function otherScopeSkillCount(currentDir) {
   const home = homedir();
@@ -3266,7 +3338,7 @@ async function resolveTargetTools(installDir, isGlobal, flags) {
   for (const tool of picked) {
     const dir = TOOL_DIRS[tool];
     if (dir)
-      mkdirSync4(join9(installDir, dir), { recursive: true });
+      mkdirSync4(join11(installDir, dir), { recursive: true });
   }
   return picked;
 }
@@ -3370,6 +3442,11 @@ Installing ${names.length} skills...
         console.error(`Error: ${result.error}`);
         process.exit(1);
       }
+      if (result.warnings) {
+        for (const warning of result.warnings) {
+          console.warn(`\u26A0 ${warning}`);
+        }
+      }
       console.log(`\u2713 Removed '${skillName}'`);
       break;
     }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@iceinvein/agent-skills",
-  "version": "0.1.40",
+  "version": "0.2.0",
   "description": "Install agent skills into AI coding tools",
   "author": "iceinvein",
   "license": "MIT",

package/skills/index.json

@@ -219,9 +219,15 @@
   },
   {
     "name": "magpie",
-    "description": "Interactive PR review pipeline. Runs five parallel specialist subagents (security, bugs, performance, code-smells, architecture), dedupes findings, applies a critic rubric, peer-reviews via codex exec (falling back to a Claude second opinion when codex is unavailable), and serves an interactive HTML report for selecting findings to post via gh. Bundles a Bun CLI installed onto PATH via the skill's postinstall step. Use when the user asks to review a GitHub pull request.",
+    "description": "Interactive PR review pipeline. Runs five parallel specialist subagents (security, bugs, performance, code-smells, architecture), dedupes findings, applies a critic rubric, peer-reviews via codex exec (falling back to a Claude second opinion when codex is unavailable), and serves an interactive HTML report for selecting findings to post via gh. Bundles a Bun CLI installed onto PATH via the skill's postinstall step. Use when the user asks to review a GitHub pull request. Splits oversized diffs into budgeted shards and rebuilds the diff from the local clone when gh pr diff refuses it.",
     "type": "prompt",
-    "version": "0.9.0"
+    "version": "0.10.0"
+  },
+  {
+    "name": "migrate",
+    "description": "Source-agnostic legacy migration mapping. Walks a legacy codebase through probe, enumerate, seam, extract, parity, and queue, building an auditable requirements ledger with mandatory citations and a `migrate check` gate in place of self-reported completeness. Use when the user asks to migrate, re-specify, replatform, or map a legacy system onto a new stack, or to resume, check, or report on a mapping run already under way.",
+    "type": "prompt",
+    "version": "0.2.0"
   },
   {
     "name": "module-secret-auditor",
@@ -273,6 +279,12 @@
     ],
     "quick": false
   },
+  {
+    "name": "sluice",
+    "description": "Routes work by change shape into four channels (bypass, fast, main, deep) and applies only the rules each channel needs, so a one-line fix does not pay the cost of a multi-subsystem build. Carries six rules as one-liners in the router and the full treatment in references read only on friction. Claude Code only; conflicts with the superpowers plugin.",
+    "type": "prompt",
+    "version": "1.0.0"
+  },
   {
     "name": "temporal-coupling-detector",
     "description": "Hidden ordering dependency analysis: detect two-phase init, method order dependencies, invisible preconditions, and resource lifecycle violations; fix with types, parameters, and factory patterns",

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