tspl-cli 0.0.0-stage → 0.1.1

package/src/workflow/evidence.js

@@ -0,0 +1,276 @@
+'use strict'
+
+const Fs = require('fs')
+const Path = require('path')
+const { TEST_CATEGORIES, checkHash } = require('../shared')
+
+const { runProcess } = require('./process')
+
+const OUTPUT_TAIL = 4000
+const SECRET = /(bearer\s+)[\w.~+/=-]+|\b(gh[pousr]_[A-Za-z0-9]{20,}|sk-[A-Za-z0-9_-]{16,}|xox[abp]-[A-Za-z0-9-]{10,}|AKIA[0-9A-Z]{16})\b|((?:password|passwd|secret|token|api[_-]?key)\s*[=:]\s*)\S+/gi
+// eslint-disable-next-line no-control-regex
+const ANSI = /\u001b\[[0-9;?]*[ -/]*[@-~]/g
+
+const sanitize = (text, replacements = []) => {
+  let out = String(text || '').replace(ANSI, '').replace(/\r/g, '')
+  replacements.filter(([from]) => from).forEach(([from, to]) => { out = out.split(from).join(to) })
+  out = out.replace(SECRET, (match, bearer, token, assignment) => (bearer ? `${bearer}[redacted]` : assignment ? `${assignment}[redacted]` : '[redacted]'))
+  return out.length > OUTPUT_TAIL ? `…${out.slice(out.length - OUTPUT_TAIL)}` : out
+}
+
+const git = (dir, args) => {
+  const result = require('child_process').spawnSync('git', ['-C', dir, ...args], { encoding: 'utf8' })
+  return result.status === 0 ? result.stdout.trim() : null
+}
+
+/** The current commit, branch and cleanliness of each repo of a build. build = { branch, repos: [{ name, baseSha|base }] } */
+const captureHeads = (paths, build) =>
+  (build.repos || []).map(entry => {
+    const dir = paths.get(entry.name)
+    const headSha = dir ? git(dir, ['rev-parse', 'HEAD']) : null
+    const status = dir ? git(dir, ['status', '--porcelain', '--untracked-files=all']) : null
+    return {
+      name: entry.name,
+      baseSha: entry.baseSha || entry.base || null,
+      headSha,
+      branch: dir ? git(dir, ['rev-parse', '--abbrev-ref', 'HEAD']) : null,
+      clean: Boolean(dir) && status === '',
+    }
+  })
+
+const number = (text, pattern) => {
+  const all = [...String(text).matchAll(pattern)]
+  return all.length ? Number(all[all.length - 1][1]) : null
+}
+
+const CASE_TAG = /\bTC\s*-?\s*(\d+)\b/i
+const MEDIA = { '.png': 'image/png', '.jpg': 'image/jpeg', '.jpeg': 'image/jpeg', '.webp': 'image/webp', '.webm': 'video/webm', '.mp4': 'video/mp4' }
+const MAX_FILES = 30
+const MAX_FILE_BYTES = 10 * 1024 * 1024
+
+/** "TC2: blank email shows an error" belongs to done-when item 2. */
+const criterionOf = title => {
+  const match = CASE_TAG.exec(String(title || ''))
+  return match ? Number(match[1]) : null
+}
+
+/** Individual test results from node's TAP report, so each done-when item can show its own pass or fail. */
+const nodeCases = text =>
+  [...String(text).matchAll(/^\s*(not ok|ok) \d+ - (.+?)(?:\s+#\s*(SKIP|TODO)\b.*)?$/gm)]
+    .filter(match => !/\.[cm]?[jt]s$/.test(match[2].trim()))
+    .map(match => ({ title: match[2].trim(), status: match[3] ? 'skipped' : match[1] === 'ok' ? 'passed' : 'failed', criterion: criterionOf(match[2]) }))
+    .slice(0, 300)
+
+const readPlaywright = text => {
+  const source = String(text || '')
+  const start = source.indexOf('{')
+  const end = source.lastIndexOf('}')
+  if (start === -1 || end <= start) return null
+  try {
+    const data = JSON.parse(source.slice(start, end + 1))
+    return data && data.stats ? data : null
+  } catch (err) {
+    return null
+  }
+}
+
+/** Specs of a Playwright JSON report with their final status and attached screenshots or videos. */
+const playwrightCases = data => {
+  const cases = []
+  const attachments = []
+  const walk = (suite, parents) => {
+    const titles = suite.title ? [...parents, suite.title] : parents
+    ;(suite.specs || []).forEach(spec => {
+      const title = [...titles, spec.title].filter(Boolean).join(' › ')
+      const results = (spec.tests || []).flatMap(item => item.results || [])
+      const last = results[results.length - 1] || {}
+      const status = last.status === 'passed' ? 'passed' : last.status === 'skipped' || !results.length ? 'skipped' : 'failed'
+      const criterion = criterionOf(title)
+      cases.push({ title, status, criterion })
+      results.forEach(result => (result.attachments || []).filter(item => item.path).forEach(item => attachments.push({ path: item.path, name: item.name, contentType: item.contentType, criterion, step: title })))
+    })
+    ;(suite.suites || []).forEach(child => walk(child, titles))
+  }
+  ;(data.suites || []).forEach(suite => walk(suite, []))
+  return { cases: cases.slice(0, 300), attachments }
+}
+
+/** Images and videos a check left in its artifacts folder during this run. */
+const collectArtifacts = (dir, sinceMs) => {
+  const found = []
+  const visit = folder => {
+    let entries = []
+    try {
+      entries = Fs.readdirSync(folder, { withFileTypes: true })
+    } catch (err) {
+      return
+    }
+    entries.forEach(entry => {
+      const file = Path.join(folder, entry.name)
+      if (entry.isDirectory()) return visit(file)
+      const type = MEDIA[Path.extname(entry.name).toLowerCase()]
+      if (!type) return
+      const stat = Fs.statSync(file)
+      if (stat.mtimeMs + 1000 < sinceMs) return
+      const relative = Path.relative(dir, file)
+      found.push({ path: file, name: entry.name, contentType: type, criterion: criterionOf(relative), step: Path.dirname(relative) === '.' ? null : Path.dirname(relative) })
+    })
+  }
+  visit(dir)
+  return found
+}
+
+/** Keeps the uploadable files: known media types, not too big, a bounded number. */
+const usableAttachments = list =>
+  list
+    .filter(item => MEDIA[Path.extname(item.path).toLowerCase()] || /^(image|video)\//.test(item.contentType || ''))
+    .filter(item => {
+      try {
+        const size = Fs.statSync(item.path).size
+        return size > 0 && size <= MAX_FILE_BYTES
+      } catch (err) {
+        return false
+      }
+    })
+    .map(item => ({ ...item, contentType: MEDIA[Path.extname(item.path).toLowerCase()] || item.contentType }))
+    .slice(0, MAX_FILES)
+
+/** Counts executed tests from a runner's own report. Returns null when the report cannot be read. */
+const parseResults = (parser, stdout, stderr) => {
+  const text = `${stdout}\n${stderr}`
+  if (parser === 'playwright-json') {
+    const data = readPlaywright(stdout)
+    if (!data) return null
+    const stats = data.stats
+    const failed = (stats.unexpected || 0)
+    const { cases, attachments } = playwrightCases(data)
+    return { testCount: (stats.expected || 0) + failed + (stats.flaky || 0), failed, skipped: stats.skipped || 0, cases, attachments }
+  }
+  if (parser === 'node-tap') {
+    const total = number(text, /^# tests (\d+)/gm) ?? number(text, /^ℹ tests (\d+)/gm)
+    if (total === null) return null
+    const skipped = number(text, /^# skipped (\d+)/gm) ?? number(text, /^ℹ skipped (\d+)/gm) ?? 0
+    const todo = number(text, /^# todo (\d+)/gm) ?? number(text, /^ℹ todo (\d+)/gm) ?? 0
+    const cancelled = number(text, /^# cancelled (\d+)/gm) ?? number(text, /^ℹ cancelled (\d+)/gm) ?? 0
+    const failed = number(text, /^# fail (\d+)/gm) ?? number(text, /^ℹ fail (\d+)/gm) ?? 0
+    // Node reports a test file that registered no tests as one passing "test" named after the file.
+    const emptyFiles = [...text.matchAll(/^# Subtest: (\S+\.[cm]?[jt]s)\nok \d+ - \1$/gm)].length
+    return { testCount: Math.max(0, total - skipped - todo - cancelled - emptyFiles), failed: failed + cancelled, skipped, cases: nodeCases(text) }
+  }
+  if (parser === 'jest-json') {
+    const json = text.match(/\{[^{}]*"numTotalTests"\s*:\s*\d+[\s\S]*?\}(?=\s*$)/m) || text.match(/\{[\s\S]*"numTotalTests"[\s\S]*\}/)
+    if (json) {
+      try {
+        const data = JSON.parse(json[0])
+        return { testCount: (data.numPassedTests || 0) + (data.numFailedTests || 0), failed: data.numFailedTests || 0, skipped: (data.numPendingTests || 0) + (data.numTodoTests || 0) }
+      } catch (err) {
+        // fall through to the summary line
+      }
+    }
+    const line = text.match(/^Tests:\s+(.*)$/m)
+    if (!line) return null
+    const count = name => Number((line[1].match(new RegExp(`(\\d+) ${name}`)) || [0, 0])[1])
+    return { testCount: count('passed') + count('failed'), failed: count('failed'), skipped: count('skipped') + count('todo') }
+  }
+  return null
+}
+
+const insideRepo = (repoDir, cwd) => {
+  try {
+    const real = Fs.realpathSync(Path.resolve(repoDir, cwd))
+    const repoReal = Fs.realpathSync(repoDir)
+    return real === repoReal || real.startsWith(`${repoReal}${Path.sep}`) ? real : null
+  } catch (err) {
+    return null
+  }
+}
+
+const headChanged = (before, after) =>
+  !after || after.headSha !== before.headSha || after.branch !== before.branch || after.clean !== true
+
+/**
+ * Runs the approved checks against the captured heads and returns head-bound evidence.
+ * Nothing here trusts an AI report: a check passes only when it ran, exited 0 and (for tests) the runner counted tests.
+ * deps: { run, now, capture } for tests; defaults run real processes.
+ */
+const runChecks = async ({ snapshot, heads, paths, signal, build }, deps = {}) => {
+  const run = deps.run || runProcess
+  const now = deps.now || (() => new Date().toISOString())
+  const capture = deps.capture || captureHeads
+  const evidence = []
+  const redactions = [...paths.entries()].map(([name, dir]) => [dir, `<${name}>`])
+
+  for (const check of snapshot.checks.filter(item => item.required)) {
+    const head = heads.find(item => item.name === check.repo)
+    const dir = paths.get(check.repo)
+    const base = {
+      checkId: check.id,
+      repo: check.repo,
+      headSha: head ? head.headSha : null,
+      configHash: snapshot.configHash,
+      commandHash: checkHash(check),
+      status: 'missing',
+      exitCode: null,
+      testCount: null,
+      executed: false,
+      source: 'cli',
+      startedAt: now(),
+      finishedAt: null,
+      output: '',
+    }
+    const done = (patch, output) => evidence.push({ ...base, ...patch, finishedAt: now(), output: sanitize(output, redactions) })
+
+    if (signal && signal.aborted) { done({ status: 'cancelled' }, 'Cancelled before it started.'); continue }
+    if (!head || !dir) { done({ status: 'missing' }, `Repo ${check.repo} is not available on this machine.`); continue }
+    const current = capture(paths, { branch: build && build.branch, repos: [head] })[0]
+    if (headChanged(head, current)) {
+      done({ status: 'stale' }, current && current.clean === false ? 'The repo has uncommitted changes, so this commit is not what would be tested.' : 'The branch or commit moved since the heads were captured.')
+      continue
+    }
+    if (build && build.branch && current.branch !== build.branch) { done({ status: 'stale' }, `Expected branch ${build.branch} but the repo is on ${current.branch}.`); continue }
+    const cwd = insideRepo(dir, check.cwd)
+    if (!cwd) { done({ status: 'missing' }, `Working directory ${check.cwd} does not exist inside ${check.repo}.`); continue }
+    const isTest = TEST_CATEGORIES.includes(check.category)
+    if (isTest && check.parser === 'custom' && check.attested !== true) { done({ status: 'missing' }, 'A custom test command must be attested in the project file before it counts.'); continue }
+
+    base.startedAt = now()
+    const result = await run('sh', ['-c', check.command], { cwd, timeoutMs: check.timeoutMs, signal, env: { CI: '1', NODE_TEST_CONTEXT: undefined } })
+    const after = capture(paths, { branch: build && build.branch, repos: [head] })[0]
+    const output = `${result.stdout}\n${result.stderr}${result.error ? `\n${result.error}` : ''}`.trim()
+    const patch = { executed: !result.error, exitCode: result.exitCode }
+    const startedMs = Date.parse(base.startedAt) || Date.now()
+    const files = check.artifacts ? collectArtifacts(Path.join(cwd, check.artifacts), startedMs) : []
+    if (files.length) patch.attachments = usableAttachments(files)
+    const counted = isTest && check.parser !== 'custom' ? parseResults(check.parser, result.stdout, result.stderr) : null
+    if (counted) {
+      patch.cases = counted.cases || []
+      patch.attachments = usableAttachments([...(counted.attachments || []), ...files.filter(file => !(counted.attachments || []).some(item => item.path === file.path))])
+    }
+
+    if (headChanged(head, after)) { done({ ...patch, status: 'stale' }, `The commit or worktree changed while the check ran.\n${output}`); continue }
+    if (result.cancelled) { done({ ...patch, status: 'cancelled' }, output); continue }
+    if (result.timedOut) { done({ ...patch, status: 'timed-out' }, output); continue }
+    if (result.error || result.exitCode !== 0) { done({ ...patch, status: 'failed' }, output); continue }
+
+    if (isTest && check.parser !== 'custom') {
+      if (!counted) { done({ ...patch, status: 'failed' }, `tspl could not read the ${check.parser} test results, so the check cannot count as passed.\n${output}`); continue }
+      if (counted.failed > 0) { done({ ...patch, status: 'failed', testCount: counted.testCount }, output); continue }
+      if (counted.testCount === 0) { done({ ...patch, status: 'failed', testCount: 0 }, `The check ran zero tests${counted.skipped ? ` (${counted.skipped} skipped)` : ''}; that is not evidence.\n${output}`); continue }
+      done({ ...patch, status: 'passed', testCount: counted.testCount }, output)
+      continue
+    }
+    done({ ...patch, status: 'passed' }, output)
+  }
+  return evidence
+}
+
+module.exports = {
+  criterionOf,
+  collectArtifacts,
+  usableAttachments,
+  OUTPUT_TAIL,
+  sanitize,
+  captureHeads,
+  parseResults,
+  runChecks,
+}

package/src/workflow/pr-body.js

@@ -0,0 +1,52 @@
+'use strict'
+
+const START = '<!-- tspl:start -->'
+const END = '<!-- tspl:end -->'
+
+const row = (...cells) => `| ${cells.join(' | ')} |`
+
+/** The tspl-managed section of a pull request description: what was asked, what ran on which commit, what review said. */
+const renderPrBody = ({ task, summary, repo, head, evidence = [], criteria = [], review = null, limitations = [], ci = null }) => {
+  const lines = [
+    START,
+    `## ${task.card && task.card.ticket ? `${task.card.ticket} · ` : ''}${(task.card && task.card.what) || task.id}`,
+    '',
+    `tspl task \`${task.id || task.key}\` · repo \`${repo}\` · tested commit \`${head.headSha}\` (base \`${head.baseSha}\`)`,
+    '',
+    summary ? `${summary}\n` : '',
+    '### Acceptance',
+    ...(criteria.length ? criteria.map(item => `- ${item.text}: ${item.how}`) : ['- (no done-when items)']),
+    '',
+    '### Checks run on this commit (by the tspl CLI on the developer machine)',
+    row('Check', 'Result', 'Tests'),
+    row('---', '---', '---'),
+    ...evidence.map(item => row(item.checkId, item.status, item.testCount === null || item.testCount === undefined ? '-' : item.testCount)),
+    '',
+    '### Separate review',
+    review
+      ? `${review.verdict === 'passed' ? 'Passed' : 'Changes requested'} by ${review.engine || 'an AI reviewer'} in a fresh session on \`${review.heads.map(head => head.headSha).join(', ')}\`.${review.findings.length ? `\n${review.findings.map(item => `- [${item.severity}] ${item.file ? `${item.file}${item.line ? `:${item.line}` : ''}: ` : ''}${item.message}`).join('\n')}` : ' No findings.'}`
+      : 'No review recorded.',
+    '',
+    '### Required CI',
+    ci || 'Reported by the provider after the PR is opened; this section does not claim it.',
+    ...(limitations.length ? ['', '### Limitations', ...limitations.map(item => `- ${item}`)] : []),
+    END,
+  ]
+  return lines.join('\n')
+}
+
+/** Replaces only the tspl section; text a person wrote above or below it stays. */
+const mergeBody = (existing, managed) => {
+  const body = String(existing || '')
+  const start = body.indexOf(START)
+  const end = body.indexOf(END)
+  if (start !== -1 && end > start) return `${body.slice(0, start)}${managed}${body.slice(end + END.length)}`
+  return `${body.trimEnd()}${body.trim() ? '\n\n' : ''}${managed}\n`
+}
+
+module.exports = {
+  START,
+  END,
+  renderPrBody,
+  mergeBody,
+}

package/src/workflow/process.js

@@ -0,0 +1,82 @@
+'use strict'
+
+const { spawn } = require('child_process')
+
+const DEFAULT_MAX_OUTPUT = 64 * 1024
+const KILL_GRACE_MS = 2000
+
+const keepTail = (current, chunk, max) => {
+  const next = current + chunk
+  return next.length > max ? next.slice(next.length - max) : next
+}
+
+const killGroup = (child, signal) => {
+  try {
+    process.kill(-child.pid, signal)
+  } catch (err) {
+    try {
+      child.kill(signal)
+    } catch (ignored) {
+      // already gone
+    }
+  }
+}
+
+/**
+ * Runs a command with a timeout and cancellation. The child gets its own process group so a timeout or an abort
+ * ends everything it started. Only the last maxOutputBytes of each stream are kept.
+ * Resolves (never rejects) with { exitCode, signal, stdout, stderr, timedOut, cancelled, error }.
+ */
+const runProcess = (command, args = [], { cwd, timeoutMs, signal, input, maxOutputBytes = DEFAULT_MAX_OUTPUT, env } = {}) =>
+  new Promise(resolve => {
+    if (signal && signal.aborted) {
+      resolve({ exitCode: null, signal: null, stdout: '', stderr: '', timedOut: false, cancelled: true, error: null })
+      return
+    }
+    let stdout = ''
+    let stderr = ''
+    let timedOut = false
+    let cancelled = false
+    let settled = false
+    let forceTimer = null
+    const childEnv = { ...process.env, ...(env || {}) }
+    Object.keys(childEnv).forEach(key => childEnv[key] === undefined && delete childEnv[key])
+    const child = spawn(command, args, {
+      cwd,
+      env: childEnv,
+      detached: true,
+      stdio: [input === undefined ? 'ignore' : 'pipe', 'pipe', 'pipe'],
+    })
+
+    const stop = () => {
+      killGroup(child, 'SIGTERM')
+      forceTimer = setTimeout(() => killGroup(child, 'SIGKILL'), KILL_GRACE_MS)
+    }
+    const timer = timeoutMs ? setTimeout(() => { timedOut = true; stop() }, timeoutMs) : null
+    const onAbort = () => { cancelled = true; stop() }
+    if (signal) signal.addEventListener('abort', onAbort, { once: true })
+
+    const finish = result => {
+      if (settled) return
+      settled = true
+      clearTimeout(timer)
+      clearTimeout(forceTimer)
+      if (signal) signal.removeEventListener('abort', onAbort)
+      killGroup(child, 'SIGKILL')
+      resolve({ stdout, stderr, timedOut, cancelled, error: null, ...result })
+    }
+
+    child.stdout.on('data', chunk => { stdout = keepTail(stdout, chunk.toString('utf8'), maxOutputBytes) })
+    child.stderr.on('data', chunk => { stderr = keepTail(stderr, chunk.toString('utf8'), maxOutputBytes) })
+    child.on('error', err => finish({ exitCode: null, signal: null, error: err.message }))
+    child.on('close', (code, sig) => finish({ exitCode: code, signal: sig }))
+    if (input !== undefined) {
+      child.stdin.on('error', () => {})
+      child.stdin.end(input)
+    }
+  })
+
+module.exports = {
+  DEFAULT_MAX_OUTPUT,
+  runProcess,
+}

package/src/workflow/review.js

@@ -0,0 +1,128 @@
+'use strict'
+
+const { spawnSync } = require('child_process')
+
+const { AgentError, checkCapability, invoke, extractJson, newSessionId, testCaseLines } = require('./agents')
+const { captureHeads } = require('./evidence')
+
+const MAX_DIFF = 60 * 1024
+const SEVERITIES = ['low', 'medium', 'high', 'critical']
+
+const REVIEW_SCHEMA = {
+  type: 'object',
+  properties: {
+    verdict: { type: 'string', enum: ['passed', 'changes-requested'] },
+    heads: { type: 'array', items: { type: 'object', properties: { name: { type: 'string' }, headSha: { type: 'string' } }, required: ['name', 'headSha'] } },
+    findings: {
+      type: 'array',
+      items: {
+        type: 'object',
+        properties: { severity: { type: 'string', enum: SEVERITIES }, repo: { type: 'string' }, file: { type: 'string' }, line: { type: 'number' }, message: { type: 'string' } },
+        required: ['severity', 'message'],
+      },
+    },
+  },
+  required: ['verdict', 'heads', 'findings'],
+}
+
+const diffFor = (dir, head) => {
+  const result = spawnSync('git', ['-C', dir, 'diff', `${head.baseSha}...${head.headSha}`], { encoding: 'utf8', maxBuffer: 16 * 1024 * 1024 })
+  const diff = result.status === 0 ? result.stdout : '(the diff could not be read)'
+  return diff.length > MAX_DIFF ? `${diff.slice(0, MAX_DIFF)}\n… (diff cut at ${MAX_DIFF} bytes; read the files for the rest)` : diff
+}
+
+const reviewPrompt = ({ task, instructions, heads, paths, evidence }) =>
+  [
+    'You are an independent reviewer. You did not write this change. Judge it only from the task, the approved scope, the diff, the project rules and the test results below. Do NOT edit any file.',
+    '',
+    `TASK ${task.id || task.key}: ${(task.card && task.card.what) || task.summary || ''}`,
+    'TEST CASES (check that each one is really proven by a test named TC<n>, or left for a person)',
+    ...testCaseLines(task.card),
+    '',
+    'APPROVED SCOPE',
+    ...['edit', 'create', 'remove'].flatMap(kind => ((task.plan && task.plan[kind]) || []).map(item => `  ${kind}: ${item.file}`)),
+    instructions ? `\nPROJECT RULES\n${instructions}` : '',
+    '',
+    'TEST EVIDENCE',
+    ...(evidence || []).flatMap(item => [
+      `  ${item.checkId}: ${item.status}${item.testCount ? `, ${item.testCount} tests` : ''}`,
+      ...(item.cases || []).filter(entry => entry.criterion).map(entry => `    ${entry.title}: ${entry.status}`),
+    ]),
+    '',
+    ...heads.flatMap(head => [`COMMITS ${head.name}: ${head.baseSha}..${head.headSha}`, '```diff', diffFor(paths.get(head.name), head), '```', '']),
+    'Reply with JSON only: {"verdict": "passed" | "changes-requested", "heads": [{"name": "<repo>", "headSha": "<the exact head sha above>"}], "findings": [{"severity": "low|medium|high|critical", "repo": "", "file": "", "line": 0, "message": ""}]}.',
+    'Use "passed" only when nothing blocks merging. Bugs, missing tests, scope creep and rule violations are findings.',
+  ].join('\n')
+
+const validateReview = (value, heads) => {
+  if (!value || typeof value !== 'object') throw new AgentError('invalid-output', 'The review was not a JSON object')
+  if (!['passed', 'changes-requested'].includes(value.verdict)) throw new AgentError('invalid-output', 'The review has no valid verdict')
+  if (!Array.isArray(value.heads) || !Array.isArray(value.findings)) throw new AgentError('invalid-output', 'The review needs "heads" and "findings" lists')
+  value.findings.forEach(finding => {
+    if (!finding || typeof finding.message !== 'string' || !finding.message.trim()) throw new AgentError('invalid-output', 'A finding has no message')
+    if (finding.severity && !SEVERITIES.includes(finding.severity)) throw new AgentError('invalid-output', `Unknown finding severity ${finding.severity}`)
+  })
+  heads.forEach(head => {
+    const seen = value.heads.find(item => item && item.name === head.name)
+    if (!seen || seen.headSha !== head.headSha) {
+      throw new AgentError('stale', `The review is for ${seen ? seen.headSha : 'no commit'} of ${head.name}, not the tested commit ${head.headSha}`)
+    }
+  })
+  if (value.verdict === 'passed' && value.findings.some(finding => ['high', 'critical'].includes(finding.severity))) {
+    throw new AgentError('invalid-output', 'The review passed the change but lists a high-severity finding')
+  }
+  return value
+}
+
+const sameState = (before, after) =>
+  before.length === after.length &&
+  before.every((head, i) => head.headSha === after[i].headSha && head.branch === after[i].branch && head.clean === after[i].clean)
+
+/**
+ * Reviews the tested commits in a brand-new session. Anything but a schema-valid verdict on exactly these commits is a
+ * blocker (thrown as AgentError), never an approval. Edits made during the review invalidate it; they are reported, not undone.
+ */
+const reviewTask = async (context, deps = {}) => {
+  checkCapability(context.engine, 'review')
+  const build = { repos: context.heads }
+  const current = (deps.capture || captureHeads)(context.paths, build)
+  context.heads.forEach(head => {
+    const now = current.find(item => item.name === head.name)
+    if (!now || now.headSha !== head.headSha) throw new AgentError('stale', `${head.name} is no longer at the tested commit ${head.headSha}; test again before reviewing`)
+    if (!now.clean) throw new AgentError('stale', `${head.name} has uncommitted changes; the review needs a clean, committed branch`)
+  })
+
+  const sessionId = newSessionId()
+  if (context.buildSessionId && context.buildSessionId === sessionId) throw new AgentError('invalid-output', 'The review must not reuse the coding session')
+  const dirs = [...context.paths.values()]
+  const result = await invoke(context.engine, 'review', {
+    prompt: reviewPrompt(context), model: context.model, dirs, sessionId, schema: REVIEW_SCHEMA, timeoutMs: context.timeoutMs, signal: context.signal,
+  }, deps)
+
+  if (context.buildSessionId && result.sessionId === context.buildSessionId) {
+    throw new AgentError('invalid-output', 'The review ran in the coding session; it must be a separate session')
+  }
+  const after = (deps.capture || captureHeads)(context.paths, build)
+  if (!sameState(current, after)) {
+    throw new AgentError('modified-worktree', 'The reviewer changed the repository. The review does not count; nothing was discarded, so look at git status.')
+  }
+  const reply = extractJson(result.text)
+  if (!reply) throw new AgentError('invalid-output', 'The review reply had no JSON')
+  validateReview(reply, context.heads)
+
+  return {
+    heads: context.heads.map(head => ({ name: head.name, headSha: head.headSha })),
+    verdict: reply.verdict,
+    findings: reply.findings.map(finding => ({ severity: finding.severity || 'medium', repo: finding.repo || null, file: finding.file || null, line: Number.isInteger(finding.line) ? finding.line : null, message: finding.message })),
+    engine: context.engine,
+    model: context.model || null,
+    sessionId: result.sessionId || sessionId,
+    reviewedAt: new Date().toISOString(),
+  }
+}
+
+module.exports = {
+  REVIEW_SCHEMA,
+  validateReview,
+  reviewTask,
+}