@iceinvein/agent-skills 0.1.40 → 0.2.0

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 })
+  }
+})

package/skills/magpie/scripts/__tests__/dedupe-cmd.test.ts

@@ -122,3 +122,190 @@ test('runDedupe with threshold 0 keeps everything', async () => {
   const kept = JSON.parse(await readFile(join(runDir, 'findings.deduped.json'), 'utf8'))
   expect(kept).toHaveLength(1)
 })
+
+test('runDedupe collects sharded focus files', async () => {
+  await writeFile(
+    join(runDir, 'findings', 'security.shard-1.json'),
+    JSON.stringify([f('security-1', 'a.ts', 10, 'hardcoded token in the client', 'security')]),
+  )
+  await writeFile(
+    join(runDir, 'findings', 'security.shard-2.json'),
+    JSON.stringify([f('security-1', 'z.ts', 99, 'missing auth check on the handler', 'security')]),
+  )
+  const exit = await runDedupe(runDir, { threshold: 0 })
+  expect(exit).toBe(0)
+  const out = JSON.parse(await readFile(join(runDir, 'findings.deduped.json'), 'utf8'))
+  expect(out).toHaveLength(2)
+  const ids = out.map((x: { id: string }) => x.id).sort()
+  expect(ids).toEqual(['security-s1-1', 'security-s2-1'])
+})
+
+test('runDedupe leaves unsharded ids untouched', async () => {
+  await writeFile(
+    join(runDir, 'findings', 'bugs.json'),
+    JSON.stringify([f('bugs-1', 'a.ts', 10, 'off by one in the loop bound', 'bugs')]),
+  )
+  const exit = await runDedupe(runDir, { threshold: 0 })
+  expect(exit).toBe(0)
+  const out = JSON.parse(await readFile(join(runDir, 'findings.deduped.json'), 'utf8'))
+  expect(out[0]?.id).toBe('bugs-1')
+})
+
+const LLM_FOCUSES = ['security', 'bugs', 'performance', 'code-smells', 'architecture'] as const
+
+/** A manifest with `count` shards, shaped like the one `shardDiff` writes. */
+async function writeManifest(count: number): Promise<void> {
+  await mkdir(join(runDir, 'shards'), { recursive: true })
+  const shards = Array.from({ length: count }, (_, i) => ({
+    id: i + 1,
+    path: count === 1 ? 'diff.patch' : `shards/shard-${i + 1}.patch`,
+    files: [`src/f${i + 1}.ts`],
+    lines: 10,
+  }))
+  await writeFile(
+    join(runDir, 'shards', 'manifest.json'),
+    JSON.stringify({
+      budget: 6000,
+      maxFiles: 80,
+      totalFiles: count,
+      totalLines: 10 * count,
+      shards,
+    }),
+  )
+}
+
+/** Run dedupe with stdout captured, the way a human at the terminal sees it. */
+async function dedupeCapturingStdout(): Promise<{ exit: number; stdout: string }> {
+  const out: string[] = []
+  const origWrite = process.stdout.write.bind(process.stdout)
+  process.stdout.write = ((s: string) => {
+    out.push(s)
+    return true
+  }) as typeof process.stdout.write
+  try {
+    const exit = await runDedupe(runDir, { threshold: 0 })
+    return { exit, stdout: out.join('') }
+  } finally {
+    process.stdout.write = origWrite
+  }
+}
+
+async function dedupeLogEntry(status: string): Promise<Record<string, unknown> | undefined> {
+  const log = await readFile(join(runDir, 'log.jsonl'), 'utf8')
+  return log
+    .split('\n')
+    .filter(Boolean)
+    .map((l) => JSON.parse(l) as Record<string, unknown>)
+    .find((e) => e.stage === 'dedupe' && e.status === status)
+}
+
+test('runDedupe reports nothing missing when every (focus, shard) file is present', async () => {
+  await writeManifest(3)
+  for (const focus of LLM_FOCUSES) {
+    for (const shard of [1, 2, 3]) {
+      await writeFile(
+        join(runDir, 'findings', `${focus}.shard-${shard}.json`),
+        JSON.stringify([f(`${focus}-1`, `s${shard}.ts`, 1, `${focus} on shard ${shard}`, focus)]),
+      )
+    }
+  }
+  // Setup writes tests.json once for the whole run, never per shard.
+  await writeFile(join(runDir, 'findings', 'tests.json'), JSON.stringify([]))
+  const { exit, stdout } = await dedupeCapturingStdout()
+  expect(exit).toBe(0)
+  expect(stdout).not.toContain('missing')
+  expect(stdout).toContain('15')
+  const done = await dedupeLogEntry('done')
+  expect(done?.coverage).toEqual({ expected: 15, missing: [] })
+})
+
+test('runDedupe names the (focus, shard) pairs that have no findings file', async () => {
+  await writeManifest(2)
+  for (const focus of LLM_FOCUSES) {
+    await writeFile(
+      join(runDir, 'findings', `${focus}.shard-1.json`),
+      JSON.stringify([f(`${focus}-1`, 'a.ts', 1, `${focus} on shard 1`, focus)]),
+    )
+  }
+  // Shard 2 lost security and bugs: two of ten agents never wrote a file.
+  for (const focus of ['performance', 'code-smells', 'architecture']) {
+    await writeFile(
+      join(runDir, 'findings', `${focus}.shard-2.json`),
+      JSON.stringify([f(`${focus}-1`, 'b.ts', 2, `${focus} on shard 2`, focus)]),
+    )
+  }
+  const { exit, stdout } = await dedupeCapturingStdout()
+  expect(exit).toBe(0)
+  expect(stdout).toContain('missing')
+  expect(stdout).toContain('security.shard-2.json')
+  expect(stdout).toContain('bugs.shard-2.json')
+  const done = await dedupeLogEntry('done')
+  expect(done?.coverage).toEqual({
+    expected: 10,
+    missing: ['security.shard-2.json', 'bugs.shard-2.json'],
+  })
+})
+
+test('a single-shard manifest expects the unsharded findings filenames', async () => {
+  await writeManifest(1)
+  for (const focus of ['security', 'bugs', 'performance', 'code-smells']) {
+    await writeFile(
+      join(runDir, 'findings', `${focus}.json`),
+      JSON.stringify([f(`${focus}-1`, 'a.ts', 1, `${focus} finding here`, focus)]),
+    )
+  }
+  const { stdout } = await dedupeCapturingStdout()
+  // Stage 4 takes the unsharded path on a single-shard run, so the expected name
+  // has no shard suffix.
+  expect(stdout).toContain('architecture.json')
+  const done = await dedupeLogEntry('done')
+  expect(done?.coverage).toEqual({ expected: 5, missing: ['architecture.json'] })
+})
+
+test('runDedupe without a manifest reports no coverage at all', async () => {
+  await writeFile(
+    join(runDir, 'findings', 'bugs.json'),
+    JSON.stringify([f('bugs-1', 'a.ts', 10, 'off by one in the loop bound', 'bugs')]),
+  )
+  const { exit, stdout } = await dedupeCapturingStdout()
+  expect(exit).toBe(0)
+  // A run predating the sharder has nothing to reconcile against; behaviour is
+  // exactly as before.
+  expect(stdout).toBe('')
+  const done = await dedupeLogEntry('done')
+  expect(done).toBeDefined()
+  expect(done?.coverage).toBeUndefined()
+})
+
+test('a zero-shard manifest expects nothing (the diff filtered down to nothing)', async () => {
+  await writeManifest(0)
+  const { exit, stdout } = await dedupeCapturingStdout()
+  expect(exit).toBe(0)
+  expect(stdout).toBe('')
+  const done = await dedupeLogEntry('done')
+  expect(done?.coverage).toBeUndefined()
+})
+
+test('a malformed shards/manifest.json is treated as no manifest', async () => {
+  await mkdir(join(runDir, 'shards'), { recursive: true })
+  await writeFile(join(runDir, 'shards', 'manifest.json'), '{ not json')
+  const { exit, stdout } = await dedupeCapturingStdout()
+  expect(exit).toBe(0)
+  expect(stdout).toBe('')
+  const done = await dedupeLogEntry('done')
+  expect(done?.coverage).toBeUndefined()
+})
+
+test('runDedupe still skips files it cannot map to a focus', async () => {
+  await writeFile(join(runDir, 'findings', 'nonsense.json'), JSON.stringify([]))
+  await writeFile(join(runDir, 'findings', 'security.shard-x.json'), JSON.stringify([]))
+  const exit = await runDedupe(runDir)
+  expect(exit).toBe(0)
+  const log = await readFile(join(runDir, 'log.jsonl'), 'utf8')
+  const skips = log
+    .split('\n')
+    .filter(Boolean)
+    .map((l) => JSON.parse(l))
+    .filter((e) => e.status === 'skip' && e.reason === 'unknown-focus')
+  expect(skips.map((s) => s.file).sort()).toEqual(['nonsense.json', 'security.shard-x.json'])
+})

