@iceinvein/agent-skills 0.22.0 → 0.23.1

package/README.md

@@ -121,7 +121,7 @@ Skills that compose the other audit skills into higher-level workflows.
 | Skill | What it does |
 |-------|--------------|
 | **improve-my-codebase** | Runs every applicable audit skill in parallel against your codebase, ranks findings by convergence (multiple audits agreeing) and per-file rollup, and writes a prioritized improvement report. Default sweeps everything; positional args switch modes (`quick`, `diff`, `interactive`) or narrow scope (`focus <area>`, `module <path>`). |
-| **magpie** | 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`. |
+| **magpie** | 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`. A local mode reviews the current branch diff before a PR exists and hands the findings back in the terminal. |
 
 ## Commands
 

package/package.json

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

package/skills/bug-hunter/SKILL.md

@@ -1,6 +1,7 @@
 ---
 name: bug-hunter
 description: Use when asked to hunt for bugs or edge cases in a change or area, to say what QA will find before QA does, or to prove a change correct. Runs QA-style scenarios as failing reproductions in the repo's own test runner and reports only bugs it can prove, plus the questions intent leaves open.
+argument-hint: "[<commit>|<base>..<head>|<path>...]"
 ---
 
 # Bug hunter
@@ -12,7 +13,8 @@ a failing reproduction, checked against what the change was meant to do.
 ## Method
 
 1. **Name the target** in one line: a diff (a commit, a range, the working
-   changes) or a set of paths. Every later step is scoped to it.
+   changes) or a set of paths, taken from the arguments when given and the
+   working changes otherwise. Every later step is scoped to it.
 2. **Collect intent** into `intent.md`: numbered claims (`I1`, `I2`, ...),
    each one checkable statement with its source. Sources are the request or
    ticket, commit messages, specs and designs, docs, `CLAUDE.md`/`AGENTS.md`,
@@ -76,6 +78,11 @@ The `.bug-hunter/` directory is the one path in the caller's tree the skill
 writes. Promoting a repro into the tree as a regression test is the caller's
 job.
 
+The directory ignores itself, so no repo has to add a line for it: if
+`.bug-hunter/.gitignore` is absent, write it holding `*` before anything else
+in the run. Leave an existing one alone; deleting it is how a repo chooses to
+commit its runs.
+
 ## Hand-back
 
 The run directory, the counts per bucket, then each bug in one line:

package/skills/bug-hunter/evals/README.md

@@ -11,7 +11,7 @@ skill.
 | `proves-a-spec-boundary-bug` | Usernames are 3 to 20 characters inclusive; the code rejects 20 | A bug in `findings.json` citing the limit, with a repro that fails against the fixture |
 | `silent-spec-is-an-ambiguity` | Quantities are "capped"; the spec never says where, the code uses 99 | The cap lands in `ambiguities` and `bugs` is empty |
 | `correct-code-has-no-bugs` | Pagination that meets every stated range at its edge | `bugs` is empty |
-| `callers-tree-unchanged` | A backoff whose first delay is doubled | Nothing changes in the caller's tree outside `.bug-hunter/` |
+| `callers-tree-unchanged` | A backoff whose first delay is doubled | Nothing changes in the caller's tree outside `.bug-hunter/`, and `.bug-hunter/.gitignore` is written holding `*` |
 | `bug-cites-intent-from-spec` | A coupon that floors where the spec rounds half up | `intent.md` is written, and the bug cites a claim sourced from `SPEC.md`, not from the code's floor |
 | `spec-outranks-target-docstring` | The spec keeps a sealed export on offer when its rewrite fails; the module's docstring and code drop it | A bug citing the spec claim, not an ambiguity between spec and docstring |
 | `impossible-value-is-a-bug` | The spec is silent on rounding; the code shows `60s` and `1m 60s` | A bug for the seconds field of 60, which no rounding rule gives |
@@ -97,6 +97,11 @@ a file needs its exact path and throws on a glob. So:
   An edit to `package.json` or `SPEC.md` is still unseen. A run that writes
   nothing passes all three, which is why the case also has
   `bug-hunter-fired`.
+- `output-ignores-itself` in the same case reads the trace for a Write of
+  `.bug-hunter/.gitignore` whose content is `*`, or a shell command that
+  writes a `*` into it. The `files` target would show the path but not its
+  content, and an empty `.gitignore` ignores nothing. A script that opens the
+  file itself is not caught.
 - `bug-cites-the-spec` in `bug-cites-intent-from-spec` is an `llm` judge over
   the trace, with the same window and last-write limits as
   `bug-cites-the-limit`. It resolves the bug's `claim` through the `intent`

package/skills/bug-hunter/evals/callers-tree-unchanged/graders/output-ignores-itself.md

