@iceinvein/agent-skills 0.1.39 → 0.1.40

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

@@ -2,7 +2,7 @@ import { beforeAll, expect, test } from 'bun:test'
 import type { Highlighter } from 'shiki'
 import { getHighlighter } from '../highlight.ts'
 import { renderFindingsHtml } from '../render-findings.ts'
-import type { ReviewFinding } from '../types.ts'
+import type { PrBrief, ReviewFinding } from '../types.ts'
 
 function f(p: Partial<ReviewFinding> & { id: string; title: string }): ReviewFinding {
   return {
@@ -200,3 +200,120 @@ test('renders pr meta when supplied', () => {
   expect(html).toContain('feat/x')
   expect(html).toContain('deadbeefdead')
 })
+
+const SAMPLE_BRIEF: PrBrief = {
+  purpose:
+    'Adds bounded retries to the upload path so transient S3 failures stop surfacing to users.',
+  changes: ['Wraps the S3 put in a bounded retry', 'Adds a jittered backoff helper'],
+  subsystems: [
+    { name: 'upload', role: 'owns the client-facing put path' },
+    { name: 'storage-client', role: 'wraps the S3 SDK' },
+  ],
+  watchItems: ['The PR body claims idempotency but no request key is sent'],
+  unclear: ['Whether the retry budget interacts with the outer request timeout'],
+}
+
+test('brief header renders purpose, changes, and subsystem chips', () => {
+  const html = renderFindingsHtml({
+    findings: SAMPLE_FINDINGS,
+    postStatus: {},
+    highlighter: hl,
+    brief: SAMPLE_BRIEF,
+  })
+  expect(html).toContain('class="pr-brief"')
+  expect(html).toContain('Adds bounded retries to the upload path')
+  expect(html).toContain('Wraps the S3 put in a bounded retry')
+  expect(html).toContain('class="brief-chip"')
+  expect(html).toContain('>upload<')
+  expect(html).toContain('>storage-client<')
+})
+
+test('brief header omits watchItems and unclear, which are prompt-only', () => {
+  const html = renderFindingsHtml({
+    findings: SAMPLE_FINDINGS,
+    postStatus: {},
+    highlighter: hl,
+    brief: SAMPLE_BRIEF,
+  })
+  expect(html).not.toContain('no request key is sent')
+  expect(html).not.toContain('outer request timeout')
+})
+
+test('no brief means no brief header at all', () => {
+  const html = renderFindingsHtml({ findings: SAMPLE_FINDINGS, postStatus: {}, highlighter: hl })
+  expect(html).not.toContain('class="pr-brief"')
+})
+
+test('an empty subsystem list renders no chip row', () => {
+  const html = renderFindingsHtml({
+    findings: SAMPLE_FINDINGS,
+    postStatus: {},
+    highlighter: hl,
+    brief: { ...SAMPLE_BRIEF, subsystems: [] },
+  })
+  expect(html).toContain('class="pr-brief"')
+  expect(html).not.toContain('brief-subsystems')
+})
+
+test('brief header renders on the empty-findings page too', () => {
+  const html = renderFindingsHtml({
+    findings: [],
+    postStatus: {},
+    highlighter: hl,
+    brief: SAMPLE_BRIEF,
+  })
+  expect(html).toContain('No findings')
+  expect(html).toContain('class="pr-brief"')
+})
+
+test('linked issues render as links when supplied', () => {
+  const html = renderFindingsHtml({
+    findings: SAMPLE_FINDINGS,
+    postStatus: {},
+    highlighter: hl,
+    brief: SAMPLE_BRIEF,
+    issues: [
+      { number: 42, title: 'Uploads fail intermittently', url: 'https://example.test/issues/42' },
+    ],
+  })
+  expect(html).toContain('https://example.test/issues/42')
+  expect(html).toContain('#42')
+})
+
+test('brief content is HTML-escaped', () => {
+  const html = renderFindingsHtml({
+    findings: SAMPLE_FINDINGS,
+    postStatus: {},
+    highlighter: hl,
+    brief: { ...SAMPLE_BRIEF, purpose: 'Fixes <script>alert(1)</script> handling' },
+  })
+  expect(html).not.toContain('<script>alert(1)</script>')
+  expect(html).toContain('&lt;script&gt;')
+})
+
+test('subsystem role and issue title escape quotes in their title="" attribute context', () => {
+  const html = renderFindingsHtml({
+    findings: SAMPLE_FINDINGS,
+    postStatus: {},
+    highlighter: hl,
+    brief: {
+      ...SAMPLE_BRIEF,
+      subsystems: [{ name: 'upload', role: 'owns the put path" onmouseover="alert(1)' }],
+    },
+    issues: [
+      {
+        number: 42,
+        title: 'fails intermittently" onmouseover="alert(2)',
+        url: 'https://example.test/issues/42',
+      },
+    ],
+  })
+  // Raw quote-breakout must never appear unescaped in either attribute.
+  expect(html).not.toContain('path" onmouseover="alert(1)')
+  expect(html).not.toContain('intermittently" onmouseover="alert(2)')
+  // Escaped form must appear instead.
+  expect(html).toContain('path&quot; onmouseover=&quot;alert(1)')
+  expect(html).toContain('intermittently&quot; onmouseover=&quot;alert(2)')
+  // purpose escaping (already covered above) must remain intact alongside this.
+  expect(html).toContain('Adds bounded retries to the upload path')
+})

package/skills/magpie/scripts/__tests__/skill-lint.test.ts

@@ -24,7 +24,7 @@ test('references/ ships in the install bundle', async () => {
   }
   const covers = (p: string) =>
     manifest.bundle.include.some((inc) => inc === p || p.startsWith(`${inc}/`))
-  for (const name of ['specialists.md', 'critic.md', 'peer-review.md']) {
+  for (const name of ['specialists.md', 'critic.md', 'peer-review.md', 'scout.md']) {
     expect(covers(`references/${name}`)).toBe(true)
   }
 })
@@ -81,6 +81,22 @@ test('references/peer-review.md holds the prompt and the Claude preamble', async
   }
 })
 
