@iceinvein/agent-skills 0.1.35 → 0.1.37

package/package.json

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

package/skills/index.json

@@ -219,9 +219,9 @@
   },
   {
     "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, 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.",
     "type": "prompt",
-    "version": "0.5.1"
+    "version": "0.7.0"
   },
   {
     "name": "module-secret-auditor",

package/skills/magpie/README.md

@@ -4,14 +4,14 @@ Interactive Claude Code skill that runs a multi-stage PR review pipeline inside
 
 ## What it does
 
-Given a GitHub PR number, dispatches five specialist subagents in parallel (security, bugs, performance, code-smells, architecture), dedupes their findings, applies a critic rubric, peer-reviews via `codex exec`, serves an interactive HTML report, and posts the findings the user selects via `gh`.
+Given a GitHub PR number, dispatches five specialist subagents in parallel (security, bugs, performance, code-smells, architecture), dedupes their findings, applies a critic rubric, peer-reviews via `codex exec` (falling back to a Claude second-opinion subagent when codex is unavailable), serves an interactive HTML report, and posts the findings the user selects via `gh`.
 
 ## Requirements
 
 - `bun` on PATH (https://bun.sh)
 - `gh` on PATH, authenticated (`gh auth status`)
-- `codex` on PATH, authenticated
 - `git` on PATH
+- `codex` on PATH, authenticated (optional; if absent the peer-review stage falls back to a Claude second-opinion subagent)
 
 ## Install
 

package/skills/magpie/SKILL.md

@@ -1,13 +1,13 @@
 ---
 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, and serves an interactive HTML report for selecting findings to post via gh. 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. Use when the user asks to review a GitHub pull request.
 ---
 
 # Magpie
 
 ## Prerequisites
 
-The skill pre-flights `bun`, `gh`, `codex`, `git`. If any are missing the run aborts with a single install hint line.
+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"]}`).
 
 ## Stage walkthrough
 
@@ -58,7 +58,7 @@ magpie render "$RUN_DIR" progress
 
 Dispatch the five specialist subagents in a single message using five Agent tool calls in parallel. For each focus in (security, bugs, performance, code-smells, architecture), the prompt is:
 
-```
+````
 <specialist block for focus from this SKILL.md>
 
 You are reviewing PR #<PR_NUMBER>.
@@ -95,6 +95,7 @@ Write findings to $RUN_DIR/findings/<focus>.json before returning. The file MUST
 - `severity`, `risk.impact`, `risk.confidence` use category names (e.g. `high`, `low`), not sentences.
 - `risk.likelihood` describes frequency, not impact. Valid values are exactly `likely`, `possible`, `edge-case`, `unknown`. NEVER use `high`/`medium`/`low` here (those are likelihood-as-impact and will be auto-corrected, but pick the right axis).
 - `risk.action` is the disposition tag, not the recommendation text. Valid values are exactly `must-fix`, `should-fix`, `consider`, `optional`. The recommendation prose belongs in `description` under `Suggested direction:`, never in `risk.action`.
+- Keep `severity` coherent with `risk`. `severity` is the headline label: use `blocker`/`high` only with `risk.impact` of `critical`/`high` and `risk.action` of `must-fix`/`should-fix`. A `low` severity paired with `must-fix`, or a `blocker` paired with `optional`, is contradictory. The 0-10 score that gates the drop threshold is derived from `risk`, not from `severity`, so an inflated `severity` on a weak `risk` is still dropped. Set `risk` accurately rather than leaning on `severity`.
 
 Bad (will be silently coerced, do not rely on this):
 ```
@@ -111,7 +112,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>`
+- `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.
 
 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.
 
@@ -123,7 +124,7 @@ One idea per paragraph. Do not collapse them into a single wall of text. Do not
 - Wrapping the code in a `` ``` `` fence inside `body` is tolerated (the poster hoists the inner code out), but bare code is preferred.
 
 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.
-```
+````
 
 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`.)
 
@@ -143,21 +144,27 @@ Re-render progress.
 
 ### 5. Critic
 
-Read `$RUN_DIR/findings.deduped.json`. Apply the critic rubric from this SKILL.md verbatim (one verdict per finding). Write the kept subset to `$RUN_DIR/findings.kept.json`. Append `{stage: critic, status: done}` and re-render progress.
+Read `$RUN_DIR/findings.deduped.json`. Substitute both placeholders in the critic rubric (the compact candidate list including each finding's `onChangedLine`, and the `<<DIFF_EXCERPT>>` hunks for the referenced files), then apply the rubric verbatim (one verdict per finding). Write the kept subset to `$RUN_DIR/findings.kept.json`. Append `{stage: critic, status: done}` and re-render progress.
 
 ### 6. Peer review
 
-Build the peer-review prompt by taking the `magpie-peer-review` block from this SKILL.md and substituting the placeholders listed in its `## Substitute before use` preamble. Write the substituted prompt to `$RUN_DIR/peer-prompt.md`. Then run codex with the prompt piped on stdin:
+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.
+
+Build the peer-review prompt first: take the `magpie-peer-review` block from this SKILL.md and substitute the placeholders listed in its `## Substitute before use` preamble. Write the substituted prompt to `$RUN_DIR/peer-prompt.md`.
+
+**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 exec < "$RUN_DIR/peer-prompt.md" > "$RUN_DIR/peer.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` for record-keeping.
+`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.
 
-If codex returns non-zero, ask the user once: "Codex peer-review failed: <stderr>. Skip peer-review and proceed, or abort?". On "skip", copy `findings.kept.json` to `findings.final.json` and add `{stage: peer-review, status: skipped}`.
+If codex returns non-zero, do not abort: fall through to the Claude path and record `{stage: peer-review, provider: codex, status: error}` first.
 
-Otherwise parse the verdicts JSON, apply them (drop / downgrade), and write `findings.final.json`. Append `{stage: peer-review, status: done}` and re-render progress.
+**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 this SKILL.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}`.
+
+**Apply the verdicts (both paths).** Parse the verdicts JSON and apply the `update` / `add` entries (an empty array means no change), then write `findings.final.json`. Re-render progress.
 
 ### 7. Report
 
@@ -267,7 +274,9 @@ For each potential finding:
 - medium: Defense-in-depth concern or validation gap with limited or uncertain exploitability
 - low: Minor hardening opportunity with low impact
 
-Report only credible concerns grounded in code shown. If a concern depends on context you can't see, note it as "needs verification" in the description. Do not invent vulnerabilities without evidence.
+Report only credible concerns grounded in code shown. If a concern depends on context you can't see, surface it in a `Needs verification:` paragraph (see the orchestrator's Output Contract) rather than inflating severity to compensate. Do not invent vulnerabilities without evidence.
+
+Boundary with Architecture: report missing input validation here when it enables an attack (injection, path traversal, SSRF, auth bypass). Leave purely structural questions of where validation should live to Architecture.
 
 Use the JSON schema defined in the orchestrator's `## Output Contract` block; do not invent fields.
 ```
@@ -328,7 +337,9 @@ For each potential bug:
 - medium: Edge-case bug or missing guard with limited blast radius
 - low: Very small correctness cleanup with low user impact
 
-Prioritize bugs that cause silent wrong behavior over those that crash (crashes are at least visible). Flag "needs verification" when you can't determine reachability from the diff alone.
+Prioritize bugs that cause silent wrong behavior over those that crash (crashes are at least visible). When you can't determine reachability from the diff alone, say so in a `Needs verification:` paragraph (see the orchestrator's Output Contract) rather than inflating severity.
+
+Boundary with Performance: report leaks, unbounded growth, and missing cleanup here only when the primary consequence is incorrect behavior, a crash, or resource exhaustion that breaks a workflow. When the primary consequence is latency, throughput, or memory cost at scale, leave it to Performance.
 
 Use the JSON schema defined in the orchestrator's `## Output Contract` block; do not invent fields.
 ```
@@ -387,6 +398,8 @@ For each potential issue:
 
 Only flag issues that would have noticeable impact at realistic scale. Don't suggest micro-optimizations on cold paths.
 
+Boundary with Bugs: focus on cost at realistic scale. Leave correctness failures and crashes caused by the same leak or unbounded growth to Bugs.
+
 Use the JSON schema defined in the orchestrator's `## Output Contract` block; do not invent fields.
 ```
 
@@ -504,6 +517,8 @@ For each potential issue:
 
 Boundary with Code Smells: focus on module boundaries, public contracts, ownership, and system-level data flow. Leave local implementation smells such as duplicate branches, long functions, and primitive obsession to Code Smells.
 
+Boundary with Security: flag validation gaps as design/contract issues (where validation belongs, which boundary should enforce it). Leave exploitability assessment to Security.
+
 Focus on design decisions introduced or materially worsened by this PR that affect the long-term health of the codebase. Don't flag things that are "technically impure" but work well in practice.
 
 Use the JSON schema defined in the orchestrator's `## Output Contract` block; do not invent fields.
@@ -515,24 +530,24 @@ The main agent runs this in-conversation against `findings.deduped.json` and wri
 
 ## Substitute before use
 
-The block below contains one placeholder. Replace it before running the rubric.
+The block below contains two placeholders. Replace both before running the rubric.
 
-- `<<DEDUPED_FINDINGS_COMPACT>>` — pretty-printed JSON array of the deduped candidates with only the fields the critic needs. Build with:
+- `<<DEDUPED_FINDINGS_COMPACT>>` — pretty-printed JSON array of the deduped candidates with only the fields the critic needs. Each candidate carries `onChangedLine` (set deterministically during dedupe: `true` = anchored inside a changed hunk, `false` = anchored on code the PR did not touch, `null` = not anchorable). Build with:
   ```
-  jq '[.[] | {id, file, line, severity, risk, domain, title, description}]' "$RUN_DIR/findings.deduped.json"
+  jq '[.[] | {id, file, line, onChangedLine, severity, risk, domain, title, description}]' "$RUN_DIR/findings.deduped.json"
   ```
+- `<<DIFF_EXCERPT>>` — the diff hunks for the files referenced by the candidates. For small PRs the full `diff.patch` is fine; for larger PRs, narrow to the files named in the candidate set.
 
 ````magpie-critic
-You are a senior code reviewer auditing a list of candidate review findings produced by other agents on a pull request. Your only job is to keep the findings that a busy reviewer would genuinely thank you for surfacing, and drop the rest. You do not see the diff itself; you only see what the candidate finding claims, its anchor, and its risk fields. Treat each candidate skeptically.
+You are a senior code reviewer auditing a list of candidate review findings produced by other agents on a pull request. Your only job is to keep the findings that a busy reviewer would genuinely thank you for surfacing, and drop the rest. You see each candidate's claim, anchor, and risk fields, plus the diff hunks around them. Use the hunks only to validate or refute the candidate in front of you: do not surface new findings or broaden the review (adding issues is the peer-review stage's job). Treat each candidate skeptically.
 
 Drop a finding if any of the following hold:
 - The description sounds speculative, hedged, or "needs verification" without strong evidence in the title or anchor.
 - The finding is a stylistic preference, micro-optimization, or "nice to have" cleanup with no concrete user or maintenance impact.
