@iceinvein/agent-skills 0.1.36 → 0.1.37

package/package.json

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

package/skills/index.json

@@ -221,7 +221,7 @@
     "name": "magpie",
     "description": "Interactive PR review pipeline. Runs five parallel specialist subagents (security, bugs, performance, code-smells, architecture), dedupes findings, applies a critic rubric, peer-reviews via codex exec (falling back to a Claude second opinion when codex is unavailable), and serves an interactive HTML report for selecting findings to post via gh. Bundles a Bun CLI installed onto PATH via the skill's postinstall step. Use when the user asks to review a GitHub pull request.",
     "type": "prompt",
-    "version": "0.6.0"
+    "version": "0.7.0"
   },
   {
     "name": "module-secret-auditor",

package/skills/magpie/SKILL.md

@@ -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,7 +144,7 @@ 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
 
@@ -273,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.
 ```
@@ -334,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.
 ```
@@ -393,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.
 ```
 
@@ -510,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.
@@ -521,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.
 
@@ -566,6 +575,11 @@ 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

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