+test('references/scout.md holds the scout prompt and the brief contract', async () => {
+  const text = await readFile(ref('scout.md'), 'utf8')
+  expect(text).toContain('```magpie-scout')
+  expect(text).toContain('brief.json')
+  for (const key of ['purpose', 'changes', 'subsystems', 'watchItems', 'unclear']) {
+    expect(text).toContain(key)
+  }
+  for (const ph of ['<<RUN_DIR>>', '<<PR_NUMBER>>']) {
+    expect(text).toContain(ph)
+  }
+  // The scout must never trigger a full index; that is a consent-gated GPU pass.
+  expect(text).toMatch(/never call `approve_indexing`|do not call `approve_indexing`/i)
+  // watchItems are context for specialists, not findings in their own right.
+  expect(text).toMatch(/not a finding/i)
+})
+
 test('SKILL.md sends each stage to the reference file it needs', async () => {
   const text = await readFile(SKILL, 'utf8')
   const section = (heading: string) => {
@@ -89,20 +105,73 @@ test('SKILL.md sends each stage to the reference file it needs', async () => {
     const next = text.indexOf('\n### ', start + heading.length)
     return text.slice(start, next === -1 ? undefined : next)
   }
-  expect(section('### 3. Specialists')).toContain('references/specialists.md')
-  expect(section('### 5. Critic')).toContain('references/critic.md')
-  expect(section('### 6. Peer review')).toContain('references/peer-review.md')
+  expect(section('### 3. Context')).toContain('references/scout.md')
+  expect(section('### 4. Specialists')).toContain('references/specialists.md')
+  expect(section('### 6. Critic')).toContain('references/critic.md')
+  expect(section('### 7. Peer review')).toContain('references/peer-review.md')
 })
 
 test('SKILL.md no longer inlines the prompt bodies it moved out', async () => {
   const text = await readFile(SKILL, 'utf8')
-  for (const tag of ['magpie-specialist-', 'magpie-critic', 'magpie-peer-review']) {
+  for (const tag of ['magpie-specialist-', 'magpie-critic', 'magpie-peer-review', 'magpie-scout']) {
     expect(text).not.toContain(`\`\`\`${tag}`)
   }
   // The walkthrough is the always-read part; keep it small enough to be cheap.
   expect(text.split(/\s+/).length).toBeLessThan(2600)
 })
 
+test('SKILL.md never instructs the agent to approve indexing', async () => {
+  const text = await readFile(SKILL, 'utf8')
+  // A full index is a consent-gated GPU pass. The context stage degrades instead.
+  expect(text).toContain('approve_indexing')
+  expect(text).toMatch(/never call `approve_indexing`|do not call `approve_indexing`/i)
+})
+
+test('SKILL.md logs codeIntelligence on both the done and skipped context outcomes', async () => {
+  const text = await readFile(SKILL, 'utf8')
+  const start = text.indexOf('### 3. Context')
+  expect(start).toBeGreaterThan(-1)
+  const section = text.slice(start, text.indexOf('\n### 4.', start))
+  // The bind probe's result is known by the time either log line is written,
+  // regardless of whether the scout produced a brief; specialists read this key
+  // to decide whether to include the codebase-intelligence block.
+  const doneEntry = section.match(/\{stage: context, status: done[^}]*\}/)
+  const skippedEntry = section.match(/\{stage: context, status: skipped[^}]*\}/)
+  expect(doneEntry?.[0]).toContain('codeIntelligence')
+  expect(skippedEntry?.[0]).toContain('codeIntelligence')
+})
+
+test('SKILL.md rebinds the code-intelligence session at cleanup', async () => {
+  const text = await readFile(SKILL, 'utf8')
+  const start = text.indexOf('### 10. Cleanup')
+  expect(start).toBeGreaterThan(-1)
+  const section = text.slice(start, text.indexOf('\n## ', start))
+  // Binding is per session with no per-call override, so a run that ends without
+  // rebinding leaves the session pointed at a worktree that no longer exists.
+  expect(section).toContain('bind_workspace')
+})
+
+test('SKILL.md rebinds before cleanup on the abort path too', async () => {
+  const text = await readFile(SKILL, 'utf8')
+  const start = text.indexOf('## Aborting')
+  expect(start).toBeGreaterThan(-1)
+  const section = text.slice(start)
+  // Stage 3 bound the session to the worktree; `abort` deletes that worktree via
+  // `magpie cleanup`, so it must rebind first or leave the session dangling.
+  expect(section).toMatch(/rebind.*(\$REPO|stage 10)/i)
+  expect(section).toContain('magpie cleanup')
+})
+
+test('SKILL.md rebinds before the stage-4 all-specialists-failed hard stop', async () => {
+  const text = await readFile(SKILL, 'utf8')
+  const start = text.indexOf('### 4. Specialists')
+  expect(start).toBeGreaterThan(-1)
+  const section = text.slice(start, text.indexOf('\n### 5.', start))
+  // This path stops the run without calling cleanup, but a later resume or
+  // abort must not find the session still pointed at the worktree.
+  expect(section).toMatch(/rebind.*(\$REPO|stage 10)/i)
+})
+
 test('styles.css declares a prefers-color-scheme:dark block that overrides core tokens', async () => {
   const STYLES = new URL('../../templates/styles.css', import.meta.url).pathname
   const css = await readFile(STYLES, 'utf8')
@@ -195,7 +264,8 @@ test('SKILL.md does not gate resume on state/server-info', async () => {
   expect(section).not.toMatch(/if .*server-info.* exists/i)
   // Resuming must restart the server; the old one is gone.
   expect(section).toContain('magpie serve')
-  // `context` is a no-op stage: say so, or the agent stalls on it.
+  // `context` re-runs on resume too (bind probe plus a conditional scout
+  // dispatch); the resume section must still call it out explicitly.
   expect(section).toContain('context')
 })
 
@@ -222,3 +292,38 @@ test('SKILL.md has the stage walkthrough', async () => {
   expect(text).toMatch(/magpie render/)
   expect(text).toMatch(/magpie cleanup/)
 })
+
+test('references/specialists.md carries the codebase-intelligence block', async () => {
+  const text = await readFile(ref('specialists.md'), 'utf8')
+  expect(text).toContain('```magpie-codebase-intelligence')
+  const start = text.indexOf('```magpie-codebase-intelligence')
+  const block = text.slice(start, text.indexOf('```', start + 32))
+  expect(block).toContain('bind_workspace')
+  expect(block).toContain('indexing_in_progress')
+  // The one operation a specialist must never perform.
+  expect(block).toMatch(/never call `approve_indexing`|do not call `approve_indexing`/i)
+})
+
+test('every focus block names the code-intelligence tool for its focus', async () => {
+  const text = await readFile(ref('specialists.md'), 'utf8')
+  const tools: Record<(typeof FOCUSES)[number], string> = {
+    security: 'trace_data_flow',
+    bugs: 'get_call_hierarchy',
+    performance: 'find_affected_code',
+    'code-smells': 'search_code',
+    architecture: 'explore_dependency_graph',
+  }
+  for (const focus of FOCUSES) {
+    const fence = `\`\`\`magpie-specialist-${focus}`
+    const start = text.indexOf(fence)
+    const block = text.slice(start, text.indexOf('```', start + fence.length))
+    expect(block).toContain(tools[focus])
+  }
+})
+
+test('the output contract tells specialists to look before they hedge', async () => {
+  const text = await readFile(ref('specialists.md'), 'utf8')
+  const contract = text.slice(0, text.indexOf('```magpie-specialist-'))
+  expect(contract).toContain('Needs verification:')
+  expect(contract).toMatch(/look before .*hedg/i)
+})

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

@@ -6,6 +6,7 @@ import {
   FOCUS_IDS,
   isSuggestion,
   looksLikeProse,
+  parseBrief,
   parseFinding,
 } from '../types.ts'
 
@@ -316,3 +317,49 @@ describe('isSuggestion', () => {
     ).toBe(false)
   })
 })