package/skills/magpie/scripts/__tests__/diff-chunks.test.ts

@@ -0,0 +1,51 @@
+import { expect, test } from 'bun:test'
+import { chunkPath, splitFileChunks, splitRawChunks } from '../diff-chunks.ts'
+
+/** A file chunk with `bodyLines` added lines, shaped like a real patch. */
+function chunk(path: string, bodyLines: number): string {
+  const body = Array.from({ length: bodyLines }, (_, i) => `+line ${i}`).join('\n')
+  return [
+    `diff --git a/${path} b/${path}`,
+    'index 0000000..1111111 100644',
+    `--- a/${path}`,
+    `+++ b/${path}`,
+    `@@ -0,0 +1,${bodyLines} @@`,
+    body,
+    '',
+  ].join('\n')
+}
+
+test('splitFileChunks finds one chunk per file with its path and line count', () => {
+  const diff = chunk('src/a.ts', 3) + chunk('src/b.ts', 5)
+  const chunks = splitFileChunks(diff)
+  expect(chunks.map((c) => c.path)).toEqual(['src/a.ts', 'src/b.ts'])
+  expect(chunks[0]?.lines).toBeGreaterThan(3)
+  expect(chunks[0]?.text).toContain('diff --git a/src/a.ts')
+})
+
+test('splitFileChunks returns nothing for an empty diff', () => {
+  expect(splitFileChunks('')).toEqual([])
+  expect(splitFileChunks('\n\n')).toEqual([])
+})
+
+test('splitRawChunks keeps a leading preamble as its own element', () => {
+  const diff = `some preamble text\n${chunk('src/a.ts', 2)}`
+  const raw = splitRawChunks(diff)
+  expect(raw[0]).toBe('some preamble text\n')
+  expect(raw[1]?.startsWith('diff --git ')).toBe(true)
+})
+
+test('chunkPath prefers the b-side path when a rename changes it', () => {
+  const rename = [
+    'diff --git a/old/name.ts b/new/name.ts',
+    'similarity index 100%',
+    'rename from old/name.ts',
+    'rename to new/name.ts',
+    '',
+  ].join('\n')
+  expect(chunkPath(rename)).toBe('new/name.ts')
+})
+
+test('chunkPath returns null when the header cannot be parsed', () => {
+  expect(chunkPath('not a diff header at all')).toBeNull()
+})

