@iceinvein/agent-skills 0.1.39 → 0.1.40

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@iceinvein/agent-skills",
-  "version": "0.1.39",
+  "version": "0.1.40",
   "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.8.0"
+    "version": "0.9.0"
   },
   {
     "name": "module-secret-auditor",

package/skills/magpie/README.md

@@ -12,6 +12,7 @@ Given a GitHub PR number, dispatches five specialist subagents in parallel (secu
 - `gh` on PATH, authenticated (`gh auth status`)
 - `git` on PATH
 - `codex` on PATH, authenticated (optional; if absent the peer-review stage falls back to a Claude second-opinion subagent)
+- the code-intelligence MCP server, with a completed index for the repo under review (optional; if absent the specialists review from the diff and worktree alone)
 
 ## Install
 
@@ -54,7 +55,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: `specialists.md` (stage 3, the five focus blocks plus the shared output contract), `critic.md` (stage 5), `peer-review.md` (stage 6, 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), `specialists.md` (stage 4, the five focus blocks plus the shared output contract and the codebase-intelligence block), `critic.md` (stage 6), `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.).

package/skills/magpie/SKILL.md

@@ -46,8 +46,6 @@ When a prior run exists for the same PR (active or archived under `~/.magpie/`),
 
 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 written to `$RUN_DIR/findings/tests.json`. This is a sixth domain that flows through dedupe/critic/peer-review alongside the five LLM specialists. No specialist subagent is dispatched for it.
 
-The pipeline has no separate context-indexing stage, but `magpie status` and the progress page track one. After setup succeeds, append `{stage: context, status: skipped}` to `$RUN_DIR/log.jsonl`; both treat a skipped stage as behind them, so the pipeline advances to `specialists`.
-
 ### 2. Serve
 
 Start the HTML server in the background using the Bash tool with `run_in_background: true`:
@@ -66,7 +64,22 @@ Render the first progress paint:
 magpie render "$RUN_DIR" progress
 ```
 
-### 3. Specialists
+### 3. Context
+
+Append `{stage: context, status: running}` to `$RUN_DIR/log.jsonl` and re-render progress. This stage has two steps and never aborts the run.
+
+**Bind probe.** If the `mcp__code-intelligence__*` tools are not in your tool list, skip straight to the scout with `CODE_INTELLIGENCE=unavailable`. Otherwise call `bind_workspace` with `$RUN_DIR/worktree`. The worktree is a linked git worktree, so an already-indexed base repo seeds its index instead of re-indexing.
+
+- `consent_required` means the base repo has never completed an index. **Never call `approve_indexing`**: that is a full GPU pass the user did not ask for. Set `CODE_INTELLIGENCE=unavailable`, and print one line: "Code intelligence is unavailable (the base repo has no index); specialists will review from the diff alone."
+- `indexing_started` or `indexing_in_progress` means the seed took. Poll `get_index_stats` every 5s for at most 60s, then set `CODE_INTELLIGENCE=available` either way. Do not block the pipeline on completion; the specialist contract handles a still-indexing tool.
+- A ready result sets `CODE_INTELLIGENCE=available`.
+- Any other error sets `CODE_INTELLIGENCE=unavailable`. Do not retry.
+
+**Scout.** Read `references/scout.md` and dispatch one subagent (Agent tool, `general-purpose`) carrying the `magpie-scout` block with `<<RUN_DIR>>`, `<<PR_NUMBER>>`, and `<<CODE_INTELLIGENCE>>` substituted. It writes `$RUN_DIR/brief.json`.
+
+Append `{stage: context, status: done, codeIntelligence: true|false}` and re-render progress. If the scout returned without writing `brief.json`, append `{stage: context, status: skipped, codeIntelligence: true|false}` instead and continue: the brief is optional everywhere it is read. The bind probe's result is known regardless of what the scout did, so both entries carry it.
+
+### 4. Specialists
 
 Read `references/specialists.md` now, before dispatching anything. It holds the five focus blocks and the output contract that every specialist prompt is built from. Assemble the prompts from that file verbatim: prompts written from memory drift off the JSON contract, and `magpie dedupe` drops findings it cannot parse.
 
@@ -74,9 +87,9 @@ Append `{stage: specialists, status: running}` to `$RUN_DIR/log.jsonl` and re-re
 
 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`.)
 
-If all five specialists fail (no findings files written), log `{stage: specialists, status: error}` and stop. Otherwise mark `{stage: specialists, status: done}`.
+If all five specialists fail (no findings files written), log `{stage: specialists, status: error}`, rebind code intelligence to `$REPO` if bound (stage 10), and stop. Otherwise mark `{stage: specialists, status: done}`.
 
-### 4. Dedupe
+### 5. Dedupe
 
 ```
 magpie dedupe "$RUN_DIR" [--threshold <0-10>]
@@ -88,11 +101,11 @@ Each finding receives a derived 0-10 `score` from its risk fields. Findings belo
 
 Re-render progress.
 
-### 5. Critic
+### 6. Critic
 
 Read `references/critic.md` and `$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
+### 7. Peer review
 
 Append `{stage: peer-review, status: running}` to `$RUN_DIR/log.jsonl` and re-render progress. 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.
 
@@ -112,7 +125,7 @@ If codex returns non-zero, do not abort: record `{stage: peer-review, provider:
 
 **Apply the verdicts (both paths).** Parse the verdicts JSON and apply the `update` / `add` entries (an empty array means no change). For each `add`, mint a unique `id` on the new finding before merging (`peer-1`, `peer-2`, ...): the peer contract does not include ids, but every finding in `findings.final.json` must carry one or the report render and post stages will crash. Then write `findings.final.json`. Re-render progress.
 
-### 7. Report
+### 8. Report
 
 ```
 magpie render "$RUN_DIR" findings
@@ -124,7 +137,7 @@ Print to the terminal: "Findings ready at <url>. Tick the ones you want and clic
 
 End the turn.
 
-### 8. Post
+### 9. Post
 
 Most users will tick the checkboxes in the served report and click **Post Selected** (or **Post Recommended**, which takes every finding whose `risk.action` is `must-fix` or `should-fix`, skipping the `consider`/`optional` ones); the report server handles the rest and posts the batch as one GitHub review with inline threads. The agent only handles posts when the user explicitly types `post` (optionally `post 1,3,7` for indices) in the conversation, which takes the CLI path below: separate inline comments plus a top-level summary comment. Either path records posted ids in `post-status.json`, so the two cannot double-post the same finding.
 
@@ -147,12 +160,14 @@ Pass `--dry-run` to record the would-be gh commands without invoking gh. After p
 magpie render "$RUN_DIR" findings
 ```
 
-### 9. Cleanup
+### 10. Cleanup
 
 ```
 magpie cleanup "$RUN_DIR" --repo "$REPO"
 ```
 
+If the context stage bound code intelligence, rebind the session to the repository now: call `bind_workspace` with `$REPO`. Binding is per session with no per-call override, so a run that ends without this leaves your session pointed at a worktree `cleanup` just deleted. The daemon prunes the seeded index on its own once the worktree is gone.
+
 The run directory is renamed to `<run-dir>.archived-<timestamp>` and the worktree is removed. The CLI prints two lines on success: `archived to <path>` and `view later: magpie open <archived-id>`. Surface that second line to the user verbatim so they have a one-command path back to the report.
 
 The archived `findings.html` is self-contained and auto-switches to read-only "archived" mode when opened, so:
@@ -172,7 +187,7 @@ magpie status "$RUN_DIR"
 
 The JSON output tells you `lastCompleted` and `next`. Resume from `next`:
 
-- `context` is a no-op. Append `{stage: context, status: skipped}` and continue at `specialists`.
+- `context` re-runs by redoing the bind probe, then dispatching the scout only if `$RUN_DIR/brief.json` is missing. The seeded index survives a crash, so the rebind is near-instant.
 - Any other stage: run it as written in the walkthrough.
 - If a specialist focus has no findings file but its sibling stages are done, re-dispatch only that focus.
 - Non-null `error` means the run stopped on a failed stage. Report which stage to the user and confirm before re-running it.
@@ -181,4 +196,4 @@ The server from the original run is gone. Restart it with `magpie serve "$RUN_DI
 
 ## Aborting
 
-If the user types `abort` mid-run, run `magpie cleanup` immediately and exit.
+If the user types `abort` mid-run, rebind code intelligence to `$REPO` if bound (stage 10), then run `magpie cleanup` and exit.

package/skills/magpie/fixtures/example-pr/brief.json

@@ -0,0 +1,18 @@
+{
+  "purpose": "Adds bounded retries to the upload path so transient S3 failures stop surfacing to end users as hard errors.",
+  "changes": [
+    "Wraps the S3 put call in a bounded retry with jittered backoff",
+    "Threads a per-request deadline through the storage client",
+    "Adds a metrics counter for exhausted retry budgets"
+  ],
+  "subsystems": [
+    { "name": "upload", "role": "owns the client-facing put path" },
+    { "name": "storage-client", "role": "wraps the S3 SDK and owns timeouts" }
+  ],
+  "watchItems": [
+    "The PR body claims the retry is idempotent, but no idempotency key is sent with the put"
+  ],
+  "unclear": [
+    "Whether the new per-request deadline interacts correctly with the outer HTTP timeout"
+  ]
+}

package/skills/magpie/fixtures/fake-gh.sh

@@ -19,6 +19,20 @@ case "$1 $2" in
       "deletions": 0,
       "changeType": "modified"
     }
+  ],
+  "commits": [
+    {
+      "oid": "deadbeefdeadbeefdeadbeefdeadbeefdeadbeef",
+      "messageHeadline": "Add retry handling to the upload path",
+      "messageBody": ""
+    }
+  ],
+  "closingIssuesReferences": [
+    {
+      "number": 42,
+      "title": "Uploads fail intermittently under load",
+      "url": "https://github.com/octocat/Hello-World/issues/42"
+    }
   ]
 }
 JSON

package/skills/magpie/package.json

@@ -1,6 +1,6 @@
 {
   "name": "magpie",
-  "version": "0.8.0",
+  "version": "0.9.0",
   "private": true,
   "type": "module",
   "scripts": {

package/skills/magpie/references/scout.md

@@ -0,0 +1,90 @@
+# Scout prompt
+
+Stage 3 of the walkthrough dispatches one subagent from this file, before the five
+specialists. Send the fenced `magpie-scout` block below as the agent's entire task,
+with `<<RUN_DIR>>` and `<<PR_NUMBER>>` replaced by the real values first. The
+subagent has no shell variables from your session, so an unexpanded path means it
+writes the brief where nothing will read it.
+
+Substitute `<<CODE_INTELLIGENCE>>` with `available` when the bind probe succeeded and
+`unavailable` otherwise. The scout still runs when code-intelligence is unavailable;
+only the subsystem map degrades.
+
+```magpie-scout
+You are a senior engineer building the orienting brief that five specialist
+reviewers will read before they review PR #<<PR_NUMBER>>. You are not reviewing the
+code. You are answering "what is this PR for, and what does it actually do".
+
+Working directory: <<RUN_DIR>>/worktree
+PR metadata: <<RUN_DIR>>/pr.json
+Diff: <<RUN_DIR>>/diff.patch
+Code intelligence: <<CODE_INTELLIGENCE>>
+
+## What to read
+
+1. `pr.json` for the author's stated intent: `title`, `body`, `commits[].messageHeadline`,
+   and `closingIssuesReferences[].title`. This is the claim.
+2. `diff.patch` for what the change actually does. This is the evidence.
+3. The worktree for surrounding context on any file the diff changes but does not
+   explain.
+
+## Code intelligence
+
+When the line above says `available`, the code-intelligence MCP tools are indexed
+against `<<RUN_DIR>>/worktree`, seeded from the base repository. Call `bind_workspace`
+with `<<RUN_DIR>>/worktree` before your first query. Use them to map where the change
+lands:
+
+- `get_module_summary` on each directory the diff touches, to name the subsystem and
+  say what it is responsible for.
+- `explore_dependency_graph` on the touched modules, to say what depends on them.
+
+If a tool returns `indexing_in_progress`, finish reading the diff and retry once. If
+it still is not ready, or the line above says `unavailable`, write `"subsystems": []`
+and carry on. Never call `approve_indexing`. Never call `refresh_index`. Triggering a
+full index is a consent-gated operation that is not yours to start.
+
+## How to reason
+
+1. State the purpose in your own words, not the author's. If you cannot restate it
+   without quoting the PR body, you have not understood it yet.
+2. Group the diff into 3-7 concerns. A concern is a thing a reviewer would evaluate
+   as a unit, not a file.
+3. Compare the claim against the evidence. Where the diff does something the stated
+   intent does not cover, or omits something the stated intent implies, that is a
+   watch item.
+4. Be honest about what you could not determine. An empty `unclear` on a large PR is
+   not credible.
+
+## Output contract
+
+Write `<<RUN_DIR>>/brief.json` before returning. The file MUST be a JSON object with
+exactly these five keys:
+
+{
+  "purpose":    string,   // 1-3 sentences: what this PR is for, in your words. Required
+                          //   and non-empty; a brief with no purpose is discarded whole.
+  "changes":    string[], // 3-7 entries: what it actually does, grouped by concern.
+                          //   One clause each, no trailing period needed.
+  "subsystems": [ { "name": string, "role": string } ],
+                          // Code-intelligence derived. `name` is the subsystem, `role`
+                          //   is one clause on what it is responsible for. [] when
+                          //   code intelligence is unavailable.
+  "watchItems": string[], // Where the diff and the stated intent diverge, or where the
+                          //   intent implies a risk the diff does not address. Often
+                          //   empty. See the boundary below.
+  "unclear":    string[]  // What you could not determine from the bundle.
+}
+
+A watch item is not a finding. You do not assign severity, you do not assign risk,
+and you do not recommend a fix. A watch item is a pointer a specialist may escalate
+into a finding in its own domain, with its own risk fields, or dismiss. Write it as
+an observation: "the PR body claims X, but the diff does Y".
+
+Do not add keys. Do not omit keys; write `[]` for an empty list. Do not transcribe
+commit messages or issue titles into the brief: the report reads those from `pr.json`
+directly, and repeating them wastes the specialists' attention.
+
+Return as your final tool result a single line:
+`brief: <N> changes, <M> subsystems, <K> watch items`. Do not include other prose.
+```

package/skills/magpie/references/specialists.md

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

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

@@ -45,3 +45,24 @@ test('fetchPr returns ok=false when gh exits non-zero', async () => {
     expect(result.error).toBeDefined()
   }
 })
+
+test('PR_VIEW_FIELDS requests commit messages and linked issues', async () => {
+  const { PR_VIEW_FIELDS } = await import('../gh.ts')
+  const fields = PR_VIEW_FIELDS.split(',')
+  expect(fields).toContain('commits')
+  expect(fields).toContain('closingIssuesReferences')
+  // The pre-existing fields must survive the edit.
+  for (const field of ['number', 'title', 'body', 'url', 'files', 'headRefOid']) {
+    expect(fields).toContain(field)
+  }
+})
+
+test('fetchPr carries commits and linked issues into pr.json', async () => {
+  const result = await fetchPr({ ghBin: FAKE_GH, prNumber: 1234, runDir })
+  expect(result.ok).toBe(true)
+  const pr = JSON.parse(await readFile(join(runDir, 'pr.json'), 'utf8'))
+  expect(Array.isArray(pr.commits)).toBe(true)
+  expect(pr.commits[0].messageHeadline).toBe('Add retry handling to the upload path')
+  expect(Array.isArray(pr.closingIssuesReferences)).toBe(true)
+  expect(pr.closingIssuesReferences[0]).toMatchObject({ number: 42 })
+})

package/skills/magpie/scripts/__tests__/preview-cmd.test.ts

@@ -208,3 +208,19 @@ test('bundled fixture covers all five focus domains', async () => {
     expect(html).toContain(`data-domain="${domain}"`)
   }
 })
+
+test('bundled fixture brief.json renders the PR brief header', async () => {
+  await runPreview({
+    page: 'findings',
+    stage: DEFAULT_STAGE,
+    outDir: workDir,
+    openInBrowser: false,
+  })
+  const html = await readFile(join(workDir, 'findings.html'), 'utf8')
+  expect(html).toContain('class="pr-brief"')
+  // Unique to fixtures/example-pr/brief.json; would not appear from any other
+  // part of the fixture or the page shell.
+  expect(html).toContain(
+    'Adds bounded retries to the upload path so transient S3 failures stop surfacing to end users as hard errors.',
+  )
+})

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

@@ -84,3 +84,48 @@ test('refreshFindings sets data-run-id from the run directory basename', async (
   const expectedId = runDir.split('/').pop()
   expect(fresh).toContain(`data-run-id="${expectedId}"`)
 })
+
+test('refreshFindings carries the brief header through, so archives keep it on re-render', async () => {
+  await writeFile(join(runDir, 'findings.final.json'), JSON.stringify([]))
+  await writeFile(
+    join(runDir, 'brief.json'),
+    JSON.stringify({
+      purpose: 'Adds bounded retries to the upload path.',
+      changes: ['Wraps the S3 put in a bounded retry'],
+      subsystems: [{ name: 'upload', role: 'owns the put path' }],
+      watchItems: [],
+      unclear: [],
+    }),
+  )
+  const result = await refreshFindings(runDir)
+  expect(result.refreshed).toBe(true)
+  const fresh = await readFile(join(runDir, 'screen', 'findings.html'), 'utf8')
+  expect(fresh).toContain('class="pr-brief"')
+  expect(fresh).toContain('Adds bounded retries to the upload path.')
+})
+
+test('refreshFindings omits the brief header when brief.json is absent', async () => {
+  await writeFile(join(runDir, 'findings.final.json'), JSON.stringify([]))
+  await refreshFindings(runDir)
+  const fresh = await readFile(join(runDir, 'screen', 'findings.html'), 'utf8')
+  expect(fresh).not.toContain('class="pr-brief"')
+})
+
+test('refreshFindings carries linked issues from pr.json through the brief header', async () => {
+  await writeFile(join(runDir, 'findings.final.json'), JSON.stringify([]))
+  await writeFile(
+    join(runDir, 'pr.json'),
+    JSON.stringify({
+      number: 1234,
+      headRefName: 'feature-x',
+      headRefOid: 'deadbeef',
+      closingIssuesReferences: [
+        { number: 42, title: 'Uploads fail', url: 'https://example.test/issues/42' },
+      ],
+    }),
+  )
+  await writeFile(join(runDir, 'brief.json'), JSON.stringify({ purpose: 'Fixes uploads.' }))
+  await refreshFindings(runDir)
+  const fresh = await readFile(join(runDir, 'screen', 'findings.html'), 'utf8')
+  expect(fresh).toContain('https://example.test/issues/42')
+})

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

@@ -1,5 +1,5 @@
 import { afterEach, beforeEach, expect, test } from 'bun:test'
-import { mkdir, mkdtemp, readdir, rm, writeFile } from 'node:fs/promises'
+import { mkdir, mkdtemp, readdir, readFile, rm, writeFile } from 'node:fs/promises'
 import { tmpdir } from 'node:os'
 import { join } from 'node:path'
 import { runRender } from '../render-cmd.ts'
@@ -115,3 +115,80 @@ test('findings render includes files and diff when provided', async () => {
   expect(html).toContain('data-file-pane="src/app.ts"')
   expect(html).toContain('data-file-pane="src/util.ts"')
 })
+
+test('findings render includes the brief header when brief.json is present', async () => {
+  await writeFile(join(runDir, 'findings.final.json'), JSON.stringify([]))
+  await writeFile(
+    join(runDir, 'brief.json'),
+    JSON.stringify({
+      purpose: 'Adds bounded retries to the upload path.',
+      changes: ['Wraps the S3 put in a bounded retry'],
+      subsystems: [{ name: 'upload', role: 'owns the put path' }],
+      watchItems: [],
+      unclear: [],
+    }),
+  )
+  expect(await runRender(runDir, 'findings')).toBe(0)
+  const html = await readFile(join(runDir, 'screen', 'findings.html'), 'utf8')
+  expect(html).toContain('class="pr-brief"')
+  expect(html).toContain('Adds bounded retries to the upload path.')
+})
+
+test('findings render omits the brief header when brief.json is absent', async () => {
+  await writeFile(join(runDir, 'findings.final.json'), JSON.stringify([]))
+  expect(await runRender(runDir, 'findings')).toBe(0)
+  const html = await readFile(join(runDir, 'screen', 'findings.html'), 'utf8')
+  expect(html).not.toContain('class="pr-brief"')
+})
+
+test('a malformed brief.json degrades to no header instead of failing the render', async () => {
+  await writeFile(join(runDir, 'findings.final.json'), JSON.stringify([]))
+  await writeFile(join(runDir, 'brief.json'), '{ this is not json')
+  expect(await runRender(runDir, 'findings')).toBe(0)
+  const html = await readFile(join(runDir, 'screen', 'findings.html'), 'utf8')
+  expect(html).not.toContain('class="pr-brief"')
+})
+
+test('linked issues from pr.json render in the brief header', async () => {
+  await writeFile(join(runDir, 'findings.final.json'), JSON.stringify([]))
+  await writeFile(
+    join(runDir, 'pr.json'),
+    JSON.stringify({
+      number: 1234,
+      headRefName: 'feature-x',
+      headRefOid: 'deadbeef',
+      closingIssuesReferences: [
+        { number: 42, title: 'Uploads fail', url: 'https://example.test/issues/42' },
+      ],
+    }),
+  )
+  await writeFile(join(runDir, 'brief.json'), JSON.stringify({ purpose: 'Fixes uploads.' }))
+  expect(await runRender(runDir, 'findings')).toBe(0)
+  const html = await readFile(join(runDir, 'screen', 'findings.html'), 'utf8')
+  expect(html).toContain('https://example.test/issues/42')
+})
+
+test('issue entries with a missing, zero, or negative number are dropped, not defaulted to 0', async () => {
+  await writeFile(join(runDir, 'findings.final.json'), JSON.stringify([]))
+  await writeFile(
+    join(runDir, 'pr.json'),
+    JSON.stringify({
+      number: 1234,
+      headRefName: 'feature-x',
+      headRefOid: 'deadbeef',
+      closingIssuesReferences: [
+        { number: 42, title: 'Uploads fail', url: 'https://example.test/issues/42' },
+        { title: 'Missing number', url: 'https://example.test/issues/missing' },
+        { number: 0, title: 'Zero number', url: 'https://example.test/issues/zero' },
+        { number: -1, title: 'Negative number', url: 'https://example.test/issues/negative' },
+      ],
+    }),
+  )
+  await writeFile(join(runDir, 'brief.json'), JSON.stringify({ purpose: 'Fixes uploads.' }))
+  expect(await runRender(runDir, 'findings')).toBe(0)
+  const html = await readFile(join(runDir, 'screen', 'findings.html'), 'utf8')
+  expect(html).toContain('https://example.test/issues/42')
+  expect(html).not.toContain('https://example.test/issues/missing')
+  expect(html).not.toContain('https://example.test/issues/zero')
+  expect(html).not.toContain('https://example.test/issues/negative')
+})