+
+test('parseBrief accepts a well-formed brief', () => {
+  const brief = parseBrief({
+    purpose: 'Adds retry handling to the upload path.',
+    changes: ['Wraps the S3 put in a bounded retry', 'Adds a jittered backoff helper'],
+    subsystems: [{ name: 'upload', role: 'owns the client-facing put path' }],
+    watchItems: ['The PR body claims idempotency but no request key is sent'],
+    unclear: ['Whether the retry budget interacts with the outer request timeout'],
+  })
+  expect(brief).not.toBeNull()
+  expect(brief?.purpose).toBe('Adds retry handling to the upload path.')
+  expect(brief?.changes).toHaveLength(2)
+  expect(brief?.subsystems[0]).toEqual({ name: 'upload', role: 'owns the client-facing put path' })
+  expect(brief?.watchItems).toHaveLength(1)
+  expect(brief?.unclear).toHaveLength(1)
+})
+
+test('parseBrief returns null for a brief with no purpose', () => {
+  expect(parseBrief({ changes: ['a'] })).toBeNull()
+  expect(parseBrief({ purpose: '   ', changes: ['a'] })).toBeNull()
+})
+
+test('parseBrief returns null for non-objects', () => {
+  expect(parseBrief(null)).toBeNull()
+  expect(parseBrief('a brief')).toBeNull()
+  expect(parseBrief(['a brief'])).toBeNull()
+})
+
+test('parseBrief drops junk entries instead of throwing', () => {
+  const brief = parseBrief({
+    purpose: 'Does a thing.',
+    changes: ['kept', 42, null, '   ', 'also kept'],
+    subsystems: [{ name: 'kept', role: 'r' }, { role: 'no name' }, 'not an object', null],
+    watchItems: 'not an array',
+    unclear: undefined,
+  })
+  expect(brief?.changes).toEqual(['kept', 'also kept'])
+  expect(brief?.subsystems).toEqual([{ name: 'kept', role: 'r' }])
+  expect(brief?.watchItems).toEqual([])
+  expect(brief?.unclear).toEqual([])
+})
+
+test('parseBrief defaults a subsystem with no role to an empty role', () => {
+  const brief = parseBrief({ purpose: 'p', subsystems: [{ name: 'auth' }] })
+  expect(brief?.subsystems).toEqual([{ name: 'auth', role: '' }])
+})

