@iceinvein/agent-skills 0.1.39 → 0.2.0

package/skills/magpie/references/specialists.md

@@ -1,9 +1,12 @@
 # Specialist prompts
 
-Stage 3 of the walkthrough dispatches five subagents from this file. Build each prompt from three 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>.
@@ -11,15 +14,76 @@ 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 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.
+6. The brief, when `<RUN_DIR>/brief.json` exists, rendered as:
 
-Replace every `<RUN_DIR>` and `<PR_NUMBER>` with the real values before sending: the subagent has no shell variables from your session, so an unexpanded path means it writes its findings where nothing will read them. Leave `<focus>` as written; the contract tells the subagent to substitute it.
+```
+## What this PR is for
 
-Send all three parts every time. The contract is what makes the output parseable by `magpie dedupe`, and the focus blocks are what keep the five reviews from collapsing into the same generic pass. Do not paraphrase, summarise, or trim either one.
+<purpose>
+
+What it does:
+- <each entry of changes>
+
+Subsystems it lands in:
+- <name>: <role>          (omit this heading when subsystems is empty)
+
+Watch items:
+- <each entry of watchItems>   (omit this heading when watchItems is empty)
+
+Open questions the scout could not resolve:
+- <each entry of unclear>      (omit this heading when unclear is empty)
+
+This brief is the author's claim as understood by a reader who has not reviewed the
+code. It is not ground truth. Where the diff contradicts it, that is a finding in
+your domain, not a correction to the brief. A watch item is a pointer, not a verdict:
+escalate it into a finding with your own risk fields, or leave it alone.
+```
+
+Replace every `<RUN_DIR>` and `<PR_NUMBER>` with the real values before sending: the
+subagent has no shell variables from your session, so an unexpanded path means it
+writes its findings where nothing will read them. Leave `<focus>` as written; the
+contract tells the subagent to substitute it.
+
+Parts 1, 2, and 3 go every time. The contract is what makes the output parseable by
+`magpie dedupe`, and the focus blocks are what keep the five reviews from collapsing
+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):
 
 ```
 {
@@ -66,7 +130,7 @@ Good:
 - `Observation: <one idea, what the diff actually does and where>`
 - `Why it matters: <impact at realistic scale or on a real user path>`
 - `Suggested direction: <one concrete next step, optional if the fix isn't obvious>`
-- `Needs verification: <what you couldn't confirm from the bundle, optional, low/medium severity only>` This labelled paragraph is the only channel for uncertainty: never hedge inside another section, and never raise `severity` to compensate for what you couldn't verify (a blocker/high you cannot stand behind is not a blocker/high). Use the exact `Needs verification:` prefix, not inline phrasing.
+- `Needs verification: <what you couldn't confirm from the bundle, optional, low/medium severity only>` This labelled paragraph is the only channel for uncertainty: never hedge inside another section, and never raise `severity` to compensate for what you couldn't verify (a blocker/high you cannot stand behind is not a blocker/high). Use the exact `Needs verification:` prefix, not inline phrasing. When the codebase-intelligence tools are available and one of them could answer the question, look before you hedge. A question you resolved is not a `Needs verification:` paragraph, it is evidence: cite the file:line you found under `Observation:` and omit the paragraph entirely.
 
 One idea per paragraph. Do not collapse them into a single wall of text. Do not invent extra labels. If a section doesn't apply, omit it. The interactive report and the GitHub comment both parse these labels and render them as section headers, so missing labels degrade the output.
 
@@ -79,6 +143,47 @@ One idea per paragraph. Do not collapse them into a single wall of text. Do not
 
 If you have no findings, write []. Return as your final tool result a single line: `<focus>: <N> findings (<blocker>/<high>/<medium>/<low>)`. Do not include other prose.
 
