@iceinvein/agent-skills 0.23.9 → 0.23.13

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

@@ -8,9 +8,79 @@ export type RunCleanupInput = {
   runDir: string
   repoPath: string
   gitBin: string
+  ghBin: string
   killGraceMs?: number
 }
 
+async function run(
+  cmd: string[],
+  cwd: string,
+): Promise<{ exit: number; stdout: string; stderr: string }> {
+  const proc = Bun.spawn(cmd, { cwd, stdout: 'pipe', stderr: 'pipe' })
+  const [exit, stdout, stderr] = await Promise.all([
+    proc.exited,
+    new Response(proc.stdout).text(),
+    new Response(proc.stderr).text(),
+  ])
+  return { exit, stdout, stderr }
+}
+
+/**
+ * Setup fetches a PR head into `refs/magpie/pr-<n>` when the commit is not local,
+ * and the ref keeps that head reachable for the next re-review's changed-files
+ * list. Once the PR is closed or merged nothing will re-review it.
+ */
+export type PruneResult = { deleted: string[]; failed: Array<{ ref: string; error: string }> }
+
+/** The decision for one ref: true to delete. Throws when its PR state cannot be known. */
+async function isClosedPr(ghBin: string, repoPath: string, n: string): Promise<boolean> {
+  const view = await run([ghBin, 'pr', 'view', n, '--json', 'state'], repoPath)
+  if (view.exit !== 0) throw new Error(`gh pr view ${n} exit ${view.exit}: ${view.stderr.trim()}`)
+  let state: unknown
+  try {
+    state = (JSON.parse(view.stdout) as { state?: unknown }).state
+  } catch (err) {
+    throw new Error(`gh pr view ${n}: ${err instanceof Error ? err.message : String(err)}`)
+  }
+  if (state === 'OPEN') return false
+  if (state === 'CLOSED' || state === 'MERGED') return true
+  throw new Error(`gh pr view ${n}: unexpected state ${JSON.stringify(state)}`)
+}
+
+/**
+ * Setup fetches a PR head into `refs/magpie/pr-<n>` when the commit is not local,
+ * and the ref keeps that head reachable for the next re-review's changed-files
+ * list. Once the PR is closed or merged nothing will re-review it. A ref whose
+ * PR cannot be checked is kept and reported, without holding up the others.
+ */
+export async function pruneClosedPrRefs(input: {
+  gitBin: string
+  ghBin: string
+  repoPath: string
+}): Promise<PruneResult> {
+  const list = await run(
+    [input.gitBin, 'for-each-ref', '--format=%(refname)', 'refs/magpie/'],
+    input.repoPath,
+  )
+  if (list.exit !== 0) throw new Error(`git for-each-ref exit ${list.exit}: ${list.stderr.trim()}`)
+  const result: PruneResult = { deleted: [], failed: [] }
+  for (const ref of list.stdout.split('\n').filter(Boolean)) {
+    const match = ref.match(/^refs\/magpie\/pr-(\d+)$/)
+    if (!match) continue
+    try {
+      if (!(await isClosedPr(input.ghBin, input.repoPath, match[1] as string))) continue
+      const del = await run([input.gitBin, 'update-ref', '-d', ref], input.repoPath)
+      if (del.exit !== 0) {
+        throw new Error(`git update-ref -d ${ref} exit ${del.exit}: ${del.stderr.trim()}`)
+      }
+      result.deleted.push(ref)
+    } catch (err) {
+      result.failed.push({ ref, error: err instanceof Error ? err.message : String(err) })
+    }
+  }
+  return result
+}
+
 export type KillOutcome =
   | 'no-server-info'
   | 'no-pid'
@@ -95,6 +165,21 @@ export async function runCleanup(input: RunCleanupInput): Promise<number> {
     await writeLabels(input.runDir)
   }
 