package/skills/magpie/scripts/gh.ts

@@ -13,7 +13,7 @@ export type FetchPrResult =
   | { ok: true; prJsonPath: string; diffPath: string }
   | { ok: false; error: string }
 
-const PR_VIEW_FIELDS = [
+export const PR_VIEW_FIELDS = [
   'number',
   'title',
   'headRefName',
@@ -26,6 +26,9 @@ const PR_VIEW_FIELDS = [
   // depending on cwd (the worktree is gone after cleanup).
   'url',
   'files',
+  // Intent evidence for the scout's brief, and issue links for the report header.
+  'commits',
+  'closingIssuesReferences',
 ].join(',')
 
 export async function fetchPr(input: FetchPrInput): Promise<FetchPrResult> {

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

@@ -4,7 +4,7 @@ import type { PostStatusMap } from './render-findings.ts'
 import { renderFindingsToDisk } from './render-findings.ts'
 import type { RenderProgressInput, StageId, StageStatus } from './render-progress.ts'
 import { renderProgressToDisk } from './render-progress.ts'
-import { parseFinding } from './types.ts'
+import { type PrBrief, parseBrief, parseFinding } from './types.ts'
 
 export type PreviewPage = 'findings' | 'progress' | 'both'
 
@@ -181,6 +181,7 @@ async function readFixture(fixtureDir: string): Promise<{
   postStatus: PostStatusMap
   files: Array<{ path: string; additions: number; deletions: number }>
   diff: string
+  brief: PrBrief | undefined
 }> {
   const prRaw = JSON.parse(await readFile(join(fixtureDir, 'pr.json'), 'utf8')) as Record<
     string,
@@ -214,6 +215,13 @@ async function readFixture(fixtureDir: string): Promise<{
   } catch {
     // optional file
   }
+  let brief: PrBrief | undefined
+  try {
+    const briefRaw = JSON.parse(await readFile(join(fixtureDir, 'brief.json'), 'utf8'))
+    brief = parseBrief(briefRaw) ?? undefined
+  } catch {
+    // optional file
+  }
   return {
     pr: {
       number: Number(prRaw.number ?? 0),
@@ -224,6 +232,7 @@ async function readFixture(fixtureDir: string): Promise<{
     postStatus: postStatusRaw as PostStatusMap,
     files: filesArray,
     diff,
+    brief,
   }
 }
 
@@ -270,6 +279,7 @@ export async function runPreview(opts: PreviewOptions): Promise<PreviewResult> {
         pr: fixture.pr,
         files: fixture.files,
         diff: fixture.diff,
+        brief: fixture.brief,
       },
       findingsPath,
     )

package/skills/magpie/scripts/refresh.ts

@@ -1,7 +1,7 @@
 import { readdir, readFile, unlink } from 'node:fs/promises'
 import { basename, join } from 'node:path'
-import { type PostStatusMap, renderFindingsToDisk } from './render-findings.ts'
-import { type PrFileEntry, parseFinding } from './types.ts'
+import { type PostStatusMap, parseClosingIssues, renderFindingsToDisk } from './render-findings.ts'
+import { type PrFileEntry, parseBrief, parseFinding } from './types.ts'
 
 export type RefreshResult = {
   refreshed: boolean
@@ -61,6 +61,7 @@ export async function refreshFindings(runDir: string): Promise<RefreshResult> {
 
   let pr: { number: number; branch: string; headSha: string } | undefined
   let files: PrFileEntry[] = []
+  let issues: ReturnType<typeof parseClosingIssues> = []
   try {
     const prJson = (await Bun.file(join(runDir, 'pr.json')).json()) as Record<string, unknown>
     const prNumber = Number(prJson.number ?? 0)
@@ -80,14 +81,34 @@ export async function refreshFindings(runDir: string): Promise<RefreshResult> {
         deletions: Number(entry.deletions ?? 0),
       }
     })
+    issues = parseClosingIssues(prJson)
   } catch {
     // optional file; archived runs may not include pr.json
   }
 
+  // Scout-produced summary. Same lenient-degrade contract as render-cmd.ts: a
+  // missing or malformed brief.json simply omits the header rather than
+  // failing the refresh (older archives predate the scout stage entirely).
+  let brief: ReturnType<typeof parseBrief> | undefined
+  try {
+    brief = parseBrief(await Bun.file(join(runDir, 'brief.json')).json())
+  } catch {
+    // optional file
+  }
+
   const diff = await readFile(join(runDir, 'diff.patch'), 'utf8').catch(() => '')
 
   await renderFindingsToDisk(
-    { findings, postStatus, runId: basename(runDir), pr, files, diff },
+    {
+      findings,
+      postStatus,
+      runId: basename(runDir),
+      pr,
+      files,
+      diff,
+      brief: brief ?? undefined,
+      issues,
+    },
     join(screenDir, 'findings.html'),
   )
 

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

@@ -1,8 +1,8 @@
 import { readdir, readFile } from 'node:fs/promises'
 import { basename, join } from 'node:path'
-import { type PostStatusMap, renderFindingsToDisk } from './render-findings.ts'
+import { type PostStatusMap, parseClosingIssues, renderFindingsToDisk } from './render-findings.ts'
 import { renderProgressToDisk } from './render-progress.ts'
-import { parseFinding } from './types.ts'
+import { parseBrief, parseFinding } from './types.ts'
 
 async function nextVersionedPath(screenDir: string, base: string): Promise<string> {
   const entries: string[] = await readdir(screenDir).catch(() => [] as string[])
@@ -119,9 +119,14 @@ export async function runRender(runDir: string, page: 'progress' | 'findings'):
     }
   })
   const diff = await readFile(join(runDir, 'diff.patch'), 'utf8').catch(() => '')
+  // `readJson` swallows both a missing file and malformed JSON, and `parseBrief`
+  // returns null for a brief that parsed but is unusable. Either way the header
+  // is simply omitted.
+  const brief = parseBrief(await readJson<unknown>(join(runDir, 'brief.json'), null)) ?? undefined
+  const issues = parseClosingIssues(prJson)
   const outPath = await nextVersionedPath(screenDir, 'findings')
   await renderFindingsToDisk(
-    { findings, postStatus, runId: basename(runDir), pr, files, diff },
+    { findings, postStatus, runId: basename(runDir), pr, files, diff, brief, issues },
     outPath,
   )
   return 0

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

@@ -7,7 +7,7 @@ import { renderActionBar } from './render-action-bar.ts'
 import { renderSplitDiff, renderUnifiedDiff } from './render-diff.ts'
 import { renderFileTree } from './render-file-tree.ts'
 import { renderIssuesList } from './render-issues-list.ts'
-import type { PostStatusMap, PrFileEntry, ReviewFinding } from './types.ts'
+import type { PostStatusMap, PrBrief, PrFileEntry, ReviewFinding } from './types.ts'
 
 export type { PostStatusEntry, PostStatusMap } from './types.ts'
 
@@ -17,6 +17,31 @@ export type FindingsPrMeta = {
   headSha: string
 }
 
+export type BriefIssue = {
+  number: number
+  title: string
+  url: string
+}
+
+/**
+ * Maps pr.json's `closingIssuesReferences` into the brief header's issue links.
+ * Shared by render-cmd's findings branch and refresh (which re-renders
+ * findings.html for `magpie open` / `magpie serve <archived-id>`), so both
+ * call sites stay in lockstep instead of drifting apart.
+ */
+export function parseClosingIssues(prJson: Record<string, unknown>): BriefIssue[] {
+  const issuesRaw = Array.isArray(prJson.closingIssuesReferences)
+    ? (prJson.closingIssuesReferences as unknown[])
+    : []
+  return issuesRaw.flatMap((entry) => {
+    if (!entry || typeof entry !== 'object') return []
+    const e = entry as Record<string, unknown>
+    const number = Number(e.number ?? 0)
+    if (!Number.isFinite(number) || number <= 0) return []
+    return [{ number, title: String(e.title ?? ''), url: String(e.url ?? '') }]
+  })
+}
+
 export type RenderFindingsInput = {
   findings: ReviewFinding[]
   postStatus: PostStatusMap
@@ -28,6 +53,10 @@ export type RenderFindingsInput = {
   files?: PrFileEntry[]
   /** Raw unified diff text for the PR. */
   diff?: string
+  /** Scout-produced PR summary. When absent, the report renders no brief header. */
+  brief?: PrBrief
+  /** Issues this PR closes, from pr.json's closingIssuesReferences. */
+  issues?: BriefIssue[]
   /** Shiki highlighter, prepared by the caller. */
   highlighter: Highlighter
 }
@@ -76,6 +105,40 @@ function prHeader(input: RenderFindingsInput): string {
   </header>`
 }
 
+function briefBlock(brief: PrBrief | undefined, issues: BriefIssue[]): string {
+  // Absent brief renders nothing: archived runs from before the scout stage
+  // existed must still open cleanly.
+  if (!brief) return ''
+  const changes =
+    brief.changes.length > 0
+      ? `<ul class="brief-changes">${brief.changes.map((c) => `<li>${esc(c)}</li>`).join('')}</ul>`
+      : ''
+  const subsystems =
+    brief.subsystems.length > 0
+      ? `<div class="brief-subsystems">${brief.subsystems
+          .map((s) => `<span class="brief-chip" title="${esc(s.role)}">${esc(s.name)}</span>`)
+          .join('')}</div>`
+      : ''
+  const issueLinks =
+    issues.length > 0
+      ? `<div class="brief-issues">${issues
+          .map(
+            (i) =>
+              `<a class="brief-issue" href="${esc(i.url)}" title="${esc(i.title)}">#${i.number}</a>`,
+          )
+          .join('')}</div>`
+      : ''
+  return `<details class="pr-brief" open>
+    <summary class="brief-summary">What this PR is for</summary>
+    <div class="brief-body">
+      <p class="brief-purpose">${esc(brief.purpose)}</p>
+      ${changes}
+      ${subsystems}
+      ${issueLinks}
+    </div>
+  </details>`
+}
+
 function filePane(opts: {
   file: PrFileEntry
   fileDiff: string
@@ -163,6 +226,7 @@ export function renderFindingsHtml(input: RenderFindingsInput): string {
   const diff = input.diff ?? ''
   const splitDiffs = splitDiffByFile(diff)
   const selectedIds = new Set<string>()
+  const briefHtml = briefBlock(input.brief, input.issues ?? [])
 
   if (input.findings.length === 0) {
     return `<!DOCTYPE html>
@@ -175,6 +239,7 @@ export function renderFindingsHtml(input: RenderFindingsInput): string {
 </head>
 <body data-run-id="${esc(runId)}" data-page="findings" data-view="files" data-diff-mode="unified" data-show-suggestions="false">
 ${prHeader(input)}
+${briefHtml}
 <main class="page-main">
   <div class="empty-state"><h1>No findings</h1><p>All specialists returned cleanly.</p></div>
 </main>
@@ -223,6 +288,7 @@ ${prHeader(input)}
 </head>
 <body data-run-id="${esc(runId)}" data-page="findings" data-view="files" data-diff-mode="unified" data-show-suggestions="false">
 ${prHeader(input)}
+${briefHtml}
 <main class="page-main">
   <div class="view files-view">
     ${tree}

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

@@ -15,9 +15,9 @@ const ORDER = [
 export type StatusResult = {
   /**
    * Highest stage the log says is behind us. A stage logged `skipped` counts:
-   * `context` has no work in the pipeline and is always logged that way, so
-   * treating it as unfinished would send a resume back to a stage that has no
-   * step to run.
+   * `context` logs `skipped` when the scout produced no brief, and the pipeline
+   * has nothing to go back for, so treating it as unfinished would send a resume
+   * to a stage with no remaining work.
    */
   lastCompleted: (typeof ORDER)[number] | null
   next: (typeof ORDER)[number] | 'cleanup'

package/skills/magpie/scripts/types.ts

@@ -332,3 +332,53 @@ export type PrFileEntry = {
 export function isSuggestion(f: ReviewFinding): boolean {
   return f.risk.action === 'consider' || f.risk.action === 'optional'
 }
+
+export type BriefSubsystem = {
+  name: string
+  role: string
+}
+
+/** Scout-produced PR summary. Written to `$RUN_DIR/brief.json` by the context stage. */
+export type PrBrief = {
+  purpose: string
+  changes: string[]
+  subsystems: BriefSubsystem[]
+  watchItems: string[]
+  unclear: string[]
+}
+
+function briefStrings(raw: unknown): string[] {
+  if (!Array.isArray(raw)) return []
+  return raw
+    .filter((v): v is string => typeof v === 'string')
+    .map((v) => v.trim())
+    .filter((v) => v.length > 0)
+}
+
+/**
+ * Lenient by design, unlike `parseFinding`. A subagent-authored brief that came
+ * back malformed must degrade the report header to absent, not throw away an
+ * otherwise-complete review at render time.
+ */
+export function parseBrief(raw: unknown): PrBrief | null {
+  if (!raw || typeof raw !== 'object' || Array.isArray(raw)) return null
+  const r = raw as Record<string, unknown>
+  const purpose = typeof r.purpose === 'string' ? r.purpose.trim() : ''
+  if (purpose.length === 0) return null
+  const subsystems: BriefSubsystem[] = Array.isArray(r.subsystems)
+    ? (r.subsystems as unknown[]).flatMap((entry) => {
+        if (!entry || typeof entry !== 'object' || Array.isArray(entry)) return []
+        const e = entry as Record<string, unknown>
+        const name = typeof e.name === 'string' ? e.name.trim() : ''
+        if (name.length === 0) return []
+        return [{ name, role: typeof e.role === 'string' ? e.role.trim() : '' }]
+      })
+    : []
+  return {
+    purpose,
+    changes: briefStrings(r.changes),
+    subsystems,
+    watchItems: briefStrings(r.watchItems),
+    unclear: briefStrings(r.unclear),
+  }
+}