@@ -0,0 +1,11 @@
+---
+type: regex
+# SKILL.md has the run drop a .gitignore holding `*` into .bug-hunter/ when
+# none is there, so no repo has to ignore the directory itself. The files
+# target would show the path but not what it holds, and an empty .gitignore
+# ignores nothing, so this reads the trace: a Write call whose content is `*`,
+# or a shell command that writes a `*` into it.
+pattern: '\.bug-hunter/\.gitignore"\s*,\s*"content"\s*:\s*"\*(?:\\n)?"|"command":"(?:\\.|[^"\\])*?\*(?:\\.|[^"\\])*?>\s*[^"\s]*\.bug-hunter/\.gitignore'
+target: trace
+weight: 2
+---

package/skills/bug-hunter/evals/rules.json

@@ -153,6 +153,14 @@
         "callers-tree-unchanged"
       ]
     },
+    {
+      "id": "bug-hunter-dir-ignores-itself",
+      "states": "SKILL.md: Output",
+      "origin": "skills/sluice/references/status.md",
+      "cases": [
+        "callers-tree-unchanged"
+      ]
+    },
     {
       "id": "promoting-a-repro-is-the-callers-job",
       "states": "SKILL.md: Output",

package/skills/bug-hunter/skill.json

@@ -1,6 +1,6 @@
 {
   "name": "bug-hunter",
-  "version": "0.4.0",
+  "version": "0.4.2",
   "description": "Hunts logic and correctness bugs in a change or area and proves each one with a failing reproduction checked against stated intent. One agent collects intent from the request, specs, docs and unchanged code, runs QA-style scenarios from a catalog as repros in the repo's own test runner inside a scratch copy, and re-runs each failure clean before reporting it. Counts a contradicted claim, or a result wrong under every reading, as a bug; keeps ambiguities for questions with more than one acceptable answer; reports latent defects without filing them. No repro, no finding. Writes report.md and findings.json (bugs, ambiguities, covered) to .bug-hunter/<date>-<slug>/ and never modifies the caller's tree. Language-agnostic; ships no per-language scripts.",
   "author": "iceinvein",
   "type": "prompt",

package/skills/index.json

@@ -13,7 +13,7 @@
     "name": "bug-hunter",
     "description": "Hunts logic and correctness bugs in a change or area and proves each one with a failing reproduction checked against stated intent. One agent collects intent from the request, specs, docs and unchanged code, runs QA-style scenarios from a catalog as repros in the repo's own test runner inside a scratch copy, and re-runs each failure clean before reporting it. Counts a contradicted claim, or a result wrong under every reading, as a bug; keeps ambiguities for questions with more than one acceptable answer; reports latent defects without filing them. No repro, no finding. Writes report.md and findings.json (bugs, ambiguities, covered) to .bug-hunter/<date>-<slug>/ and never modifies the caller's tree. Language-agnostic; ships no per-language scripts.",
     "type": "prompt",
-    "version": "0.4.0"
+    "version": "0.4.2"
   },
   {
     "name": "codebase-architecture",
@@ -225,9 +225,9 @@
   },
   {
     "name": "magpie",
-    "description": "Interactive PR review pipeline. Runs five parallel specialist subagents (security, bugs, performance, code-smells, architecture), drops findings whose quoted evidence is not in the code, dedupes, runs critic subagents that re-check each finding against the worktree and set its risk label, peer-reviews via codex exec (falling back to a Claude second opinion when codex is unavailable), and serves an interactive HTML report for selecting or dismissing findings to post via gh, recording the outcome per finding as labels. Bundles a Bun CLI installed onto PATH via the skill's postinstall step. Use when the user asks to review a GitHub pull request. Splits oversized diffs into budgeted shards and rebuilds the diff from the local clone when gh pr diff refuses it.",
+    "description": "Interactive PR review pipeline. Runs five parallel specialist subagents (security, bugs, performance, code-smells, architecture) plus a once-per-PR checks pass that finds tests and controls able to pass without proving their purpose, drops findings whose quoted evidence is not in the code, dedupes, runs critic subagents that re-check each finding against the worktree and set its risk label, peer-reviews via codex exec (falling back to a Claude second opinion when codex is unavailable), and serves an interactive HTML report for selecting or dismissing findings to post via gh, recording the outcome per finding as labels. Bundles a Bun CLI installed onto PATH via the skill's postinstall step. Use when the user asks to review a GitHub pull request. Local mode (setup --local) runs the same pipeline on the current branch's diff from its merge base, uncommitted and untracked work included, against the caller's live tree, with no server or posting, and hands the ranked findings back in the terminal for an implementing or orchestrating agent to address. Splits oversized diffs into budgeted shards and rebuilds the diff from the local clone when gh pr diff refuses it.",
     "type": "prompt",
-    "version": "0.13.1"
+    "version": "0.14.1"
   },
   {
     "name": "migrate",
@@ -269,7 +269,7 @@
     "name": "scope-estimate",
     "description": "Scopes and estimates a rebuild or respec of an existing system for a proposal: read-only discovery agents write cited inventories, a capability register gives every capability a status and a proposed disposition, area agents turn it into sized functional requirements, and a bundled Bun scheduler groups them into slices and contracts-first work packages and schedules them across engineers x worktrees at fast, planning and floor rates. The scheduler refuses a plan that misses or double-counts a requirement or has a dependency cycle, so every figure in the docs comes from one reproducible run. Also covers current and target architecture pages, proposal review, and a two-week calibration before committing to a date. Lighter than migrate: no store and no phase gates.",
     "type": "prompt",
-    "version": "0.1.0"
+    "version": "0.1.1"
   },
   {
     "name": "seam-finder",
@@ -293,9 +293,9 @@
   },
   {
     "name": "sluice",
-    "description": "Routes work by change shape into four channels (bypass, fast, main, deep) and applies only the rules each channel needs, so a one-line fix does not pay the cost of a multi-subsystem build. Carries nine rules as one-liners in the router and the full treatment in references read only on friction. Checks the finished plan with plan.sh validate rather than trusting it to memory, seeds the run state from it, keeps a deep run's task breakdown in .sluice/run.json so a statusline segment, one status command and a SessionStart hook can answer where the run is (the hook prints a live run at every session start, compaction included), and closes each run with a ledger read out of the session transcript: elapsed, tools, tokens, and what each dispatched agent cost where the transcript recorded it. Claude Code only; stands down where the superpowers pipeline governs the repo.",
+    "description": "Routes work by change shape into four channels (bypass, fast, main, deep) and applies only the rules each channel needs, so a one-line fix does not pay the cost of a multi-subsystem build. Carries nine rules as one-liners in the router and the full treatment in references read only on friction. Checks the finished plan with plan.sh validate rather than trusting it to memory, seeds the run state from it, keeps a deep run's task breakdown in .sluice/run.json so a statusline segment, one status command and a SessionStart hook can answer where the run is (the hook prints a live run at every session start, compaction included), and closes each run with a ledger read out of the session transcript: elapsed, tools, tokens, and what each dispatched agent cost where the transcript recorded it. Two Stop hooks hold a handback: one refuses a tree that moved since its last recorded check, the other refuses a changed existing test not proven to fail on the session's starting code (or recorded with a reason). Claude Code only; stands down where the superpowers pipeline governs the repo.",
     "type": "prompt",
-    "version": "0.24.1"
+    "version": "0.25.1"
   },
   {
     "name": "temporal-coupling-detector",

package/skills/magpie/README.md

@@ -4,7 +4,7 @@ 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), each quoting an evidence snippet for every anchored finding. Dedupe drops findings whose snippet is not in the file and groups nearby findings from different domains as merge candidates. Critic subagents then re-check each surviving finding against the worktree, keep, drop or merge it, and set its risk label, from which the severity is derived. Peer review runs via `codex exec` (falling back to a Claude second-opinion subagent when codex is unavailable). The interactive HTML report puts the top recommended findings first, lets the user dismiss findings with a reason, and posts the ones they select via `gh`; cleanup records what was posted, dismissed or ignored in `labels.json`.
+Given a GitHub PR number, dispatches five specialist subagents in parallel (security, bugs, performance, code-smells, architecture), each quoting an evidence snippet for every anchored finding, plus one checks pass per PR that reviews the tests, harnesses and controls for ways they can pass without proving what they exist for. Dedupe drops findings whose snippet is not in the file and groups nearby findings from different domains as merge candidates. Critic subagents then re-check each surviving finding against the worktree, keep, drop or merge it, and set its risk label, from which the severity is derived. Peer review runs via `codex exec` (falling back to a Claude second-opinion subagent when codex is unavailable). The interactive HTML report puts the top recommended findings first, lets the user dismiss findings with a reason, and posts the ones they select via `gh`; cleanup records what was posted, dismissed or ignored in `labels.json`.
 
 ## Requirements
 
@@ -27,6 +27,8 @@ If you cloned this repo and want to run from source, you can also invoke `./inst
 
 Inside Claude Code, ask: "Review PR 1234" (or paste a PR URL). The agent reads SKILL.md and walks the pipeline; the CLI runs as `magpie setup`, `magpie serve`, etc.
 
+An implementing or orchestrating agent can also ask for a review of its own branch before a PR exists: local mode (`magpie setup <run-dir> --local [--base <ref>]`) reviews the merge base to working tree diff in place and hands the ranked findings back as terminal text via `magpie handoff`, with no server, report or posting.
+
 ## Development
 
 ```
@@ -54,7 +56,7 @@ The fixture lives at `fixtures/example-pr/` (pr.json + findings.final.json + pos
 ## Layout
 
 - `SKILL.md` is the agent-facing prompt: the stage walkthrough and nothing else. Installed by the agent-skills CLI.
-- `references/` holds the prompt bodies the walkthrough loads on demand, one file per stage that needs one: `scout.md` (stage 3, the PR-brief prompt and the `brief.json` contract, including the repository review rules), `specialists.md` (stage 4, the five focus blocks plus the shared output contract), `critic.md` (stage 6, the critic subagent prompt `magpie critic-prompt` fills), `peer-review.md` (stage 7, including the Claude-fallback preamble). They ship in the bundle and sit next to `SKILL.md` once installed.
+- `references/` holds the prompt bodies the walkthrough loads on demand, one file per stage that needs one: `scout.md` (stage 3, the PR-brief prompt and the `brief.json` contract, including the repository review rules), `checks.md` (stage 3, the once-per-PR checks pass that writes `findings/checks.json`), `specialists.md` (stage 4, the five focus blocks plus the shared output contract), `critic.md` (stage 6, the critic subagent prompt `magpie critic-prompt` fills), `peer-review.md` (stage 7, including the Claude-fallback preamble). They ship in the bundle and sit next to `SKILL.md` once installed.
 - `skill.json` is the agent-skills manifest.
 - `bin/magpie` is the CLI invoked by the agent during stages; symlinked onto PATH by `install.sh`.
 - `scripts/` holds the implementation (server, dedupe, render, setup, cleanup, etc.).
@@ -66,4 +68,4 @@ The fixture lives at `fixtures/example-pr/` (pr.json + findings.final.json + pos
 
 ## Run directory layout
 
-Each invocation creates `~/.magpie/pr-<n>-<ts>/` with `pr.json`, `diff.patch`, `findings/`, `findings.deduped.json`, `merge-candidates.json`, `critic-prompt.md` and `critic.json` (numbered per batch when there is more than one), `findings.kept.json`, `critic-dropped.json`, `findings.final.json`, `labels.json`, `screen/`, `state/`, `log.jsonl`. On completion the directory is renamed to `<run-dir>.archived-<timestamp>` rather than deleted, so logs survive for postmortem.
+Each invocation creates `~/.magpie/pr-<n>-<ts>/` (`~/.magpie/local-<branch-slug>-<ts>/` for a local run, with `local.json` and `target.json`, no `pr.json` and no worktree) with `pr.json`, `diff.patch`, `findings/`, `findings.deduped.json`, `merge-candidates.json`, `critic-prompt.md` and `critic.json` (numbered per batch when there is more than one), `findings.kept.json`, `critic-dropped.json`, `findings.final.json`, `labels.json`, `screen/`, `state/`, `log.jsonl`. On completion the directory is renamed to `<run-dir>.archived-<timestamp>` rather than deleted, so logs survive for postmortem.

package/skills/magpie/SKILL.md

@@ -1,6 +1,7 @@
 ---
 name: magpie
-description: Use when the user asks to review a GitHub pull request (a PR number, PR URL, or "review this PR"). Interactive PR review pipeline; five parallel specialist subagents, dedupe, critic, codex/Claude peer review, and an interactive HTML report for posting selected findings via gh. Follow the stage walkthrough in this skill; the description is not the procedure.
+description: Use when the user asks to review a GitHub pull request (a PR number, PR URL, or "review this PR"), or to self-review the current branch diff before a PR exists, typically requested by an implementing or orchestrating agent, with findings handed back in the terminal. Interactive PR review pipeline; five parallel specialist subagents, dedupe, critic, codex/Claude peer review, and an interactive HTML report for posting selected findings via gh. Follow the stage walkthrough in this skill; the description is not the procedure.
+argument-hint: "[<pr#>|<pr-url>|local] [--base <ref>] [--intent-file <path>]"
 ---
 
 # Magpie
@@ -15,6 +16,8 @@ Stop reading and follow these steps in order. Do not skip stages. Use the exact
 
 ### 0. Identify the PR
 
+A request with no PR that asks to review the current branch, the working tree, or work in progress, or arguments starting `local` (any `--base` or `--intent-file` after it go to setup), is local mode: follow "Local mode" below in place of this step and stages 1 and 2, then run stages 3 to 7 as written, taking `TARGET` from Local mode.
+
 Parse the user's request for a PR number, URL, or "this PR" (current branch). If ambiguous, ask one clarifying terminal question. Capture the PR number into `$PR_NUMBER` and the repo path into `$REPO` (default: the current working directory).
 
 Before minting a new id, check whether an earlier run on this PR is unfinished:
@@ -42,13 +45,10 @@ If exit is non-zero, surface stderr verbatim and stop. The CLI removes the workt
 
 Setup filters lockfiles, build output, generated source, and snapshot fixtures from `diff.patch` before specialists see it. Users override with `.magpie.json` at the repo root: `{"exclude": [...glob], "include": [...glob], "useDefaults": true|false}`. When anything is filtered, the raw diff is kept as `$RUN_DIR/diff.full.patch` and the exclusion list as `$RUN_DIR/excluded-files.json`.
 
-When `gh pr diff` refuses the diff (HTTP 406 above roughly 300 files) or returns an
-empty diff for a PR with changed files, setup rebuilds it from the local clone instead
-of aborting: it fetches `pull/<n>/head` and diffs from the merge base against the PR's
-base branch, reproducing the three-dot semantics `gh pr diff` uses. A local head that
-does not match the PR's `headRefOid` is a hard error, not a silently stale review. The
-`fetch-pr` log entry records `source: "gh" | "git"` and the merge base, and
-`$RUN_DIR/diff-source.json` carries the same for the report.
+When `gh pr diff` refuses the diff (HTTP 406 above roughly 300 files) or returns it
+empty, setup rebuilds it from the local clone: `pull/<n>/head` diffed from the merge
+base, as `gh pr diff` does. A local head that does not match the PR's `headRefOid` is a
+hard error. `$RUN_DIR/diff-source.json` records `source: "gh" | "git"` and the merge base.
 
 Setup then splits the filtered diff into shards, writing `$RUN_DIR/shards/manifest.json`
 and, when more than one shard results, `$RUN_DIR/shards/shard-<n>.patch`. `diff.patch`
@@ -61,7 +61,7 @@ nothing reviewed.
 
 When a prior run exists for the same PR (active or archived under `~/.magpie/`), setup writes `$RUN_DIR/incremental.json` with `{previousRunId, previousSha, currentSha, sameSha}`. The post stage surfaces this as a "Incremental review since `<sha>`" trailer on the summary comment.
 
-Setup also runs a deterministic test-coverage check: when the diff contains zero test or spec files anywhere, each non-test source file with `>= 10` added code lines gets a `domain: "tests"` finding in `$RUN_DIR/findings/tests.json`. That sixth domain flows through dedupe/critic/peer-review alongside the five LLM specialists; no subagent is dispatched for it.
+Setup also runs a deterministic test-coverage check: when the diff contains zero test or spec files anywhere, each non-test source file with `>= 10` added code lines gets a `domain: "tests"` finding in `$RUN_DIR/findings/tests.json`. That domain flows through dedupe/critic/peer-review like the LLM findings; no subagent is dispatched for it.
 
 ### 2. Serve
 
@@ -73,7 +73,7 @@ magpie serve "$RUN_DIR"
 
 Read `$RUN_DIR/state/server-info` for the URL; the server writes it asynchronously, so if it is missing, wait a moment and re-read (it appears within ~1s). Print to the user: "Open <url> in your browser to follow along."
 
-The server shuts down after 30 idle minutes (an open report tab heartbeats every 30s, so it stays up while the user is looking) and deletes `state/server-info` on the way out. Nothing in the pipeline depends on it: re-run `magpie serve "$RUN_DIR"` to bring the report back.
+The server shuts down after 30 idle minutes (an open report tab keeps it up) and deletes `state/server-info`. Nothing in the pipeline depends on it: re-run `magpie serve "$RUN_DIR"` to bring the report back.
 
 Render the first progress paint:
 
@@ -85,9 +85,11 @@ magpie render "$RUN_DIR" progress
 
 Append `{stage: context, status: running}` to `$RUN_DIR/log.jsonl` and re-render progress. This stage never aborts the run.
 
-Read `references/scout.md` and dispatch one subagent (Agent tool, `general-purpose`) carrying the `magpie-scout` block with `<<RUN_DIR>>` and `<<PR_NUMBER>>` substituted. It writes `$RUN_DIR/brief.json`.
+Set `WORKTREE=$(magpie target "$RUN_DIR")`, the directory findings are anchored against (the run's own `worktree/` checkout on a PR run), and `TARGET` to `PR #$PR_NUMBER`. Every prompt from here on takes both.
+
+Read `references/scout.md` and `references/checks.md`, then dispatch two subagents (Agent tool, `general-purpose`) in one message: the scout, carrying the `magpie-scout` block with `<<RUN_DIR>>`, `<<WORKTREE>>` and `<<TARGET>>` substituted, which writes `$RUN_DIR/brief.json`; and the checks pass, built as `references/checks.md` says, which writes `$RUN_DIR/findings/checks.json` once for the run.
 
-Append `{stage: context, status: done}` and re-render progress. If the scout returned without writing `brief.json`, append `{stage: context, status: skipped}` instead and continue: the brief is optional everywhere it is read.
+Append `{stage: context, status: done}` and re-render progress. If the scout wrote no `brief.json`, append `{stage: context, status: skipped}` instead and continue: the brief is optional everywhere it is read. If the checks pass wrote no `checks.json`, append `{stage: checks, status: skipped}`; nothing downstream needs it.
 
 ### 4. Specialists
 
@@ -134,7 +136,7 @@ advances `magpie status`.)
 
 Before leaving this stage, list `$RUN_DIR/findings` and confirm one file per expected
 `(focus, shard)` pair: `5 × <shard count>` named `findings/<focus>.shard-<n>.json` when
-sharded, five `findings/<focus>.json` otherwise, plus `findings/tests.json` from setup.
+sharded, five `findings/<focus>.json` otherwise, plus `findings/tests.json` from setup and `findings/checks.json` from stage 3.
 Re-dispatch any pair missing from a shard you meant to review; a shard skipped at the
 gate is expected to have none. `magpie dedupe` re-checks this against the manifest and
 names every missing pair on stdout, as a backstop rather than a substitute.
@@ -148,7 +150,7 @@ If every specialist fails (no findings files written), log
 magpie dedupe "$RUN_DIR" [--threshold <0-10>]
 ```
 
-`magpie dedupe` also checks evidence against the worktree, dropping an anchored finding whose file is missing (`hallucinated-file`), whose line is out of range (`invented-line`), that has no `evidence` snippet (`missing-evidence`), or whose snippet is not near its line (`evidence-not-found`); a snippet found exactly once elsewhere in the file re-anchors it. Both go to `$RUN_DIR/evidence-dropped.json` as `{dropped, reanchored}`, written only when non-empty, so no file is normal. The check is skipped when the worktree is gone (archived run replay).
+`magpie dedupe` also checks evidence against `$WORKTREE`, dropping an anchored finding whose file is missing (`hallucinated-file`), whose line is out of range (`invented-line`), that has no `evidence` snippet (`missing-evidence`), or whose snippet is not near its line (`evidence-not-found`); a snippet found exactly once elsewhere in the file re-anchors it. Both go to `$RUN_DIR/evidence-dropped.json` as `{dropped, reanchored}`, written only when non-empty, so no file is normal. The check is skipped when the worktree is gone (archived run replay).
 
 It always writes `$RUN_DIR/merge-candidates.json`: ids from different domains anchored close together in one file, for the critic to merge or keep apart.
 
@@ -158,7 +160,7 @@ Re-render progress.
 
 ### 6. Critic
 
-The critic runs as worktree-reading subagents. The CLI fills its prompt from `references/critic.md`; substitute nothing by hand. Append `{stage: critic, status: running}` to `$RUN_DIR/log.jsonl`, re-render progress, then:
+The critic runs as subagents that read `$WORKTREE`. The CLI fills its prompt from `references/critic.md`; substitute nothing by hand. Append `{stage: critic, status: running}` to `$RUN_DIR/log.jsonl`, re-render progress, then:
 
 ```
 magpie critic-prompt "$RUN_DIR"
@@ -254,6 +256,27 @@ The archived `findings.html` is self-contained and auto-switches to read-only "a
 - `magpie serve <id>` re-spins the Bun server against an archived run for the live interactive surface (posts still work: `pr.json` retains the head SHA).
 - `magpie --list-runs` enumerates all runs in `~/.magpie/`.
 
+## Local mode
+
+Reviews the current branch's diff for an agent that wants findings before a PR exists. Nothing is posted, served or rendered. Deltas from the walkthrough:
+
+`REPO` is the repo root the caller is working in (default: the current working directory). Resume an `active` run from `magpie --list-runs` only when its id is exactly `local-<slug>-<digits>` and `branch` in its `local.json` is the current branch. Otherwise:
+
+```
+SLUG=$(git -C "$REPO" branch --show-current | sed -E 's/[^A-Za-z0-9._-]+/-/g')
+RUN_DIR="$HOME/.magpie/local-${SLUG:-detached}-$(date +%s)"
+magpie setup "$RUN_DIR" --local --repo "$REPO" [--base <ref>] [--intent-file <path>]
+```
+
+On a non-zero exit, show stderr verbatim to the caller and stop. The diff runs from the merge base with `<ref>` to the working tree, untracked files included. `<ref>` defaults to `origin/HEAD`; when that is not the branch the work merges into, pass `--base` naming it (setup fails on an unresolvable ref rather than guessing). Pass `--intent-file` for the caller's spec or plan.
+
+- `WORKTREE=$(magpie target "$RUN_DIR")` is the repo itself. `TARGET` is `local branch <branch> against <baseRef>` (`detached HEAD against <baseRef>` when `branch` is null), from `local.json`.
+- Skip every `magpie render`. Peer review uses the "Local runs" list in `references/peer-review.md`. The stage 4 shard question goes to whoever asked for the review, which may be an orchestrating agent.
+- Stage 8: `magpie handoff "$RUN_DIR"`. On exit 4 (`findings.final.json` or `local.json` missing) or 2 (not a local run), show stderr to the caller and stop.
+- Then `magpie cleanup "$RUN_DIR" --repo "$REPO"` at once. Reply to the caller with the handoff stdout verbatim, then one line `Run archived at <path>`, `<path>` from cleanup's `archived to <path>`. End the turn.
+
+Do not edit the tree mid-run: anchors and evidence are read from it live. Without the Agent tool, stop and say so rather than reviewing single-handed. The local ladder ends at handoff, then cleanup; there is no server to restart.
+
 ## Resuming a crashed run
 
 A run is resumable while `$RUN_DIR/log.jsonl` exists and the run has not been archived. Do not test for `state/server-info`: the server deletes it whenever it stops, so a perfectly resumable run fails that check. Step 0 finds the run directory via `magpie --list-runs` when you don't already have it in `$RUN_DIR`.
@@ -265,7 +288,10 @@ magpie status "$RUN_DIR"
 The JSON output tells you `lastCompleted` and `next`. Resume from `next`:
 
 - `context`: if `$RUN_DIR/brief.json` exists, append `{stage: context, status: done}` and move on; otherwise re-run stage 3.
+- Any resume: re-dispatch the checks pass when `findings/checks.json` is missing and no `checks: skipped` is logged.
+- Any stage after context: first set `WORKTREE` and `TARGET` as in stage 3 (on a local run, as in Local mode).
 - Any other stage: run it as written in the walkthrough.
+- Local run at `next: cleanup`: if the caller has not been sent the findings, re-run `magpie handoff` first (it only reads files).
 - If a specialist focus has no findings file but its sibling stages are done,
   re-dispatch only that focus. On a sharded run the unit is the `(focus, shard)` pair:
   read `shards/manifest.json`, and re-dispatch only the pairs with no

package/skills/magpie/bin/magpie.ts

@@ -8,6 +8,11 @@ const USAGE = `Usage: magpie <subcommand> [args]
 
 Subcommands:
   setup <run-dir> --pr <n>   Pre-flight, fetch PR, create worktree
+  setup <run-dir> --local [--base <ref>] [--intent-file <path>]
+                             Review the current branch in place against <ref>
+                             (default origin/HEAD), committed and uncommitted
+  target <run-dir>           Print the directory findings are anchored against
+  handoff <run-dir>          Print local review findings as a ranked list
   serve <run-dir-or-id>      Start the HTML server (accepts active or archived run id)
   dedupe <run-dir>           Merge specialist findings into deduped set
   critic-prompt <run-dir> [--batch-size N]
@@ -57,20 +62,84 @@ const HANDLERS: Record<string, Handler> = {
   setup: async (args) => {
     const runDir = args[0]
     const prFlag = args.indexOf('--pr')
-    const prValue = prFlag !== -1 ? args[prFlag + 1] : undefined
-    const repoFlag = args.indexOf('--repo')
-    if (!runDir || prFlag === -1 || !prValue) {
-      process.stderr.write('setup: missing <run-dir> --pr <n> [--repo <path>]\n')
+    const isLocal = args.includes('--local')
+    // A flag in the run-dir slot is usually an unset, unquoted $RUN_DIR.
+    if (!runDir || runDir.startsWith('-')) {
+      process.stderr.write(
+        'setup: missing <run-dir> (--pr <n> | --local [--base <ref>] [--intent-file <path>]) [--repo <path>]\n',
+      )
+      return 2
+    }
+    if ((prFlag !== -1) === isLocal) {
+      process.stderr.write('setup: pass exactly one of --pr <n> or --local\n')
       return 2
     }
+    const flagValue = (name: string): string | undefined | null => {
+      const idx = args.indexOf(name)
+      if (idx === -1) return undefined
+      const value = args[idx + 1]
+      if (!value || value.startsWith('--')) {
+        process.stderr.write(`setup: ${name} needs a value\n`)
+        return null
+      }
+      return value
+    }
+    const repoValue = flagValue('--repo')
+    if (repoValue === null) return 2
+    const repoPath = repoValue ?? process.cwd()
+    const { runSetup } = await import('../scripts/setup-cmd.ts')
+    if (isLocal) {
+      const baseRef = flagValue('--base')
+      if (baseRef === null) return 2
+      const intentFile = flagValue('--intent-file')
+      if (intentFile === null) return 2
+      return runSetup({
+        mode: 'local',
+        runDir,
+        repoPath,
+        ...(baseRef !== undefined ? { baseRef } : {}),
+        ...(intentFile !== undefined ? { intentFile } : {}),
+      })
+    }
+    const prValue = flagValue('--pr')
+    if (prValue === null || prValue === undefined) return 2
     const prNumber = Number(prValue)
     if (!Number.isFinite(prNumber)) {
       process.stderr.write(`setup: invalid PR number ${prValue}\n`)
       return 2
     }
-    const repoPath = (repoFlag !== -1 ? args[repoFlag + 1] : undefined) ?? process.cwd()
-    const { runSetup } = await import('../scripts/setup-cmd.ts')
-    return runSetup({ runDir, prNumber, repoPath })
+    return runSetup({ mode: 'pr', runDir, prNumber, repoPath })
+  },
+  target: async (args) => {
+    const runDir = args[0]
+    if (!runDir || runDir.startsWith('-')) {
+      process.stderr.write('target: missing <run-dir>\n')
+      return 2
+    }
+    const { reviewRoot } = await import('../scripts/target.ts')
+    try {
+      process.stdout.write(`${await reviewRoot(runDir)}\n`)
+    } catch (err) {
+      process.stderr.write(`target: ${err instanceof Error ? err.message : String(err)}\n`)
+      return 2
+    }
+    return 0
+  },
+  handoff: async (args) => {
+    const runDir = args[0]
+    if (!runDir || runDir.startsWith('-')) {
+      process.stderr.write('handoff: missing <run-dir>\n')
+      return 2
+    }
+    const { readTarget } = await import('../scripts/target.ts')
+    try {
+      await readTarget(runDir)
+    } catch (err) {
+      process.stderr.write(`handoff: ${err instanceof Error ? err.message : String(err)}\n`)
+      return 2
+    }
+    const { runHandoff } = await import('../scripts/handoff-cmd.ts')
+    return runHandoff(runDir, { gitBin: process.env.MAGPIE_GIT_BIN || 'git' })
   },
   serve: async (args) => {
     const idOrPath = args[0]
@@ -275,6 +344,13 @@ const HANDLERS: Record<string, Handler> = {
       process.stderr.write('status: missing <run-dir>\n')
       return 2
     }
+    const { readTarget } = await import('../scripts/target.ts')
+    try {
+      await readTarget(runDir)
+    } catch (err) {
+      process.stderr.write(`status: ${err instanceof Error ? err.message : String(err)}\n`)
+      return 2
+    }
     const { runStatus } = await import('../scripts/status-cmd.ts')
     const result = await runStatus(runDir)
     process.stdout.write(`${JSON.stringify(result)}\n`)

package/skills/magpie/evals/README.md

@@ -1,6 +1,6 @@
 # magpie evals
 
-Five cases for `claude plugin eval`. Every one starts mid-pipeline, because the
+Six cases for `claude plugin eval`. Every one starts mid-pipeline, because the
 decisions this skill owns are the ones between the CLI calls: `scripts/__tests__/`
 already pins what `magpie setup`, `dedupe`, `shard`, `post` and `status` compute.
 What no unit test can reach is whether the agent stops where the walkthrough says
@@ -14,6 +14,7 @@ must not touch.
 | `report-ends-the-turn` | Stage 8 reached | Renders, logs the stage done, hands back for selection, posts nothing |
 | `post-folds-selection-events` | The user typed `post` after re-ticking | Folds `state/events` last-event-wins, posts `bugs-1,perf-1` only |
 | `resume-finds-active-run` | A fresh review ask on a PR with a live run | Checks `--list-runs` first, never calls `setup`, surfaces the interrupted run |
+| `local-mode-hands-back` | A local run resumed after peer review | Runs `handoff` then `cleanup`, replies with both finding titles, never serves, renders, posts or calls `gh` |
 
 ## Running
 
@@ -83,9 +84,11 @@ Three things follow from the sandbox, and cases are written around them:
   reports the workspace path.
 - **Fakes compute rather than answer.** `magpie status` reads `log.jsonl` with
   the same stage ladder as `scripts/status-cmd.ts`, so a stage the agent logs
-  moves `next` exactly as the real CLI would. A canned answer went stale the
-  moment the agent appended to the log, and the agent noticed and spent a
-  paragraph on it.
+  moves `next` exactly as the real CLI would. A local run uses the local ladder
+  (ending at `handoff`): the `local-mode-hands-back` fake reads `target.json` to
+  pick it, as the real CLI does, while the older fakes only know the PR ladder.
+  A canned answer went stale the moment the agent appended to the log, and the
+  agent noticed and spent a paragraph on it.
 
 Each fake also appends its argv to `.magpie-calls.log` in the workspace. That
 file is what most of the graders read: "posted exactly these ids", "never ran

package/skills/magpie/evals/local-mode-hands-back/case.yaml

@@ -0,0 +1,4 @@
+schema_version: "1.1"
+name: local-mode-hands-back
+context:
+  scaffold_script: fixture.sh