@1aboveio/skills 0.10.0

package/skills/engineering/review-pr/scripts/post-review.mjs

@@ -0,0 +1,405 @@
+// Post a review-pr verdict + findings to GitHub as ONE review (inline comments +
+// summary + verdict event), handling the self-authored-PR downgrade. The fiddly,
+// error-prone glue that should be code, not prose. Pure core is unit-tested; the
+// `gh` calls live only in the CLI.
+//
+//   node post-review.mjs --findings review.json --pr 482 [--repo owner/name]
+//     [--pr-context pr-context.json] [--dry-run] [--file-issues]
+//
+// `review.json` matches schemas/findings.schema.json: { verdict, summary, findings[] }.
+// Verification is enforced upstream by that schema — a finding with no file/line is
+// invalid and this script refuses to post it. The BLOCK-n/NOTE-n label and the
+// verdict are DERIVED here from each finding's {priority, in_scope}; the reviewer
+// never writes them. Non-blocking notes and out-of-scope criticals route to tracked
+// issues — but ONLY under --file-issues (default OFF prints what it WOULD open),
+// because opening an issue is an outward action. --pr-context reuses pr-context.mjs's
+// own changed-file list to catch a finding whose path is not actually in the diff
+// (in_scope alone is not a reliable proxy for that — #635); never anchored inline
+// either way, only where the detail lands (comment vs. review-body section) changes.
+
+import fs from 'node:fs'
+import { execFileSync } from 'node:child_process'
+import {
+  validateFinding,
+  validateReviewDocument,
+  reviewDocumentWarnings,
+  isBlockingFinding,
+  isOutOfScopeCritical,
+  findingInScope,
+} from './finding-contract.mjs'
+import { isMainModule } from '../../engineering-runtime/scripts/main-module.mjs'
+
+// ---- pure core ----
+
+export const VERDICT_EVENT = {
+  PASS: 'APPROVE',
+  NEEDS_CHANGES: 'REQUEST_CHANGES',
+  FAIL: 'REQUEST_CHANGES',
+  BLOCKED: 'COMMENT',
+}
+
+// Map verdict -> GitHub review event, downgrading to COMMENT on a self-authored PR
+// (GitHub forbids APPROVE/REQUEST_CHANGES on your own PR).
+export function resolveEvent(verdict, { selfAuthored = false } = {}) {
+  const base = VERDICT_EVENT[verdict]
+  if (!base) throw new Error(`unknown verdict: ${verdict}`)
+  if (selfAuthored && (base === 'APPROVE' || base === 'REQUEST_CHANGES')) {
+    return { event: 'COMMENT', downgraded: true, intended: base }
+  }
+  return { event: base, downgraded: false, intended: base }
+}
+
+// Enforce the finding contract (the part the schema guarantees, re-checked here so a
+// hand-built file can't post a location-less "finding").
+export function validateFindings(findings) {
+  if (!Array.isArray(findings)) return ['findings is not an array']
+  return findings.flatMap((finding, index) => validateFinding(finding, index))
+}
+
+export { validateReviewDocument }
+
+// ---- rendered contract: label, verdict, and issue routing are DERIVED here ----
+//
+// The reviewer model returns JSON only ({priority, in_scope, ...}); it never
+// writes a label prefix or the final verdict. post-review.mjs renders both, so
+// any reviewer model maps to one output (#399). `blocking` is not a stored field:
+// it is `in_scope && priority <= 1`, computed by isBlockingFinding.
+
+// Assign a rendered label to each finding, sequenced per class:
+//   in_scope && priority<=1 → BLOCK-n (holds the PR)
+//   everything else         → NOTE-n
+// An out-of-scope critical (!in_scope && priority<=1) is a NOTE-n label but is
+// surfaced loudly (its own issue + a warning), never buried — see planIssues.
+export function renderFindings(findings) {
+  let blockN = 0
+  let noteN = 0
+  return findings.map((finding) => {
+    const blocking = isBlockingFinding(finding)
+    const outOfScopeCritical = isOutOfScopeCritical(finding)
+    const label = blocking ? `BLOCK-${++blockN}` : `NOTE-${++noteN}`
+    return { finding, label, blocking, outOfScopeCritical }
+  })
+}
+
+// Verdict is mechanized: NEEDS_CHANGES iff ≥1 BLOCK-n, else PASS. FAIL/BLOCKED are
+// structural reviewer calls (unusable contract / unreachable evidence) and pass
+// through untouched.
+export function deriveVerdict(declaredVerdict, findings) {
+  if (declaredVerdict === 'FAIL' || declaredVerdict === 'BLOCKED') return declaredVerdict
+  return findings.some((finding) => isBlockingFinding(finding)) ? 'NEEDS_CHANGES' : 'PASS'
+}
+
+function prLink({ pr, repo } = {}) {
+  if (repo && pr != null) return `https://github.com/${repo}/pull/${pr}`
+  if (pr != null) return `#${pr}`
+  return 'this PR'
+}
+
+// The loud, free warning: prints regardless of any flag, and rides in the review
+// body + handoff. An out-of-scope critical does not block the PR, so nothing else
+// forces a human to look at it — the warning is that forcing function.
+export function outOfScopeCriticalWarnings(findings, context = {}) {
+  return renderFindings(findings)
+    .filter(({ outOfScopeCritical }) => outOfScopeCritical)
+    .map(({ finding: f, label }) =>
+      `> ⚠️ **OUT-OF-SCOPE CRITICAL — ${label} (does NOT block this PR):** ${f.title} — \`${f.file}:${f.line_start}\` ` +
+      `(priority ${f.priority}, confidence ${f.confidence}). A dedicated critical/security issue is owed; do not fold it into the refactor-later batch.`)
+}
+
+// Plan the tracked issues a set of findings should open — pure, returns intended
+// payloads (never shells out). The CLI decides whether to create them (--file-issues)
+// or print them (default). Two kinds:
+//   refactor-later — ONE batched issue for every priority>=2 note (both scopes).
+//   out-of-scope-critical — ONE dedicated issue per !in_scope && priority<=1 finding.
+export function planIssues(findings, context = {}) {
+  const rendered = renderFindings(findings)
+  const link = prLink(context)
+  const notes = rendered.filter(({ finding }) => Number.isInteger(finding.priority) && finding.priority >= 2)
+  const criticals = rendered.filter(({ outOfScopeCritical }) => outOfScopeCritical)
+  const issues = []
+  if (notes.length) {
+    const rows = notes.map(({ finding: f, label }) =>
+      `- **${label}** ${f.in_scope === false ? '(out-of-scope) ' : ''}${f.title} — \`${f.file}:${f.line_start}\`` +
+      (f.recommendation ? ` — ${f.recommendation}` : ''))
+    issues.push({
+      kind: 'refactor-later',
+      labels: ['refactor-later'],
+      title: `refactor-later: ${notes.length} deferred note${notes.length === 1 ? '' : 's'} from ${link}`,
+      body: `Deferred non-blocking notes batched from ${link} — not merge-blocking, tracked so they are neither lost nor left holding attention on the PR.\n\n${rows.join('\n')}`,
+    })
+  }
+  for (const { finding: f, label } of criticals) {
+    issues.push({
+      kind: 'out-of-scope-critical',
+      labels: ['critical', 'security'],
+      title: `out-of-scope critical: ${f.title}`,
+      body: `Surfaced as ${label} from ${link} — a priority-${f.priority} issue in code the PR did not change, so it does NOT block that PR but must not be buried in a refactor batch.\n\n` +
+        `**Location:** \`${f.file}:${f.line_start}\`\n**Why:** ${f.why}` +
+        (f.consequence ? `\n**Consequence:** ${f.consequence}` : '') +
+        (f.recommendation ? `\n**Fix:** ${f.recommendation}` : ''),
+    })
+  }
+  return issues
+}
+
+export function commentBody(f, label) {
+  const prefix = label ? `${label}: ` : ''
+  let body = `**${prefix}${f.title}** _(priority ${f.priority}, confidence ${f.confidence})_` +
+    (f.theme?.contract ? `\n\n**Governing contract:** ${f.theme.contract}` : '') +
+    `\n\n${f.why}` +
+    (f.consequence ? `\n\n**Consequence:** ${f.consequence}` : '') +
+    (f.recommendation ? `\n\n**Fix:** ${f.recommendation}` : '')
+  // A domain-semantic blocker's hazard_candidate is the ready-to-paste repo-hazards row the
+  // fix commit owes (docs/domain-hazards.md). The posted review is the durable form the fix
+  // agent works from — dropping the row here would force the fixer to reinvent it and leave
+  // the re-reviewer nothing to verify the written row against.
+  const h = f.hazard_candidate
+  if (h && (h.covered_by || h.rule)) {
+    body += h.covered_by
+      ? `\n\n**Hazard row:** covered by \`${h.covered_by}\` in \`docs/domain-hazards.md\` — no new row owed.`
+      : `\n\n**Hazard row owed** (\`docs/domain-hazards.md\` → ${h.section || 'cross-cutting'}):\n\n\`\`\`markdown\n| ${h.id || '<id>'} | ${h.rule} | ${h.prove || '<what to prove>'} | <this PR> |\n\`\`\``
+  }
+  return body
+}
+
+// ---- #635: is a finding's file actually IN the diff? ----
+//
+// `pr-context.mjs` computes the changed-file list once, at review-establishment
+// time, as `changedFiles: [{status, path}]` (see its --base CLI). Reuse that same
+// list here rather than recomputing it — post-review.mjs never shells out to git
+// or `gh` to rediscover the diff; the CLI accepts it via `--pr-context <file>`
+// (pr-context.mjs's own JSON output) so the two steps of one review share one
+// computation instead of drifting.
+
+// Normalize a path for changed-file/finding-file comparison. The diff list and a
+// finding's `file` can name the same path while disagreeing on a leading `./`,
+// backslashes, a leading `/` (repo-relative vs. an absolute path the reviewer
+// pasted), or case (a case-insensitive checkout vs. GitHub's committed case).
+export function normalizeDiffPath(p) {
+  if (!p) return ''
+  return String(p).replace(/\\/g, '/').replace(/^(\.\/)+/, '').replace(/^\/+/, '').toLowerCase()
+}
+
+// Build the changed-file set from pr-context.mjs's own `changedFiles` shape
+// ([{status, path}]), or a bare array of path strings. `null` (not an array at
+// all) means "the diff is unknown" — distinct from an empty Set ("known: nothing
+// changed") — so `anchorable` below can tell "can't verify" from "verified: not
+// in the diff".
+export function changedFileSet(changedFiles) {
+  if (!Array.isArray(changedFiles)) return null
+  const set = new Set()
+  for (const entry of changedFiles) {
+    const p = typeof entry === 'string' ? entry : entry?.path
+    if (p) set.add(normalizeDiffPath(p))
+  }
+  return set
+}
+
+// Can this finding be anchored as an inline comment? Two independent gates:
+//   - in_scope (the reviewer's judgment — unchanged from #628/#399), and
+//   - the file is actually in the diff, when the diff is known (#635) — an
+//     in_scope finding earned by tracing into unchanged code to prove impact can
+//     still name a file the diff never touched, and GitHub 422s on that path
+//     exactly like it does for an out-of-scope one.
+// `knownChangedFiles === null` means the caller could not establish the diff (no
+// `--pr-context`, an unreadable/malformed file, a git/gh error upstream of it) —
+// fail TOWARD POSTING: keep the pre-#635 permissive behavior (in_scope alone
+// decides) rather than guessing either way about a diff this run cannot see. A
+// finding is never dropped either way — undecidable-but-in-scope still anchors
+// (old behavior); anything that fails the check lands in the body instead.
+export function anchorable(finding, knownChangedFiles) {
+  if (!findingInScope(finding)) return false
+  if (knownChangedFiles === null) return true
+  return knownChangedFiles.has(normalizeDiffPath(finding.file))
+}
+
+// An out-of-scope finding's file is by definition absent from the diff — GitHub
+// refuses to anchor a review comment there and 422s the ENTIRE review, losing the
+// verdict, the summary, and every in-scope comment with it (#628). So an
+// out-of-scope finding never reaches `comments`; this renders the detail an
+// inline comment would have carried (why/consequence/fix) into the review body
+// instead — the only place left for it, since a `NOTE-n` label alone would bury
+// it and, for a non-critical note, `--file-issues` is opt-in and OFF by default.
+// An out-of-scope CRITICAL still gets this in addition to its existing loud
+// warning above (`outOfScopeCriticalWarnings`) — that warning alone omits
+// why/consequence/recommendation, so without this section a critical's full
+// reasoning would vanish along with its inline comment.
+//
+// #635: `in_scope` was only ever a proxy for "this file is in the diff", and the
+// proxy is inexact in the direction that still 422s the whole review — review-pr's
+// own doctrine (SKILL.md § Review Posture) permits tracing into UNCHANGED code to
+// *prove* impact, so a finding can be `in_scope: true` and still name a file the
+// diff never touched. So this section now also catches any finding — in scope or
+// not — whose `file` isn't in the known changed-file list, subsuming the in_scope
+// check rather than sitting beside it: the question is no longer "is this in
+// scope?" (a judgment) but "is this path in the diff?" (a fact `changedFiles`,
+// when known, settles). `in_scope`'s own effect is unchanged either way.
+export function outOfScopeFindingsBody(rendered, { changedFiles } = {}) {
+  const knownChangedFiles = changedFileSet(changedFiles)
+  const diverted = rendered.filter(({ finding: f }) => !anchorable(f, knownChangedFiles))
+  if (!diverted.length) return ''
+  const blocks = diverted.map(({ finding: f, label }) => {
+    const reason = !findingInScope(f) ? 'out-of-scope — not anchored inline' : 'file not in diff — not anchored inline'
+    return `**${label} — \`${f.file}:${f.line_start}\`** _(${reason})_\n\n${commentBody(f, null)}`
+  })
+  return `## Findings not anchored inline\n\n${blocks.join('\n\n---\n\n')}`
+}
+
+// Build the single-review payload for POST /repos/{o}/{r}/pulls/{n}/reviews.
+// The verdict is DERIVED from the findings ({priority, in_scope}), not taken from
+// the reviewer's declared field; each inline comment carries its rendered
+// BLOCK-n/NOTE-n label; out-of-scope criticals ride a loud warning at the top.
+// `changedFiles` is the diff's changed-file list (pr-context.mjs's own shape,
+// [{status, path}]) — optional, and never part of the reviewer's document (like
+// `pr`/`repo`, it's a posting-time input, not something the model emits).
+export function buildReviewPayload({ verdict, summary = '', findings = [], selfAuthored = false, pr, repo, changedFiles, ...metadata }) {
+  const documentErrors = validateReviewDocument({ verdict, summary, findings, ...metadata })
+  if (documentErrors.length) throw new Error(`invalid review document: ${documentErrors.join('; ')}`)
+  const derivedVerdict = deriveVerdict(verdict, findings)
+  const { event, downgraded, intended } = resolveEvent(derivedVerdict, { selfAuthored })
+  const rendered = renderFindings(findings)
+  const knownChangedFiles = changedFileSet(changedFiles)
+  let body = summary || `Review verdict: ${derivedVerdict}`
+  if (downgraded) {
+    const kind = intended === 'APPROVE' ? 'approve' : 'request changes on'
+    body = `> **Intended verdict: ${derivedVerdict}** — posted as a comment because the reviewer authored this PR and GitHub does not allow you to ${kind} your own PR. Treat the findings below as binding.\n\n${body}`
+  }
+  const warnings = outOfScopeCriticalWarnings(findings, { pr, repo })
+  if (warnings.length) body = `${warnings.join('\n\n')}\n\n${body}`
+  const oosBody = outOfScopeFindingsBody(rendered, { changedFiles })
+  if (oosBody) body = `${body}\n\n${oosBody}`
+  const comments = rendered
+    .filter(({ finding: f }) => anchorable(f, knownChangedFiles)) // never anchor out-of-scope or off-diff — see outOfScopeFindingsBody
+    .map(({ finding: f, label }) => {
+      const lineCount = f.line_count ?? 1 // line_count is optional; a bare line_start anchors one line
+      return {
+        path: f.file,
+        line: f.line_start + lineCount - 1,
+        side: 'RIGHT',
+        ...(lineCount > 1
+          ? { start_line: f.line_start, start_side: 'RIGHT' }
+          : {}),
+        body: commentBody(f, label),
+      }
+    })
+  // #941 / epic-876: self-authored downgrade is a first-class posting fact for guarantee 2.
+  // Orchestrators must record reviewPostedAs on the unit when downgraded — COMMENT + intended
+  // PASS + model read-back is the proof, not a GitHub APPROVE event (which GitHub forbids).
+  return {
+    event,
+    body,
+    comments,
+    verdict: derivedVerdict,
+    reviewPostedAs: downgraded ? 'comment-self-authored' : (event === 'COMMENT' ? 'comment' : 'review-event'),
+    selfAuthored: !!selfAuthored,
+    intendedEvent: intended,
+  }
+}
+
+// ---- CLI (gh side effects) ----
+
+function gh(args, opts = {}) {
+  return execFileSync('gh', args, { encoding: 'utf8', ...opts }).trim()
+}
+
+function parseArgs(argv) {
+  const f = {}
+  for (let i = 2; i < argv.length; i++) {
+    const a = argv[i]
+    if (a === '--dry-run') f.dryRun = true
+    else if (a === '--no-self-check') f.noSelfCheck = true
+    else if (a === '--file-issues') f.fileIssues = true
+    else if (a.startsWith('--')) f[a.slice(2)] = argv[++i]
+  }
+  return f
+}
+
+// Load the changed-file list from a saved `pr-context.mjs` JSON output (its own
+// `--base <target>` invocation, piped to a file at review-establishment time — see
+// SKILL.md § Review Workflow step 1). Never throws: a missing/unreadable/malformed
+// file is exactly the "unavailable" case `anchorable` already handles by failing
+// TOWARD POSTING, so this warns and returns `undefined` rather than crashing a run
+// that would otherwise post cleanly.
+function loadChangedFiles(prContextPath) {
+  if (!prContextPath) return undefined
+  try {
+    const ctx = JSON.parse(fs.readFileSync(prContextPath, 'utf8'))
+    if (Array.isArray(ctx.changedFiles)) return ctx.changedFiles
+    console.error(`warning: --pr-context ${prContextPath} has no changedFiles array; not validating comment paths against the diff`)
+  } catch (e) {
+    console.error(`warning: could not read --pr-context ${prContextPath} (${e.message}); not validating comment paths against the diff`)
+  }
+  return undefined
+}
+
+// Print, or actually open, the tracked issues these findings route to. Issue
+// creation is an OUTWARD action, so it is gated behind --file-issues and DEFAULTS
+// OFF: without the flag we only print what WOULD open. The loud out-of-scope
+// warnings print in EITHER mode — a warning is free; opening an issue is not.
+function routeIssues(findings, { pr, repo, fileIssues, ghImpl = gh }) {
+  for (const warning of outOfScopeCriticalWarnings(findings, { pr, repo })) console.error(warning)
+  const issues = planIssues(findings, { pr, repo })
+  if (!issues.length) return
+  if (!fileIssues) {
+    console.log(`\n--file-issues not set (default) — would open ${issues.length} issue(s); pass --file-issues to create them:`)
+    for (const issue of issues) console.log(`  [${issue.kind}] ${issue.title}  labels: ${issue.labels.join(',')}`)
+    return
+  }
+  for (const issue of issues) {
+    const args = ['issue', 'create', '--title', issue.title, '--body', issue.body]
+    if (repo) args.push('--repo', repo)
+    for (const label of issue.labels) args.push('--label', label)
+    const url = ghImpl(args)
+    console.log(`opened [${issue.kind}] ${url}`)
+  }
+}
+
+function main() {
+  const a = parseArgs(process.argv)
+  if (!a.findings || !a.pr) {
+    console.error('usage: post-review.mjs --findings <file.json> --pr <number> [--repo owner/name] [--pr-context <pr-context.json>] [--dry-run] [--no-self-check] [--file-issues]')
+    process.exit(2)
+  }
+  const data = JSON.parse(fs.readFileSync(a.findings, 'utf8'))
+  const errs = validateReviewDocument(data)
+  if (errs.length) {
+    console.error('Refusing to post — invalid findings:\n  ' + errs.join('\n  '))
+    process.exit(2)
+  }
+  // Read-tolerance: a finding still carrying a removed field (e.g. blocking) warns
+  // but never blocks posting; the derived value is used.
+  for (const w of reviewDocumentWarnings(data)) console.error(`warn: ${w}`)
+  let selfAuthored = false
+  if (!a.noSelfCheck) {
+    try {
+      const me = gh(['api', 'user', '--jq', '.login'])
+      const author = gh(['pr', 'view', String(a.pr), '--json', 'author', '--jq', '.author.login'])
+      selfAuthored = me === author
+    } catch {
+      console.error('warning: could not determine reviewer vs author; not downgrading. Pass --no-self-check to silence.')
+    }
+  }
+  // --repo is optional for the review post and for opening issues (resolved from
+  // gh when actually posting); --dry-run resolves nothing (PR links fall back to #n).
+  const repo = a.repo || (a.dryRun ? undefined : gh(['repo', 'view', '--json', 'nameWithOwner', '--jq', '.nameWithOwner']))
+  // --pr-context reuses the changed-file list pr-context.mjs already computed at
+  // review-establishment time (its own JSON stdout, saved to a file) — this script
+  // never recomputes the diff itself. Omitted/unreadable => undefined => anchorable()
+  // falls back to the pre-#635 in_scope-only check (see its doc comment).
+  const changedFiles = loadChangedFiles(a['pr-context'])
+  const { verdict, reviewPostedAs, selfAuthored: postedSelf, intendedEvent, ...payload } = buildReviewPayload({ ...data, selfAuthored, pr: a.pr, repo, changedFiles })
+  if (a.dryRun) {
+    // --dry-run touches nothing: it never posts the review and never opens an
+    // issue, even with --file-issues — it prints what both would do.
+    console.log(JSON.stringify({ ...payload, verdict, reviewPostedAs, selfAuthored: postedSelf, intendedEvent }, null, 2))
+    console.log(`\nDerived verdict: ${verdict} (from ${data.findings.length} finding(s)); reviewPostedAs=${reviewPostedAs}`)
+    routeIssues(data.findings, { pr: a.pr, repo, fileIssues: false })
+    return
+  }
+  // Strip orchestrator-only fields before the GitHub reviews API body.
+  execFileSync('gh', ['api', `repos/${repo}/pulls/${a.pr}/reviews`, '--method', 'POST', '--input', '-'], { input: JSON.stringify(payload), stdio: ['pipe', 'inherit', 'inherit'] })
+  console.log(`posted ${payload.event} (verdict ${verdict}; reviewPostedAs=${reviewPostedAs})${postedSelf ? ' (self-authored → downgraded)' : ''} with ${payload.comments.length} inline comment(s)`)
+  routeIssues(data.findings, { pr: a.pr, repo, fileIssues: a.fileIssues })
+}
+
+if (isMainModule(import.meta.url)) main()

