@1aboveio/skills 0.0.0-stage → 1.0.0

package/skills/engineering/resolve-issues/scripts/github-reviews.mjs

@@ -0,0 +1,384 @@
+#!/usr/bin/env node
+// Bring reviews posted on the PR on GitHub into a resolve-issues review round.
+//
+//   github-reviews.mjs merge --pr <owner/name#N> --head <sha> --review <run>/reviews/<unit>-r<N>.json
+//                            [--prior <reviews/<unit>-r<N-1>.json>]
+//   github-reviews.mjs structured --pr <owner/name#N> --head <sha> --out <run>/reviews/<unit>-r<N>.json
+//                            --unit <id> --round <N> --fix-round <F>
+//
+// Only reviews and comments from an account with write access to the repository, other
+// than the PR author, count; the rest are listed under `external.ignored`.
+//
+// merge: add the PR's blocking GitHub feedback to the round's result file, in place, before
+//   review-verdict.mjs reads it. Rerunning it on the same file replaces what it added.
+//   - A reviewer whose latest review requests changes is a P1 finding `gh-review-<id>`.
+//     Once a fix brief has carried it, it is `awaiting` that reviewer's re-review instead.
+//   - An inline thread, review body, or PR comment whose first line is tagged P0 or P1
+//     (`P1:`, `**P1**`, `[P1]`, a `![P1 Badge]` image, also inside `<sub>`) is a finding `gh-comment-<id>`, until
+//     its thread is resolved or a fix brief has carried it once. P2/P3 tags stay on GitHub.
+//   - A GitHub finding is handled once the prior round's fix brief (`<prior>.fix.json`,
+//     written only on a `fix` verdict) carried it; `external.handled` carries the set from
+//     round to round. An incomplete or handed-back round hands nothing on.
+//   - Every `gh-review-<n>`/`gh-comment-<n>` finding is this script's: it removes each one
+//     the file holds, the reviewer's carried-forward copies included, and adds the current
+//     set, each with a trigger, rule, and open path like any blocking finding.
+//   Every review, thread and comment is read, page by page. A permission lookup that fails
+//   for any reason but "not a user" stops the merge (exit 2) rather than drop feedback.
+//   Exit 0 merged · 2 bad command or unreadable file or GitHub failure.
+//
+// structured: write a GitHub-posted better-review result for --head as this round's result
+//   file, so no reviewer is spawned. The result is a comment or review body holding
+//   STRUCTURED_MARKER and one ```json block; its `head` must be --head, and it must be
+//   complete by the reviewer's own rules (complete, every pass, checks run). The file takes
+//   --unit, --round and --fix-round from the caller and records its `source`.
+//   Exit 0 whenever it ran (`found: false` when none is found) · 2 bad command or GitHub failure.
+
+import { execFileSync } from 'node:child_process'
+import { readFileSync, writeFileSync } from 'node:fs'
+import { basename, dirname, join } from 'node:path'
+
+import { isMainModule } from '../../engineering-runtime/scripts/main-module.mjs'
+import { reviewCompletionProblems } from '../../engineering-runtime/scripts/review-completion.mjs'
+
+export const STRUCTURED_MARKER = '<!-- better-review-result -->'
+// GitHub's base access level; `role_name` may be a custom role's name.
+export const WRITE_PERMISSIONS = Object.freeze(['admin', 'write'])
+export const GITHUB_ID = /^gh-(?:review|comment)-\d+$/
+const BLOCKING_TAG = /^(?:[\s*_[(!]|<[^>\n]+>)*(P[0-3])\b/
+
+export class GithubReviewsError extends Error {}
+
+const isText = (value) => typeof value === 'string' && value.trim() !== ''
+const firstLine = (body) => String(body ?? '').trim().split('\n', 1)[0]
+
+// The P0-P3 tag a comment's first line opens with, or null.
+export function severityTag(body) {
+  const m = firstLine(body).match(BLOCKING_TAG)
+  return m ? m[1] : null
+}
+
+export function parsePr(text) {
+  const m = String(text ?? '').match(/^([\w.-]+)\/([\w.-]+)#(\d+)$/)
+  if (!m) throw new GithubReviewsError(`--pr must be <owner/name#N>, got ${JSON.stringify(text)}`)
+  return { owner: m[1], name: m[2], number: Number(m[3]) }
+}
+
+// Split the PR's authors into trusted (write access, not the PR author) and ignored.
+function trustOf(login, { prAuthor, permissionOf }) {
+  if (!isText(login)) return 'no author'
+  if (login === prAuthor) return 'PR author'
+  const permission = permissionOf(login)
+  return WRITE_PERMISSIONS.includes(permission) ? null : `permission ${permission ?? 'none'}`
+}
+
+// The result a body posts: the marker and a JSON block shaped like a result (a HEAD and a
+// findings array); null otherwise, so any other comment is read as feedback.
+function structuredJson(body) {
+  const text = String(body ?? '')
+  if (!text.includes(STRUCTURED_MARKER)) return null
+  const block = text.match(/```json\s*\n([\s\S]*?)\n```/)
+  if (!block) return null
+  let result
+  try { result = JSON.parse(block[1]) } catch { return null }
+  return isText(result?.head) && Array.isArray(result?.findings) ? result : null
+}
+
+// The blocking-finding shape review-verdict.mjs requires of every P0/P1.
+function shaped(finding, what, where) {
+  return {
+    ...finding,
+    trigger: `${finding.author}'s ${what} on GitHub: ${finding.url}`,
+    rule: 'blocking review feedback on the PR is resolved before merge',
+    paths: [{ path: where || finding.url || 'the PR', status: 'open' }],
+  }
+}
+
+function summaryOf(body, fallback) {
+  const line = firstLine(body).replace(/!\[[^\]]*\]\([^)]*\)/g, '').replace(/<[^>]+>/g, '').replace(/[*_[\]]/g, '')
+    .replace(/^\s*P[0-3]\b[:\s-]*/, '').trim()
+  return line || fallback
+}
+
+/**
+ * The PR's blocking GitHub feedback for --head. `pr` is the GraphQL pullRequest node;
+ * `handled` holds the ids a fix brief has already carried.
+ */
+export function collectExternal(pr, head, { permissionOf, handled = new Set() }) {
+  const prAuthor = pr?.author?.login ?? null
+  const trustCache = new Map()
+  const trusted = (login) => {
+    if (!trustCache.has(login)) trustCache.set(login, trustOf(login, { prAuthor, permissionOf }))
+    return trustCache.get(login)
+  }
+  const findings = []
+  const awaiting = []
+  const ignored = []
+  const ignore = (login, url, reason) => ignored.push({ author: login ?? null, url: url ?? null, reason })
+
+  // A reviewer's latest decisive review is their standing state, as GitHub counts it.
+  const latest = new Map()
+  for (const review of pr?.reviews?.nodes ?? []) {
+    const login = review?.author?.login
+    if (!['APPROVED', 'CHANGES_REQUESTED', 'DISMISSED'].includes(review?.state)) continue
+    const before = latest.get(login)
+    if (!before || String(review.submittedAt) >= String(before.submittedAt)) latest.set(login, review)
+  }
+  for (const [login, review] of latest) {
+    if (review.state !== 'CHANGES_REQUESTED') continue
+    const reason = trusted(login)
+    if (reason) { ignore(login, review.url, reason); continue }
+    const id = `gh-review-${review.databaseId}`
+    if (handled.has(id)) {
+      awaiting.push({ id, author: login, url: review.url, commit: review.commit?.oid ?? null })
+      continue
+    }
+    findings.push(shaped({
+      id, severity: 'P1', pass: 'external', source: 'github', author: login, url: review.url,
+      commit: review.commit?.oid ?? null,
+      summary: summaryOf(review.body, `${login} requested changes`),
+      ...(isText(review.body) ? { detail: review.body.trim() } : {}),
+    }, 'changes request'))
+  }
+
+  const tagged = (node, extra = {}) => {
+    const body = node?.body
+    if (structuredJson(body)) return
+    const severity = severityTag(body)
+    if (severity !== 'P0' && severity !== 'P1') return
+    const login = node?.author?.login
+    const reason = trusted(login)
+    if (reason) { ignore(login, node.url, reason); return }
+    const id = `gh-comment-${node.databaseId}`
+    if (handled.has(id)) return
+    const where = isText(extra.file) ? `${extra.file}${extra.line ? `:${extra.line}` : ''}` : null
+    findings.push(shaped({
+      id, severity, pass: 'external', source: 'github', author: login, url: node.url,
+      summary: summaryOf(body, `${login} flagged ${severity}`), detail: String(body).trim(), ...extra,
+    }, `${severity} comment`, where))
+  }
+  for (const thread of pr?.reviewThreads?.nodes ?? []) {
+    if (thread?.isResolved) continue
+    const comment = thread?.comments?.nodes?.[0]
+    if (!comment) continue
+    tagged(comment, {
+      ...(isText(comment.path) ? { file: comment.path } : {}),
+      ...(Number.isSafeInteger(comment.line ?? comment.originalLine) ? { line: comment.line ?? comment.originalLine } : {}),
+      commit: comment.originalCommit?.oid ?? comment.commit?.oid ?? null,
+    })
+  }
+  // A changes-requested review is already its reviewer's finding.
+  for (const review of pr?.reviews?.nodes ?? []) {
+    if (review?.state !== 'CHANGES_REQUESTED') tagged(review, { commit: review?.commit?.oid ?? null })
+  }
+  for (const comment of pr?.comments?.nodes ?? []) tagged(comment)
+
+  return { prAuthor, head, findings, awaiting, ignored }
+}
+
+// Ids a fix brief has carried: the prior round's ledger plus the GitHub findings in the
+// prior round's fix brief, which exists only when its verdict sent them to a fix worker.
+export function handledIds(prior, priorFixBrief = null) {
+  const ids = new Set(Array.isArray(prior?.external?.handled) ? prior.external.handled.filter((id) => GITHUB_ID.test(id)) : [])
+  for (const f of Array.isArray(priorFixBrief?.fix) ? priorFixBrief.fix : []) {
+    if (isText(f?.id) && GITHUB_ID.test(f.id)) ids.add(f.id)
+  }
+  return ids
+}
+
+/** The review file with this round's GitHub feedback in place of any added before. */
+export function mergeExternal(review, external, handled) {
+  // GitHub is the authority on its own findings, so drop any copy the reviewer carried.
+  const own = (Array.isArray(review?.findings) ? review.findings : []).filter((f) => !GITHUB_ID.test(String(f?.id)))
+  return {
+    ...review,
+    findings: [...own, ...external.findings],
+    external: {
+      added: external.findings.map((f) => f.id),
+      head: external.head,
+      prAuthor: external.prAuthor,
+      awaiting: external.awaiting,
+      handled: [...handled].sort(),
+      ignored: external.ignored,
+    },
+  }
+}
+
+/**
+ * The newest trusted GitHub-posted better-review result for --head, or null. Bodies
+ * without the marker, with no JSON block, or of another HEAD are passed over.
+ */
+export function findStructured(pr, head, { permissionOf }) {
+  const prAuthor = pr?.author?.login ?? null
+  const bodies = [
+    ...(pr?.reviews?.nodes ?? []).map((n) => ({ ...n, at: n?.submittedAt })),
+    ...(pr?.comments?.nodes ?? []).map((n) => ({ ...n, at: n?.createdAt })),
+  ].filter((n) => String(n?.body ?? '').includes(STRUCTURED_MARKER))
+    .sort((a, b) => String(b.at).localeCompare(String(a.at)))
+  for (const node of bodies) {
+    const result = structuredJson(node.body)
+    if (result?.head !== head) continue
+    // Unlike a legacy local record, a posted result must say it is complete.
+    if (result.complete !== true || reviewCompletionProblems(result, { requirePasses: true }).length) continue
+    if (trustOf(node?.author?.login, { prAuthor, permissionOf })) continue
+    return { result, source: { kind: 'github', author: node.author.login, url: node.url ?? null } }
+  }
+  return null
+}
+
+const CONNECTIONS = {
+  reviews: 'databaseId author { login } state body submittedAt url commit { oid }',
+  reviewThreads: `isResolved isOutdated comments(first: 1) {
+    nodes { databaseId author { login } body path line originalLine url commit { oid } originalCommit { oid } } }`,
+  comments: 'databaseId author { login } body createdAt url',
+}
+const pageQuery = (field) => `query($owner: String!, $name: String!, $number: Int!, $after: String) {
+  repository(owner: $owner, name: $name) {
+    pullRequest(number: $number) {
+      author { login }
+      ${field}(first: 100, after: $after) { pageInfo { hasNextPage endCursor } nodes { ${CONNECTIONS[field]} } }
+    }
+  }
+}`
+
+function gh(args) {
+  try {
+    return execFileSync('gh', args, { encoding: 'utf8', stdio: ['ignore', 'pipe', 'pipe'] })
+  } catch (error) {
+    throw new GithubReviewsError(`gh ${args[0]} ${args[1] ?? ''} failed: ${String(error.stderr || error.message).trim()}`)
+  }
+}
+
+// Every node of each connection, page by page; `query` runs one GraphQL page.
+export function fetchPr({ owner, name, number }, query = ghGraphql) {
+  const pr = {}
+  for (const field of Object.keys(CONNECTIONS)) {
+    const nodes = []
+    let after = null
+    do {
+      const page = query(pageQuery(field), { owner, name, number, after })?.data?.repository?.pullRequest
+      if (!page) throw new GithubReviewsError(`no pull request ${owner}/${name}#${number}`)
+      pr.author = page.author
+      const connection = page[field]
+      if (!Array.isArray(connection?.nodes)) throw new GithubReviewsError(`no ${field} in the GitHub response`)
+      nodes.push(...connection.nodes)
+      after = connection.pageInfo?.hasNextPage ? connection.pageInfo.endCursor : null
+      if (connection.pageInfo?.hasNextPage && !isText(after)) throw new GithubReviewsError(`${field}: a next page without a cursor`)
+    } while (after)
+    pr[field] = { nodes }
+  }
+  return pr
+}
+
+function ghGraphql(query, { owner, name, number, after }) {
+  const args = ['api', 'graphql', '-f', `query=${query}`, '-F', `owner=${owner}`, '-F', `name=${name}`, '-F', `number=${number}`]
+  if (after) args.push('-f', `after=${after}`)
+  return JSON.parse(gh(args))
+}
+
+// A bot answers 200 with permission "none"; a login that is no user answers 404. Any other
+// failure is unknown access, so it stops the merge.
+export function permissionFetcher({ owner, name }, api = (path) => gh(['api', path])) {
+  return (login) => {
+    let text
+    try {
+      text = api(`repos/${owner}/${name}/collaborators/${encodeURIComponent(login)}/permission`)
+    } catch (error) {
+      if (/\(HTTP 404\)/.test(error.message)) return 'none'
+      throw new GithubReviewsError(`cannot tell ${login}'s access: ${error.message}`)
+    }
+    const out = JSON.parse(text)
+    return out?.permission || 'none'
+  }
+}
+
+const USAGE = `usage:
+  github-reviews.mjs merge --pr <owner/name#N> --head <sha> --review <reviews/<unit>-r<N>.json> [--prior <file>]
+  github-reviews.mjs structured --pr <owner/name#N> --head <sha> --out <file> --unit <id> --round <N> --fix-round <F>`
+
+function parseArgs(argv) {
+  const [mode, ...rest] = argv
+  const opts = { mode }
+  for (let i = 0; i < rest.length; i += 2) {
+    if (!rest[i]?.startsWith('--') || rest[i + 1] === undefined) throw new GithubReviewsError(USAGE)
+    opts[rest[i].slice(2)] = rest[i + 1]
+  }
+  const need = { merge: ['pr', 'head', 'review'], structured: ['pr', 'head', 'out', 'unit', 'round', 'fix-round'] }[mode]
+  if (!need || need.some((k) => !isText(opts[k]))) throw new GithubReviewsError(USAGE)
+  return opts
+}
+
+function readJson(path) {
+  try {
+    return JSON.parse(readFileSync(path, 'utf8'))
+  } catch (error) {
+    throw new GithubReviewsError(`cannot read ${path}: ${error.message}`)
+  }
+}
+
+function priorPath(opts) {
+  if (opts.prior) return opts.prior
+  const m = basename(opts.review).match(/^(.*-r)(\d+)\.json$/)
+  return m && Number(m[2]) >= 2 ? join(dirname(opts.review), `${m[1]}${Number(m[2]) - 1}.json`) : null
+}
+
+function counter(text, flag) {
+  const n = Number(text)
+  if (!Number.isSafeInteger(n) || n < 1) throw new GithubReviewsError(`--${flag} must be a positive integer`)
+  return n
+}
+
+export function run(argv, { fetch = fetchPr, permissions = permissionFetcher } = {}) {
+  const opts = parseArgs(argv)
+  const target = parsePr(opts.pr)
+  const pr = fetch(target)
+  const permissionOf = permissions(target)
+  if (opts.mode === 'structured') {
+    const found = findStructured(pr, opts.head, { permissionOf })
+    if (!found) return { out: { found: false, head: opts.head } }
+    const result = {
+      ...found.result,
+      unit: opts.unit,
+      round: counter(opts.round, 'round'),
+      fixRound: counter(opts['fix-round'], 'fix-round'),
+      source: found.source,
+    }
+    writeFileSync(opts.out, `${JSON.stringify(result, null, 2)}\n`)
+    return { out: { found: true, path: opts.out, source: found.source } }
+  }
+  const review = readJson(opts.review)
+  const path = priorPath(opts)
+  let prior = null
+  if (path) {
+    try { prior = JSON.parse(readFileSync(path, 'utf8')) } catch (error) {
+      if (opts.prior || error.code !== 'ENOENT') throw new GithubReviewsError(`cannot read prior ${path}: ${error.message}`)
+    }
+  }
+  let priorFixBrief = null
+  if (path) {
+    const briefPath = join(dirname(path), `${basename(path, '.json')}.fix.json`)
+    try { priorFixBrief = JSON.parse(readFileSync(briefPath, 'utf8')) } catch (error) {
+      if (error.code !== 'ENOENT') throw new GithubReviewsError(`cannot read ${briefPath}: ${error.message}`)
+    }
+  }
+  const handled = handledIds(prior, priorFixBrief)
+  const external = collectExternal(pr, opts.head, { permissionOf, handled })
+  const merged = mergeExternal(review, external, handled)
+  writeFileSync(opts.review, `${JSON.stringify(merged, null, 2)}\n`)
+  return {
+    out: {
+      findings: external.findings.map(({ id, severity, author }) => ({ id, severity, author })),
+      awaiting: external.awaiting,
+      ignored: external.ignored.length,
+    },
+  }
+}
+
+if (isMainModule(import.meta.url)) {
+  try {
+    const { out } = run(process.argv.slice(2))
+    process.stdout.write(`${JSON.stringify(out, null, 2)}\n`)
+  } catch (error) {
+    process.stderr.write(`${error instanceof GithubReviewsError ? error.message : error.stack}\n`)
+    process.exitCode = 2
+  }
+}

package/skills/engineering/resolve-issues/scripts/github-reviews.test.mjs

@@ -0,0 +1,264 @@
+import { test } from 'node:test'
+import assert from 'node:assert/strict'
+import { mkdtempSync, readFileSync, rmSync, writeFileSync } from 'node:fs'
+import { tmpdir } from 'node:os'
+import { join } from 'node:path'
+
+import {
+  collectExternal,
+  fetchPr,
+  permissionFetcher,
+  findStructured,
+  handledIds,
+  mergeExternal,
+  parsePr,
+  run,
+  severityTag,
+  STRUCTURED_MARKER,
+} from './github-reviews.mjs'
+
+const HEAD = 'abc1234'
+const ROLES = { vera932: 'write', alo335: 'admin', reader: 'read' }
+const permissionOf = (login) => ROLES[login] ?? 'none'
+const review = (id, login, state, body = '', at = '2026-10-08T10:00:00Z', commit = HEAD) => ({
+  databaseId: id, author: { login }, state, body, submittedAt: at, url: `https://github.com/o/r/pull/1#pullrequestreview-${id}`, commit: { oid: commit },
+})
+const thread = (id, login, body, extra = {}) => ({
+  isResolved: false, isOutdated: false, ...extra,
+  comments: { nodes: [{ databaseId: id, author: { login }, body, path: 'src/a.ts', line: 12, url: `https://github.com/o/r/pull/1#discussion_r${id}`, originalCommit: { oid: HEAD } }] },
+})
+const pr = (parts = {}) => ({
+  author: { login: 'cory-bot' },
+  reviews: { nodes: parts.reviews ?? [] },
+  reviewThreads: { nodes: parts.threads ?? [] },
+  comments: { nodes: parts.comments ?? [] },
+})
+
+test('severity tags are read from the first line in the usual forms only', () => {
+  for (const [body, tag] of [
+    ['P1: refund sign flips', 'P1'], ['**P0** token leaks', 'P0'], ['[P1] missing check', 'P1'],
+    ['![P1 Badge](https://img.shields.io/badge/P1-orange) Wrong total', 'P1'], ['P2: rename', 'P2'],
+    ['**<sub><sub>![P1 Badge](https://img.shields.io/badge/P1-orange?style=flat)</sub></sub>  Keep the lock**', 'P1'],
+    ['<!-- codex-pull-request-review-summary -->', null],
+    ['Pretty sure this is fine', null], ['P10 items', null], ['nit\nP1: on line two', null], ['', null],
+  ]) assert.equal(severityTag(body), tag, body)
+})
+
+test('a trusted changes request is a P1 finding; approvals, dismissals and later approvals clear it', () => {
+  const blocked = collectExternal(pr({ reviews: [review(11, 'vera932', 'CHANGES_REQUESTED', 'Refund rounds the wrong way\nmore')] }), HEAD, { permissionOf })
+  assert.deepEqual(blocked.findings.map((f) => [f.id, f.severity, f.summary, f.author]), [['gh-review-11', 'P1', 'Refund rounds the wrong way', 'vera932']])
+  assert.match(blocked.findings[0].detail, /more/)
+  const cleared = collectExternal(pr({ reviews: [
+    review(11, 'vera932', 'CHANGES_REQUESTED', 'x', '2026-10-08T10:00:00Z'),
+    review(12, 'vera932', 'COMMENTED', 'thanks', '2026-10-08T11:00:00Z'),
+    review(13, 'vera932', 'APPROVED', '', '2026-10-08T12:00:00Z'),
+  ] }), HEAD, { permissionOf })
+  assert.deepEqual(cleared.findings, [])
+  const dismissed = collectExternal(pr({ reviews: [review(11, 'vera932', 'CHANGES_REQUESTED', 'x'), review(14, 'vera932', 'DISMISSED', '', '2026-10-08T12:00:00Z')] }), HEAD, { permissionOf })
+  assert.deepEqual(dismissed.findings, [])
+})
+
+test('only write access counts, and never the PR author', () => {
+  const external = collectExternal(pr({
+    reviews: [review(21, 'reader', 'CHANGES_REQUESTED', 'no'), review(22, 'cory-bot', 'CHANGES_REQUESTED', 'self')],
+    threads: [thread(31, 'codex-bot', 'P1: bot says'), thread(32, 'alo335', 'P1: maintainer says')],
+  }), HEAD, { permissionOf })
+  assert.deepEqual(external.findings.map((f) => f.id), ['gh-comment-32'])
+  assert.deepEqual(external.ignored.map((i) => [i.author, i.reason]).sort(), [
+    ['codex-bot', 'permission none'], ['cory-bot', 'PR author'], ['reader', 'permission read'],
+  ])
+})
+
+test('tagged comments block until resolved; P2/P3 and untagged comments never do', () => {
+  const external = collectExternal(pr({
+    threads: [
+      thread(41, 'vera932', '**P0** tenant check missing'),
+      thread(42, 'vera932', 'P1: resolved already', { isResolved: true }),
+      thread(43, 'vera932', 'P2: rename'),
+      thread(44, 'vera932', 'looks off to me'),
+    ],
+    reviews: [review(45, 'vera932', 'COMMENTED', '[P1] the export drops currency')],
+    comments: [{ databaseId: 46, author: { login: 'alo335' }, body: 'P1: migration not reversible', createdAt: '2026-10-08T10:00:00Z', url: 'u46' }],
+  }), HEAD, { permissionOf })
+  assert.deepEqual(external.findings.map((f) => [f.id, f.severity]), [['gh-comment-41', 'P0'], ['gh-comment-45', 'P1'], ['gh-comment-46', 'P1']])
+  assert.equal(external.findings[0].file, 'src/a.ts')
+  assert.equal(external.findings[0].line, 12)
+  const badge = collectExternal(pr({ threads: [thread(49, 'vera932', '**<sub><sub>![P1 Badge](https://img.shields.io/badge/P1-orange)</sub></sub>  Keep the lock**')] }), HEAD, { permissionOf })
+  assert.equal(badge.findings[0].summary, 'Keep the lock')
+})
+
+test('a changes request whose body is tagged counts once', () => {
+  const external = collectExternal(pr({ reviews: [review(47, 'vera932', 'CHANGES_REQUESTED', 'P1: wrong total')] }), HEAD, { permissionOf })
+  assert.deepEqual(external.findings.map((f) => f.id), ['gh-review-47'])
+})
+
+test('after a fix brief carried them, a standing changes request is awaited and a comment is dropped', () => {
+  const handled = new Set(['gh-review-11', 'gh-comment-41'])
+  const external = collectExternal(pr({
+    reviews: [review(11, 'vera932', 'CHANGES_REQUESTED', 'x', '2026-10-08T10:00:00Z', 'old1234')],
+    threads: [thread(41, 'vera932', 'P1: still unresolved'), thread(48, 'vera932', 'P1: new one')],
+  }), HEAD, { permissionOf, handled })
+  assert.deepEqual(external.findings.map((f) => f.id), ['gh-comment-48'])
+  assert.deepEqual(external.awaiting.map((a) => [a.id, a.author, a.commit]), [['gh-review-11', 'vera932', 'old1234']])
+  const rerequested = collectExternal(pr({ reviews: [
+    review(11, 'vera932', 'CHANGES_REQUESTED', 'x', '2026-10-08T10:00:00Z', 'old1234'),
+    review(15, 'vera932', 'CHANGES_REQUESTED', 'still wrong', '2026-10-08T13:00:00Z'),
+  ] }), HEAD, { permissionOf, handled })
+  assert.deepEqual(rerequested.findings.map((f) => f.id), ['gh-review-15'], 'a new changes request is a new finding')
+  assert.deepEqual(rerequested.awaiting, [])
+})
+
+test('the handled ledger carries forward and merge replaces what it added before', () => {
+  const prior = { findings: [{ id: 'gh-review-11', severity: 'P1' }, { id: 'R1', severity: 'P1' }], external: { added: ['gh-review-11'], handled: ['gh-comment-41'] } }
+  const brief = { fix: [{ id: 'gh-review-11' }, { id: 'R1' }] }
+  assert.deepEqual([...handledIds(prior, brief)].sort(), ['gh-comment-41', 'gh-review-11'])
+  assert.deepEqual([...handledIds(prior, null)], ['gh-comment-41'], 'no fix brief: the prior round handed nothing on')
+  assert.deepEqual([...handledIds(null)], [])
+  const own = { id: 'R2', severity: 'P1' }
+  const stale = { id: 'gh-comment-1', severity: 'P1', source: 'github' }
+  const fresh = { findings: [{ id: 'gh-comment-2', severity: 'P1', source: 'github' }], awaiting: [], ignored: [], head: HEAD, prAuthor: 'cory-bot' }
+  const merged = mergeExternal({ version: 1, findings: [own, stale], external: { added: ['gh-comment-1'] } }, fresh, new Set(['gh-review-11']))
+  assert.deepEqual(merged.findings.map((f) => f.id), ['R2', 'gh-comment-2'])
+  assert.deepEqual(merged.external.added, ['gh-comment-2'])
+  assert.deepEqual(merged.external.handled, ['gh-review-11'])
+})
+
+const PASSES = { spec: 'done', correctness: 'done', tests: 'done', standards: 'done' }
+const structuredBody = (head, extra = {}) => `${STRUCTURED_MARKER}\nReview by Agentier\n\n\`\`\`json\n${JSON.stringify({ version: 1, head, complete: true, passes: PASSES, findings: [], commands: ['npm test'], ...extra })}\n\`\`\`\n`
+
+test('a structured result stands in only when trusted and of this HEAD, newest first', () => {
+  const comments = [
+    { databaseId: 51, author: { login: 'alo335' }, body: structuredBody(HEAD, { commands: ['older'] }), createdAt: '2026-10-08T10:00:00Z', url: 'u51' },
+    { databaseId: 52, author: { login: 'alo335' }, body: structuredBody(HEAD, { commands: ['newer'] }), createdAt: '2026-10-08T11:00:00Z', url: 'u52' },
+    { databaseId: 53, author: { login: 'alo335' }, body: structuredBody('other99'), createdAt: '2026-10-08T12:00:00Z', url: 'u53' },
+    { databaseId: 54, author: { login: 'reader' }, body: structuredBody(HEAD, { commands: ['untrusted'] }), createdAt: '2026-10-08T13:00:00Z', url: 'u54' },
+    { databaseId: 55, author: { login: 'cory-bot' }, body: structuredBody(HEAD, { commands: ['self'] }), createdAt: '2026-10-08T14:00:00Z', url: 'u55' },
+    { databaseId: 56, author: { login: 'alo335' }, body: `${STRUCTURED_MARKER}\n\`\`\`json\n{not json\n\`\`\``, createdAt: '2026-10-08T15:00:00Z', url: 'u56' },
+  ]
+  const found = findStructured(pr({ comments }), HEAD, { permissionOf })
+  assert.deepEqual(found.result.commands, ['newer'])
+  assert.deepEqual(found.source, { kind: 'github', author: 'alo335', url: 'u52' })
+  assert.equal(findStructured(pr({ comments: comments.slice(2) }), HEAD, { permissionOf }), null)
+  const tagged = collectExternal(pr({ comments: [{ ...comments[0], body: structuredBody(HEAD, { findings: [{ id: 'R1', severity: 'P1' }] }).replace('Review by', 'P1 Review by') }] }), HEAD, { permissionOf })
+  assert.deepEqual(tagged.findings, [], 'a structured result is never read as a tagged comment')
+})
+
+test('parsePr takes owner/name#N only', () => {
+  assert.deepEqual(parsePr('1aboveio/ai#1545'), { owner: '1aboveio', name: 'ai', number: 1545 })
+  assert.throws(() => parsePr('1545'), /owner\/name#N/)
+})
+
+test('run merges into the round file using the prior beside it, and writes a structured result with the caller\'s counters', (t) => {
+  const dir = mkdtempSync(join(tmpdir(), 'github-reviews-'))
+  t.after(() => rmSync(dir, { recursive: true, force: true }))
+  const deps = (node) => ({ fetch: () => node, permissions: () => permissionOf })
+  writeFileSync(join(dir, '7-r1.json'), JSON.stringify({ findings: [{ id: 'gh-review-11', severity: 'P1', source: 'github' }], external: { added: ['gh-review-11'] } }))
+  writeFileSync(join(dir, '7-r1.fix.json'), JSON.stringify({ fix: [{ id: 'gh-review-11' }] }))
+  const path = join(dir, '7-r2.json')
+  writeFileSync(path, JSON.stringify({ version: 1, unit: '7', round: 2, head: HEAD, findings: [] }))
+  const node = pr({ reviews: [review(11, 'vera932', 'CHANGES_REQUESTED', 'x', '2026-10-08T10:00:00Z', 'old1234')], threads: [thread(61, 'vera932', 'P1: new')] })
+  const merged = run(['merge', '--pr', 'o/r#1', '--head', HEAD, '--review', path], deps(node))
+  assert.deepEqual(merged.out.awaiting.map((a) => a.id), ['gh-review-11'])
+  const file = JSON.parse(readFileSync(path, 'utf8'))
+  assert.deepEqual(file.findings.map((f) => f.id), ['gh-comment-61'])
+  assert.deepEqual(file.external.awaiting.map((a) => a.id), ['gh-review-11'])
+  assert.deepEqual(file.external.handled, ['gh-review-11'])
+
+  const out = join(dir, '7-r3.json')
+  const none = run(['structured', '--pr', 'o/r#1', '--head', HEAD, '--out', out, '--unit', '7', '--round', '3', '--fix-round', '2'], deps(pr()))
+  assert.equal(none.out.found, false)
+  const withResult = pr({ comments: [{ databaseId: 71, author: { login: 'alo335' }, body: structuredBody(HEAD, { unit: 'theirs', round: 9, fixRound: 9 }), createdAt: '2026-10-08T10:00:00Z', url: 'u71' }] })
+  const written = run(['structured', '--pr', 'o/r#1', '--head', HEAD, '--out', out, '--unit', '7', '--round', '3', '--fix-round', '2'], deps(withResult))
+  assert.equal(written.out.found, true)
+  const result = JSON.parse(readFileSync(out, 'utf8'))
+  assert.deepEqual([result.unit, result.round, result.fixRound, result.source.author], ['7', 3, 2, 'alo335'])
+  assert.throws(() => run(['merge', '--pr', 'o/r#1', '--head', HEAD], deps(node)), /usage/)
+})
+
+test('a GitHub finding from an incomplete or handed-back round is not handled: it still blocks', (t) => {
+  const dir = mkdtempSync(join(tmpdir(), 'github-reviews-nofix-'))
+  t.after(() => rmSync(dir, { recursive: true, force: true }))
+  // round 1 was incomplete (or handed back): the verdict wrote no fix brief
+  writeFileSync(join(dir, '7-r1.json'), JSON.stringify({ complete: false, findings: [{ id: 'gh-comment-1', severity: 'P1', source: 'github' }], external: { added: ['gh-comment-1'] } }))
+  const path = join(dir, '7-r2.json')
+  writeFileSync(path, JSON.stringify({ version: 1, unit: '7', round: 2, head: HEAD, findings: [] }))
+  run(['merge', '--pr', 'o/r#1', '--head', HEAD, '--review', path], { fetch: () => pr({ threads: [thread(1, 'vera932', 'P1: still broken')] }), permissions: () => permissionOf })
+  assert.deepEqual(JSON.parse(readFileSync(path, 'utf8')).findings.map((f) => f.id), ['gh-comment-1'])
+})
+
+test('merge never removes a reviewer finding that only claims github provenance', () => {
+  const forged = { id: 'R1', severity: 'P1', summary: 'real local blocker', source: 'github' }
+  const merged = mergeExternal({ version: 1, findings: [forged] }, { findings: [], awaiting: [], ignored: [], head: HEAD }, new Set())
+  assert.deepEqual(merged.findings, [forged])
+  const faked = mergeExternal({ version: 1, findings: [forged], external: { added: ['R1'] } }, { findings: [], awaiting: [], ignored: [], head: HEAD }, new Set())
+  assert.deepEqual(faked.findings, [forged], 'listing a reviewer id under external.added does not make it removable')
+})
+
+test('every page is read: a standing changes request behind 100 comments still blocks', () => {
+  const standing = review(1, 'vera932', 'CHANGES_REQUESTED', 'no', '2026-10-08T09:00:00Z')
+  const chatter = Array.from({ length: 150 }, (_, i) => review(100 + i, 'alo335', 'COMMENTED', 'ok', '2026-10-08T10:00:00Z'))
+  const all = { reviews: [standing, ...chatter], reviewThreads: [], comments: [] }
+  const calls = []
+  const query = (text, { after }) => {
+    const field = Object.keys(all).find((f) => text.includes(`${f}(first: 100`))
+    calls.push([field, after])
+    const start = after ? Number(after) : 0
+    const nodes = all[field].slice(start, start + 100)
+    const next = start + 100 < all[field].length
+    return { data: { repository: { pullRequest: { author: { login: 'cory-bot' }, [field]: { nodes, pageInfo: { hasNextPage: next, endCursor: next ? String(start + 100) : null } } } } } }
+  }
+  const fetched = fetchPr({ owner: 'o', name: 'r', number: 1 }, query)
+  assert.equal(fetched.reviews.nodes.length, 151)
+  assert.deepEqual(calls.filter(([f]) => f === 'reviews'), [['reviews', null], ['reviews', '100']])
+  assert.deepEqual(collectExternal(fetched, HEAD, { permissionOf }).findings.map((f) => f.id), ['gh-review-1'])
+  assert.throws(() => fetchPr({ owner: 'o', name: 'r', number: 1 }, () => ({ data: { repository: { pullRequest: { reviews: { nodes: [], pageInfo: { hasNextPage: true, endCursor: null } } } } } })), /without a cursor/)
+})
+
+test('an access lookup that fails stops the merge; only "not a user" means no access', () => {
+  const failing = (message) => permissionFetcher({ owner: 'o', name: 'r' }, () => { throw new Error(message) })
+  assert.throws(() => failing('gh api failed: connection reset')('vera932'), /cannot tell vera932's access/)
+  assert.equal(failing('gh: x is not a user (HTTP 404)')('x'), 'none')
+  const answering = (body) => permissionFetcher({ owner: 'o', name: 'r' }, () => JSON.stringify(body))
+  assert.equal(answering({ permission: 'none', role_name: '' })('codex[bot]'), 'none', 'a bot answers 200 with no access')
+  assert.equal(answering({ permission: 'write', role_name: 'maintain' })('alo335'), 'write')
+  assert.equal(answering({ permission: 'write', role_name: 'Security reviewer' })('sec'), 'write', 'a custom role keeps its base access')
+  const blocked = () => collectExternal(pr({ reviews: [review(1, 'alo335', 'CHANGES_REQUESTED', 'no')] }), HEAD, { permissionOf: failing('HTTP 502') })
+  assert.throws(blocked, /cannot tell alo335's access/)
+})
+
+test('a GitHub finding the reviewer carried forward is replaced, not doubled or refused', () => {
+  const carried = { id: 'gh-comment-1', severity: 'P1', summary: 'carried by the reviewer', trigger: 't', rule: 'r', paths: [{ path: 'a', status: 'open' }] }
+  const current = collectExternal(pr({ threads: [thread(1, 'vera932', 'P1: still broken')] }), HEAD, { permissionOf })
+  const merged = mergeExternal({ version: 1, findings: [carried, { id: 'R2', severity: 'P3' }] }, current, new Set())
+  assert.deepEqual(merged.findings.map((f) => [f.id, f.summary]), [['R2', undefined], ['gh-comment-1', 'still broken']])
+  const resolved = mergeExternal({ version: 1, findings: [carried] }, collectExternal(pr(), HEAD, { permissionOf }), new Set())
+  assert.deepEqual(resolved.findings, [], 'GitHub decides whether its finding is still open')
+})
+
+test('GitHub findings carry the blocking shape, so the verdict needs no exemption', () => {
+  const [finding] = collectExternal(pr({ threads: [thread(1, 'vera932', 'P1: still broken')] }), HEAD, { permissionOf }).findings
+  assert.match(finding.trigger, /vera932's P1 comment on GitHub/)
+  assert.ok(finding.rule)
+  assert.deepEqual(finding.paths, [{ path: 'src/a.ts:12', status: 'open' }])
+})
+
+test('a comment that only mentions the marker is still read as feedback', () => {
+  for (const body of [
+    `P1: Parser drops feedback containing ${STRUCTURED_MARKER}`,
+    `P1: Parser drops feedback containing ${STRUCTURED_MARKER}\n\n\`\`\`json\n{}\n\`\`\``,
+    `P1: wrong\n${STRUCTURED_MARKER}\n\`\`\`json\n{"head":"${HEAD}"}\n\`\`\``,
+  ]) {
+    const external = collectExternal(pr({ threads: [thread(1, 'vera932', body)] }), HEAD, { permissionOf })
+    assert.deepEqual(external.findings.map((f) => f.id), ['gh-comment-1'], body)
+  }
+})
+
+test('a posted result must be complete by the reviewer\'s own rules', () => {
+  const posted = (extra) => pr({ comments: [{ databaseId: 1, author: { login: 'alo335' }, body: structuredBody(HEAD, extra), createdAt: '2026-10-08T10:00:00Z', url: 'u1' }] })
+  assert.ok(findStructured(posted({}), HEAD, { permissionOf }))
+  assert.equal(findStructured(posted({ complete: undefined, passes: undefined }), HEAD, { permissionOf }), null)
+  assert.equal(findStructured(posted({ passes: { ...PASSES, tests: 'partial' } }), HEAD, { permissionOf }), null)
+  assert.equal(findStructured(posted({ commands: [] }), HEAD, { permissionOf }), null)
+  assert.equal(findStructured(posted({ findings: undefined }), HEAD, { permissionOf }), null)
+  assert.equal(findStructured(posted({ complete: undefined }), HEAD, { permissionOf }), null, 'all passes done but no complete: true')
+})