-- The finding is a pre-existing concern not introduced by the PR.
-- The finding is a theoretical risk that requires unlikely preconditions, or defense-in-depth on already-defended code.
+- Its `onChangedLine` is `false` and the description does not explain why the PR newly triggers a pre-existing concern (i.e. it is anchored on code this PR did not change).
+- The finding is a theoretical risk that requires unlikely preconditions, or defense-in-depth on code the supplied hunks show is already guarded.
 - The finding belongs to a category the repository's linter already enforces (naming, formatting, unused imports).
 - The finding is on a test file or a generated/vendored file unless it materially affects test correctness.
-- The finding duplicates another candidate at a similar anchor and is the weaker version.
 
 Keep a finding if it points to a concrete defect on a changed line, with enough specificity that a reviewer could decide to act on it without re-reading the entire PR.
 
@@ -560,17 +575,18 @@ Output every candidate exactly once. Do not invent ids. Do not output anything o
 ```json
 <<DEDUPED_FINDINGS_COMPACT>>
 ```
+
+## Diff Hunks For Those Candidates
+```diff
+<<DIFF_EXCERPT>>
+```
 ````
 
 ## Peer-review prompt
 
-The agent substitutes the placeholders below, writes the result to `<run-dir>/peer-prompt.md`, then runs:
-
-```
-codex exec < <run-dir>/peer-prompt.md > <run-dir>/peer.out
-```
+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.
 