package/skills/magpie/scripts/__tests__/filter-diff-preservation.test.ts

@@ -0,0 +1,54 @@
+import { expect, test } from 'bun:test'
+import { filterDiff } from '../path-filter.ts'
+
+// filterDiff's refactor onto the shared diff-chunks module (scripts/diff-chunks.ts)
+// must preserve two branches that scripts/__tests__/path-filter.test.ts's DIFF
+// fixture never exercises, because that fixture always starts with a well-formed
+// `diff --git a/... b/...` header:
+//
+//   1. a leading non-`diff --git` preamble chunk is kept in `filtered`
+//   2. a chunk whose header cannot be parsed is kept in `filtered`
+//
+// These tests assert directly on filterDiff's output for both, so a future edit
+// to diff-chunks.ts that breaks either preservation is caught here rather than
+// resting on a manual code trace.
+
+const VALID_CHUNK = [
+  'diff --git a/src/a.ts b/src/a.ts',
+  'index 1..2 100644',
+  '--- a/src/a.ts',
+  '+++ b/src/a.ts',
+  '@@ -1 +1 @@',
+  '-x',
+  '+y',
+  '',
+].join('\n')
+
+test('filterDiff keeps a leading preamble that appears before the first file header', () => {
+  const preamble = 'Note: this diff was truncated by the transport layer\n'
+  const diff = preamble + VALID_CHUNK
+  const { filtered } = filterDiff(diff, { exclude: [], include: [], useDefaults: false })
+  expect(filtered).toContain('Note: this diff was truncated by the transport layer')
+})
+
+test('filterDiff keeps a chunk whose diff --git header cannot be parsed', () => {
+  // No " b/" separator after the a-side path, so FILE_HEADER cannot match and
+  // chunkPath returns null; filterDiff must keep the chunk rather than drop it.
+  const malformed = [
+    'diff --git a/foo.ts b-badformat',
+    'index 1234567..89abcde 100644',
+    '--- a/foo.ts',
+    '+++ b-badformat',
+    '@@ -1 +1 @@',
+    '-x',
+    '+y',
+    '',
+  ].join('\n')
+  const { filtered, excluded } = filterDiff(malformed, {
+    exclude: ['**/*'],
+    include: [],
+    useDefaults: false,
+  })
+  expect(filtered).toContain('b-badformat')
+  expect(excluded).toEqual([])
+})

