@1aboveio/skills 0.0.0-stage → 1.0.0

package/skills/engineering/better-review/references/result.md

@@ -0,0 +1,151 @@
+# The result
+
+How to rate findings and, when a caller gives a result path, the file to write. Without a caller,
+report in chat as [SKILL.md](../SKILL.md#5-run-the-checks-and-report-2-min) says.
+
+## Severity
+
+Only P0/P1 block. Pick the level by consequence, not by which pass found it. Never report P3.
+
+| Level | Meaning |
+|---|---|
+| **P0** | Exploitable security, auth, tenancy, money, or data-loss defect on a reachable path. |
+| **P1** | A contract break: an acceptance criterion unmet or wrong, required behavior wrong, a correctness bug with a concrete breaking input, a required repo standard or gate violated, a dishonest test cited as proof, or prose agents act on that contradicts the code. |
+| **P2** | A real defect outside the contract: optional hardening, an untested branch whose failure is observable, scope creep, test tooling that hides no product bug. |
+| **P3** | Not reported. Cleanup, naming, smells, cosmetics, architecture opinions, minor pre-existing issues: leave them out of the result and the chat report. |
+
+A pre-existing defect the diff neither causes nor worsens is never P0/P1 for this change, however
+serious; rate it P2 when serious (leave it out otherwise) and say in its summary how serious it is, so
+its follow-up gets triaged.
+
+## The result file
+
+Write it to the path the caller gave. Callers decide the next step from severities alone, so do
+not state a verdict. The file is incomplete when `complete` is not `true`, `commands` is empty (a
+skip record excepted), `head` is not the HEAD you reviewed, an `executionIncident` is open, or a
+P2 lacks its follow-up URL when the caller asked for follow-ups.
+
+```json
+{
+  "version": 1, "unit": "1201", "round": 1, "fixRound": 1, "head": "<reviewed sha>",
+  "complete": true, "executionIncident": null,
+  "mergeBase": "<merge-base sha from pr-context>", "patchId": "<patchId from pr-context>",
+  "patchFingerprint": "<patchFingerprint from pr-context>",
+  "tier": "full", "fixLinesSinceFull": 0, "oversize": false,
+  "commands": ["npm test -- src/billing", "npm run lint"],
+  "notRun": [{ "command": "npm run e2e:android", "error": "no emulator in this environment" }],
+  "passes": {
+    "spec": "done", "correctness": "done", "tests": "done", "standards": "done"
+  },
+  "sweeps": [
+    {
+      "rule": "every refund row carries currency, rate, and amount, or none of them",
+      "points": [
+        { "location": "src/billing/refund.ts:30", "enforced": true },
+        { "location": "src/export/refunds.ts:12", "enforced": false, "finding": "R1" }
+      ]
+    }
+  ],
+  "windows": [
+    { "step": "SessionStore.logout", "location": "src/export/temp-file.ts:20",
+      "callers": ["settings button", "401 handler", "session-expiry timer"],
+      "coincides": ["app backgrounded", "offline"],
+      "outcomes": { "success": "file deleted", "error": "file kept (R4)", "timeout": "file kept (R4)" },
+      "outcome": "backgrounded: temp file kept until logout settles (R4)" }
+  ],
+  "boundaries": [
+    { "location": "src/billing/parse.ts:8", "pattern": "/^\\d+(\\.\\d{2})?$/",
+      "inputs": ["\"\"", "\"1.\"", "\"1.234\"", "\" 1.00\"", "\"-1.00\""], "outcome": "all rejected" }
+  ],
+  "findings": [
+    {
+      "id": "R1", "severity": "P1", "pass": "correctness",
+      "summary": "Refund path converts USD→EUR with the inverted rate",
+      "file": "src/billing/refund.ts", "line": 42,
+      "trigger": "refund 100 USD at rate 0.9 returns 111.11 EUR, expected 90.00",
+      "rule": "every currency conversion multiplies by the source-to-target rate",
+      "paths": [
+        { "path": "src/billing/refund.ts:42", "status": "open", "evidence": "divides by rate" },
+        { "path": "src/billing/charge.ts:31", "status": "closed", "evidence": "convert() at :31" }
+      ]
+    },
+    {
+      "id": "R2", "severity": "P2", "pass": "tests",
+      "summary": "refund rounding branch for zero-decimal currencies has no test",
+      "file": "src/billing/refund.ts", "line": 58,
+      "followUpUrl": "https://github.com/o/r/issues/9"
+    }
+  ]
+}
+```
+
+- `unit` is the caller's id for the change, when it gave one.
+- `complete` is `true` only when every pass finished. Stopped part-way (interrupted, out of
+  context, or told to stop; a slow pass is not a reason): set it to `false`, set each pass you did
+  not finish to `unfinished`, keep every command you ran and every finding you wrote, and stop;
+  the caller resumes you or replaces the round. Never erase checks or invent findings to make it
+  look done.
+- `notRun` lists each check the environment cannot run at all (no emulator, no device, no
+  credentials for a live service), with the command and its error verbatim; `[]` when none. It is
+  not a finding and does not make the review incomplete. A criterion whose proving test exists
+  but is listed here is not "unverified": say so in its spec row.
+- `executionIncident` is for something that broke during this review and can be fixed (the test
+  database crashed, the runner lost its network): `{ "status": "open", "note": "<one line>" }`,
+  `null` when nothing broke. An open incident leaves the review incomplete until the caller fixes
+  it and you resume; then set `status: "resolved"`. Write no disposition document about it.
+- `passes` holds, for a finished pass, `done`, `skipped: no spec found`,
+  `skipped: no standards found`, or
+  `skipped: not applicable: <reason>`. Any other value leaves the review incomplete. Never
+  `partial`, and never mark unfinished work skipped: a pass you did not finish is `unfinished`,
+  which correctly marks the whole review incomplete.
+- `commands` lists the checks you ran against the code. Leave out this skill's update check and its
+  scripts (`pr-context.mjs`, `scan-diff.mjs`, `rereview-scope.mjs`): a caller reads a non-empty
+  list as proof the code was checked.
+- `trigger` is required on P0/P1: the input, state, or sequence that breaks it.
+- `rule` and `paths` are required on P0/P1, with at least one row `open`: the rule as one
+  sentence, and one row per path the diff adds, changes, or relies on (a writer, caller, sweep
+  place, or async cell), each `open` or `closed`, a closed row citing its guard's `file:line`.
+  A spec finding's `rule` is the criterion and its rows the places it must hold. When every row
+  is closed the finding is resolved: leave it out. A sweep's unenforced points are its finding's
+  open rows; `finding` names that id.
+- `round` counts review attempts, skip records included, and names their files. `fixRound`
+  starts at `1`; on later rounds copy `rereview-scope.mjs`'s value, never your own. It is the
+  caller's fix counter: the tier never changes it.
+- `tier` is `full` or `delta` (see [Review tiers](../SKILL.md#review-tiers)). Never write a
+  `scope` field.
+- `mergeBase`, `patchId`, `patchFingerprint`, `tier`,
+  `fixLinesSinceFull` (`0` on a full round; the script's value on a delta), and `sweeps` (each
+  enforcement-point sweep: the rule and one row per place) let the next round run
+  `rereview-scope.mjs` and re-check the sweeps instead of redoing them. Take `mergeBase` and
+  `patchId` and `patchFingerprint` from `pr-context` on a full round and from
+  `rereview-scope.mjs` on a delta; `null` for an empty diff. The fingerprint also
+  preserves edit locations and binary bytes: patch-id alone cannot prove equivalence.
+  A reachable prior HEAD uses the actual PR-file tree diff; an unavailable prior HEAD
+  needs both matching identities, otherwise review in full. Empty `sweeps` is `[]`.
+- On a delta, retain the tier decision (`reasons`, `integrationFiles`, `integrationLines`,
+  `baseMovedFiles`, and prior HEAD) so carry-forward approval names what was checked.
+- `windows` lists each async step the change relies on, every caller of it you found (timers,
+  push events, expiry, and error handlers too), the events it was checked against, and for each
+  outcome (success, refusal, error, timeout) what the code did or the guard that rules the cell
+  out; `[]` when the diff has none.
+- `boundaries` lists each regex, glob, parser, or validator the diff adds or changes with the
+  inputs tried against it; `[]` when the diff has none.
+- On a re-review, keep a prior finding's `id` while its rule is broken anywhere, with every
+  row updated; a new witness of that rule is a new row, never a new id.
+
+## The skip record
+
+You never write one by hand. On a skip, `rereview-scope.mjs --write-skip <path>` writes it in
+place of review findings, whether you or the caller ran the script: `tier: "skip"`,
+`carriedFrom` (the HEAD whose approval it carries), the new HEAD and patch identities, `round`
+(the previous plus one), `fixRound` and `fixLinesSinceFull` carried over, `complete: true`, the
+previous `passes` and `sweeps`, `commands: []` and `findings: []`. It claims no checks; CI on its
+HEAD is the proof. A caller confirms it against the history and the scripts rather than trusting
+the file. The next round uses a skip record as its previous result like any other.
+
+## Follow-ups
+
+When the caller asks, file one issue per P2 before writing the file:
+search for an existing one first, link it to the PR and the spec, and put its URL in
+`followUpUrl`. When the caller says to file none, give each P2 its `file` and `line`; the
+caller records it and writes its `dropboxId`. You change no code and push nothing.

package/skills/engineering/better-review/release-check.mjs

@@ -0,0 +1,93 @@
+#!/usr/bin/env node
+import { spawnSync } from 'node:child_process';
+import { mkdirSync, readFileSync, writeFileSync } from 'node:fs';
+import { homedir } from 'node:os';
+import { dirname, join } from 'node:path';
+import { fileURLToPath } from 'node:url';
+
+const DAY_MS = 24 * 60 * 60 * 1000;
+const WEEK_MS = 7 * DAY_MS;
+const here = dirname(fileURLToPath(import.meta.url));
+
+function readJson(path, fallback = {}) {
+  try { return JSON.parse(readFileSync(path, 'utf8')); } catch { return fallback; }
+}
+
+function frontmatterValue(text, key) {
+  const frontmatter = /^---\n([\s\S]*?)\n---/.exec(text)?.[1] ?? '';
+  const match = new RegExp('^' + key + ':\\s*([^\\n]+)$', 'm').exec(frontmatter);
+  return match?.[1].trim().replace(/^['"]|['"]$/g, '') ?? null;
+}
+
+function repositoryOf(source) {
+  const value = String(source ?? '').trim();
+  const match = /^(?:git@github\.com:|https:\/\/github\.com\/)?([A-Za-z0-9_.-]+\/[A-Za-z0-9_.-]+?)(?:\.git)?$/.exec(value);
+  return match?.[1] ?? null;
+}
+
+function stableVersion(value) {
+  const match = /^v?(\d+)\.(\d+)\.(\d+)$/.exec(String(value ?? '').trim());
+  return match ? match.slice(1).map(Number) : null;
+}
+
+function newer(left, right) {
+  for (let index = 0; index < 3; index += 1) {
+    if (left[index] !== right[index]) return left[index] > right[index];
+  }
+  return false;
+}
+
+function writeCache(path, value) {
+  try {
+    mkdirSync(dirname(path), { recursive: true });
+    writeFileSync(path, JSON.stringify(value));
+  } catch { /* A read-only cache must not block skill use. */ }
+}
+
+function main(now = Date.now()) {
+  if (process.env.ONEABOVEIO_NO_UPDATE_CHECK) return;
+  const skill = readFileSync(join(here, 'SKILL.md'), 'utf8');
+  const name = frontmatterValue(skill, 'name');
+  const localVersion = stableVersion(frontmatterValue(skill, 'release-version'));
+  if (!name || !localVersion) return;
+
+  const lock = readJson(join(process.env.HOME || homedir(), '.agents', '.skill-lock.json'));
+  const entry = lock.skills?.[name];
+  const repository = repositoryOf(entry?.sourceUrl || entry?.source);
+  if (!repository) return;
+
+  const cacheRoot = process.env.XDG_CACHE_HOME || join(process.env.HOME || homedir(), '.cache');
+  const cachePath = join(cacheRoot, '1aboveio-skills', 'release-check.json');
+  const all = readJson(cachePath);
+  const cache = all[repository] && typeof all[repository] === 'object' ? all[repository] : {};
+
+  if (!cache.lastCheck || now - cache.lastCheck >= DAY_MS) {
+    const result = spawnSync('gh', ['api', 'repos/' + repository + '/releases/latest', '--jq', '.tag_name'], {
+      encoding: 'utf8',
+      stdio: ['ignore', 'pipe', 'ignore'],
+      timeout: 1500,
+    });
+    cache.lastCheck = now;
+    if (result.status === 0 && stableVersion(result.stdout)) cache.latestTag = result.stdout.trim();
+    else delete cache.latestTag;
+    all[repository] = cache;
+    writeCache(cachePath, all);
+  }
+
+  const latestVersion = stableVersion(cache.latestTag);
+  if (!latestVersion || !newer(latestVersion, localVersion)) return;
+  if (cache.notifiedTag === cache.latestTag && cache.notifiedAt && now - cache.notifiedAt < WEEK_MS) return;
+
+  cache.notifiedTag = cache.latestTag;
+  cache.notifiedAt = now;
+  all[repository] = cache;
+  writeCache(cachePath, all);
+  const command = `npx skills@1.5.23 add '${repository}#${cache.latestTag}' --global --agent universal claude-code --skill ${name} --yes`;
+  process.stdout.write(
+    `UPDATE_AVAILABLE: A newer 1AboveIO skills release (${cache.latestTag}) is available; this skill is `
+      + `v${localVersion.join('.')}. Ask once whether to refresh ${name}. On approval run \`${command}\`. `
+      + 'The refreshed instructions apply next session. Either way, continue the current task and do not ask again this session.\n',
+  );
+}
+
+try { main(); } catch { /* Update checks are advisory and always fail silent. */ }

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

@@ -0,0 +1,212 @@
+// 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 references/passes.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'
+import { prPatchId, prPatchFingerprint } from './rereview-scope.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,
+    // Write it into the result: a later round uses it to reuse this review across a
+    // content-equivalent rebase (rereview-scope.mjs).
+    patchId: prPatchId(base, a.head),
+    patchFingerprint: prPatchFingerprint(base, a.head),
+    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()

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

@@ -0,0 +1,168 @@
+import { test } from 'node:test'
+import assert from 'node:assert/strict'
+import { threeDotRange, parseNameStatus, parseLog, fastForwardable, isPromotionTarget, isIntegrationBranch, isPromotion, reviewNote, normalizeHeadName } from './pr-context.mjs'
+
+test('threeDotRange uses three dots (the merge diff, not two-dot)', () => {
+  assert.equal(threeDotRange('abc123'), 'abc123...HEAD')
+  assert.equal(threeDotRange('abc', 'feat'), 'abc...feat')
+})
+
+test('parseNameStatus handles add/modify/delete and rename', () => {
+  const text = ['M\tsrc/a.ts', 'A\tsrc/new.ts', 'D\tsrc/old.ts', 'R100\tsrc/from.ts\tsrc/to.ts'].join('\n')
+  assert.deepEqual(parseNameStatus(text), [
+    { status: 'M', path: 'src/a.ts' },
+    { status: 'A', path: 'src/new.ts' },
+    { status: 'D', path: 'src/old.ts' },
+    { status: 'R100', path: 'src/to.ts' },
+  ])
+})
+
+test('parseNameStatus empty → []', () => {
+  assert.deepEqual(parseNameStatus(''), [])
+})
+
+test('parseLog splits sha + subject', () => {
+  const text = '1a2b3c add export\n4d5e6f fix expired coupon'
+  assert.deepEqual(parseLog(text), [
+    { sha: '1a2b3c', subject: 'add export' },
+    { sha: '4d5e6f', subject: 'fix expired coupon' },
+  ])
+})
+
+test('fastForwardable: empty = FF possible; non-empty (base has commits head lacks) = not FF', () => {
+  assert.equal(fastForwardable([]), true)
+  assert.equal(fastForwardable([{ sha: 'h0tf1x', subject: 'hotfix prod' }]), false)
+  assert.equal(fastForwardable(undefined), true)
+})
+
+test('isPromotionTarget: production branches only (the base half of a promotion)', () => {
+  assert.equal(isPromotionTarget('main'), true)
+  assert.equal(isPromotionTarget('master'), true)
+  assert.equal(isPromotionTarget('production'), true)
+  assert.equal(isPromotionTarget('origin/main'), true)
+  assert.equal(isPromotionTarget('dev'), false)
+  assert.equal(isPromotionTarget('feature/x'), false)
+  assert.equal(isPromotionTarget('release/1.2'), false)
+})
+
+test('isIntegrationBranch: only integration/release-shaped heads (the head half of a promotion)', () => {
+  // integration branches
+  assert.equal(isIntegrationBranch('dev'), true)
+  assert.equal(isIntegrationBranch('develop'), true)
+  assert.equal(isIntegrationBranch('origin/dev'), true)
+  assert.equal(isIntegrationBranch('refs/heads/develop'), true)
+  // release / hotfix / staging shapes
+  assert.equal(isIntegrationBranch('release/1.4'), true)
+  assert.equal(isIntegrationBranch('release/2.0.0'), true)
+  assert.equal(isIntegrationBranch('hotfix/urgent-fix'), true)
+  assert.equal(isIntegrationBranch('staging'), true)
+  assert.equal(isIntegrationBranch('staging/eu'), true)
+  assert.equal(isIntegrationBranch('origin/release/1.4'), true)
+  // ordinary feature branches — NOT integration
+  assert.equal(isIntegrationBranch('feature/x'), false)
+  assert.equal(isIntegrationBranch('chore/388-doc-code-prose-audit'), false)
+  assert.equal(isIntegrationBranch('issue-392-promotion-heuristic'), false)
+  assert.equal(isIntegrationBranch('main'), false)
+  assert.equal(isIntegrationBranch('develop-tweaks'), false) // not exactly `develop`
+  assert.equal(isIntegrationBranch('feature/release-notes'), false) // `release` not its own segment
+  // unresolvable head (a bare SHA, or empty) — NOT integration → safe default
+  assert.equal(isIntegrationBranch('a1b2c3d'), false)
+  assert.equal(isIntegrationBranch(''), false)
+  assert.equal(isIntegrationBranch(undefined), false)
+})
+
+test('isPromotion: true ONLY when base is production AND head is integration/release-shaped', () => {
+  // the ~15x false-positive this fixes: a feature branch → main is NOT a promotion
+  assert.equal(isPromotion('main', 'chore/388-doc-code-prose-audit'), false)
+  assert.equal(isPromotion('main', 'feature/x'), false)
+  assert.equal(isPromotion('main', 'issue-392-promotion-heuristic'), false)
+  // genuine promotions: integration/release branch → production
+  assert.equal(isPromotion('main', 'dev'), true)
+  assert.equal(isPromotion('main', 'release/1.4'), true)
+  assert.equal(isPromotion('main', 'hotfix/x'), true)
+  assert.equal(isPromotion('master', 'develop'), true)
+  assert.equal(isPromotion('origin/main', 'origin/dev'), true)
+  // base is not a production branch → never a promotion, even from an integration head
+  assert.equal(isPromotion('dev', 'feature/x'), false)
+  assert.equal(isPromotion('release/1.4', 'dev'), false)
+  // unresolvable head (bare SHA / empty) → false (documented safe default)
+  assert.equal(isPromotion('main', 'a1b2c3d'), false)
+  assert.equal(isPromotion('main', ''), false)
+  assert.equal(isPromotion('main', undefined), false)
+})
+
+test('normalizeHeadName strips ONLY known ref prefixes — never an arbitrary leading segment', () => {
+  // known ref prefixes → stripped to the bare name
+  assert.equal(normalizeHeadName('refs/heads/develop'), 'develop')
+  assert.equal(normalizeHeadName('refs/remotes/origin/release/1.4'), 'release/1.4')
+  assert.equal(normalizeHeadName('origin/dev'), 'dev')
+  assert.equal(normalizeHeadName('origin/release/1.4'), 'release/1.4')
+  assert.equal(normalizeHeadName('upstream/staging'), 'staging')
+  // NOT a known prefix → left intact (the any-prefix hole this closes)
+  assert.equal(normalizeHeadName('jsmith/dev'), 'jsmith/dev')
+  assert.equal(normalizeHeadName('feature/release/notes'), 'feature/release/notes')
+  assert.equal(normalizeHeadName('team/staging/eu'), 'team/staging/eu')
+  // plain names pass through
+  assert.equal(normalizeHeadName('dev'), 'dev')
+  assert.equal(normalizeHeadName('release/1.4'), 'release/1.4')
+  assert.equal(normalizeHeadName(''), '')
+  assert.equal(normalizeHeadName(undefined), '')
+})
+
+// LEFT-BOUNDARY REGRESSION (issue #392, fix round): the integration/release name must
+// open the branch (after ref-prefix stripping), never be buried under a namespace. A
+// nested-prefix feature branch is an ordinary feature PR, not a promotion — the unsafe
+// direction if mis-classified. Removing the `^`/normalization makes these go RED.
+test('isIntegrationBranch: nested-prefix feature branches are NOT integration (left-boundary hole)', () => {
+  // line-79 (release/hotfix/staging path) hole
+  assert.equal(isIntegrationBranch('feature/release/notes'), false)
+  assert.equal(isIntegrationBranch('feature/hotfix/x'), false)
+  assert.equal(isIntegrationBranch('team/staging/eu'), false)
+  // line-77 (exact dev/develop/staging) hole
+  assert.equal(isIntegrationBranch('jsmith/dev'), false)
+  assert.equal(isIntegrationBranch('alice/develop'), false)
+  assert.equal(isIntegrationBranch('wip/staging'), false)
+})
+
+test('isIntegrationBranch: supported ref prefixes still resolve to TRUE after normalization', () => {
+  assert.equal(isIntegrationBranch('origin/dev'), true)
+  assert.equal(isIntegrationBranch('refs/heads/develop'), true)
+  assert.equal(isIntegrationBranch('refs/remotes/origin/release/1.4'), true)
+})
+
+test('isPromotion: nested-prefix feature branches → main are NOT promotions (left-boundary hole)', () => {
+  // these all classified promotion=true before the anchor fix (the fail-open direction)
+  assert.equal(isPromotion('main', 'feature/release/notes'), false)
+  assert.equal(isPromotion('main', 'feature/hotfix/x'), false)
+  assert.equal(isPromotion('main', 'team/staging/eu'), false)
+  assert.equal(isPromotion('main', 'jsmith/dev'), false)
+  assert.equal(isPromotion('main', 'alice/develop'), false)
+  assert.equal(isPromotion('main', 'wip/staging'), false)
+  // supported prefixes remain genuine promotions
+  assert.equal(isPromotion('main', 'refs/heads/develop'), true)
+  assert.equal(isPromotion('main', 'refs/remotes/origin/release/1.4'), true)
+})
+
+test('reviewNote: PROMOTION + NOT fast-forwardable note still fires for a genuine promotion that is not FF', () => {
+  const note = reviewNote({
+    promotion: true,
+    fastForwardable: false,
+    base: 'main',
+    head: 'release/1.4',
+    commitsOnBaseNotInHead: [{ sha: 'h0tf1x', subject: 'hotfix prod' }],
+  })
+  assert.match(note, /PROMOTION \+ NOT fast-forwardable/)
+  assert.match(note, /main has 1 commit\(s\) not in release\/1\.4/)
+  assert.match(note, /HOLD/)
+})
+
+test('reviewNote: fast-forwardable promotion → release-readiness note (not a re-review)', () => {
+  const note = reviewNote({ promotion: true, fastForwardable: true, base: 'main', head: 'dev', commitsOnBaseNotInHead: [] })
+  assert.match(note, /PROMOTION \(fast-forwardable\)/)
+  assert.doesNotMatch(note, /NOT fast-forwardable/)
+})
+
+test('reviewNote: not a promotion → review the NET diff (the common feature-PR path)', () => {
+  const note = reviewNote({ promotion: false, fastForwardable: true, base: 'main', head: 'feature/x', commitsOnBaseNotInHead: [] })
+  assert.match(note, /Review the NET diff/)
+})