+  // Pruning is housekeeping for the repo, so a failure warns rather than leaving the run unarchived.
+  let pruneError: string | null = null
+  if (mode === 'pr') {
+    try {
+      const pruned = await pruneClosedPrRefs(input)
+      await appendFile(
+        join(input.runDir, 'log.jsonl'),
+        `${JSON.stringify({ stage: 'cleanup', status: 'prune-refs', deleted: pruned.deleted, failed: pruned.failed.map((f) => f.ref), ts: Date.now() })}\n`,
+      )
+      if (pruned.failed.length > 0) pruneError = pruned.failed.map((f) => f.error).join('; ')
+    } catch (err) {
+      pruneError = err instanceof Error ? err.message : String(err)
+    }
+  }
+
   const target = `${input.runDir}.archived-${Date.now()}`
   await rename(input.runDir, target)
   process.stdout.write(`archived to ${target}\n`)
@@ -102,6 +187,9 @@ export async function runCleanup(input: RunCleanupInput): Promise<number> {
   if (archivedId && mode !== 'local') {
     process.stdout.write(`view later: magpie open ${archivedId}\n`)
   }
+  if (pruneError !== null) {
+    process.stderr.write(`magpie: warning: could not prune refs/magpie: ${pruneError}\n`)
+  }
   if (kill.outcome === 'failed') {
     process.stderr.write(
       `magpie: warning: server process pid=${kill.pid} survived cleanup; kill it manually\n`,

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

@@ -7,6 +7,7 @@ import {
   DEFAULT_BATCH_SIZE,
   parseCriticVerdicts,
 } from './critic.ts'
+import { readHistory, renderAlreadyRaised } from './history.ts'
 import { reviewRoot } from './target.ts'
 import { parseBrief, parseFinding, type ReviewFinding, type ReviewRule } from './types.ts'
 
@@ -85,6 +86,7 @@ export async function runCriticPrompt(
       candidates: await readCandidates(runDir),
       mergeCandidates: await readMergeCandidates(runDir),
       reviewRules: await readReviewRules(runDir),
+      alreadyRaised: renderAlreadyRaised(await readHistory(runDir)),
       worktree: await reviewRoot(runDir),
       diffPath: join(runDir, 'diff.patch'),
       runDir,

package/skills/magpie/scripts/critic.ts

@@ -19,6 +19,7 @@ export const CRITIC_PLACEHOLDERS = [
   '<<CANDIDATES>>',
   '<<MERGE_CANDIDATES>>',
   '<<REVIEW_RULES>>',
+  '<<ALREADY_RAISED>>',
   '<<WORKTREE>>',
   '<<DIFF_PATH>>',
   '<<OUTPUT_PATH>>',
@@ -237,6 +238,8 @@ export function buildCriticPrompts(input: {
   candidates: ReviewFinding[]
   mergeCandidates: string[][]
   reviewRules: ReviewRule[]
+  /** Rendered by `renderAlreadyRaised`, `(none)` when there is nothing. */
+  alreadyRaised: string
   worktree: string
   diffPath: string
   runDir: string
@@ -258,6 +261,7 @@ export function buildCriticPrompts(input: {
       '<<CANDIDATES>>': renderCandidates(batch),
       '<<MERGE_CANDIDATES>>': JSON.stringify(groups, null, 2),
       '<<REVIEW_RULES>>': renderRules(input.reviewRules),
+      '<<ALREADY_RAISED>>': input.alreadyRaised,
       '<<WORKTREE>>': input.worktree,
       '<<DIFF_PATH>>': input.diffPath,
       '<<OUTPUT_PATH>>': outputPath,

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

@@ -6,6 +6,7 @@ import { deduplicateFindings, findMergeCandidates } from './dedupe.ts'
 import { verifyEvidence } from './evidence-filter.ts'
 import { namespaceId, parseFindingsFilename } from './findings-files.ts'
 import { DEFAULT_THRESHOLD, scoreRisk } from './score.ts'
+import { readShardCoverage } from './shard-coverage.ts'
 import { readTarget } from './target.ts'
 import { FOCUS_IDS, parseFinding, type ReviewFinding } from './types.ts'
 
@@ -53,9 +54,12 @@ async function reconcileCoverage(runDir: string, present: Set<string>): Promise<
   // A single-shard manifest means stage 4 took the unsharded path, so its
   // specialists write `<focus>.json` with no shard suffix.
   const sharded = shards.length > 1
+  // A shard skipped at the stage 4 gate has no findings by design, and the report says so.
+  const skipped = new Set((await readShardCoverage(runDir))?.skipped.map((s) => s.id))
   const expected: string[] = []
   for (const [i, shard] of shards.entries()) {
     const id = typeof shard?.id === 'number' ? shard.id : i + 1
+    if (skipped.has(id)) continue
     for (const focus of SPECIALIST_FOCUS_IDS) {
       expected.push(sharded ? `${focus}.shard-${id}.json` : `${focus}.json`)
     }

package/skills/magpie/scripts/evidence-filter.ts

@@ -72,6 +72,16 @@ function locateEvidence(fileLines: string[], snippet: string[], line: number): n
   return matches.length === 1 ? (matches[0] ?? null) : null
 }
 
+/** True when `evidence` appears anywhere in `fileText`, whitespace normalised as above. */
+export function containsEvidence(fileText: string, evidence: string): boolean {
+  const lines = fileText.split('\n')
+  const snippet = evidence.trim().split('\n').map(normalise)
+  for (let start = 1; start <= lines.length; start++) {
+    if (matchesAt(lines, snippet, start)) return true
+  }
+  return false
+}
+
 export async function verifyEvidence(
   findings: ReviewFinding[],
   worktreePath: string,

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

@@ -14,8 +14,14 @@ async function git(
   gitBin: string,
   cwd: string,
   args: string[],
+  env?: Record<string, string>,
 ): Promise<{ exit: number; stdout: string; stderr: string }> {
-  const proc = Bun.spawn([gitBin, ...args], { cwd, stdout: 'pipe', stderr: 'pipe' })
+  const proc = Bun.spawn([gitBin, ...args], {
+    cwd,
+    stdout: 'pipe',
+    stderr: 'pipe',
+    ...(env ? { env: { ...process.env, ...env } } : {}),
+  })
   const stdout = await new Response(proc.stdout).text()
   const stderr = await new Response(proc.stderr).text()
   const exit = await proc.exited
@@ -49,31 +55,47 @@ function fetchDiagnostic(result: { exit: number; stderr: string }): string {
  * `gh pr diff`'s three-dot semantics: the PR's own changes, not every commit
  * the base branch gained since the branch point.
  */
-export async function localPrDiff(input: LocalDiffInput): Promise<LocalDiffResult> {
-  const { gitBin, repoPath, prNumber, baseRefName, headRefOid } = input
+export type PrHeadInput = {
+  gitBin: string
+  repoPath: string
+  prNumber: number
+  headRefOid: string
+}
+
+/**
+ * The PR's head commit in the local clone, exactly `headRefOid`. The local
+ * branch named `headRefName` can be behind, ahead with unpushed commits, or
+ * absent on a fork PR, so it is never what gets reviewed.
+ */
+export async function resolvePrHead(
+  input: PrHeadInput,
+): Promise<{ ok: true; sha: string } | { ok: false; error: string }> {
+  const { gitBin, repoPath, prNumber, headRefOid } = input
   const prRef = `refs/magpie/pr-${prNumber}`
 
+  // Present, the SHA is the PR head by definition, so there is nothing to fetch
+  // and a stale ref from an earlier run does not matter.
+  const local = await resolveCommit(gitBin, repoPath, headRefOid)
+  if (local) return { ok: true, sha: local }
+
   // Best effort. `pull/<n>/head` is a GitHub convention and resolves fork PRs
-  // that `headRefName` cannot, but a repo with no `origin`, an offline run, or
-  // a non-GitHub remote must still work when the commits are already local.
-  // Each fetch's own result is kept (not discarded) so, if resolution below
-  // still fails, the error can say why the fetch didn't help.
-  const headFetch = await git(gitBin, repoPath, [
-    'fetch',
-    'origin',
-    `pull/${prNumber}/head:${prRef}`,
-  ])
-  const baseFetch = await git(gitBin, repoPath, ['fetch', 'origin', baseRefName])
+  // that `headRefName` cannot. The fetch's own result is kept (not discarded)
+  // so, if resolution below still fails, the error can say why the fetch didn't
+  // help. The `+` lets the ref follow a force-push; without it git keeps the head
+  // an earlier run fetched. No terminal prompt, so missing credentials fail
+  // instead of waiting on a tty nobody is watching.
+  const headFetch = await git(
+    gitBin,
+    repoPath,
+    ['fetch', 'origin', `+pull/${prNumber}/head:${prRef}`],
+    { GIT_TERMINAL_PROMPT: '0' },
+  )
 
-  let head: string | null = null
-  for (const ref of [prRef, headRefOid]) {
-    head = await resolveCommit(gitBin, repoPath, ref)
-    if (head) break
-  }
+  const head = await resolveCommit(gitBin, repoPath, prRef)
   if (!head) {
     return {
       ok: false,
-      error: `cannot resolve PR head ${headRefOid} locally (tried ${prRef} and the SHA); fetch the PR branch and retry${fetchDiagnostic(headFetch)}`,
+      error: `cannot resolve PR head ${headRefOid} locally (tried the SHA and ${prRef}); run \`git fetch <remote> pull/${prNumber}/head\` from the remote that holds the PR, then retry${fetchDiagnostic(headFetch)}`,
     }
   }
   // Reviewing a stale local ref and reporting it as a review of the PR is worse
@@ -84,6 +106,15 @@ export async function localPrDiff(input: LocalDiffInput): Promise<LocalDiffResul
       error: `local PR head ${head} does not match the PR head ${headRefOid}; the local ref is stale`,
     }
   }
+  return { ok: true, sha: head }
+}
+
+export async function localPrDiff(input: LocalDiffInput): Promise<LocalDiffResult> {
+  const { gitBin, repoPath, prNumber, baseRefName, headRefOid } = input
+  const resolved = await resolvePrHead({ gitBin, repoPath, prNumber, headRefOid })
+  if (!resolved.ok) return resolved
+  const head = resolved.sha
+  const baseFetch = await git(gitBin, repoPath, ['fetch', 'origin', baseRefName])
 
   let base: string | null = null
   for (const ref of [`origin/${baseRefName}`, baseRefName]) {

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

@@ -3,7 +3,10 @@ import { appendFile, readFile } from 'node:fs/promises'
 import { join } from 'node:path'
 import { formatFindingDescriptionMarkdown } from './finding-description.ts'
 import { diffSha256, localBranchDiff } from './local-diff.ts'
+import type { ProofDropped } from './proof.ts'
+import { readProofDropped } from './proof-cmd.ts'
 import { rankActionable } from './render-issues-list.ts'
+import { describeUnreviewed, readShardCoverage, type ShardCoverage } from './shard-coverage.ts'
 import { readTarget } from './target.ts'
 import { isSuggestion, parseFinding, type ReviewFinding, type Suggestion } from './types.ts'
 
@@ -16,6 +19,18 @@ export type FormatHandoffInput = {
   target: string
   findings: ReviewFinding[]
   stale: boolean
+  /** Shards skipped at the stage 4 gate; absent when every shard was reviewed. */
+  unreviewed?: ShardCoverage
+  /** Findings the proof stage removed because a passing test showed the code is right. */
+  disproved?: ProofDropped[]
+}
+
+function formatDisproved(disproved: ProofDropped[]): string {
+  const lines = disproved.map((d) => {
+    const anchor = d.line === null ? d.file : `${d.file}:${d.line}`
+    return `- ${anchor}: ${d.title} (${d.reason}; \`${d.repro.command}\`)`
+  })
+  return ['Dropped because a passing test disproved them:', ...lines].join('\n')
 }
 
 /** A fence longer than any backtick run in the body, so the body cannot close it early. */
@@ -31,22 +46,37 @@ function formatSuggestion(s: Suggestion): string {
   return `Suggested replacement for ${lines}:\n${fence}\n${s.body}\n${fence}`
 }
 
+function formatProof(f: ReviewFinding): string | null {
+  if (f.proof?.status === 'not-proven') return `Not proven: ${f.proof.reason}`
+  if (f.proof?.status !== 'reproduced') return null
+  const { command, source } = f.proof.repro
+  const fence = fenceFor(source)
+  return `Reproduced with \`${command}\`:\n${fence}\n${source}\n${fence}`
+}
+
 function formatItem(n: number, f: ReviewFinding): string {
   const anchor = f.line === null ? f.file : `${f.file}:${f.line}`
   const parts = [`${n}. [${f.risk.action}] ${anchor}: ${f.title}`]
   const body = formatFindingDescriptionMarkdown(f.description)
   if (body) parts.push(body)
   if (f.suggestion) parts.push(formatSuggestion(f.suggestion))
+  const proof = formatProof(f)
+  if (proof) parts.push(proof)
   return parts.join('\n\n')
 }
 
 export function formatHandoff(input: FormatHandoffInput): string {
-  const { target, findings, stale } = input
+  const { target, findings, stale, unreviewed, disproved = [] } = input
   const header = [`# magpie local review: ${target}`]
   if (stale) {
     header.push('Warning: the tree changed since this review began; line anchors may be off.')
   }
-  if (findings.length === 0) return `${header.join('\n')}\n\nNo findings.\n`
+  if (unreviewed) {
+    const files = unreviewed.skipped.flatMap((s) => s.files.map((f) => `- ${f}`))
+    header.push(`Warning: ${describeUnreviewed(unreviewed)}:`, ...files)
+  }
+  const tail = disproved.length > 0 ? [formatDisproved(disproved)] : []
+  if (findings.length === 0) return `${[header.join('\n'), 'No findings.', ...tail].join('\n\n')}\n`
 
   const mustFix = findings.filter((f) => f.risk.action === 'must-fix').length
   const shouldFix = findings.filter((f) => f.risk.action === 'should-fix').length
@@ -60,6 +90,7 @@ export function formatHandoff(input: FormatHandoffInput): string {
     `${mustFix} must-fix, ${shouldFix} should-fix, ${optional} optional`,
     ...ordered.map((f, i) => formatItem(i + 1, f)),
     'Address every must-fix and should-fix, or say why not. The rest are optional.',
+    ...tail,
   ]
   return `${sections.join('\n\n')}\n`
 }
@@ -124,8 +155,16 @@ export async function runHandoff(runDir: string, opts: { gitBin?: string } = {})
   const stale = recorded === null || currentSha === null || currentSha !== recorded
 
   const subject = meta.branch === null ? 'detached HEAD' : `local branch ${meta.branch}`
+  const unreviewed = await readShardCoverage(runDir)
+  const disproved = await readProofDropped(runDir)
   process.stdout.write(
-    formatHandoff({ target: `${subject} against ${meta.baseRef}`, findings, stale }),
+    formatHandoff({
+      target: `${subject} against ${meta.baseRef}`,
+      findings,
+      stale,
+      ...(unreviewed ? { unreviewed } : {}),
+      disproved,
+    }),
   )
   await logLine(runDir, { stage: 'handoff', status: 'done', findings: findings.length })
   return 0

package/skills/magpie/scripts/history.ts

@@ -0,0 +1,143 @@
+import { readFile } from 'node:fs/promises'
+import { join } from 'node:path'
+import type { PrActivity } from './pr-activity.ts'
+import type { PreviousFindings } from './previous-findings.ts'
+
+export type HistoryIncremental = {
+  previousSha: string
+  changedSincePrevious: string[] | null
+}
+
+export type History = {
+  activity: PrActivity | null
+  previous: PreviousFindings | null
+  incremental: HistoryIncremental | null
+}
+
+const MAX_BODY = 280
+
+// Conclusions that mean the check found something; CANCELLED and SKIPPED say nothing about the code.
+const FAILING = new Set(['FAILURE', 'ERROR', 'TIMED_OUT', 'ACTION_REQUIRED', 'STARTUP_FAILURE'])
+
+function flatten(body: string): string {
+  const text = body
+    .replace(/<!--[\s\S]*?-->/g, '')
+    .replace(/\s+/g, ' ')
+    .trim()
+  return text.length > MAX_BODY ? `${text.slice(0, MAX_BODY)}…` : text
+}
+
+function location(file: string, line: number | null): string {
+  return line === null ? file : `${file}:${line}`
+}
+
+function section(heading: string, lines: string[]): string[] {
+  return lines.length === 0 ? [] : [`${heading}:`, ...lines]
+}
+
+function joinSections(sections: string[][]): string {
+  return sections
+    .filter((s) => s.length > 0)
+    .map((s) => s.join('\n'))
+    .join('\n\n')
+}
+
+// The account GitHub Actions posts as: coverage tables, deploy previews and other
+// CI output, which reaches the review as checks. Review bots post as their own
+// apps, and what they raise still counts. gh prints the login without `[bot]`,
+// the REST API with it.
+const CI_AUTHORS = new Set(['github-actions', 'github-actions[bot]'])
+
+function raisedSections(input: Pick<History, 'activity' | 'previous'>): string[][] {
+  const threads = (input.activity?.threads ?? [])
+    .filter((t) => !t.resolved)
+    .map((t) => {
+      const who = t.magpie ? 'magpie, earlier run' : `${t.author}, ${t.replies} replies`
+      const outdated = t.outdated ? ' [outdated]' : ''
+      return `- ${location(t.file, t.line)} (${who})${outdated}: ${flatten(t.body)}`
+    })
+  const comments = (input.activity?.comments ?? [])
+    .filter((c) => !CI_AUTHORS.has(c.author))
+    .map((c) => `- ${c.magpie ? 'magpie, earlier run' : c.author}: ${flatten(c.body)}`)
+  const dismissed = (input.previous?.findings ?? []).flatMap((f) =>
+    f.label === 'dismissed' ? [`- ${location(f.file, f.line)} [${f.reason}]: ${f.title}`] : [],
+  )
+  return [
+    section('Open review threads', threads),
+    section('PR comments', comments),
+    section('Dismissed by the reviewer in an earlier magpie run', dismissed),
+  ]
+}
+
+/** What the critic weighs a candidate against for the "already raised" drop. */
+export function renderAlreadyRaised(input: Pick<History, 'activity' | 'previous'>): string {
+  return joinSections(raisedSections(input)) || '(none)'
+}
+
+/** The specialists' "Already on this PR" prompt part; empty when there is nothing to say. */
+export function renderHistory(history: History): string {
+  const checks = (history.activity?.checks ?? [])
+    .filter((c) => FAILING.has(c.conclusion))
+    .map((c) => `- ${c.name}: ${c.conclusion}${c.url ? ` (${c.url})` : ''}`)
+  const changed = history.incremental?.changedSincePrevious ?? []
+  const sinceHeading = history.incremental
+    ? `Files changed since the last review at ${history.incremental.previousSha.slice(0, 7)} (the whole diff is still your scope)`
+    : ''
+  const raised = joinSections(raisedSections(history))
+  const leads = joinSections([
+    section('Failing CI checks (a lead to investigate, not a finding in itself)', checks),
+    section(
+      sinceHeading,
+      changed.map((f) => `- ${f}`),
+    ),
+  ])
+  if (raised === '' && leads === '') return ''
+  const parts = ['## Already on this PR']
+  if (raised !== '') {
+    parts.push(
+      'The threads, comments and dismissals below were raised before this review. Do not report a finding that repeats one of them: the critic drops repeats. Report it again only when you have something material it lacks, and say what that is.',
+      raised,
+    )
+  }
+  if (leads !== '') {
+    parts.push('Leads, not repeats: a finding that explains one of these is wanted.', leads)
+  }
+  return parts.join('\n\n')
+}
+
+async function readSidecar<T>(runDir: string, name: string): Promise<T | null> {
+  const path = join(runDir, name)
+  let text: string
+  try {
+    text = await readFile(path, 'utf8')
+  } catch (err) {
+    if ((err as NodeJS.ErrnoException)?.code === 'ENOENT') return null
+    throw err
+  }
+  try {
+    return JSON.parse(text) as T
+  } catch (err) {
+    throw new Error(`${path}: ${err instanceof Error ? err.message : String(err)}`)
+  }
+}
+
+/** Each sidecar is optional: local runs, first runs and runs from older versions lack them. */
+export async function readHistory(runDir: string): Promise<History> {
+  const incremental = await readSidecar<{
+    previousSha?: unknown
+    changedSincePrevious?: unknown
+  }>(runDir, 'incremental.json')
+  return {
+    activity: await readSidecar<PrActivity>(runDir, 'pr-activity.json'),
+    previous: await readSidecar<PreviousFindings>(runDir, 'previous-findings.json'),
+    incremental:
+      incremental && typeof incremental.previousSha === 'string'
+        ? {
+            previousSha: incremental.previousSha,
+            changedSincePrevious: Array.isArray(incremental.changedSincePrevious)
+              ? (incremental.changedSincePrevious as string[])
+              : null,
+          }
+        : null,
+  }
+}