package/skills/magpie/scripts/__tests__/findings-files.test.ts

@@ -0,0 +1,35 @@
+import { expect, test } from 'bun:test'
+import { namespaceId, parseFindingsFilename } from '../findings-files.ts'
+
+test('parseFindingsFilename reads an unsharded focus file', () => {
+  expect(parseFindingsFilename('security.json')).toEqual({ focus: 'security', shard: null })
+  expect(parseFindingsFilename('code-smells.json')).toEqual({ focus: 'code-smells', shard: null })
+})
+
+test('parseFindingsFilename reads a sharded focus file', () => {
+  expect(parseFindingsFilename('security.shard-2.json')).toEqual({ focus: 'security', shard: 2 })
+  expect(parseFindingsFilename('architecture.shard-11.json')).toEqual({
+    focus: 'architecture',
+    shard: 11,
+  })
+})
+
+test('parseFindingsFilename rejects names it cannot read', () => {
+  expect(parseFindingsFilename('notes.txt')).toBeNull()
+  expect(parseFindingsFilename('security.shard-x.json')).toBeNull()
+  expect(parseFindingsFilename('security.shard-2.extra.json')).toBeNull()
+  expect(parseFindingsFilename('.json')).toBeNull()
+})
+
+test('namespaceId leaves unsharded ids alone', () => {
+  expect(namespaceId('security-1', 'security', null)).toBe('security-1')
+})
+
+test('namespaceId inserts the shard tag after the focus prefix', () => {
+  expect(namespaceId('security-1', 'security', 2)).toBe('security-s2-1')
+  expect(namespaceId('code-smells-7', 'code-smells', 3)).toBe('code-smells-s3-7')
+})
+
+test('namespaceId prefixes ids that do not carry the focus', () => {
+  expect(namespaceId('finding-1', 'security', 2)).toBe('s2-finding-1')
+})