package/skills/engineering/review-pr/scripts/pr-context.mjs

@@ -0,0 +1,207 @@
+// Establish the review SUBJECT correctly, every time: the net three-dot diff from
+// the merge-base, the changed files, and the commit list (for the history scan).
+// Pure git — language-agnostic. Pure parsers are unit-tested; git calls live in
+// the CLI. Removes the classic diff-discipline footgun (two-dot vs three-dot, wrong
+// base) so the reviewer reasons over the right change-set.
+//
+//   node pr-context.mjs --base main [--head HEAD] [--head-ref <branch-name>]
+//                                                        # prints JSON review context
+//
+// The range it emits is `<merge-base>...HEAD` (three-dot = what would merge), which
+// is what review-method.md requires.
+//
+// PROMOTION SIGNAL. `promotion: true` marks a release/integration branch being merged
+// into production (review as a release: fast-forward gate + readiness checklist, not a
+// line-by-line re-review). It requires BOTH halves: the BASE is a production branch
+// (main/master/production/prod) AND the HEAD is a recognized integration/release branch
+// (dev, develop, release/*, hotfix/*, staging, staging/*). A base check alone is wrong
+// in a trunk-based repo, where every feature PR targets `main` — those are feature PRs,
+// not promotions (see issue #392).
+//
+// The head is classified by its BRANCH NAME. `--head` is a rev (default HEAD); the name
+// is resolved from it (`git rev-parse --abbrev-ref`), or you may pass it explicitly with
+// `--head-ref`. When the name cannot be resolved (a detached HEAD or a bare SHA — nothing
+// to classify), the SAFE DEFAULT is `promotion: false`: treating a real promotion as a
+// feature PR just runs the normal review; the reverse (issue #392's bug) mis-routes it.
+
+import { execFileSync } from 'node:child_process'
+import { isMainModule } from '../../engineering-runtime/scripts/main-module.mjs'
+
+// ---- pure core ----
+
+export function threeDotRange(base, head = 'HEAD') {
+  return `${base}...${head}`
+}
+
+// Parse `git diff --name-status <range>` → [{status, path}] (handles rename "R100\told\tnew").
+export function parseNameStatus(text) {
+  return (text || '').split(/\r?\n/).filter(Boolean).map((line) => {
+    const parts = line.split('\t')
+    const status = parts[0]
+    const path = status.startsWith('R') || status.startsWith('C') ? parts[parts.length - 1] : parts[1]
+    return { status, path }
+  })
+}
+
+// Parse `git log --oneline <base>..HEAD` → [{sha, subject}] (two-dot here is correct:
+// the commits unique to the PR head).
+export function parseLog(text) {
+  return (text || '').split(/\r?\n/).filter(Boolean).map((line) => {
+    const sp = line.indexOf(' ')
+    return sp === -1 ? { sha: line, subject: '' } : { sha: line.slice(0, sp), subject: line.slice(sp + 1) }
+  })
+}
+
+// A promotion (e.g. dev→main) must FAST-FORWARD: the base must be an ancestor of
+// HEAD, i.e. no commits live on base that HEAD lacks. A non-empty list = base has
+// commits (usually hotfixes) the promotion would REVERT — hold and back-merge first.
+export function fastForwardable(commitsOnBaseNotInHead) {
+  return (commitsOnBaseNotInHead || []).length === 0
+}
+
+// A promotion TARGET: the base is a production branch. Necessary but NOT sufficient —
+// a promotion also needs an integration/release HEAD (see isPromotion). Keying on this
+// alone flags every feature PR in a trunk-based repo as a promotion (issue #392).
+export function isPromotionTarget(baseRef) {
+  return /(^|\/)(main|master|production|prod)$/.test(baseRef || '')
+}
+
+// Conventional remote names recognized in the SHORT remote-tracking form
+// (`origin/dev`). The full `refs/remotes/<remote>/…` form strips any remote segment
+// because the namespace is explicit and unambiguous; the short form is ambiguous with
+// an ordinary namespaced branch (`jsmith/dev`), so we only strip a KNOWN remote — never
+// an arbitrary first segment. This is normalization, not part of the integration
+// allowlist.
+const KNOWN_REMOTES = ['origin', 'upstream']
+
+// Normalize a head ref to a bare branch name by stripping ONLY known ref prefixes, so
+// the integration/release name (if any) lands at the START of the string. Handles the
+// three git ref shapes: `refs/heads/<name>`, `refs/remotes/<remote>/<name>`, and the
+// short remote-tracking `<known-remote>/<name>`. It NEVER strips an arbitrary leading
+// path segment — that is exactly the any-prefix hole (issue #392) this closes: a
+// namespaced feature branch like `feature/release/notes` or `jsmith/dev` keeps its
+// namespace and so cannot masquerade as an integration branch.
+export function normalizeHeadName(headRef) {
+  const name = headRef || ''
+  if (name.startsWith('refs/heads/')) return name.slice('refs/heads/'.length)
+  if (name.startsWith('refs/remotes/')) {
+    // drop `refs/remotes/` + exactly ONE remote segment
+    return name.slice('refs/remotes/'.length).replace(/^[^/]+\//, '')
+  }
+  for (const remote of KNOWN_REMOTES) {
+    if (name.startsWith(`${remote}/`)) return name.slice(remote.length + 1)
+  }
+  return name
+}
+
+// A promotion HEAD: an integration or release branch, by NAME. A small, documented
+// allowlist of integration/release shapes — dev/develop, staging, and release/hotfix/
+// staging/*. After normalizing away known ref prefixes (`refs/heads/`, `refs/remotes/`,
+// and short `origin/`-style remotes), the integration name is matched ANCHORED AT THE
+// START (`^`): the exact whole-name shapes (`dev`/`develop`/`staging`) and the path
+// shapes (`release/`/`hotfix/`/`staging/`). The name must OPEN the branch, never be
+// buried under a namespace — so `origin/dev` and `refs/heads/develop` resolve, but a
+// namespaced feature branch like `feature/release/notes` or `jsmith/dev` does not.
+// Anything else (the common case: an ordinary feature branch, or an unresolvable bare
+// SHA) → false.
+export function isIntegrationBranch(headRef) {
+  const name = normalizeHeadName(headRef)
+  // exact whole-name integration branches: dev, develop, staging
+  if (/^(dev|develop|staging)$/.test(name)) return true
+  // release-family branches with a version/name suffix, name at the START: release/*, hotfix/*, staging/*
+  if (/^(release|hotfix|staging)\//.test(name)) return true
+  return false
+}
+
+// A PROMOTION = a production BASE receiving an integration/release HEAD. Both halves
+// required. Review it as a release (fast-forward gate + readiness checklist), not a
+// line-by-line re-review of feature code already merged & green on the integration
+// branch. An unresolvable head (bare SHA → not integration-shaped) yields false, the
+// documented safe default.
+export function isPromotion(baseRef, headRef) {
+  return isPromotionTarget(baseRef) && isIntegrationBranch(headRef)
+}
+
+// The reviewer-facing note for the emitted context. Pure so the promotion branches are
+// unit-testable without git. The PROMOTION + NOT fast-forwardable hold-and-back-merge
+// guidance is unchanged — only the trigger (isPromotion) is corrected.
+export function reviewNote({ promotion, fastForwardable: ff, base, head, commitsOnBaseNotInHead }) {
+  if (promotion && !ff) {
+    const n = (commitsOnBaseNotInHead || []).length
+    return `PROMOTION + NOT fast-forwardable: ${base} has ${n} commit(s) not in ${head} (likely hotfixes). HOLD — back-merge ${base} → ${head} first; promoting would revert them. Then apply the release-readiness checklist (migrations/secrets/flag-defaults/version/rollback).`
+  }
+  if (promotion) {
+    return 'PROMOTION (fast-forwardable): do not re-review feature code already merged & green on the integration branch. Run only the release-readiness checklist on the content: migrations/backfills, secrets & config, feature-flag defaults, version/changelog, rollback.'
+  }
+  return 'Review the NET diff (range above), not commit-by-commit. Scope findings to what this range introduces; pre-existing issues (present at mergeBase) are notes, not blockers. Scan `commits` for secrets added-then-removed / unsafe intermediate states.'
+}
+
+// ---- CLI ----
+
+function git(args) {
+  return execFileSync('git', args, { encoding: 'utf8' }).trim()
+}
+
+function parseArgs(argv) {
+  const f = { head: 'HEAD' }
+  for (let i = 2; i < argv.length; i++) {
+    const a = argv[i]
+    if (a.startsWith('--')) f[a.slice(2)] = argv[++i]
+  }
+  return f
+}
+
+// Resolve the head's symbolic BRANCH NAME (what isIntegrationBranch classifies), or null
+// when there is nothing to classify. Prefer an explicit --head-ref; otherwise ask git for
+// the symbolic name of --head. A detached HEAD (`git rev-parse --abbrev-ref` → "HEAD") or a
+// bare SHA (echoed back unchanged) has no branch name → null → promotion defaults false.
+function resolveHeadName(a) {
+  if (a['head-ref']) return a['head-ref']
+  const head = a.head || 'HEAD'
+  let name
+  try {
+    name = git(['rev-parse', '--abbrev-ref', head])
+  } catch {
+    return null
+  }
+  if (!name || name === 'HEAD' || /^[0-9a-f]{7,40}$/i.test(name)) return null
+  return name
+}
+
+function main() {
+  const a = parseArgs(process.argv)
+  if (!a.base) {
+    console.error('usage: pr-context.mjs --base <target-branch-or-ref> [--head HEAD] [--head-ref <branch-name>]')
+    process.exit(2)
+  }
+  const base = git(['merge-base', a.base, a.head])
+  const range = threeDotRange(base, a.head)
+  const files = parseNameStatus(git(['diff', '--name-status', range]))
+  const commits = parseLog(git(['log', '--oneline', `${base}..${a.head}`]))
+  const diffstat = git(['diff', '--shortstat', range])
+  // commits on the base that HEAD lacks (in base, not in head) — the fast-forward / drift signal
+  const commitsOnBaseNotInHead = parseLog(git(['log', '--oneline', `${a.head}..${a.base}`]))
+  const ff = fastForwardable(commitsOnBaseNotInHead)
+  // Promotion requires BOTH a production base AND an integration/release head — a base
+  // check alone flags every feature→main PR (issue #392). headRef is the resolved head
+  // branch name (null when unresolvable → not integration-shaped → promotion false).
+  const headRef = resolveHeadName(a)
+  const promotion = isPromotion(a.base, headRef)
+  const ctx = {
+    targetRef: a.base,
+    headRef,
+    mergeBase: base,
+    range,
+    diffCommand: `git diff ${range}`,
+    changedFiles: files,
+    commits,
+    diffstat,
+    promotion,
+    fastForwardable: ff,
+    commitsOnBaseNotInHead,
+    note: reviewNote({ promotion, fastForwardable: ff, base: a.base, head: a.head, commitsOnBaseNotInHead }),
+  }
+  console.log(JSON.stringify(ctx, null, 2))
+}
+
+if (isMainModule(import.meta.url)) main()