+## Codebase intelligence
+
+Include this block as part 5 only when the context stage logged `codeIntelligence: true`.
+
+```magpie-codebase-intelligence
+## Codebase intelligence
+
+You have code-intelligence MCP tools against an index of this exact worktree,
+including the PR's own changes. Call `bind_workspace` with `<RUN_DIR>/worktree` before
+your first query.
+
+These answer the cross-file questions a diff cannot:
+
+- `ask_code`: a natural-language question, answered with grounded evidence. Start here
+  when you do not yet know which symbol to pivot on.
+- `find_references` / `get_call_hierarchy`: who calls this, and what does it call.
+  Use for reachability: is the path you are worried about actually reachable.
+- `find_affected_code`: the full reverse-dependency set for a symbol. Use for blast
+  radius before claiming a change is safe or unsafe.
+- `trace_data_flow`: follow a value from its origin to where it is used. Use to
+  confirm that untrusted input actually reaches the sink you are worried about.
+- `search_code`: hybrid semantic and literal search. Use to check whether something
+  already exists before claiming the PR should add it.
+- `get_definition`: the body of a symbol the diff calls but does not show.
+- `explore_dependency_graph`: module-level edges. Use for cycles and boundaries.
+- `find_tests_for_symbol`: whether the symbol you are flagging is covered.
+
+Rules:
+
+- Cite what you find as ordinary `file:line` evidence under `Observation:`. Do not
+  say "code intelligence told me"; the location is the evidence.
+- Verify before you report. A finding you could have refuted with one query and did
+  not is worse than no finding: it costs the author trust and the critic a slot.
+- Verify before you hedge. If a tool can answer the question, a `Needs verification:`
+  paragraph is a failure to look, not honest uncertainty.
+- If a tool returns `indexing_in_progress`, finish reading the diff and retry once.
+  If it is still not ready, review from the diff and worktree alone. Do not block.
+- Never call `approve_indexing`. Never call `refresh_index`. Starting a full index is
+  a consent-gated operation that is not yours to start.
+```
+
 ## Focus blocks
 
 ### security
@@ -132,6 +237,7 @@ For each potential finding:
 2. Identify the trust boundary: is this crossing from untrusted to trusted context?
 3. Assess exploitability: can an attacker realistically trigger this?
 4. Evaluate impact: what's the blast radius if exploited?
+5. Confirm the flow with `trace_data_flow` from the entry point to the sink before reporting. A taint path you asserted but did not trace is a guess.
 
 **Risk guide:**
 - blocker: Realistic path to remote code execution, auth bypass, data breach, or privilege escalation
@@ -196,6 +302,8 @@ For each potential bug:
 3. What's the consequence: crash, data corruption, silent wrong behavior?
 4. Is there an existing guard I'm not seeing?
 
+Question 4 is answerable: `get_call_hierarchy` on the changed symbol shows every caller, and `find_references` shows where the guard would have to live. Check before you file.
+
 **Risk guide:**
 - blocker: Data loss, data corruption, broken auth/session behavior, or consistently crashing a major workflow
 - high: Reachable incorrect behavior, race, resource leak, or crash in a meaningful workflow
@@ -254,6 +362,7 @@ For each potential issue:
 2. How often does this code path execute? (once on init vs. every keystroke)
 3. What's the measurable impact? (milliseconds vs. seconds)
 4. Is the optimization worth the complexity cost?
+5. Establish the call frequency with `find_affected_code` before claiming a path is hot. "Called from one cold init path" and "called per keystroke" are different findings.
 
 **Risk guide:**
 - blocker: Change can make a major workflow unusable or cause unbounded production resource exhaustion
@@ -315,6 +424,7 @@ For each potential smell:
 2. Confirm the smell is introduced or materially worsened by this PR, not merely pre-existing nearby code.
 3. Suggest the smallest refactor that fits the surrounding codebase patterns.
 4. Weigh the cost: do not ask for a new abstraction unless it reduces real duplication, coupling, or reasoning burden now.
+5. Before claiming the PR duplicates something or should reuse an existing helper, find it with `search_code`. Name the file:line of the thing it should have reused, or do not make the claim.
 
 **Risk guide:**
 - blocker: Smell creates a high-risk maintenance trap likely to cause defects across modules soon
@@ -373,6 +483,7 @@ For each potential issue:
 2. Is this coupling necessary or incidental?
 3. Would a new team member understand where to make changes?
 4. Is this over-engineered for the current requirements, or appropriately future-proofed?
+5. Confirm boundary and cycle claims with `explore_dependency_graph` on the touched modules. A cycle you inferred from import statements in the diff may already be broken by an interface you cannot see.
 
 **Risk guide:**
 - blocker: Change introduces a serious boundary violation or contract break likely to cascade across subsystems

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