-Then extract the fenced `review-peer-review` block from `peer.out` and save it to `<run-dir>/peer.json`.
+Either way, extract the fenced `review-peer-review` block from `peer.out` and save it to `<run-dir>/peer.json`.
 
 ## Substitute before use
 
@@ -638,6 +654,18 @@ 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.
+
+````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.
+
+Ground every verdict in the diff hunks provided, not in the prose of the finding. For each finding, independently re-derive whether the described problem is actually present on the cited line before you accept it. If a finding's reasoning does not hold against the hunk, or the anchor is wrong, or the severity is off, say so with "update"; if you can see a clearly actionable adjacent issue in the same hunks that was missed, add it. When the existing finding survives your own check unchanged, leave it alone.
+
+Hold yourself to the exact same output contract and constraints described below. Return [] when the review is already sound.
+````
+
 ## Resuming a crashed run
 
 If the user re-invokes the skill and a `$RUN_DIR/state/server-info` exists:

package/skills/magpie/scripts/__tests__/changed-lines.test.ts

@@ -0,0 +1,66 @@
+import { describe, expect, test } from 'bun:test'
+import { annotateChangedLines } from '../changed-lines.ts'
+import type { ReviewFinding } from '../types.ts'
+
+const SAMPLE = `diff --git a/src/a.ts b/src/a.ts
+index abc..def 100644
+--- a/src/a.ts
++++ b/src/a.ts
+@@ -1,3 +1,4 @@
+ line1
+-old
++new
++added
+ line3
+`
+
+function finding(overrides: Partial<ReviewFinding>): ReviewFinding {
+  return {
+    id: 'x-1',
+    file: 'src/a.ts',
+    line: 2,
+    severity: 'high',
+    risk: { impact: 'high', likelihood: 'likely', confidence: 'high', action: 'must-fix' },
+    title: 't',
+    description: 'd',
+    domain: 'bugs',
+    ...overrides,
+  }
+}
+
+describe('annotateChangedLines', () => {
+  test('flags an anchor inside a changed hunk as true', () => {
+    const [f] = annotateChangedLines([finding({ line: 3 })], SAMPLE)
+    expect(f?.onChangedLine).toBe(true)
+  })
+
+  test('flags a context line inside a hunk as true', () => {
+    const [f] = annotateChangedLines([finding({ line: 4 })], SAMPLE)
+    expect(f?.onChangedLine).toBe(true)
+  })
+
+  test('flags an anchor outside any hunk as false', () => {
+    const [f] = annotateChangedLines([finding({ line: 99 })], SAMPLE)
+    expect(f?.onChangedLine).toBe(false)
+  })
+
+  test('flags a finding whose file is absent from the diff as false', () => {
+    const [f] = annotateChangedLines([finding({ file: 'src/other.ts', line: 1 })], SAMPLE)
+    expect(f?.onChangedLine).toBe(false)
+  })
+
+  test('leaves unanchorable findings null', () => {
+    const [f] = annotateChangedLines([finding({ line: null })], SAMPLE)
+    expect(f?.onChangedLine).toBeNull()
+  })
+
+  test('leaves everything null when the diff is unavailable', () => {
+    const [f] = annotateChangedLines([finding({ line: 3 })], '')
+    expect(f?.onChangedLine).toBeNull()
+  })
+
+  test('matches paths that differ only by a b/ prefix', () => {
+    const [f] = annotateChangedLines([finding({ file: 'b/src/a.ts', line: 2 })], SAMPLE)
+    expect(f?.onChangedLine).toBe(true)
+  })
+})

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

@@ -1,5 +1,10 @@
 import { describe, expect, test } from 'bun:test'
-import { filePathMatches, parseUnifiedDiffToHunks, splitDiffByFile } from '../diff-utils.ts'
+import {
+  buildNewSideLineIndex,
+  filePathMatches,
+  parseUnifiedDiffToHunks,
+  splitDiffByFile,
+} from '../diff-utils.ts'
 
 const SAMPLE = `diff --git a/src/a.ts b/src/a.ts
 index abc..def 100644
@@ -93,6 +98,20 @@ describe('splitDiffByFile', () => {
   })
 })
 
+describe('buildNewSideLineIndex', () => {
+  test('collects added and context new-side line numbers per file', () => {
+    const index = buildNewSideLineIndex(SAMPLE)
+    // src/a.ts: context(1), added(2), added(3), context(4). Removed line has no new-side number.
+    expect([...(index.get('src/a.ts') ?? [])].sort((a, b) => a - b)).toEqual([1, 2, 3, 4])
+    // src/b.ts: two added lines.
+    expect([...(index.get('src/b.ts') ?? [])].sort((a, b) => a - b)).toEqual([1, 2])
+  })
+
+  test('returns empty map for empty input', () => {
+    expect(buildNewSideLineIndex('').size).toBe(0)
+  })
+})
+
 describe('filePathMatches', () => {
   test('exact match', () => {
     expect(filePathMatches('src/a.ts', 'src/a.ts')).toBe(true)

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

@@ -10,18 +10,30 @@ test('returns ok when all binaries resolve', async () => {
   })
   expect(result.ok).toBe(true)
   expect(result.missing).toEqual([])
+  expect(result.missingOptional).toEqual([])
 })
 
-test('returns missing list when binaries do not resolve', async () => {
+test('returns missing list when required binaries do not resolve', async () => {
   const result = await preflight({
     bun: 'bun',
     gh: 'definitely-not-a-binary-xyz123',
-    codex: 'also-not-real-abc456',
+    codex: 'echo',
     git: 'git',
   })
   expect(result.ok).toBe(false)
   expect(result.missing).toContain('gh')
-  expect(result.missing).toContain('codex')
+})
+
+test('missing codex is optional and does not abort the run', async () => {
+  const result = await preflight({
+    bun: 'bun',
+    gh: 'echo',
+    codex: 'also-not-real-abc456',
+    git: 'git',
+  })
+  expect(result.ok).toBe(true)
+  expect(result.missing).not.toContain('codex')
+  expect(result.missingOptional).toContain('codex')
 })
 
 test('renderInstallHint produces a single-line message per missing tool', () => {

package/skills/magpie/scripts/__tests__/render-progress.test.ts

@@ -92,7 +92,7 @@ test('each pipeline stage exposes a short sublabel so first-timers can learn wha
   })
   expect(html).toContain('class="hint"')
   expect(html).toContain('five reviewers in parallel')
-  expect(html).toContain('second opinion via codex')
+  expect(html).toContain('independent second opinion')
 })
 
 test('renderProgressHtml includes the archived banner element', () => {

package/skills/magpie/scripts/changed-lines.ts

@@ -0,0 +1,36 @@
+import { buildNewSideLineIndex, filePathMatches } from './diff-utils.ts'
+import type { ReviewFinding } from './types.ts'
+
+function lookup(index: Map<string, Set<number>>, file: string): Set<number> | undefined {
+  const direct = index.get(file)
+  if (direct) return direct
+  for (const [key, set] of index) {
+    if (filePathMatches(key, file)) return set
+  }
+  return undefined
+}
+
+/**
+ * Annotate each finding with `onChangedLine`: whether its anchor falls on a line
+ * this PR added or kept as context within a changed hunk.
+ *
+ * - `true`  — anchor is inside a changed hunk (plausibly introduced/triggered here).
+ * - `false` — anchor is on code this PR did not touch (pre-existing / unrelated).
+ * - `null`  — undecidable: the finding has no line anchor, or the diff is
+ *   unavailable (e.g. archived-run replay).
+ *
+ * This is a deterministic input for the critic so it never has to eyeball
+ * "was this introduced by the PR?" from prose alone.
+ */
+export function annotateChangedLines(findings: ReviewFinding[], diff: string): ReviewFinding[] {
+  if (!diff.trim()) {
+    return findings.map((f) => ({ ...f, onChangedLine: null }))
+  }
+  const index = buildNewSideLineIndex(diff)
+  return findings.map((f) => {
+    if (f.line == null || !f.file) return { ...f, onChangedLine: null }
+    const set = lookup(index, f.file)
+    if (!set) return { ...f, onChangedLine: false }
+    return { ...f, onChangedLine: set.has(f.line) }
+  })
+}

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

@@ -1,5 +1,6 @@
 import { appendFile, readdir, readFile, writeFile } from 'node:fs/promises'
 import { join } from 'node:path'
+import { annotateChangedLines } from './changed-lines.ts'
 import { deduplicateFindings } from './dedupe.ts'
 import { verifyEvidence } from './evidence-filter.ts'
 import { DEFAULT_THRESHOLD, scoreRisk } from './score.ts'
@@ -77,8 +78,15 @@ export async function runDedupe(runDir: string, options: RunDedupeOptions = {}):
   const deduped = deduplicateFindings(collected)
   const scored = deduped.map((f) => ({ ...f, score: scoreRisk(f.risk) }))
   const evidence = await verifyEvidence(scored, join(runDir, 'worktree'))
-  const aboveThreshold = evidence.kept.filter((f) => (f.score ?? 0) >= threshold)
-  const belowThreshold = evidence.kept.filter((f) => (f.score ?? 0) < threshold)
+  let diff = ''
+  try {
+    diff = await readFile(join(runDir, 'diff.patch'), 'utf8')
+  } catch {
+    diff = ''
+  }
+  const annotated = annotateChangedLines(evidence.kept, diff)
+  const aboveThreshold = annotated.filter((f) => (f.score ?? 0) >= threshold)
+  const belowThreshold = annotated.filter((f) => (f.score ?? 0) < threshold)
   await writeFile(
     join(runDir, 'findings.deduped.json'),
     `${JSON.stringify(aboveThreshold, null, 2)}\n`,

package/skills/magpie/scripts/diff-utils.ts

@@ -76,6 +76,31 @@ export function parseUnifiedDiffToHunks(diff: string): DiffHunk[] {
   return hunks
 }
 
+/**
+ * Per-file set of new-side (RIGHT) line numbers that fall within a changed hunk
+ * (added or context lines). These are the lines GitHub accepts as inline-comment
+ * anchors, and also the lines we treat as "within the PR's diff" when deciding
+ * whether a finding is anchored on changed code vs pre-existing/unrelated code.
+ * Keyed by the post-image (`b/`) file path.
+ */
+export function buildNewSideLineIndex(diff: string): Map<string, Set<number>> {
+  const result = new Map<string, Set<number>>()
+  if (!diff) return result
+  for (const [file, chunk] of splitDiffByFile(diff)) {
+    const hunks = parseUnifiedDiffToHunks(chunk)
+    const set = new Set<number>()
+    for (const h of hunks) {
+      for (const l of h.lines) {
+        if (l.newLineNo != null && (l.type === 'added' || l.type === 'context')) {
+          set.add(l.newLineNo)
+        }
+      }
+    }
+    result.set(file, set)
+  }
+  return result
+}
+
 export function splitDiffByFile(diff: string): Map<string, string> {
   const m = new Map<string, string>()
   if (!diff) return m
@@ -83,7 +108,7 @@ export function splitDiffByFile(diff: string): Map<string, string> {
   for (const chunk of chunks) {
     if (!chunk.startsWith('diff --git ')) continue
     const headerMatch = chunk.match(FILE_HEADER)
-    if (!headerMatch || !headerMatch[2]) continue
+    if (!headerMatch?.[2]) continue
     m.set(headerMatch[2], chunk)
   }
   return m

package/skills/magpie/scripts/post-cmd.ts

@@ -1,7 +1,7 @@
 import { createHash } from 'node:crypto'
 import { appendFile, readFile, writeFile } from 'node:fs/promises'
 import { join } from 'node:path'
-import { parseUnifiedDiffToHunks, splitDiffByFile } from './diff-utils.ts'
+import { buildNewSideLineIndex } from './diff-utils.ts'
 import { formatFindingDescriptionMarkdown } from './finding-description.ts'
 import {
   type FocusId,
@@ -11,29 +11,6 @@ import {
   type Severity,
 } from './types.ts'
 
-/**
- * Build a per-file set of RIGHT-side line numbers that GitHub's PR Reviews API
- * will accept as inline-comment anchors (added or context lines within hunks).
- * Returns an empty map when the diff is empty/unavailable.
- */
-function buildValidRightLines(diff: string): Map<string, Set<number>> {
-  const result = new Map<string, Set<number>>()
-  if (!diff) return result
-  for (const [file, chunk] of splitDiffByFile(diff)) {
-    const hunks = parseUnifiedDiffToHunks(chunk)
-    const set = new Set<number>()
-    for (const h of hunks) {
-      for (const l of h.lines) {
-        if (l.newLineNo != null && (l.type === 'added' || l.type === 'context')) {
-          set.add(l.newLineNo)
-        }
-      }
-    }
-    result.set(file, set)
-  }
-  return result
-}
-
 export type PostInput = {
   runDir: string
   findingIds: string[]
@@ -555,7 +532,7 @@ export async function postFindingsAsReview(input: PostReviewInput): Promise<Post
   let validRightLines: Map<string, Set<number>> | null = null
   try {
     const diff = await readFile(join(input.runDir, 'diff.patch'), 'utf8')
-    validRightLines = buildValidRightLines(diff)
+    validRightLines = buildNewSideLineIndex(diff)
   } catch {
     // diff.patch absent (archived/legacy runs); skip validation and trust caller.
     validRightLines = null

package/skills/magpie/scripts/preflight.ts

@@ -7,10 +7,17 @@ export type Deps = {
 
 export type PreflightResult = {
   ok: boolean
+  /** Required binaries that did not resolve; any entry here aborts the run. */
   missing: string[]
+  /** Optional binaries that did not resolve; these only degrade features, they never abort. */
+  missingOptional: string[]
   resolved: Record<keyof Deps, string | null>
 }
 
+// codex only powers the optional peer-review stage; a missing codex degrades that
+// stage to skipped rather than blocking the whole run.
+const OPTIONAL_DEPS: ReadonlySet<keyof Deps> = new Set<keyof Deps>(['codex'])
+
 export async function preflight(deps: Deps): Promise<PreflightResult> {
   const resolved: Record<keyof Deps, string | null> = {
     bun: Bun.which(deps.bun),
@@ -18,8 +25,12 @@ export async function preflight(deps: Deps): Promise<PreflightResult> {
     codex: Bun.which(deps.codex),
     git: Bun.which(deps.git),
   }
-  const missing = (Object.keys(resolved) as Array<keyof Deps>).filter((k) => resolved[k] === null)
-  return { ok: missing.length === 0, missing, resolved }
+  const unresolved = (Object.keys(resolved) as Array<keyof Deps>).filter(
+    (k) => resolved[k] === null,
+  )
+  const missing = unresolved.filter((k) => !OPTIONAL_DEPS.has(k))
+  const missingOptional = unresolved.filter((k) => OPTIONAL_DEPS.has(k))
+  return { ok: missing.length === 0, missing, missingOptional, resolved }
 }
 
 const HINTS: Record<string, string> = {

package/skills/magpie/scripts/render-progress.ts

@@ -19,7 +19,7 @@ const STAGE_HINT: Record<StageId, string> = {
   specialists: 'five reviewers in parallel',
   dedupe: 'merge overlaps',
   critic: 'keep the high-signal ones',
-  'peer-review': 'second opinion via codex',
+  'peer-review': 'independent second opinion',
   report: 'render this page',
   post: 'comment on the PR',
 }
@@ -30,7 +30,7 @@ const STAGE_NOW_DOING: Record<StageId, string> = {
   specialists: 'Five reviewers reading the diff in parallel',
   dedupe: 'Merging overlapping findings',
   critic: 'Keeping only the high-signal ones',
-  'peer-review': 'Asking a second opinion via codex',
+  'peer-review': 'Getting an independent second opinion',
   report: 'Composing the report page',
   post: 'Ready to post; switch tabs to pick findings',
 }

package/skills/magpie/scripts/setup-cmd.ts

@@ -32,7 +32,18 @@ export async function runSetup(input: RunSetupInput): Promise<number> {
     await cleanup(input.runDir)
     return 3
   }
-  await logLine(input.runDir, { stage: 'preflight', status: 'done' })
+  if (preResult.missingOptional.length > 0) {
+    await logLine(input.runDir, {
+      stage: 'preflight',
+      status: 'done',
+      missingOptional: preResult.missingOptional,
+    })
+    process.stderr.write(
+      `magpie: optional dependency unavailable, some stages will be skipped:\n${renderInstallHint(preResult.missingOptional)}\n`,
+    )
+  } else {
+    await logLine(input.runDir, { stage: 'preflight', status: 'done' })
+  }
 
   const fetched = await fetchPr({
     ghBin: deps.gh,

package/skills/magpie/scripts/types.ts

@@ -54,6 +54,11 @@ export type ReviewFinding = {
   mergedFrom?: MergedFromEntry[]
   /** Derived 0-10 importance score from risk fields. Populated during dedupe. */
   score?: number
+  /**
+   * Whether the anchor sits on a line this PR changed. Populated during dedupe
+   * from the diff; `null` when not anchorable or the diff is unavailable.
+   */
+  onChangedLine?: boolean | null
 }
 
 const SEVERITY_SYNONYMS: Record<string, Severity> = {
@@ -309,6 +314,9 @@ export function parseFinding(raw: unknown): ReviewFinding {
     domain: (r.domain as ReviewFinding['domain']) ?? null,
     mergedFrom: Array.isArray(r.mergedFrom) ? (r.mergedFrom as MergedFromEntry[]) : undefined,
     ...(typeof r.score === 'number' && Number.isFinite(r.score) ? { score: r.score } : {}),
+    ...(typeof r.onChangedLine === 'boolean' || r.onChangedLine === null
+      ? { onChangedLine: r.onChangedLine as boolean | null }
+      : {}),
   }
 }
 

package/skills/magpie/skill.json

@@ -1,7 +1,7 @@
 {
   "name": "magpie",
-  "version": "0.5.1",
-  "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, 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.",
+  "version": "0.7.0",
+  "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.",
   "author": "iceinvein",
   "type": "prompt",
   "tools": [