@webpieces/pr-gate 0.4.532 → 0.4.534

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@webpieces/pr-gate",
-  "version": "0.4.532",
+  "version": "0.4.534",
   "description": "Gated PR system: 3-point squash-merge, merge validation gate, and red/yellow/green PR dashboard. Standalone scripts, no Nx dependency required.",
   "type": "commonjs",
   "main": "./src/index.js",
@@ -26,7 +26,7 @@
     "directory": "packages/tooling/pr-gate"
   },
   "dependencies": {
-    "@webpieces/rules-config": "0.4.532",
+    "@webpieces/rules-config": "0.4.534",
     "@inversifyjs/binding-decorators": "1.1.5",
     "inversify": "7.10.4",
     "reflect-metadata": "0.2.2"

package/src/scripts/commands/finish-upsert-pr-command.d.ts

@@ -75,6 +75,22 @@ export declare class FinishUpsertPrCommand {
      * No-op for a repo with no applicable checklists.
      */
     private assertEveryReviewerRan;
+    /**
+     * Retire the review this run just used — move review.json to old-review.json beside it, stamped as
+     * audit-only (see ReviewJsonService.archiveReviewJson).
+     *
+     * WHY it moves rather than staying put: review.json left behind is a live-looking file describing a
+     * review that has already shipped, and the next `wp-review-upsert-pr` on this branch finds it sitting
+     * there. A reviewer subagent that judges the PR's stated INTENT — its title, summary or risk level —
+     * then reads the previous round's review and can return GREEN against a title that no longer exists,
+     * with nothing in the verdict distinguishing that from a real pass. Moving it makes the only route back
+     * to this command a freshly-written review.
+     *
+     * ONLY on a PR that actually went up. A run that died before publishing must stay re-runnable without
+     * making the AI rewrite a review that was never used, and prNumber === '' is exactly that case.
+     * Non-fatal: the PR is live by here, so an unwritable archive warns rather than failing the command.
+     */
+    private archiveConsumedReview;
     private gitOut;
     private prTitleFrom;
     private computeDashboardInput;

package/src/scripts/commands/finish-upsert-pr-command.js

@@ -147,6 +147,7 @@ let FinishUpsertPrCommand = class FinishUpsertPrCommand {
         // Publish each reviewer's full output as ONE combined PR comment (idempotent, opt-out-aware). Never
         // fatal — the PR is already up by now, so a comment failure only warns.
         this.postChecklistComment(repoRoot, result.prNumber, scan, review, provenance);
+        this.archiveConsumedReview(repoRoot, featureName, result);
         // The closing recap + the clickable-link directive, BOTH derived from the real merge outcome.
         // Nothing here may hard-code success: a stranded PR under a green checkmark is how PRs got
         // abandoned (see FinishBanner).
@@ -258,6 +259,36 @@ let FinishUpsertPrCommand = class FinishUpsertPrCommand {
             `(Each reviewer's generated instructions file is already written — re-running pnpm wp-review-upsert-pr\n` +
             ` is only needed if the code changed since it ran.)`);
     }
+    /**
+     * Retire the review this run just used — move review.json to old-review.json beside it, stamped as
+     * audit-only (see ReviewJsonService.archiveReviewJson).
+     *
+     * WHY it moves rather than staying put: review.json left behind is a live-looking file describing a
+     * review that has already shipped, and the next `wp-review-upsert-pr` on this branch finds it sitting
+     * there. A reviewer subagent that judges the PR's stated INTENT — its title, summary or risk level —
+     * then reads the previous round's review and can return GREEN against a title that no longer exists,
+     * with nothing in the verdict distinguishing that from a real pass. Moving it makes the only route back
+     * to this command a freshly-written review.
+     *
+     * ONLY on a PR that actually went up. A run that died before publishing must stay re-runnable without
+     * making the AI rewrite a review that was never used, and prNumber === '' is exactly that case.
+     * Non-fatal: the PR is live by here, so an unwritable archive warns rather than failing the command.
+     */
+    archiveConsumedReview(repoRoot, featureName, result) {
+        if (result.prNumber === '')
+            return;
+        // webpieces-disable no-unmanaged-exceptions -- chokepoint: the PR is already up; a failed archive must not fail the command
+        // eslint-disable-next-line @webpieces/no-unmanaged-exceptions
+        try {
+            const archived = this.reviewJsonService.archiveReviewJson((0, rules_config_1.reviewJsonPath)(repoRoot, featureName));
+            if (archived !== '')
+                process.stdout.write(`   archived this run's review.json → ${archived} (audit only) ✓\n`);
+        }
+        catch (err) {
+            const error = (0, rules_config_1.toError)(err);
+            process.stderr.write(`⚠️  Could not archive review.json (non-fatal — the PR is already up): ${error.message}\n`);
+        }
+    }
     gitOut(args) {
         const result = (0, child_process_1.spawnSync)('git', args, { encoding: 'utf8' });
         return result.status === 0 ? (result.stdout ?? '').trim() : '';

package/src/scripts/commands/finish-upsert-pr-command.js.map

@@ -1 +1 @@
-{"version":3,"file":"finish-upsert-pr-command.js","sourceRoot":"","sources":["../../../../../../../packages/tooling/pr-gate/src/scripts/commands/finish-upsert-pr-command.ts"],"names":[],"mappings":"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","sourcesContent":["import { execSync, spawnSync } from 'child_process';\nimport * as fs from 'fs';\nimport * as path from 'path';\nimport {\n    loadAndValidate, prDirFor, reviewJsonPath, ReviewJson, RequiredChecklist, ChecklistVerdict,\n    writeTemplate, RepoRootFinder, ReviewJsonService,\n    GateTokenService, SubagentProvenanceService, PROVENANCE_OK, PROVENANCE_MISSING, PROVENANCE_SKIPPED,\n    ProvenanceResult, ReviewerEvidence, EvidenceRequest, PrGateConfig,\n    ChecklistInstructionsService, InformAiError,\n} from '@webpieces/rules-config';\nimport { injectable, bindingScopeValues } from 'inversify';\nimport { AiBranchName } from '../workflow/git-readAiBranchName';\nimport { BranchNaming } from '../workflow/branch-naming';\nimport { ChecklistScan, ChecklistScanOptions, ChecklistScanner } from '../workflow/checklist-scanner';\nimport { GitExec } from '../workflow/git-exec';\nimport { BuildAffected, BuildGateOptions } from '../workflow/build-affected';\nimport { MergeState } from '../workflow/merge-state';\nimport { ReviewStageReceiptService } from '../workflow/review-stage-receipt';\nimport { PrMerger, MergeOutcome, MERGE_RESULT_FAILED } from '../workflow/pr-merger';\nimport { FinishBanner, FinishBannerInput } from '../workflow/finish-banner';\nimport { GatedPrPublisher } from '../workflow/gated-pr-publisher';\nimport { TriggeredChecklist } from '../workflow/checklist-detector';\nimport {\n    Dashboard, DashboardInput, ChecklistRow, ChecklistCommentRow, CHECKLIST_COMMENT_MARKER,\n} from '../../dashboard/dashboard';\n\nconst SEP = '━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━\\n';\n\n/**\n * The provenance outcome: whether each reviewer was VERIFIED to have run (the integrity check, which\n * blocks) plus what each one actually read (the quality signal, which is published). Data-only.\n */\nclass ProvenanceReport {\n    verified: boolean;\n    evidence: ReviewerEvidence[];\n\n    constructor(verified: boolean, evidence: ReviewerEvidence[]) {\n        this.verified = verified;\n        this.evidence = evidence;\n    }\n}\n\n// A resolved PR's number + web URL. Both '' when the PR can't be resolved (e.g. create failed).\nclass PrRef {\n    number: string;\n    url: string;\n\n    constructor(number: string, url: string) {\n        this.number = number;\n        this.url = url;\n    }\n}\n\n// The outcome of the whole upsert: the PR number + web URL ('' each when unresolved) plus what actually\n// happened to the merge, so the final summary reports the REAL result rather than assuming success. The\n// URL is carried so the closing block can hand the AI a clickable link to relay to the user verbatim.\nclass UpsertResult {\n    prNumber: string;\n    prUrl: string;\n    merge: MergeOutcome;\n\n    constructor(prNumber: string, prUrl: string, merge: MergeOutcome) {\n        this.prNumber = prNumber;\n        this.prUrl = prUrl;\n        this.merge = merge;\n    }\n}\n\n// STAGE ③ — FINISH of the AI-first PR flow, and the ONLY command that posts PRs. Runs after\n// `wp-review-upsert-pr` verified the branch and the AI spawned the reviewers + wrote review.json.\n//\n// In order: (1) REFUSE on an unvalidated 3-point merge and REQUIRE stage ②'s receipt; (2) REQUIRE\n// review.json + every reviewer's verdict + provenance; (3) run the build gate UNLESS the receipt already\n// covers this exact HEAD; (4) render the dashboard; (5) create/update the PR via `gh`.\n//\n// It no longer FINALIZES a merge — stage ② does. Two commands owning conflict-resolution validation is two\n// implementations that drift, and finalizing here came too late to help anyway: the reviewers had already\n// reviewed the pre-merge tree by then.\n@injectable(bindingScopeValues.Singleton)\nexport class FinishUpsertPrCommand {\n    constructor(\n        private readonly repoRootFinder: RepoRootFinder,\n        private readonly aiBranchName: AiBranchName,\n        private readonly branchNaming: BranchNaming,\n        private readonly gitExec: GitExec,\n        private readonly buildAffected: BuildAffected,\n        private readonly mergeState: MergeState,\n        private readonly prMerger: PrMerger,\n        private readonly publisher: GatedPrPublisher,\n        private readonly dashboard: Dashboard,\n        private readonly checklistScanner: ChecklistScanner,\n        private readonly reviewJsonService: ReviewJsonService,\n        private readonly gateTokenService: GateTokenService,\n        private readonly provenance: SubagentProvenanceService,\n        private readonly instructions: ChecklistInstructionsService,\n        private readonly receipts: ReviewStageReceiptService,\n        private readonly banner: FinishBanner,\n    ) {}\n\n    async run(): Promise<void> {\n        const repoRoot = this.repoRootFinder.resolveRepoRoot(process.cwd());\n        // Refresh the AI-facing workflow doc so it's present + current for any failure message to cite.\n        writeTemplate(repoRoot, 'webpieces.git-workflow.md');\n        // 1. REQUIRE stage ② — see assertStageTwoRan. Returns true when its receipt covers THIS commit,\n        //    which is what lets the build gate below be skipped rather than re-run for a foregone answer.\n        const buildAlreadyGreen = this.assertStageTwoRan(repoRoot);\n\n        // 2. REQUIRE the AI-authored review.json (throws InformAiError with the schema if missing/invalid).\n        //    Compute the consumer checklists this diff triggered FIRST so an unacknowledged BLOCK throws\n        //    here — BEFORE any `gh pr create` — matching the guarantee buildCommand already provides.\n        // The SAME scan wp-review-upsert-pr runs, with filterAlreadyReviewed:true so `outstanding` is exactly what\n        // still owes a verdict (Z of N of X). Sharing the computation is the point: the command that REPORTS\n        // and the command that GATES must not be able to disagree about what is owed. review-<id>.json files\n        // persist locally, so a re-run re-validates the EXISTING verdicts against the (possibly changed)\n        // applicable set for free — an unchanged checklist needs no re-review, a newly-applicable one refuses\n        // until its file is written.\n        const featureName = this.aiBranchName.getFeatureName();\n        const scan = this.checklistScanner.scan(repoRoot, loadAndValidate(repoRoot).prGate.checklists, new ChecklistScanOptions(true, 'stage3-finish'));\n        const required = scan.applicable;\n        // FAIL FAST on missing reviewers, BEFORE review.json is parsed and before the build gate runs. A\n        // missing reviewer is not a review.json defect (folding it in made the AI fix the wrong thing), and\n        // nobody should wait on a build to be told a reviewer never ran.\n        this.assertEveryReviewerRan(scan);\n        const review = this.reviewJsonService.loadReviewJson(reviewJsonPath(repoRoot, featureName), required);\n\n        // 2c. For any BLOCK checklist that names a reviewer `subagent`, VERIFY (from the harness's own\n        //     artifacts) that such a subagent actually ran on this branch — the coding agent may not\n        //     self-certify. Absent CLAUDE_CODE_SESSION_ID this skips with a warning (CI / plain terminal).\n        const currentBranch = execSync('git branch --show-current', { encoding: 'utf8' }).trim();\n        const provenance = this.enforceProvenance(required, currentBranch, repoRoot, loadAndValidate(repoRoot).prGate);\n\n        // 2b. The build gate validates the WORKING TREE but we push HEAD — so they MUST be identical.\n        this.gitExec.assertCleanTree(repoRoot);\n\n        // 3. Build gate, then post the gated body, then push (that ORDER — see GatedPrPublisher).\n        this.runOrSkipBuildGate(repoRoot, buildAlreadyGreen);\n        const base = this.branchNaming.baseBranchName(execSync('git branch --show-current', { encoding: 'utf8' }).trim());\n\n        process.stdout.write('\\n' + SEP + '📋 Dashboard + PR\\n' + SEP + '\\n');\n        const title = this.prTitleFrom(review);\n        const input = this.computeDashboardInput(repoRoot, true, review, title, required);\n        // Append the hidden HMAC gate token bound to the LOCAL HEAD sha — computed BEFORE the push, because\n        // GatedPrPublisher writes the body first so CI's `synchronize` read can never see a stale token. A\n        // valid token in the PR body is proof this gated flow ran + passed on this exact commit, which CI\n        // (`wp-check-pr`) recomputes. We reach here only after the build gate + every BLOCK checklist\n        // passed, so minting is legitimate. Nothing about HMAC(salt, HEAD) needs the remote to have it.\n        const gateSalt = loadAndValidate(repoRoot).prGate.gateSalt;\n        const headSha = this.gitOut(['rev-parse', 'HEAD']);\n        const body = this.dashboard.renderDashboard(input) + this.gateTokenBody(gateSalt, headSha);\n        const result = this.upsertPr(repoRoot, base, body, title, input);\n        // Publish each reviewer's full output as ONE combined PR comment (idempotent, opt-out-aware). Never\n        // fatal — the PR is already up by now, so a comment failure only warns.\n        this.postChecklistComment(repoRoot, result.prNumber, scan, review, provenance);\n\n        // The closing recap + the clickable-link directive, BOTH derived from the real merge outcome.\n        // Nothing here may hard-code success: a stranded PR under a green checkmark is how PRs got\n        // abandoned (see FinishBanner).\n        const bannerInput = new FinishBannerInput(result.prNumber, result.prUrl, title, base, result.merge);\n        process.stdout.write(this.banner.render(bannerInput));\n        process.stdout.write(this.banner.linkDirective(bannerInput));\n    }\n\n    // Validate + commit + finalize a 3-point merge the AI resolved, if one is in progress. Finalizing here\n    // does NOT push (pushRemote=false): this command pushes exactly ONCE, from GatedPrPublisher, and only\n    // after review.json + every BLOCK checklist + the build gate pass and the gated PR body is written.\n    /**\n     * The build gate — SKIPPED when stage ②'s receipt already covers this exact HEAD.\n     *\n     * The gate is authoritative per-COMMIT, not per-command: re-running it on a tree that has not moved\n     * since stage ② verified it buys nothing and costs a full `nx affected`. That skip is what makes the\n     * three-stage flow cost ONE build rather than two, and it is why moving the gate earlier was affordable.\n     */\n    private runOrSkipBuildGate(repoRoot: string, alreadyGreen: boolean): void {\n        if (alreadyGreen) {\n            process.stdout.write('\\n🛠️  Build gate: already green for this commit (stage ② receipt) — skipping the rebuild.\\n');\n            return;\n        }\n        this.buildAffected.runBuildGate(repoRoot, new BuildGateOptions(\n            '🛠️  Build gate (authoritative)', 'pnpm wp-finish-upsert-pr', 'Build failed — no PR created/updated.',\n        ));\n    }\n\n    /**\n     * The two stage-② preconditions, together: no unvalidated merge, and a receipt proving stage ② ran.\n     * Returns true when that receipt covers the CURRENT HEAD, i.e. the build gate can be skipped.\n     */\n    private assertStageTwoRan(repoRoot: string): boolean {\n        this.assertNoUnvalidatedMerge(repoRoot);\n        return this.assertReviewStageRan(\n            repoRoot, this.aiBranchName.getFeatureName(), this.gitOut(['rev-parse', 'HEAD']));\n    }\n\n    /**\n     * REFUSE while a 3-point merge is still unvalidated — do not finalize it here.\n     *\n     * This command used to do the finalizing itself. Finalizing means validating a conflict resolution, and\n     * two commands owning that means two implementations that can drift; `PrContextWriter`'s docstring\n     * records this codebase already paying for exactly that once. It also came too late to matter: by the\n     * time finish ran, the reviewers had already reviewed the pre-merge tree.\n     *\n     * So stage ② owns it, and finish only checks. Nothing is lost — the recovery is one command away, and\n     * running it also builds the merged tree and re-briefs the reviewers against it, which finalizing here\n     * never did.\n     */\n    private assertNoUnvalidatedMerge(repoRoot: string): void {\n        const home = this.mergeState.mergeDirFor(repoRoot, this.aiBranchName.getFeatureName());\n        const activeDir = this.mergeState.findActiveMergeRunDir(home);\n        const marker = activeDir ? this.mergeState.readMergeMarker(activeDir) : null;\n        if (!activeDir || !marker || marker.validated) return;\n        throw new InformAiError(\n            '⛔ NO PR — a 3-point merge on this branch is still unvalidated, so nothing here has been\\n' +\n            'verified: the conflict resolution is unchecked, the merged tree was never built, and any\\n' +\n            'reviewer that ran judged the PRE-merge code.\\n\\n' +\n            `Conflicted file(s): ${marker.conflictedFiles.join(', ')}\\n\\n` +\n            'Resolve them (see .webpieces/instruct-ai/webpieces.mergeprocess.md), then run:\\n' +\n            '  pnpm wp-review-upsert-pr\\n' +\n            'It validates the resolution, commits it, builds it, and re-briefs the reviewers.',\n        );\n    }\n\n    /**\n     * REQUIRE stage ② (`wp-review-upsert-pr`) to have run, and report whether it ran on THIS commit.\n     *\n     * Returns true when the receipt matches the current HEAD — the caller then skips its own build, because\n     * the receipt IS the gate for that sha and rebuilding an unchanged tree is a second full `nx affected`\n     * run for a foregone answer.\n     *\n     * Without this check a repo with NO checklists has nothing forcing stage ②: `assertEveryReviewerRan`\n     * is vacuous, and review.json — the only other interlock — is a file the AI writes itself. It could\n     * write it and come straight here, skipping the merge validation and the build entirely.\n     */\n    private assertReviewStageRan(repoRoot: string, featureName: string, headSha: string): boolean {\n        const receipt = this.receipts.read(repoRoot, featureName);\n        if (receipt === null) {\n            throw new InformAiError(\n                '⛔ NO PR — stage ② never ran on this branch. That means the 3-point merge is unvalidated,\\n' +\n                'the build gate has not run, no diff was extracted, and no reviewer was briefed.\\n\\n' +\n                'Run:  pnpm wp-review-upsert-pr\\n' +\n                '(then spawn the reviewers it names, write review.json, and re-run this command)',\n            );\n        }\n        if (receipt.headSha === headSha) return true;\n        // Not fatal. Re-reviewing on every follow-up commit would be intolerable, and most drift is a typo\n        // fix. But it is never silent: the build re-runs here, and the PR says the reviewers saw an older tree.\n        process.stderr.write(\n            `\\n⚠️  HEAD moved since stage ② ran (reviewed ${receipt.headSha.slice(0, 8)}, now ${headSha.slice(0, 8)}).\\n` +\n            '   The build gate will re-run, and the PR will record that reviewers judged an earlier tree.\\n' +\n            '   If the change was substantive, re-run pnpm wp-review-upsert-pr and re-spawn the reviewers.\\n\\n');\n        return false;\n    }\n\n    /**\n     * Refuse the PR while ANY applicable checklist still owes a verdict, naming exactly those reviewers and\n     * exactly what to tell them — via the same renderer `wp-review-upsert-pr` uses, so the AI sees the identical\n     * block it would have seen there. Lists ONLY the outstanding ones: re-instructing an already-reviewed\n     * checklist invites a redundant second run and reads as though the earlier verdict did not count.\n     * No-op for a repo with no applicable checklists.\n     */\n    private assertEveryReviewerRan(scan: ChecklistScan): void {\n        if (scan.outstanding.length === 0) return;\n        // Unreadable verdict files come FIRST. A reviewer that wrote its verdict in the removed `success`\n        // format is otherwise indistinguishable from one that never ran, and the AI would go re-run a\n        // subagent instead of correcting four characters of JSON.\n        const format = scan.formatErrors.length === 0\n            ? ''\n            : `${scan.formatErrors.length} verdict file(s) are in an UNREADABLE format:\\n\\n` +\n              scan.formatErrors.map((e: string): string => `  • ${e}`).join('\\n') + '\\n\\n';\n        throw new InformAiError(\n            `⛔ NO PR — ${scan.outstanding.length} of ${scan.applicable.length} review checklist(s) that apply to this ` +\n            `branch have no passing verdict yet: ${this.instructions.names(scan.outstanding)}\\n\\n` +\n            format +\n            `${this.instructions.render(scan.outstanding, scan.reviewPath, scan.context)}\\n\\n` +\n            `Then re-run: pnpm wp-finish-upsert-pr\\n` +\n            `(Each reviewer's generated instructions file is already written — re-running pnpm wp-review-upsert-pr\\n` +\n            ` is only needed if the code changed since it ran.)`,\n        );\n    }\n\n    private gitOut(args: string[]): string {\n        const result = spawnSync('git', args, { encoding: 'utf8' });\n        return result.status === 0 ? (result.stdout ?? '').trim() : '';\n    }\n\n    // The user-facing PR title: the AI-authored review.title, or — if omitted — a readable fallback\n    // derived from the stable feature name (NEVER the internal `Squash merge of <branch>` commit subject).\n    private prTitleFrom(review: ReviewJson): string {\n        if (review.title !== '') return review.title;\n        return this.aiBranchName.getFeatureName().replace(/[-/]+/g, ' ').trim();\n    }\n\n    // eslint-disable-next-line @typescript-eslint/max-params\n    private computeDashboardInput(repoRoot: string, buildPassed: boolean, review: ReviewJson, title: string, required: readonly RequiredChecklist[]): DashboardInput {\n        const config = loadAndValidate(repoRoot).prGate;\n        const forkPoint = this.gitOut(['merge-base', 'origin/main', 'HEAD']);\n        const featureHead = this.gitOut(['rev-parse', 'HEAD']);\n        const mainHead = this.gitOut(['rev-parse', 'origin/main']);\n        const range = `${forkPoint}..${featureHead}`;\n        const changedFiles = this.gitOut(['diff', range, '--name-only']).split('\\n').filter((f: string): boolean => f.trim() !== '');\n        const patch = this.gitOut(['diff', range]);\n\n        const gateResults = this.dashboard.computeGateResults(config.gates, changedFiles);\n        const disables = this.dashboard.countAddedDisables(patch);\n        const rows = this.checklistRows(required, review);\n        return new DashboardInput(title, gateResults, disables, buildPassed, forkPoint, featureHead, mainHead, review, rows);\n    }\n\n    // Pair each matched checklist with its resolved verdict for the dashboard. (A checklist reaching this\n    // point is always PASS/OVERRIDDEN — loadReviewJson already threw on FAIL/MISSING.)\n    private checklistRows(required: readonly RequiredChecklist[], review: ReviewJson): ChecklistRow[] {\n        return required.map((req: RequiredChecklist): ChecklistRow => {\n            const verdict = this.reviewJsonService.resolveVerdict(req, review.results);\n            return new ChecklistRow(req.id, verdict.status, verdict.detail);\n        });\n    }\n\n    /**\n     * One comment row per DEFINED checklist — matched or not — pairing the roster's match evidence with the\n     * resolved verdict. Built from `scan.roster` rather than from the applicable set: the skipped ones are\n     * absent from `applicable` by construction, and their \"why not\" evidence (the configured globs and the\n     * changed-file total) exists nowhere else without recomputing the diff a second way.\n     */\n    private commentRows(scan: ChecklistScan, review: ReviewJson, provenance: ProvenanceReport): ChecklistCommentRow[] {\n        // agentType -> did it open the diff. Absent ⇒ not assessed, which prints nothing (see ChecklistCommentRow.diffRead).\n        const readByAgent = new Map<string, boolean>();\n        for (const e of provenance.evidence) readByAgent.set(e.agentType, e.readDiff);\n        return scan.roster.entries.map((entry: TriggeredChecklist): ChecklistCommentRow => {\n            const ran = entry.matchedFiles.length > 0;\n            const req = new RequiredChecklist(\n                entry.def.id, entry.def.subagent, entry.def.doc, entry.matchedFiles, entry.matchedPatterns);\n            // A skipped checklist has no verdict to resolve — asking for one would report it as MISSING,\n            // i.e. as an unreviewed obligation, when in fact it never had one.\n            const verdict = ran\n                ? this.reviewJsonService.resolveVerdict(req, review.results)\n                : new ChecklistVerdict(entry.def.id, '', '');\n            const row = new ChecklistCommentRow(\n                entry.def.subagent, verdict.status, verdict.detail, ran,\n                entry.def.patterns, entry.matchedPatterns, entry.matchedFiles, scan.roster.changedFileCount);\n            const read = readByAgent.get(entry.def.subagent);\n            row.diffRead = read === undefined ? '' : (read ? 'yes' : 'no');\n            return row;\n        });\n    }\n\n    // Hidden HMAC gate-token marker (with a leading blank line) to append to the PR body, or '' when the\n    // repo sets no gateSalt (byte-identical body to before this feature). Bound to the pushed HEAD sha.\n    private gateTokenBody(gateSalt: string, headSha: string): string {\n        const marker = this.gateTokenService.gateTokenMarker(gateSalt, headSha);\n        return marker === '' ? '' : `\\n\\n${marker}\\n`;\n    }\n\n    // Enforce that EACH matched checklist was reviewed by its OWN named subagent, as a DISTINCT run —\n    // the coding agent may not self-certify, and one reviewer may not stand in for several. A verified set\n    // passes silently; no session id warns but passes; any missing reviewer throws so the PR does not open.\n    // eslint-disable-next-line @typescript-eslint/max-params\n    private enforceProvenance(required: readonly RequiredChecklist[], branch: string, repoRoot: string, config: PrGateConfig): ProvenanceReport {\n        const errors: string[] = [];\n        const report = new ProvenanceReport(true, []); // no reviewers to verify ⇒ vacuously verified\n        const subagents = required.map((r: RequiredChecklist): string => r.subagent.trim()).filter((s: string): boolean => s !== '');\n        if (subagents.length > 0) {\n            const result = this.provenance.verifyDistinct(subagents, branch);\n            report.verified = result.status === PROVENANCE_OK;\n            if (result.status === PROVENANCE_MISSING) {\n                errors.push(result.detail);\n            } else if (result.status === PROVENANCE_SKIPPED) {\n                process.stderr.write(`⚠️  ${result.detail}\\n`);\n            }\n            report.evidence = this.gatherEvidence(repoRoot, required, result, branch);\n            errors.push(...this.evidenceErrors(report.evidence, config));\n        }\n        if (errors.length > 0) {\n            throw new InformAiError(\n                `${errors.length} checklist(s) require an independent reviewer subagent that did not run — fix, then re-run pnpm wp-finish-upsert-pr:\\n\\n` +\n                errors.map((e: string): string => `  • ${e}`).join('\\n') +\n                `\\n\\nSpawn the named reviewer subagent to review the checklist on THIS branch, then re-run.`,\n            );\n        }\n        return report;\n    }\n\n    /**\n     * What each credited reviewer actually read. Purely observational here — {@link evidenceErrors} decides\n     * whether any of it blocks, and by default none of it does.\n     */\n    // eslint-disable-next-line @typescript-eslint/max-params\n    private gatherEvidence(repoRoot: string, required: readonly RequiredChecklist[], result: ProvenanceResult, branch: string): ReviewerEvidence[] {\n        const docPaths: Record<string, string> = {};\n        for (const req of required) {\n            if (req.subagent.trim() !== '') docPaths[req.subagent] = req.doc.trim() === '' ? '' : path.resolve(repoRoot, req.doc);\n        }\n        const diffDir = path.join(prDirFor(repoRoot, this.aiBranchName.getFeatureName()), 'diff');\n        return this.provenance.evidenceFor(new EvidenceRequest(branch, result.agentIds, diffDir, docPaths));\n    }\n\n    /**\n     * WARN (default) or REFUSE (opt-in) on a reviewer that wrote a verdict without opening the diff.\n     *\n     * Default-warn because the signal is derived from undocumented Claude Code transcript internals: if the\n     * format shifts, a blocking check wedges every PR in every consumer repo with no self-service recovery.\n     * `requireDiffEvidence` lets a repo that has watched the warning promote it deliberately.\n     */\n    private evidenceErrors(evidence: readonly ReviewerEvidence[], config: PrGateConfig): string[] {\n        const blind = evidence.filter((e: ReviewerEvidence): boolean => !e.readDiff);\n        if (blind.length === 0) return [];\n        const names = blind.map((e: ReviewerEvidence): string => e.agentType).join(', ');\n        if (!config.requireDiffEvidence) {\n            process.stderr.write(\n                `\\n⚠️  ${blind.length} reviewer(s) wrote a verdict with no record of opening the extracted diff: ${names}\\n` +\n                '   Published on the PR as a note. Not blocking — set pr-gate.requireDiffEvidence:true to make it one.\\n');\n            return [];\n        }\n        return [`these reviewers wrote a verdict without opening the diff (pr-gate.requireDiffEvidence is on): ${names}`];\n    }\n\n    /**\n     * Publish the roster + every reviewer's full `output` as ONE combined PR comment, idempotently (find the\n     * marker comment → PATCH it, else POST). Never fatal: by here the PR is already created/updated, so a\n     * `gh` failure only warns.\n     *\n     * Posted on EVERY run of a repo that defines checklists — including one where nothing matched, because\n     * \"all five were evaluated and none applied\" is the good news the old comment could not deliver. The\n     * guard is `scan.defined.length`, deliberately NOT the number of rows that ran: a repo with no\n     * checklists configured must still see no comment at all (see ChecklistNotice / renderDashboard).\n     */\n    // eslint-disable-next-line @typescript-eslint/max-params\n    // eslint-disable-next-line @typescript-eslint/max-params\n    private postChecklistComment(repoRoot: string, prNumber: string, scan: ChecklistScan, review: ReviewJson, provenance: ProvenanceReport): void {\n        if (prNumber === '' || scan.defined.length === 0) return;\n        if (!loadAndValidate(repoRoot).prGate.checklistComments) return;\n        const body = this.dashboard.renderChecklistComment(\n            this.commentRows(scan, review, provenance), provenance.verified, scan.roster.baseResolved);\n        const prDir = prDirFor(repoRoot, this.aiBranchName.getFeatureName());\n        fs.mkdirSync(prDir, { recursive: true });\n        const payload = path.join(prDir, 'checklist-comment.json');\n        fs.writeFileSync(payload, JSON.stringify({ body }));\n        const commentId = this.findChecklistCommentId(prNumber);\n        const args = commentId !== ''\n            ? ['api', '--method', 'PATCH', `repos/{owner}/{repo}/issues/comments/${commentId}`, '--input', payload]\n            : ['api', '--method', 'POST', `repos/{owner}/{repo}/issues/${prNumber}/comments`, '--input', payload];\n        const res = spawnSync('gh', args, { encoding: 'utf8' });\n        if (res.status !== 0) {\n            process.stderr.write('⚠️  Could not post the checklist review comment (non-fatal — the PR is already up).\\n');\n        } else {\n            process.stdout.write(`   ${commentId !== '' ? 'updated' : 'posted'} the checklist review comment ✓\\n`);\n        }\n    }\n\n    // The id of THIS tool's existing checklist comment on the PR (by the hidden marker), or '' if none.\n    private findChecklistCommentId(prNumber: string): string {\n        const res = spawnSync('gh', [\n            'api', '--paginate', `repos/{owner}/{repo}/issues/${prNumber}/comments`,\n            '--jq', `.[] | select(.body | contains(\"${CHECKLIST_COMMENT_MARKER}\")) | .id`,\n        ], { encoding: 'utf8' });\n        if (res.status !== 0) return '';\n        return (res.stdout ?? '').trim().split('\\n')[0] ?? '';\n    }\n\n    // The PR, the remote branch, and the local branch all share the one stable feature name. Look up /\n    // create / merge against `baseBranch` (baseBranchName tolerates a leftover `…wpN` mid-transition).\n    // GatedPrPublisher owns the edit/push/create half and its ORDERING — the gated body goes up before\n    // the push, so CI's `synchronize` read cannot see the previous run's token.\n    private upsertPr(repoRoot: string, baseBranch: string, body: string, title: string, input: DashboardInput): UpsertResult {\n        const prDir = prDirFor(repoRoot, this.aiBranchName.getFeatureName());\n        fs.mkdirSync(prDir, { recursive: true });\n        const bodyFile = path.join(prDir, 'pr-body.md');\n        fs.writeFileSync(bodyFile, body + '\\n');\n\n        const published = this.publisher.publish(baseBranch, title, bodyFile);\n        if (published.createFailed) {\n            process.stderr.write('⚠️  gh pr create failed — create the PR manually with the body in:\\n  ' + bodyFile + '\\n');\n            return new UpsertResult('', '', new MergeOutcome(false, false,\n                '⚠️  did NOT merge — there is no PR to merge (gh pr create failed above)', MERGE_RESULT_FAILED));\n        }\n        const num = published.number;\n\n        // Set the squash-merge SUBJECT to the PR title (+ the `(#N)` GitHub normally appends, which an\n        // explicit --subject would otherwise drop) and the BODY to the compact commit summary, so main's\n        // history carries the PR title + risk/flags/link — NOT the internal `Squash merge of <branch>`\n        // subject GitHub would inherit from the single squash commit on the branch.\n        const ref = this.prRef(baseBranch);\n        const subject = ref.number !== '' ? `${title} (#${ref.number})` : title;\n        const mergeBodyFile = path.join(prDir, 'merge-commit-body.md');\n        fs.writeFileSync(mergeBodyFile, this.dashboard.renderCommitBody(input, ref.url) + '\\n');\n        // PrMerger owns the direct-merge / auto-merge-fallback decision AND checks every gh status, so a\n        // merge that did not happen is reported as such instead of being swallowed (see pr-merger.ts).\n        // REQUIRED config — no default here on purpose. A missing value (an older published\n        // rules-config that has no such field) reaches PrMerger as '' and is treated as \"do not merge\".\n        const mergeMode = loadAndValidate(repoRoot).prGate.mergeMode ?? '';\n        const outcome = this.prMerger.merge(baseBranch, subject, mergeBodyFile, mergeMode);\n        return new UpsertResult(ref.number !== '' ? ref.number : num, ref.url, outcome);\n    }\n\n    // The PR's number + web URL (for the merge subject `(#N)` and the commit-body back-link). Both ''\n    // if it can't be resolved. Rendered via jq into one tab-separated line so no JSON parsing is needed.\n    private prRef(baseBranch: string): PrRef {\n        const result = spawnSync(\n            'gh', ['pr', 'view', baseBranch, '--json', 'number,url', '--jq', '\"\\\\(.number)\\\\t\\\\(.url)\"'],\n            { encoding: 'utf8' },\n        );\n        if (result.status !== 0) {\n            return new PrRef('', '');\n        }\n        const parts = (result.stdout ?? '').trim().split('\\t');\n        return new PrRef(parts[0] ?? '', parts[1] ?? '');\n    }\n}\n"]}
+{"version":3,"file":"finish-upsert-pr-command.js","sourceRoot":"","sources":["../../../../../../../packages/tooling/pr-gate/src/scripts/commands/finish-upsert-pr-command.ts"],"names":[],"mappings":"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","sourcesContent":["import { execSync, spawnSync } from 'child_process';\nimport * as fs from 'fs';\nimport * as path from 'path';\nimport {\n    loadAndValidate, prDirFor, reviewJsonPath, ReviewJson, RequiredChecklist, ChecklistVerdict,\n    writeTemplate, RepoRootFinder, ReviewJsonService,\n    GateTokenService, SubagentProvenanceService, PROVENANCE_OK, PROVENANCE_MISSING, PROVENANCE_SKIPPED,\n    ProvenanceResult, ReviewerEvidence, EvidenceRequest, PrGateConfig,\n    ChecklistInstructionsService, InformAiError, toError,\n} from '@webpieces/rules-config';\nimport { injectable, bindingScopeValues } from 'inversify';\nimport { AiBranchName } from '../workflow/git-readAiBranchName';\nimport { BranchNaming } from '../workflow/branch-naming';\nimport { ChecklistScan, ChecklistScanOptions, ChecklistScanner } from '../workflow/checklist-scanner';\nimport { GitExec } from '../workflow/git-exec';\nimport { BuildAffected, BuildGateOptions } from '../workflow/build-affected';\nimport { MergeState } from '../workflow/merge-state';\nimport { ReviewStageReceiptService } from '../workflow/review-stage-receipt';\nimport { PrMerger, MergeOutcome, MERGE_RESULT_FAILED } from '../workflow/pr-merger';\nimport { FinishBanner, FinishBannerInput } from '../workflow/finish-banner';\nimport { GatedPrPublisher } from '../workflow/gated-pr-publisher';\nimport { TriggeredChecklist } from '../workflow/checklist-detector';\nimport {\n    Dashboard, DashboardInput, ChecklistRow, ChecklistCommentRow, CHECKLIST_COMMENT_MARKER,\n} from '../../dashboard/dashboard';\n\nconst SEP = '━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━\\n';\n\n/**\n * The provenance outcome: whether each reviewer was VERIFIED to have run (the integrity check, which\n * blocks) plus what each one actually read (the quality signal, which is published). Data-only.\n */\nclass ProvenanceReport {\n    verified: boolean;\n    evidence: ReviewerEvidence[];\n\n    constructor(verified: boolean, evidence: ReviewerEvidence[]) {\n        this.verified = verified;\n        this.evidence = evidence;\n    }\n}\n\n// A resolved PR's number + web URL. Both '' when the PR can't be resolved (e.g. create failed).\nclass PrRef {\n    number: string;\n    url: string;\n\n    constructor(number: string, url: string) {\n        this.number = number;\n        this.url = url;\n    }\n}\n\n// The outcome of the whole upsert: the PR number + web URL ('' each when unresolved) plus what actually\n// happened to the merge, so the final summary reports the REAL result rather than assuming success. The\n// URL is carried so the closing block can hand the AI a clickable link to relay to the user verbatim.\nclass UpsertResult {\n    prNumber: string;\n    prUrl: string;\n    merge: MergeOutcome;\n\n    constructor(prNumber: string, prUrl: string, merge: MergeOutcome) {\n        this.prNumber = prNumber;\n        this.prUrl = prUrl;\n        this.merge = merge;\n    }\n}\n\n// STAGE ③ — FINISH of the AI-first PR flow, and the ONLY command that posts PRs. Runs after\n// `wp-review-upsert-pr` verified the branch and the AI spawned the reviewers + wrote review.json.\n//\n// In order: (1) REFUSE on an unvalidated 3-point merge and REQUIRE stage ②'s receipt; (2) REQUIRE\n// review.json + every reviewer's verdict + provenance; (3) run the build gate UNLESS the receipt already\n// covers this exact HEAD; (4) render the dashboard; (5) create/update the PR via `gh`.\n//\n// It no longer FINALIZES a merge — stage ② does. Two commands owning conflict-resolution validation is two\n// implementations that drift, and finalizing here came too late to help anyway: the reviewers had already\n// reviewed the pre-merge tree by then.\n@injectable(bindingScopeValues.Singleton)\nexport class FinishUpsertPrCommand {\n    constructor(\n        private readonly repoRootFinder: RepoRootFinder,\n        private readonly aiBranchName: AiBranchName,\n        private readonly branchNaming: BranchNaming,\n        private readonly gitExec: GitExec,\n        private readonly buildAffected: BuildAffected,\n        private readonly mergeState: MergeState,\n        private readonly prMerger: PrMerger,\n        private readonly publisher: GatedPrPublisher,\n        private readonly dashboard: Dashboard,\n        private readonly checklistScanner: ChecklistScanner,\n        private readonly reviewJsonService: ReviewJsonService,\n        private readonly gateTokenService: GateTokenService,\n        private readonly provenance: SubagentProvenanceService,\n        private readonly instructions: ChecklistInstructionsService,\n        private readonly receipts: ReviewStageReceiptService,\n        private readonly banner: FinishBanner,\n    ) {}\n\n    async run(): Promise<void> {\n        const repoRoot = this.repoRootFinder.resolveRepoRoot(process.cwd());\n        // Refresh the AI-facing workflow doc so it's present + current for any failure message to cite.\n        writeTemplate(repoRoot, 'webpieces.git-workflow.md');\n        // 1. REQUIRE stage ② — see assertStageTwoRan. Returns true when its receipt covers THIS commit,\n        //    which is what lets the build gate below be skipped rather than re-run for a foregone answer.\n        const buildAlreadyGreen = this.assertStageTwoRan(repoRoot);\n\n        // 2. REQUIRE the AI-authored review.json (throws InformAiError with the schema if missing/invalid).\n        //    Compute the consumer checklists this diff triggered FIRST so an unacknowledged BLOCK throws\n        //    here — BEFORE any `gh pr create` — matching the guarantee buildCommand already provides.\n        // The SAME scan wp-review-upsert-pr runs, with filterAlreadyReviewed:true so `outstanding` is exactly what\n        // still owes a verdict (Z of N of X). Sharing the computation is the point: the command that REPORTS\n        // and the command that GATES must not be able to disagree about what is owed. review-<id>.json files\n        // persist locally, so a re-run re-validates the EXISTING verdicts against the (possibly changed)\n        // applicable set for free — an unchanged checklist needs no re-review, a newly-applicable one refuses\n        // until its file is written.\n        const featureName = this.aiBranchName.getFeatureName();\n        const scan = this.checklistScanner.scan(repoRoot, loadAndValidate(repoRoot).prGate.checklists, new ChecklistScanOptions(true, 'stage3-finish'));\n        const required = scan.applicable;\n        // FAIL FAST on missing reviewers, BEFORE review.json is parsed and before the build gate runs. A\n        // missing reviewer is not a review.json defect (folding it in made the AI fix the wrong thing), and\n        // nobody should wait on a build to be told a reviewer never ran.\n        this.assertEveryReviewerRan(scan);\n        const review = this.reviewJsonService.loadReviewJson(reviewJsonPath(repoRoot, featureName), required);\n\n        // 2c. For any BLOCK checklist that names a reviewer `subagent`, VERIFY (from the harness's own\n        //     artifacts) that such a subagent actually ran on this branch — the coding agent may not\n        //     self-certify. Absent CLAUDE_CODE_SESSION_ID this skips with a warning (CI / plain terminal).\n        const currentBranch = execSync('git branch --show-current', { encoding: 'utf8' }).trim();\n        const provenance = this.enforceProvenance(required, currentBranch, repoRoot, loadAndValidate(repoRoot).prGate);\n\n        // 2b. The build gate validates the WORKING TREE but we push HEAD — so they MUST be identical.\n        this.gitExec.assertCleanTree(repoRoot);\n\n        // 3. Build gate, then post the gated body, then push (that ORDER — see GatedPrPublisher).\n        this.runOrSkipBuildGate(repoRoot, buildAlreadyGreen);\n        const base = this.branchNaming.baseBranchName(execSync('git branch --show-current', { encoding: 'utf8' }).trim());\n\n        process.stdout.write('\\n' + SEP + '📋 Dashboard + PR\\n' + SEP + '\\n');\n        const title = this.prTitleFrom(review);\n        const input = this.computeDashboardInput(repoRoot, true, review, title, required);\n        // Append the hidden HMAC gate token bound to the LOCAL HEAD sha — computed BEFORE the push, because\n        // GatedPrPublisher writes the body first so CI's `synchronize` read can never see a stale token. A\n        // valid token in the PR body is proof this gated flow ran + passed on this exact commit, which CI\n        // (`wp-check-pr`) recomputes. We reach here only after the build gate + every BLOCK checklist\n        // passed, so minting is legitimate. Nothing about HMAC(salt, HEAD) needs the remote to have it.\n        const gateSalt = loadAndValidate(repoRoot).prGate.gateSalt;\n        const headSha = this.gitOut(['rev-parse', 'HEAD']);\n        const body = this.dashboard.renderDashboard(input) + this.gateTokenBody(gateSalt, headSha);\n        const result = this.upsertPr(repoRoot, base, body, title, input);\n        // Publish each reviewer's full output as ONE combined PR comment (idempotent, opt-out-aware). Never\n        // fatal — the PR is already up by now, so a comment failure only warns.\n        this.postChecklistComment(repoRoot, result.prNumber, scan, review, provenance);\n        this.archiveConsumedReview(repoRoot, featureName, result);\n\n        // The closing recap + the clickable-link directive, BOTH derived from the real merge outcome.\n        // Nothing here may hard-code success: a stranded PR under a green checkmark is how PRs got\n        // abandoned (see FinishBanner).\n        const bannerInput = new FinishBannerInput(result.prNumber, result.prUrl, title, base, result.merge);\n        process.stdout.write(this.banner.render(bannerInput));\n        process.stdout.write(this.banner.linkDirective(bannerInput));\n    }\n\n    // Validate + commit + finalize a 3-point merge the AI resolved, if one is in progress. Finalizing here\n    // does NOT push (pushRemote=false): this command pushes exactly ONCE, from GatedPrPublisher, and only\n    // after review.json + every BLOCK checklist + the build gate pass and the gated PR body is written.\n    /**\n     * The build gate — SKIPPED when stage ②'s receipt already covers this exact HEAD.\n     *\n     * The gate is authoritative per-COMMIT, not per-command: re-running it on a tree that has not moved\n     * since stage ② verified it buys nothing and costs a full `nx affected`. That skip is what makes the\n     * three-stage flow cost ONE build rather than two, and it is why moving the gate earlier was affordable.\n     */\n    private runOrSkipBuildGate(repoRoot: string, alreadyGreen: boolean): void {\n        if (alreadyGreen) {\n            process.stdout.write('\\n🛠️  Build gate: already green for this commit (stage ② receipt) — skipping the rebuild.\\n');\n            return;\n        }\n        this.buildAffected.runBuildGate(repoRoot, new BuildGateOptions(\n            '🛠️  Build gate (authoritative)', 'pnpm wp-finish-upsert-pr', 'Build failed — no PR created/updated.',\n        ));\n    }\n\n    /**\n     * The two stage-② preconditions, together: no unvalidated merge, and a receipt proving stage ② ran.\n     * Returns true when that receipt covers the CURRENT HEAD, i.e. the build gate can be skipped.\n     */\n    private assertStageTwoRan(repoRoot: string): boolean {\n        this.assertNoUnvalidatedMerge(repoRoot);\n        return this.assertReviewStageRan(\n            repoRoot, this.aiBranchName.getFeatureName(), this.gitOut(['rev-parse', 'HEAD']));\n    }\n\n    /**\n     * REFUSE while a 3-point merge is still unvalidated — do not finalize it here.\n     *\n     * This command used to do the finalizing itself. Finalizing means validating a conflict resolution, and\n     * two commands owning that means two implementations that can drift; `PrContextWriter`'s docstring\n     * records this codebase already paying for exactly that once. It also came too late to matter: by the\n     * time finish ran, the reviewers had already reviewed the pre-merge tree.\n     *\n     * So stage ② owns it, and finish only checks. Nothing is lost — the recovery is one command away, and\n     * running it also builds the merged tree and re-briefs the reviewers against it, which finalizing here\n     * never did.\n     */\n    private assertNoUnvalidatedMerge(repoRoot: string): void {\n        const home = this.mergeState.mergeDirFor(repoRoot, this.aiBranchName.getFeatureName());\n        const activeDir = this.mergeState.findActiveMergeRunDir(home);\n        const marker = activeDir ? this.mergeState.readMergeMarker(activeDir) : null;\n        if (!activeDir || !marker || marker.validated) return;\n        throw new InformAiError(\n            '⛔ NO PR — a 3-point merge on this branch is still unvalidated, so nothing here has been\\n' +\n            'verified: the conflict resolution is unchecked, the merged tree was never built, and any\\n' +\n            'reviewer that ran judged the PRE-merge code.\\n\\n' +\n            `Conflicted file(s): ${marker.conflictedFiles.join(', ')}\\n\\n` +\n            'Resolve them (see .webpieces/instruct-ai/webpieces.mergeprocess.md), then run:\\n' +\n            '  pnpm wp-review-upsert-pr\\n' +\n            'It validates the resolution, commits it, builds it, and re-briefs the reviewers.',\n        );\n    }\n\n    /**\n     * REQUIRE stage ② (`wp-review-upsert-pr`) to have run, and report whether it ran on THIS commit.\n     *\n     * Returns true when the receipt matches the current HEAD — the caller then skips its own build, because\n     * the receipt IS the gate for that sha and rebuilding an unchanged tree is a second full `nx affected`\n     * run for a foregone answer.\n     *\n     * Without this check a repo with NO checklists has nothing forcing stage ②: `assertEveryReviewerRan`\n     * is vacuous, and review.json — the only other interlock — is a file the AI writes itself. It could\n     * write it and come straight here, skipping the merge validation and the build entirely.\n     */\n    private assertReviewStageRan(repoRoot: string, featureName: string, headSha: string): boolean {\n        const receipt = this.receipts.read(repoRoot, featureName);\n        if (receipt === null) {\n            throw new InformAiError(\n                '⛔ NO PR — stage ② never ran on this branch. That means the 3-point merge is unvalidated,\\n' +\n                'the build gate has not run, no diff was extracted, and no reviewer was briefed.\\n\\n' +\n                'Run:  pnpm wp-review-upsert-pr\\n' +\n                '(then spawn the reviewers it names, write review.json, and re-run this command)',\n            );\n        }\n        if (receipt.headSha === headSha) return true;\n        // Not fatal. Re-reviewing on every follow-up commit would be intolerable, and most drift is a typo\n        // fix. But it is never silent: the build re-runs here, and the PR says the reviewers saw an older tree.\n        process.stderr.write(\n            `\\n⚠️  HEAD moved since stage ② ran (reviewed ${receipt.headSha.slice(0, 8)}, now ${headSha.slice(0, 8)}).\\n` +\n            '   The build gate will re-run, and the PR will record that reviewers judged an earlier tree.\\n' +\n            '   If the change was substantive, re-run pnpm wp-review-upsert-pr and re-spawn the reviewers.\\n\\n');\n        return false;\n    }\n\n    /**\n     * Refuse the PR while ANY applicable checklist still owes a verdict, naming exactly those reviewers and\n     * exactly what to tell them — via the same renderer `wp-review-upsert-pr` uses, so the AI sees the identical\n     * block it would have seen there. Lists ONLY the outstanding ones: re-instructing an already-reviewed\n     * checklist invites a redundant second run and reads as though the earlier verdict did not count.\n     * No-op for a repo with no applicable checklists.\n     */\n    private assertEveryReviewerRan(scan: ChecklistScan): void {\n        if (scan.outstanding.length === 0) return;\n        // Unreadable verdict files come FIRST. A reviewer that wrote its verdict in the removed `success`\n        // format is otherwise indistinguishable from one that never ran, and the AI would go re-run a\n        // subagent instead of correcting four characters of JSON.\n        const format = scan.formatErrors.length === 0\n            ? ''\n            : `${scan.formatErrors.length} verdict file(s) are in an UNREADABLE format:\\n\\n` +\n              scan.formatErrors.map((e: string): string => `  • ${e}`).join('\\n') + '\\n\\n';\n        throw new InformAiError(\n            `⛔ NO PR — ${scan.outstanding.length} of ${scan.applicable.length} review checklist(s) that apply to this ` +\n            `branch have no passing verdict yet: ${this.instructions.names(scan.outstanding)}\\n\\n` +\n            format +\n            `${this.instructions.render(scan.outstanding, scan.reviewPath, scan.context)}\\n\\n` +\n            `Then re-run: pnpm wp-finish-upsert-pr\\n` +\n            `(Each reviewer's generated instructions file is already written — re-running pnpm wp-review-upsert-pr\\n` +\n            ` is only needed if the code changed since it ran.)`,\n        );\n    }\n\n    /**\n     * Retire the review this run just used — move review.json to old-review.json beside it, stamped as\n     * audit-only (see ReviewJsonService.archiveReviewJson).\n     *\n     * WHY it moves rather than staying put: review.json left behind is a live-looking file describing a\n     * review that has already shipped, and the next `wp-review-upsert-pr` on this branch finds it sitting\n     * there. A reviewer subagent that judges the PR's stated INTENT — its title, summary or risk level —\n     * then reads the previous round's review and can return GREEN against a title that no longer exists,\n     * with nothing in the verdict distinguishing that from a real pass. Moving it makes the only route back\n     * to this command a freshly-written review.\n     *\n     * ONLY on a PR that actually went up. A run that died before publishing must stay re-runnable without\n     * making the AI rewrite a review that was never used, and prNumber === '' is exactly that case.\n     * Non-fatal: the PR is live by here, so an unwritable archive warns rather than failing the command.\n     */\n    private archiveConsumedReview(repoRoot: string, featureName: string, result: UpsertResult): void {\n        if (result.prNumber === '') return;\n        // webpieces-disable no-unmanaged-exceptions -- chokepoint: the PR is already up; a failed archive must not fail the command\n        // eslint-disable-next-line @webpieces/no-unmanaged-exceptions\n        try {\n            const archived = this.reviewJsonService.archiveReviewJson(reviewJsonPath(repoRoot, featureName));\n            if (archived !== '') process.stdout.write(`   archived this run's review.json → ${archived} (audit only) ✓\\n`);\n        } catch (err: unknown) {\n            const error = toError(err);\n            process.stderr.write(`⚠️  Could not archive review.json (non-fatal — the PR is already up): ${error.message}\\n`);\n        }\n    }\n\n    private gitOut(args: string[]): string {\n        const result = spawnSync('git', args, { encoding: 'utf8' });\n        return result.status === 0 ? (result.stdout ?? '').trim() : '';\n    }\n\n    // The user-facing PR title: the AI-authored review.title, or — if omitted — a readable fallback\n    // derived from the stable feature name (NEVER the internal `Squash merge of <branch>` commit subject).\n    private prTitleFrom(review: ReviewJson): string {\n        if (review.title !== '') return review.title;\n        return this.aiBranchName.getFeatureName().replace(/[-/]+/g, ' ').trim();\n    }\n\n    // eslint-disable-next-line @typescript-eslint/max-params\n    private computeDashboardInput(repoRoot: string, buildPassed: boolean, review: ReviewJson, title: string, required: readonly RequiredChecklist[]): DashboardInput {\n        const config = loadAndValidate(repoRoot).prGate;\n        const forkPoint = this.gitOut(['merge-base', 'origin/main', 'HEAD']);\n        const featureHead = this.gitOut(['rev-parse', 'HEAD']);\n        const mainHead = this.gitOut(['rev-parse', 'origin/main']);\n        const range = `${forkPoint}..${featureHead}`;\n        const changedFiles = this.gitOut(['diff', range, '--name-only']).split('\\n').filter((f: string): boolean => f.trim() !== '');\n        const patch = this.gitOut(['diff', range]);\n\n        const gateResults = this.dashboard.computeGateResults(config.gates, changedFiles);\n        const disables = this.dashboard.countAddedDisables(patch);\n        const rows = this.checklistRows(required, review);\n        return new DashboardInput(title, gateResults, disables, buildPassed, forkPoint, featureHead, mainHead, review, rows);\n    }\n\n    // Pair each matched checklist with its resolved verdict for the dashboard. (A checklist reaching this\n    // point is always PASS/OVERRIDDEN — loadReviewJson already threw on FAIL/MISSING.)\n    private checklistRows(required: readonly RequiredChecklist[], review: ReviewJson): ChecklistRow[] {\n        return required.map((req: RequiredChecklist): ChecklistRow => {\n            const verdict = this.reviewJsonService.resolveVerdict(req, review.results);\n            return new ChecklistRow(req.id, verdict.status, verdict.detail);\n        });\n    }\n\n    /**\n     * One comment row per DEFINED checklist — matched or not — pairing the roster's match evidence with the\n     * resolved verdict. Built from `scan.roster` rather than from the applicable set: the skipped ones are\n     * absent from `applicable` by construction, and their \"why not\" evidence (the configured globs and the\n     * changed-file total) exists nowhere else without recomputing the diff a second way.\n     */\n    private commentRows(scan: ChecklistScan, review: ReviewJson, provenance: ProvenanceReport): ChecklistCommentRow[] {\n        // agentType -> did it open the diff. Absent ⇒ not assessed, which prints nothing (see ChecklistCommentRow.diffRead).\n        const readByAgent = new Map<string, boolean>();\n        for (const e of provenance.evidence) readByAgent.set(e.agentType, e.readDiff);\n        return scan.roster.entries.map((entry: TriggeredChecklist): ChecklistCommentRow => {\n            const ran = entry.matchedFiles.length > 0;\n            const req = new RequiredChecklist(\n                entry.def.id, entry.def.subagent, entry.def.doc, entry.matchedFiles, entry.matchedPatterns);\n            // A skipped checklist has no verdict to resolve — asking for one would report it as MISSING,\n            // i.e. as an unreviewed obligation, when in fact it never had one.\n            const verdict = ran\n                ? this.reviewJsonService.resolveVerdict(req, review.results)\n                : new ChecklistVerdict(entry.def.id, '', '');\n            const row = new ChecklistCommentRow(\n                entry.def.subagent, verdict.status, verdict.detail, ran,\n                entry.def.patterns, entry.matchedPatterns, entry.matchedFiles, scan.roster.changedFileCount);\n            const read = readByAgent.get(entry.def.subagent);\n            row.diffRead = read === undefined ? '' : (read ? 'yes' : 'no');\n            return row;\n        });\n    }\n\n    // Hidden HMAC gate-token marker (with a leading blank line) to append to the PR body, or '' when the\n    // repo sets no gateSalt (byte-identical body to before this feature). Bound to the pushed HEAD sha.\n    private gateTokenBody(gateSalt: string, headSha: string): string {\n        const marker = this.gateTokenService.gateTokenMarker(gateSalt, headSha);\n        return marker === '' ? '' : `\\n\\n${marker}\\n`;\n    }\n\n    // Enforce that EACH matched checklist was reviewed by its OWN named subagent, as a DISTINCT run —\n    // the coding agent may not self-certify, and one reviewer may not stand in for several. A verified set\n    // passes silently; no session id warns but passes; any missing reviewer throws so the PR does not open.\n    // eslint-disable-next-line @typescript-eslint/max-params\n    private enforceProvenance(required: readonly RequiredChecklist[], branch: string, repoRoot: string, config: PrGateConfig): ProvenanceReport {\n        const errors: string[] = [];\n        const report = new ProvenanceReport(true, []); // no reviewers to verify ⇒ vacuously verified\n        const subagents = required.map((r: RequiredChecklist): string => r.subagent.trim()).filter((s: string): boolean => s !== '');\n        if (subagents.length > 0) {\n            const result = this.provenance.verifyDistinct(subagents, branch);\n            report.verified = result.status === PROVENANCE_OK;\n            if (result.status === PROVENANCE_MISSING) {\n                errors.push(result.detail);\n            } else if (result.status === PROVENANCE_SKIPPED) {\n                process.stderr.write(`⚠️  ${result.detail}\\n`);\n            }\n            report.evidence = this.gatherEvidence(repoRoot, required, result, branch);\n            errors.push(...this.evidenceErrors(report.evidence, config));\n        }\n        if (errors.length > 0) {\n            throw new InformAiError(\n                `${errors.length} checklist(s) require an independent reviewer subagent that did not run — fix, then re-run pnpm wp-finish-upsert-pr:\\n\\n` +\n                errors.map((e: string): string => `  • ${e}`).join('\\n') +\n                `\\n\\nSpawn the named reviewer subagent to review the checklist on THIS branch, then re-run.`,\n            );\n        }\n        return report;\n    }\n\n    /**\n     * What each credited reviewer actually read. Purely observational here — {@link evidenceErrors} decides\n     * whether any of it blocks, and by default none of it does.\n     */\n    // eslint-disable-next-line @typescript-eslint/max-params\n    private gatherEvidence(repoRoot: string, required: readonly RequiredChecklist[], result: ProvenanceResult, branch: string): ReviewerEvidence[] {\n        const docPaths: Record<string, string> = {};\n        for (const req of required) {\n            if (req.subagent.trim() !== '') docPaths[req.subagent] = req.doc.trim() === '' ? '' : path.resolve(repoRoot, req.doc);\n        }\n        const diffDir = path.join(prDirFor(repoRoot, this.aiBranchName.getFeatureName()), 'diff');\n        return this.provenance.evidenceFor(new EvidenceRequest(branch, result.agentIds, diffDir, docPaths));\n    }\n\n    /**\n     * WARN (default) or REFUSE (opt-in) on a reviewer that wrote a verdict without opening the diff.\n     *\n     * Default-warn because the signal is derived from undocumented Claude Code transcript internals: if the\n     * format shifts, a blocking check wedges every PR in every consumer repo with no self-service recovery.\n     * `requireDiffEvidence` lets a repo that has watched the warning promote it deliberately.\n     */\n    private evidenceErrors(evidence: readonly ReviewerEvidence[], config: PrGateConfig): string[] {\n        const blind = evidence.filter((e: ReviewerEvidence): boolean => !e.readDiff);\n        if (blind.length === 0) return [];\n        const names = blind.map((e: ReviewerEvidence): string => e.agentType).join(', ');\n        if (!config.requireDiffEvidence) {\n            process.stderr.write(\n                `\\n⚠️  ${blind.length} reviewer(s) wrote a verdict with no record of opening the extracted diff: ${names}\\n` +\n                '   Published on the PR as a note. Not blocking — set pr-gate.requireDiffEvidence:true to make it one.\\n');\n            return [];\n        }\n        return [`these reviewers wrote a verdict without opening the diff (pr-gate.requireDiffEvidence is on): ${names}`];\n    }\n\n    /**\n     * Publish the roster + every reviewer's full `output` as ONE combined PR comment, idempotently (find the\n     * marker comment → PATCH it, else POST). Never fatal: by here the PR is already created/updated, so a\n     * `gh` failure only warns.\n     *\n     * Posted on EVERY run of a repo that defines checklists — including one where nothing matched, because\n     * \"all five were evaluated and none applied\" is the good news the old comment could not deliver. The\n     * guard is `scan.defined.length`, deliberately NOT the number of rows that ran: a repo with no\n     * checklists configured must still see no comment at all (see ChecklistNotice / renderDashboard).\n     */\n    // eslint-disable-next-line @typescript-eslint/max-params\n    // eslint-disable-next-line @typescript-eslint/max-params\n    private postChecklistComment(repoRoot: string, prNumber: string, scan: ChecklistScan, review: ReviewJson, provenance: ProvenanceReport): void {\n        if (prNumber === '' || scan.defined.length === 0) return;\n        if (!loadAndValidate(repoRoot).prGate.checklistComments) return;\n        const body = this.dashboard.renderChecklistComment(\n            this.commentRows(scan, review, provenance), provenance.verified, scan.roster.baseResolved);\n        const prDir = prDirFor(repoRoot, this.aiBranchName.getFeatureName());\n        fs.mkdirSync(prDir, { recursive: true });\n        const payload = path.join(prDir, 'checklist-comment.json');\n        fs.writeFileSync(payload, JSON.stringify({ body }));\n        const commentId = this.findChecklistCommentId(prNumber);\n        const args = commentId !== ''\n            ? ['api', '--method', 'PATCH', `repos/{owner}/{repo}/issues/comments/${commentId}`, '--input', payload]\n            : ['api', '--method', 'POST', `repos/{owner}/{repo}/issues/${prNumber}/comments`, '--input', payload];\n        const res = spawnSync('gh', args, { encoding: 'utf8' });\n        if (res.status !== 0) {\n            process.stderr.write('⚠️  Could not post the checklist review comment (non-fatal — the PR is already up).\\n');\n        } else {\n            process.stdout.write(`   ${commentId !== '' ? 'updated' : 'posted'} the checklist review comment ✓\\n`);\n        }\n    }\n\n    // The id of THIS tool's existing checklist comment on the PR (by the hidden marker), or '' if none.\n    private findChecklistCommentId(prNumber: string): string {\n        const res = spawnSync('gh', [\n            'api', '--paginate', `repos/{owner}/{repo}/issues/${prNumber}/comments`,\n            '--jq', `.[] | select(.body | contains(\"${CHECKLIST_COMMENT_MARKER}\")) | .id`,\n        ], { encoding: 'utf8' });\n        if (res.status !== 0) return '';\n        return (res.stdout ?? '').trim().split('\\n')[0] ?? '';\n    }\n\n    // The PR, the remote branch, and the local branch all share the one stable feature name. Look up /\n    // create / merge against `baseBranch` (baseBranchName tolerates a leftover `…wpN` mid-transition).\n    // GatedPrPublisher owns the edit/push/create half and its ORDERING — the gated body goes up before\n    // the push, so CI's `synchronize` read cannot see the previous run's token.\n    private upsertPr(repoRoot: string, baseBranch: string, body: string, title: string, input: DashboardInput): UpsertResult {\n        const prDir = prDirFor(repoRoot, this.aiBranchName.getFeatureName());\n        fs.mkdirSync(prDir, { recursive: true });\n        const bodyFile = path.join(prDir, 'pr-body.md');\n        fs.writeFileSync(bodyFile, body + '\\n');\n\n        const published = this.publisher.publish(baseBranch, title, bodyFile);\n        if (published.createFailed) {\n            process.stderr.write('⚠️  gh pr create failed — create the PR manually with the body in:\\n  ' + bodyFile + '\\n');\n            return new UpsertResult('', '', new MergeOutcome(false, false,\n                '⚠️  did NOT merge — there is no PR to merge (gh pr create failed above)', MERGE_RESULT_FAILED));\n        }\n        const num = published.number;\n\n        // Set the squash-merge SUBJECT to the PR title (+ the `(#N)` GitHub normally appends, which an\n        // explicit --subject would otherwise drop) and the BODY to the compact commit summary, so main's\n        // history carries the PR title + risk/flags/link — NOT the internal `Squash merge of <branch>`\n        // subject GitHub would inherit from the single squash commit on the branch.\n        const ref = this.prRef(baseBranch);\n        const subject = ref.number !== '' ? `${title} (#${ref.number})` : title;\n        const mergeBodyFile = path.join(prDir, 'merge-commit-body.md');\n        fs.writeFileSync(mergeBodyFile, this.dashboard.renderCommitBody(input, ref.url) + '\\n');\n        // PrMerger owns the direct-merge / auto-merge-fallback decision AND checks every gh status, so a\n        // merge that did not happen is reported as such instead of being swallowed (see pr-merger.ts).\n        // REQUIRED config — no default here on purpose. A missing value (an older published\n        // rules-config that has no such field) reaches PrMerger as '' and is treated as \"do not merge\".\n        const mergeMode = loadAndValidate(repoRoot).prGate.mergeMode ?? '';\n        const outcome = this.prMerger.merge(baseBranch, subject, mergeBodyFile, mergeMode);\n        return new UpsertResult(ref.number !== '' ? ref.number : num, ref.url, outcome);\n    }\n\n    // The PR's number + web URL (for the merge subject `(#N)` and the commit-body back-link). Both ''\n    // if it can't be resolved. Rendered via jq into one tab-separated line so no JSON parsing is needed.\n    private prRef(baseBranch: string): PrRef {\n        const result = spawnSync(\n            'gh', ['pr', 'view', baseBranch, '--json', 'number,url', '--jq', '\"\\\\(.number)\\\\t\\\\(.url)\"'],\n            { encoding: 'utf8' },\n        );\n        if (result.status !== 0) {\n            return new PrRef('', '');\n        }\n        const parts = (result.stdout ?? '').trim().split('\\t');\n        return new PrRef(parts[0] ?? '', parts[1] ?? '');\n    }\n}\n"]}

package/src/scripts/workflow/finish-banner.d.ts

@@ -25,8 +25,27 @@ export declare class FinishBanner {
     render(input: FinishBannerInput): string;
     isDone(merge: MergeOutcome): boolean;
     private header;
+    private behindHeader;
     private whatIsOwed;
+    /**
+     * The BEHIND follow-up. Two rules govern every word here.
+     *
+     * FIRST: the remedy is the FULL ①②③, never a shortcut. `gh pr update-branch` looks like the obvious
+     * one-command fix and is a trap — it rewrites the REMOTE branch while every fork-point consumer
+     * (`ForkPoint.resolveForkPoint`, `nx affected --base=$(git merge-base ...)`, the review diff) computes
+     * against the LOCAL HEAD. That splits reality in two: stage ③ force-pushes local over the remote and
+     * silently reverts it, the recorded hash points describe a tree that is no longer the PR head, and the
+     * rebased tree never passes a build gate. Only ① moves the fork point AND records it; only ② rebuilds
+     * and re-receipts against the new one.
+     *
+     * SECOND: it ASKS, it does not order. An imperative command list is what turns an agent into a loop —
+     * it complies, main moves again, it complies again. Asking forces a stop at a human, which is the only
+     * thing that reliably terminates a race we cannot win by retrying.
+     */
     private behindRemedy;
+    private behindSituation;
+    private behindAsk;
+    private behindAskClose;
     private doneNote;
     /**
      * The closing AI directive: the resolved PR's number/title/URL and an instruction to end the

package/src/scripts/workflow/finish-banner.js

@@ -67,37 +67,109 @@ let FinishBanner = class FinishBanner {
         if (merge.result === pr_merger_1.MERGE_RESULT_LEFT_TO_HUMAN) {
             return '✅ PR finished — posted for a human to merge (that is this repo\'s policy)\n';
         }
-        if (merge.result === pr_merger_1.MERGE_RESULT_BEHIND) {
-            return '⛔ PR NOT FINISHED — the branch is BEHIND main and will NEVER merge on its own\n';
-        }
+        // NOT "PR NOT FINISHED". Everything this command owns SUCCEEDED — the branch is pushed, the body
+        // is written, the build gate is green. What happened is that another author landed on main
+        // between our fetch and our push. Reporting that as the author's failure sent agents off
+        // re-auditing their own diff and hunting build flakes for a race they did not cause.
+        if (merge.isBehind())
+            return this.behindHeader(merge);
         return '⚠️  PR NOT FINISHED — the PR is up, but the merge did NOT happen\n';
     }
+    behindHeader(merge) {
+        if (merge.result === pr_merger_1.MERGE_RESULT_BEHIND_CONFLICTING) {
+            return '⏸️  PR IS UP AND GREEN — someone landed on main first, and it CONFLICTS with your work\n';
+        }
+        if (merge.result === pr_merger_1.MERGE_RESULT_BEHIND_UNKNOWN) {
+            return '⏸️  PR IS UP AND GREEN — GitHub has not finished computing mergeability yet\n';
+        }
+        return '⏸️  PR IS UP AND GREEN — someone landed on main first (no conflicts with your work)\n';
+    }
     // The follow-up block. '' for a done outcome — a finished run should not invent chores.
     whatIsOwed(input) {
         if (this.isDone(input.merge))
             return this.doneNote(input.merge);
-        if (input.merge.result === pr_merger_1.MERGE_RESULT_BEHIND)
+        if (input.merge.isBehind())
             return this.behindRemedy(input);
         return '\n' + SEP +
             '   ⚠️  DO NOT report this PR as done. The merge failed for the reason in step 4 above.\n' +
             '       Fix that, then re-run:  pnpm wp-finish-upsert-pr\n' +
             `   Confirm for yourself:  gh pr view ${input.prNumber === '' ? '<n>' : input.prNumber} --json mergeable,mergeStateStatus,state\n`;
     }
-    // The ONE remedy that actually clears BEHIND. wp-start-upsert-pr is what re-syncs from main (3-point
-    // merge); finishing again re-runs the gate and re-attempts the merge on an up-to-date branch.
+    /**
+     * The BEHIND follow-up. Two rules govern every word here.
+     *
+     * FIRST: the remedy is the FULL ①②③, never a shortcut. `gh pr update-branch` looks like the obvious
+     * one-command fix and is a trap — it rewrites the REMOTE branch while every fork-point consumer
+     * (`ForkPoint.resolveForkPoint`, `nx affected --base=$(git merge-base ...)`, the review diff) computes
+     * against the LOCAL HEAD. That splits reality in two: stage ③ force-pushes local over the remote and
+     * silently reverts it, the recorded hash points describe a tree that is no longer the PR head, and the
+     * rebased tree never passes a build gate. Only ① moves the fork point AND records it; only ② rebuilds
+     * and re-receipts against the new one.
+     *
+     * SECOND: it ASKS, it does not order. An imperative command list is what turns an agent into a loop —
+     * it complies, main moves again, it complies again. Asking forces a stop at a human, which is the only
+     * thing that reliably terminates a race we cannot win by retrying.
+     */
     behindRemedy(input) {
         const num = input.prNumber === '' ? '<n>' : input.prNumber;
-        return '\n' + SEP +
-            '   ⛔ DO NOT WALK AWAY — this PR is STRANDED, not pending.\n\n' +
-            '   BEHIND means the head branch is out of date with main. Auto-merge does NOT update\n' +
-            '   branches, so unlike a BLOCKED (checks-running) PR this one never resolves itself. Main\n' +
-            '   moved while you worked; re-sync and finish again, from THIS worktree:\n\n' +
-            '       pnpm wp-start-upsert-pr     # 3-point merge from main — this is what clears BEHIND\n' +
-            '       pnpm wp-finish-upsert-pr    # build gate + gated body + merge, now up to date\n\n' +
-            '   (If the re-sync conflicts, wp-start-upsert-pr walks you through resolving it.)\n' +
+        return '\n' + SEP + this.behindSituation(input.merge) + '\n' +
+            '   ⚠️  STOP HERE AND ASK THE HUMAN. Do NOT run these yourself — if main keeps moving,\n' +
+            '       running them on your own is an infinite loop with a full build inside it.\n\n' +
+            '   Ask, in your own words:\n' +
+            `       "${this.behindAsk(input.merge)}\n` +
+            `        ${this.behindAskClose(input.merge)}"\n\n` +
+            '   Only once they say yes:\n\n' +
+            '       pnpm wp-start-upsert-pr     # 3-point merge from main — re-forks onto the new main\n' +
+            '       pnpm wp-review-upsert-pr    # re-validates the merge + REBUILDS on the new fork point\n' +
+            '       pnpm wp-finish-upsert-pr    # gated body + merge, now up to date\n\n' +
+            '   Do NOT skip ②. It is the only stage that validates the new merge and rebuilds against\n' +
+            '   the new fork point; skipping it publishes a PR whose tree was never gated.\n' +
+            '   Do NOT reach for `gh pr update-branch`. It rewrites the REMOTE branch only, which stage\n' +
+            '   ③ then force-pushes over — and it lands a tree no build gate ever saw.\n' +
             `   Verify independently, do not trust this banner:\n` +
             `       gh pr view ${num} --json mergeable,mergeStateStatus,state\n`;
     }
+    // What is actually true right now, per kind. The CLEAN case gets the caveat that it may not even
+    // matter: "out of date" only blocks a merge on repos that require branches be up to date.
+    behindSituation(merge) {
+        if (merge.result === pr_merger_1.MERGE_RESULT_BEHIND_CONFLICTING) {
+            return '   Your PR is pushed, its body is written, and the build gate passed. Then someone\n' +
+                '   else landed on main, and their change CONFLICTS with yours — same lines. Real\n' +
+                '   resolution is owed, and if people keep landing ahead of you it genuinely repeats.\n' +
+                '   That is inherent to concurrent editing, not a bug and not something you did wrong.\n';
+        }
+        if (merge.result === pr_merger_1.MERGE_RESULT_BEHIND_UNKNOWN) {
+            return '   Your PR is pushed, its body is written, and the build gate passed. GitHub has not\n' +
+                '   finished computing mergeability yet (it is asynchronous, and we asked seconds after\n' +
+                '   the push), so we do NOT know whether this conflicts. Re-check before doing anything:\n' +
+                '   a few seconds later the answer is usually CLEAN and no work is owed at all.\n';
+        }
+        return '   Your PR is pushed, its body is written, and the build gate passed. Someone else simply\n' +
+            '   landed on main first. There are NO conflicts — nobody touched your lines.\n' +
+            '   This may not even matter: "out of date" blocks a merge only on repos that REQUIRE\n' +
+            '   branches be up to date. If yours does not, this PR can merge as-is.\n';
+    }
+    // The one sentence to put to the human, in their terms.
+    behindAsk(merge) {
+        if (merge.result === pr_merger_1.MERGE_RESULT_BEHIND_CONFLICTING) {
+            return 'Someone beat me to landing on main and there are conflicts. We MUST run a\n' +
+                '        3-point merge so I can resolve them properly.';
+        }
+        if (merge.result === pr_merger_1.MERGE_RESULT_BEHIND_UNKNOWN) {
+            return 'Someone beat me to landing on main. GitHub has not said yet whether it\n' +
+                '        conflicts, so I have not touched anything.';
+        }
+        return 'Someone beat me to landing on main. There are no conflicts, so this is just\n' +
+            '        a re-sync — but it costs a full rebuild.';
+    }
+    // The actual question. UNKNOWN gets a DIFFERENT one: with mergeability still uncomputed, proposing a
+    // full re-run is proposing work we cannot yet show is needed — a re-check is free and often ends it.
+    behindAskClose(merge) {
+        if (merge.result === pr_merger_1.MERGE_RESULT_BEHIND_UNKNOWN) {
+            return 'Shall I re-check in a moment, or start the wp-*-upsert-pr process over?';
+        }
+        return 'May I start the wp-*-upsert-pr process over again?';
+    }
     // A short, positive "you are free to stop" line for the two non-merged-but-fine outcomes, so an AI
     // reading a queued PR does not go hunting for work that is not owed.
     doneNote(merge) {
@@ -125,15 +197,28 @@ let FinishBanner = class FinishBanner {
         const label = this.isDone(input.merge) ? input.title : `${input.title} — ${this.notDoneTag(input.merge)}`;
         const preamble = this.isDone(input.merge)
             ? ''
-            : `AI — this PR is NOT done (${this.notDoneTag(input.merge)}). Your summary MUST say so plainly and\n` +
-                `MUST include the remedy commands printed above. Do not describe this run as complete.\n\n`;
+            : `AI — this PR is NOT done (${this.notDoneTag(input.merge)}). Your summary MUST say so plainly.\n` +
+                (input.merge.isBehind()
+                    ? `MUST END BY ASKING the human for permission to re-run the flow, and MUST NOT run any of\n` +
+                        `the commands above until they answer. Say plainly that nothing they did caused this —\n` +
+                        `another author landed on main first — and that the PR itself is pushed and gate-green.\n\n`
+                    : `MUST include the remedy commands printed above. Do not describe this run as complete.\n\n`);
         return SEP + `🔗 PR #${input.prNumber}: ${input.title}\n   ${input.prUrl}\n\n` + SEP + preamble +
             `AI — the LAST line of your summary to the user MUST be EXACTLY this clickable link, with\n` +
             `NOTHING printed after it (no sign-off, no next steps, no blank commentary):\n\n` +
             `   [#${input.prNumber} ${label}](${input.prUrl})\n\n`;
     }
+    // The tag rides INSIDE the clickable link, which the directive above forces to be the last line the
+    // AI prints — so it is the one piece of wording guaranteed to reach the user. It says who is waiting
+    // on whom: for every BEHIND flavour the answer is "a human", not "more automation".
     notDoneTag(merge) {
-        return merge.result === pr_merger_1.MERGE_RESULT_BEHIND ? 'NOT MERGED — BEHIND main, needs a re-sync' : 'NOT MERGED';
+        if (merge.result === pr_merger_1.MERGE_RESULT_BEHIND_CONFLICTING)
+            return 'NOT MERGED — main moved and it conflicts, needs your OK to re-sync';
+        if (merge.result === pr_merger_1.MERGE_RESULT_BEHIND_UNKNOWN)
+            return 'NOT MERGED — main moved, GitHub still computing mergeability';
+        if (merge.isBehind())
+            return 'NOT MERGED — main moved (no conflicts), needs your OK to re-sync';
+        return 'NOT MERGED';
     }
 };
 exports.FinishBanner = FinishBanner;

package/src/scripts/workflow/finish-banner.js.map

@@ -1 +1 @@
-{"version":3,"file":"finish-banner.js","sourceRoot":"","sources":["../../../../../../../packages/tooling/pr-gate/src/scripts/workflow/finish-banner.ts"],"names":[],"mappings":"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","sourcesContent":["import { injectable, bindingScopeValues } from 'inversify';\nimport {\n    MergeOutcome, MERGE_RESULT_MERGED, MERGE_RESULT_AUTO_QUEUED, MERGE_RESULT_LEFT_TO_HUMAN,\n    MERGE_RESULT_BEHIND,\n} from './pr-merger';\n\nconst SEP = '━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━\\n';\n\n// Everything the closing block of wp-finish-upsert-pr needs to describe what actually happened. Both\n// `prNumber` and `prUrl` are '' when the PR could not be resolved (e.g. `gh pr create` failed).\nexport class FinishBannerInput {\n    prNumber: string;\n    prUrl: string;\n    title: string;\n    base: string;\n    merge: MergeOutcome;\n\n    // eslint-disable-next-line @typescript-eslint/max-params\n    constructor(prNumber: string, prUrl: string, title: string, base: string, merge: MergeOutcome) {\n        this.prNumber = prNumber;\n        this.prUrl = prUrl;\n        this.title = title;\n        this.base = base;\n        this.merge = merge;\n    }\n}\n\n/**\n * Renders the closing block of `wp-finish-upsert-pr` — and it is the FRAME, not the merge message, that\n * this class exists to get right.\n *\n * PrMerger has long been honest in its `message`. The banner around it was not: it printed a hard-coded\n * `✅ PR finished` on every path, so a run whose merge failed still looked like a completed one at a\n * glance. The worst case is `mergeStateStatus: BEHIND` — unlike BLOCKED (waiting on checks), which\n * auto-merge resolves on its own, a BEHIND branch NEVER lands. Under a green checkmark, agents walked\n * away from stranded PRs. Three of them independently reported the output as untrustworthy.\n *\n * So the header is derived from `MergeOutcome.result`, and a not-done outcome is loud, distinct, and\n * carries the exact commands that fix it — including in the clickable-link directive, whose whole job\n * is to be the last thing the AI says.\n */\n@injectable(bindingScopeValues.Singleton)\nexport class FinishBanner {\n    // The full closing recap: header keyed to the real outcome, the four things this command did, and —\n    // when the PR is not done — what must happen next.\n    render(input: FinishBannerInput): string {\n        const prNum = input.prNumber;\n        return '\\n' + SEP + this.header(input.merge) + SEP + '\\n' +\n            `   1. validated the build gate (authoritative)\\n` +\n            `   2. ${prNum ? `wrote the gated body to PR #${prNum}` : 'composed the gated PR body'} titled: \"${input.title}\"\\n` +\n            `   3. force-pushed your work to origin/${input.base} (after the body, so CI reads the right token)\\n` +\n            `   4. ${input.merge.message}\\n` +\n            `   You are on  ${input.base}  — same name as the remote branch and the PR head.\\n` +\n            this.whatIsOwed(input) + '\\n';\n    }\n\n    // TRUE only for the outcomes where nothing further is owed: merged, queued behind green-able checks,\n    // or deliberately left for a human. Everything else — BEHIND, config mismatch, gh failure, no PR —\n    // is unfinished work, and the banner must not decorate it with a checkmark.\n    isDone(merge: MergeOutcome): boolean {\n        return merge.result === MERGE_RESULT_MERGED\n            || merge.result === MERGE_RESULT_AUTO_QUEUED\n            || merge.result === MERGE_RESULT_LEFT_TO_HUMAN;\n    }\n\n    private header(merge: MergeOutcome): string {\n        if (merge.result === MERGE_RESULT_MERGED) return '✅ PR finished AND MERGED — here is exactly what I did\\n';\n        if (merge.result === MERGE_RESULT_AUTO_QUEUED) {\n            return '✅ PR finished — auto-merge is ON; it lands itself when the checks pass\\n';\n        }\n        if (merge.result === MERGE_RESULT_LEFT_TO_HUMAN) {\n            return '✅ PR finished — posted for a human to merge (that is this repo\\'s policy)\\n';\n        }\n        if (merge.result === MERGE_RESULT_BEHIND) {\n            return '⛔ PR NOT FINISHED — the branch is BEHIND main and will NEVER merge on its own\\n';\n        }\n        return '⚠️  PR NOT FINISHED — the PR is up, but the merge did NOT happen\\n';\n    }\n\n    // The follow-up block. '' for a done outcome — a finished run should not invent chores.\n    private whatIsOwed(input: FinishBannerInput): string {\n        if (this.isDone(input.merge)) return this.doneNote(input.merge);\n        if (input.merge.result === MERGE_RESULT_BEHIND) return this.behindRemedy(input);\n        return '\\n' + SEP +\n            '   ⚠️  DO NOT report this PR as done. The merge failed for the reason in step 4 above.\\n' +\n            '       Fix that, then re-run:  pnpm wp-finish-upsert-pr\\n' +\n            `   Confirm for yourself:  gh pr view ${input.prNumber === '' ? '<n>' : input.prNumber} --json mergeable,mergeStateStatus,state\\n`;\n    }\n\n    // The ONE remedy that actually clears BEHIND. wp-start-upsert-pr is what re-syncs from main (3-point\n    // merge); finishing again re-runs the gate and re-attempts the merge on an up-to-date branch.\n    private behindRemedy(input: FinishBannerInput): string {\n        const num = input.prNumber === '' ? '<n>' : input.prNumber;\n        return '\\n' + SEP +\n            '   ⛔ DO NOT WALK AWAY — this PR is STRANDED, not pending.\\n\\n' +\n            '   BEHIND means the head branch is out of date with main. Auto-merge does NOT update\\n' +\n            '   branches, so unlike a BLOCKED (checks-running) PR this one never resolves itself. Main\\n' +\n            '   moved while you worked; re-sync and finish again, from THIS worktree:\\n\\n' +\n            '       pnpm wp-start-upsert-pr     # 3-point merge from main — this is what clears BEHIND\\n' +\n            '       pnpm wp-finish-upsert-pr    # build gate + gated body + merge, now up to date\\n\\n' +\n            '   (If the re-sync conflicts, wp-start-upsert-pr walks you through resolving it.)\\n' +\n            `   Verify independently, do not trust this banner:\\n` +\n            `       gh pr view ${num} --json mergeable,mergeStateStatus,state\\n`;\n    }\n\n    // A short, positive \"you are free to stop\" line for the two non-merged-but-fine outcomes, so an AI\n    // reading a queued PR does not go hunting for work that is not owed.\n    private doneNote(merge: MergeOutcome): string {\n        if (merge.result === MERGE_RESULT_AUTO_QUEUED) {\n            return '   Nothing else is owed: GitHub lands it when the checks go green. You can stop here.\\n';\n        }\n        if (merge.result === MERGE_RESULT_LEFT_TO_HUMAN) {\n            return '   Nothing else is owed by the tooling — a person merges it. You can stop here.\\n';\n        }\n        return '';\n    }\n\n    /**\n     * The closing AI directive: the resolved PR's number/title/URL and an instruction to end the\n     * user-facing summary with EXACTLY `[#N title](url)` as the final line, nothing after it.\n     *\n     * The link text CARRIES the outcome. Ending on a bare cheerful link is exactly how a stranded PR got\n     * reported as finished, and the directive says the link must be last — so the truth has to live\n     * inside the link itself, not merely above it.\n     *\n     * '' when the PR could not be resolved: better to say nothing than to point at a link that is not real.\n     */\n    linkDirective(input: FinishBannerInput): string {\n        if (input.prNumber === '' || input.prUrl === '') return '';\n        const label = this.isDone(input.merge) ? input.title : `${input.title} — ${this.notDoneTag(input.merge)}`;\n        const preamble = this.isDone(input.merge)\n            ? ''\n            : `AI — this PR is NOT done (${this.notDoneTag(input.merge)}). Your summary MUST say so plainly and\\n` +\n              `MUST include the remedy commands printed above. Do not describe this run as complete.\\n\\n`;\n        return SEP + `🔗 PR #${input.prNumber}: ${input.title}\\n   ${input.prUrl}\\n\\n` + SEP + preamble +\n            `AI — the LAST line of your summary to the user MUST be EXACTLY this clickable link, with\\n` +\n            `NOTHING printed after it (no sign-off, no next steps, no blank commentary):\\n\\n` +\n            `   [#${input.prNumber} ${label}](${input.prUrl})\\n\\n`;\n    }\n\n    private notDoneTag(merge: MergeOutcome): string {\n        return merge.result === MERGE_RESULT_BEHIND ? 'NOT MERGED — BEHIND main, needs a re-sync' : 'NOT MERGED';\n    }\n}\n"]}
+{"version":3,"file":"finish-banner.js","sourceRoot":"","sources":["../../../../../../../packages/tooling/pr-gate/src/scripts/workflow/finish-banner.ts"],"names":[],"mappings":";;;;AAAA,yCAA2D;AAC3D,2CAGqB;AAErB,MAAM,GAAG,GAAG,0DAA0D,CAAC;AAEvE,qGAAqG;AACrG,gGAAgG;AAChG,MAAa,iBAAiB;IAC1B,QAAQ,CAAS;IACjB,KAAK,CAAS;IACd,KAAK,CAAS;IACd,IAAI,CAAS;IACb,KAAK,CAAe;IAEpB,yDAAyD;IACzD,YAAY,QAAgB,EAAE,KAAa,EAAE,KAAa,EAAE,IAAY,EAAE,KAAmB;QACzF,IAAI,CAAC,QAAQ,GAAG,QAAQ,CAAC;QACzB,IAAI,CAAC,KAAK,GAAG,KAAK,CAAC;QACnB,IAAI,CAAC,KAAK,GAAG,KAAK,CAAC;QACnB,IAAI,CAAC,IAAI,GAAG,IAAI,CAAC;QACjB,IAAI,CAAC,KAAK,GAAG,KAAK,CAAC;IACvB,CAAC;CACJ;AAfD,8CAeC;AAED;;;;;;;;;;;;;GAaG;AAEI,IAAM,YAAY,GAAlB,MAAM,YAAY;IACrB,oGAAoG;IACpG,mDAAmD;IACnD,MAAM,CAAC,KAAwB;QAC3B,MAAM,KAAK,GAAG,KAAK,CAAC,QAAQ,CAAC;QAC7B,OAAO,IAAI,GAAG,GAAG,GAAG,IAAI,CAAC,MAAM,CAAC,KAAK,CAAC,KAAK,CAAC,GAAG,GAAG,GAAG,IAAI;YACrD,kDAAkD;YAClD,SAAS,KAAK,CAAC,CAAC,CAAC,+BAA+B,KAAK,EAAE,CAAC,CAAC,CAAC,4BAA4B,aAAa,KAAK,CAAC,KAAK,KAAK;YACnH,0CAA0C,KAAK,CAAC,IAAI,kDAAkD;YACtG,SAAS,KAAK,CAAC,KAAK,CAAC,OAAO,IAAI;YAChC,kBAAkB,KAAK,CAAC,IAAI,uDAAuD;YACnF,IAAI,CAAC,UAAU,CAAC,KAAK,CAAC,GAAG,IAAI,CAAC;IACtC,CAAC;IAED,qGAAqG;IACrG,mGAAmG;IACnG,4EAA4E;IAC5E,MAAM,CAAC,KAAmB;QACtB,OAAO,KAAK,CAAC,MAAM,KAAK,+BAAmB;eACpC,KAAK,CAAC,MAAM,KAAK,oCAAwB;eACzC,KAAK,CAAC,MAAM,KAAK,sCAA0B,CAAC;IACvD,CAAC;IAEO,MAAM,CAAC,KAAmB;QAC9B,IAAI,KAAK,CAAC,MAAM,KAAK,+BAAmB;YAAE,OAAO,yDAAyD,CAAC;QAC3G,IAAI,KAAK,CAAC,MAAM,KAAK,oCAAwB,EAAE,CAAC;YAC5C,OAAO,0EAA0E,CAAC;QACtF,CAAC;QACD,IAAI,KAAK,CAAC,MAAM,KAAK,sCAA0B,EAAE,CAAC;YAC9C,OAAO,6EAA6E,CAAC;QACzF,CAAC;QACD,iGAAiG;QACjG,2FAA2F;QAC3F,yFAAyF;QACzF,qFAAqF;QACrF,IAAI,KAAK,CAAC,QAAQ,EAAE;YAAE,OAAO,IAAI,CAAC,YAAY,CAAC,KAAK,CAAC,CAAC;QACtD,OAAO,oEAAoE,CAAC;IAChF,CAAC;IAEO,YAAY,CAAC,KAAmB;QACpC,IAAI,KAAK,CAAC,MAAM,KAAK,2CAA+B,EAAE,CAAC;YACnD,OAAO,0FAA0F,CAAC;QACtG,CAAC;QACD,IAAI,KAAK,CAAC,MAAM,KAAK,uCAA2B,EAAE,CAAC;YAC/C,OAAO,+EAA+E,CAAC;QAC3F,CAAC;QACD,OAAO,uFAAuF,CAAC;IACnG,CAAC;IAED,wFAAwF;IAChF,UAAU,CAAC,KAAwB;QACvC,IAAI,IAAI,CAAC,MAAM,CAAC,KAAK,CAAC,KAAK,CAAC;YAAE,OAAO,IAAI,CAAC,QAAQ,CAAC,KAAK,CAAC,KAAK,CAAC,CAAC;QAChE,IAAI,KAAK,CAAC,KAAK,CAAC,QAAQ,EAAE;YAAE,OAAO,IAAI,CAAC,YAAY,CAAC,KAAK,CAAC,CAAC;QAC5D,OAAO,IAAI,GAAG,GAAG;YACb,0FAA0F;YAC1F,2DAA2D;YAC3D,wCAAwC,KAAK,CAAC,QAAQ,KAAK,EAAE,CAAC,CAAC,CAAC,KAAK,CAAC,CAAC,CAAC,KAAK,CAAC,QAAQ,4CAA4C,CAAC;IAC3I,CAAC;IAED;;;;;;;;;;;;;;OAcG;IACK,YAAY,CAAC,KAAwB;QACzC,MAAM,GAAG,GAAG,KAAK,CAAC,QAAQ,KAAK,EAAE,CAAC,CAAC,CAAC,KAAK,CAAC,CAAC,CAAC,KAAK,CAAC,QAAQ,CAAC;QAC3D,OAAO,IAAI,GAAG,GAAG,GAAG,IAAI,CAAC,eAAe,CAAC,KAAK,CAAC,KAAK,CAAC,GAAG,IAAI;YACxD,yFAAyF;YACzF,sFAAsF;YACtF,8BAA8B;YAC9B,WAAW,IAAI,CAAC,SAAS,CAAC,KAAK,CAAC,KAAK,CAAC,IAAI;YAC1C,WAAW,IAAI,CAAC,cAAc,CAAC,KAAK,CAAC,KAAK,CAAC,OAAO;YAClD,gCAAgC;YAChC,6FAA6F;YAC7F,gGAAgG;YAChG,6EAA6E;YAC7E,4FAA4F;YAC5F,iFAAiF;YACjF,8FAA8F;YAC9F,6EAA6E;YAC7E,sDAAsD;YACtD,qBAAqB,GAAG,4CAA4C,CAAC;IAC7E,CAAC;IAED,iGAAiG;IACjG,0FAA0F;IAClF,eAAe,CAAC,KAAmB;QACvC,IAAI,KAAK,CAAC,MAAM,KAAK,2CAA+B,EAAE,CAAC;YACnD,OAAO,sFAAsF;gBACzF,oFAAoF;gBACpF,wFAAwF;gBACxF,yFAAyF,CAAC;QAClG,CAAC;QACD,IAAI,KAAK,CAAC,MAAM,KAAK,uCAA2B,EAAE,CAAC;YAC/C,OAAO,wFAAwF;gBAC3F,0FAA0F;gBAC1F,2FAA2F;gBAC3F,kFAAkF,CAAC;QAC3F,CAAC;QACD,OAAO,6FAA6F;YAChG,gFAAgF;YAChF,wFAAwF;YACxF,0EAA0E,CAAC;IACnF,CAAC;IAED,wDAAwD;IAChD,SAAS,CAAC,KAAmB;QACjC,IAAI,KAAK,CAAC,MAAM,KAAK,2CAA+B,EAAE,CAAC;YACnD,OAAO,6EAA6E;gBAChF,uDAAuD,CAAC;QAChE,CAAC;QACD,IAAI,KAAK,CAAC,MAAM,KAAK,uCAA2B,EAAE,CAAC;YAC/C,OAAO,0EAA0E;gBAC7E,oDAAoD,CAAC;QAC7D,CAAC;QACD,OAAO,+EAA+E;YAClF,kDAAkD,CAAC;IAC3D,CAAC;IAED,qGAAqG;IACrG,qGAAqG;IAC7F,cAAc,CAAC,KAAmB;QACtC,IAAI,KAAK,CAAC,MAAM,KAAK,uCAA2B,EAAE,CAAC;YAC/C,OAAO,yEAAyE,CAAC;QACrF,CAAC;QACD,OAAO,oDAAoD,CAAC;IAChE,CAAC;IAED,mGAAmG;IACnG,qEAAqE;IAC7D,QAAQ,CAAC,KAAmB;QAChC,IAAI,KAAK,CAAC,MAAM,KAAK,oCAAwB,EAAE,CAAC;YAC5C,OAAO,yFAAyF,CAAC;QACrG,CAAC;QACD,IAAI,KAAK,CAAC,MAAM,KAAK,sCAA0B,EAAE,CAAC;YAC9C,OAAO,mFAAmF,CAAC;QAC/F,CAAC;QACD,OAAO,EAAE,CAAC;IACd,CAAC;IAED;;;;;;;;;OASG;IACH,aAAa,CAAC,KAAwB;QAClC,IAAI,KAAK,CAAC,QAAQ,KAAK,EAAE,IAAI,KAAK,CAAC,KAAK,KAAK,EAAE;YAAE,OAAO,EAAE,CAAC;QAC3D,MAAM,KAAK,GAAG,IAAI,CAAC,MAAM,CAAC,KAAK,CAAC,KAAK,CAAC,CAAC,CAAC,CAAC,KAAK,CAAC,KAAK,CAAC,CAAC,CAAC,GAAG,KAAK,CAAC,KAAK,MAAM,IAAI,CAAC,UAAU,CAAC,KAAK,CAAC,KAAK,CAAC,EAAE,CAAC;QAC1G,MAAM,QAAQ,GAAG,IAAI,CAAC,MAAM,CAAC,KAAK,CAAC,KAAK,CAAC;YACrC,CAAC,CAAC,EAAE;YACJ,CAAC,CAAC,6BAA6B,IAAI,CAAC,UAAU,CAAC,KAAK,CAAC,KAAK,CAAC,wCAAwC;gBACjG,CAAC,KAAK,CAAC,KAAK,CAAC,QAAQ,EAAE;oBACnB,CAAC,CAAC,2FAA2F;wBAC3F,yFAAyF;wBACzF,4FAA4F;oBAC9F,CAAC,CAAC,2FAA2F,CAAC,CAAC;QACzG,OAAO,GAAG,GAAG,UAAU,KAAK,CAAC,QAAQ,KAAK,KAAK,CAAC,KAAK,QAAQ,KAAK,CAAC,KAAK,MAAM,GAAG,GAAG,GAAG,QAAQ;YAC3F,4FAA4F;YAC5F,iFAAiF;YACjF,QAAQ,KAAK,CAAC,QAAQ,IAAI,KAAK,KAAK,KAAK,CAAC,KAAK,OAAO,CAAC;IAC/D,CAAC;IAED,oGAAoG;IACpG,qGAAqG;IACrG,oFAAoF;IAC5E,UAAU,CAAC,KAAmB;QAClC,IAAI,KAAK,CAAC,MAAM,KAAK,2CAA+B;YAAE,OAAO,oEAAoE,CAAC;QAClI,IAAI,KAAK,CAAC,MAAM,KAAK,uCAA2B;YAAE,OAAO,8DAA8D,CAAC;QACxH,IAAI,KAAK,CAAC,QAAQ,EAAE;YAAE,OAAO,kEAAkE,CAAC;QAChG,OAAO,YAAY,CAAC;IACxB,CAAC;CACJ,CAAA;AA1LY,oCAAY;uBAAZ,YAAY;IADxB,IAAA,sBAAU,EAAC,8BAAkB,CAAC,SAAS,CAAC;GAC5B,YAAY,CA0LxB","sourcesContent":["import { injectable, bindingScopeValues } from 'inversify';\nimport {\n    MergeOutcome, MERGE_RESULT_MERGED, MERGE_RESULT_AUTO_QUEUED, MERGE_RESULT_LEFT_TO_HUMAN,\n    MERGE_RESULT_BEHIND_CONFLICTING, MERGE_RESULT_BEHIND_UNKNOWN,\n} from './pr-merger';\n\nconst SEP = '━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━\\n';\n\n// Everything the closing block of wp-finish-upsert-pr needs to describe what actually happened. Both\n// `prNumber` and `prUrl` are '' when the PR could not be resolved (e.g. `gh pr create` failed).\nexport class FinishBannerInput {\n    prNumber: string;\n    prUrl: string;\n    title: string;\n    base: string;\n    merge: MergeOutcome;\n\n    // eslint-disable-next-line @typescript-eslint/max-params\n    constructor(prNumber: string, prUrl: string, title: string, base: string, merge: MergeOutcome) {\n        this.prNumber = prNumber;\n        this.prUrl = prUrl;\n        this.title = title;\n        this.base = base;\n        this.merge = merge;\n    }\n}\n\n/**\n * Renders the closing block of `wp-finish-upsert-pr` — and it is the FRAME, not the merge message, that\n * this class exists to get right.\n *\n * PrMerger has long been honest in its `message`. The banner around it was not: it printed a hard-coded\n * `✅ PR finished` on every path, so a run whose merge failed still looked like a completed one at a\n * glance. The worst case is `mergeStateStatus: BEHIND` — unlike BLOCKED (waiting on checks), which\n * auto-merge resolves on its own, a BEHIND branch NEVER lands. Under a green checkmark, agents walked\n * away from stranded PRs. Three of them independently reported the output as untrustworthy.\n *\n * So the header is derived from `MergeOutcome.result`, and a not-done outcome is loud, distinct, and\n * carries the exact commands that fix it — including in the clickable-link directive, whose whole job\n * is to be the last thing the AI says.\n */\n@injectable(bindingScopeValues.Singleton)\nexport class FinishBanner {\n    // The full closing recap: header keyed to the real outcome, the four things this command did, and —\n    // when the PR is not done — what must happen next.\n    render(input: FinishBannerInput): string {\n        const prNum = input.prNumber;\n        return '\\n' + SEP + this.header(input.merge) + SEP + '\\n' +\n            `   1. validated the build gate (authoritative)\\n` +\n            `   2. ${prNum ? `wrote the gated body to PR #${prNum}` : 'composed the gated PR body'} titled: \"${input.title}\"\\n` +\n            `   3. force-pushed your work to origin/${input.base} (after the body, so CI reads the right token)\\n` +\n            `   4. ${input.merge.message}\\n` +\n            `   You are on  ${input.base}  — same name as the remote branch and the PR head.\\n` +\n            this.whatIsOwed(input) + '\\n';\n    }\n\n    // TRUE only for the outcomes where nothing further is owed: merged, queued behind green-able checks,\n    // or deliberately left for a human. Everything else — BEHIND, config mismatch, gh failure, no PR —\n    // is unfinished work, and the banner must not decorate it with a checkmark.\n    isDone(merge: MergeOutcome): boolean {\n        return merge.result === MERGE_RESULT_MERGED\n            || merge.result === MERGE_RESULT_AUTO_QUEUED\n            || merge.result === MERGE_RESULT_LEFT_TO_HUMAN;\n    }\n\n    private header(merge: MergeOutcome): string {\n        if (merge.result === MERGE_RESULT_MERGED) return '✅ PR finished AND MERGED — here is exactly what I did\\n';\n        if (merge.result === MERGE_RESULT_AUTO_QUEUED) {\n            return '✅ PR finished — auto-merge is ON; it lands itself when the checks pass\\n';\n        }\n        if (merge.result === MERGE_RESULT_LEFT_TO_HUMAN) {\n            return '✅ PR finished — posted for a human to merge (that is this repo\\'s policy)\\n';\n        }\n        // NOT \"PR NOT FINISHED\". Everything this command owns SUCCEEDED — the branch is pushed, the body\n        // is written, the build gate is green. What happened is that another author landed on main\n        // between our fetch and our push. Reporting that as the author's failure sent agents off\n        // re-auditing their own diff and hunting build flakes for a race they did not cause.\n        if (merge.isBehind()) return this.behindHeader(merge);\n        return '⚠️  PR NOT FINISHED — the PR is up, but the merge did NOT happen\\n';\n    }\n\n    private behindHeader(merge: MergeOutcome): string {\n        if (merge.result === MERGE_RESULT_BEHIND_CONFLICTING) {\n            return '⏸️  PR IS UP AND GREEN — someone landed on main first, and it CONFLICTS with your work\\n';\n        }\n        if (merge.result === MERGE_RESULT_BEHIND_UNKNOWN) {\n            return '⏸️  PR IS UP AND GREEN — GitHub has not finished computing mergeability yet\\n';\n        }\n        return '⏸️  PR IS UP AND GREEN — someone landed on main first (no conflicts with your work)\\n';\n    }\n\n    // The follow-up block. '' for a done outcome — a finished run should not invent chores.\n    private whatIsOwed(input: FinishBannerInput): string {\n        if (this.isDone(input.merge)) return this.doneNote(input.merge);\n        if (input.merge.isBehind()) return this.behindRemedy(input);\n        return '\\n' + SEP +\n            '   ⚠️  DO NOT report this PR as done. The merge failed for the reason in step 4 above.\\n' +\n            '       Fix that, then re-run:  pnpm wp-finish-upsert-pr\\n' +\n            `   Confirm for yourself:  gh pr view ${input.prNumber === '' ? '<n>' : input.prNumber} --json mergeable,mergeStateStatus,state\\n`;\n    }\n\n    /**\n     * The BEHIND follow-up. Two rules govern every word here.\n     *\n     * FIRST: the remedy is the FULL ①②③, never a shortcut. `gh pr update-branch` looks like the obvious\n     * one-command fix and is a trap — it rewrites the REMOTE branch while every fork-point consumer\n     * (`ForkPoint.resolveForkPoint`, `nx affected --base=$(git merge-base ...)`, the review diff) computes\n     * against the LOCAL HEAD. That splits reality in two: stage ③ force-pushes local over the remote and\n     * silently reverts it, the recorded hash points describe a tree that is no longer the PR head, and the\n     * rebased tree never passes a build gate. Only ① moves the fork point AND records it; only ② rebuilds\n     * and re-receipts against the new one.\n     *\n     * SECOND: it ASKS, it does not order. An imperative command list is what turns an agent into a loop —\n     * it complies, main moves again, it complies again. Asking forces a stop at a human, which is the only\n     * thing that reliably terminates a race we cannot win by retrying.\n     */\n    private behindRemedy(input: FinishBannerInput): string {\n        const num = input.prNumber === '' ? '<n>' : input.prNumber;\n        return '\\n' + SEP + this.behindSituation(input.merge) + '\\n' +\n            '   ⚠️  STOP HERE AND ASK THE HUMAN. Do NOT run these yourself — if main keeps moving,\\n' +\n            '       running them on your own is an infinite loop with a full build inside it.\\n\\n' +\n            '   Ask, in your own words:\\n' +\n            `       \"${this.behindAsk(input.merge)}\\n` +\n            `        ${this.behindAskClose(input.merge)}\"\\n\\n` +\n            '   Only once they say yes:\\n\\n' +\n            '       pnpm wp-start-upsert-pr     # 3-point merge from main — re-forks onto the new main\\n' +\n            '       pnpm wp-review-upsert-pr    # re-validates the merge + REBUILDS on the new fork point\\n' +\n            '       pnpm wp-finish-upsert-pr    # gated body + merge, now up to date\\n\\n' +\n            '   Do NOT skip ②. It is the only stage that validates the new merge and rebuilds against\\n' +\n            '   the new fork point; skipping it publishes a PR whose tree was never gated.\\n' +\n            '   Do NOT reach for `gh pr update-branch`. It rewrites the REMOTE branch only, which stage\\n' +\n            '   ③ then force-pushes over — and it lands a tree no build gate ever saw.\\n' +\n            `   Verify independently, do not trust this banner:\\n` +\n            `       gh pr view ${num} --json mergeable,mergeStateStatus,state\\n`;\n    }\n\n    // What is actually true right now, per kind. The CLEAN case gets the caveat that it may not even\n    // matter: \"out of date\" only blocks a merge on repos that require branches be up to date.\n    private behindSituation(merge: MergeOutcome): string {\n        if (merge.result === MERGE_RESULT_BEHIND_CONFLICTING) {\n            return '   Your PR is pushed, its body is written, and the build gate passed. Then someone\\n' +\n                '   else landed on main, and their change CONFLICTS with yours — same lines. Real\\n' +\n                '   resolution is owed, and if people keep landing ahead of you it genuinely repeats.\\n' +\n                '   That is inherent to concurrent editing, not a bug and not something you did wrong.\\n';\n        }\n        if (merge.result === MERGE_RESULT_BEHIND_UNKNOWN) {\n            return '   Your PR is pushed, its body is written, and the build gate passed. GitHub has not\\n' +\n                '   finished computing mergeability yet (it is asynchronous, and we asked seconds after\\n' +\n                '   the push), so we do NOT know whether this conflicts. Re-check before doing anything:\\n' +\n                '   a few seconds later the answer is usually CLEAN and no work is owed at all.\\n';\n        }\n        return '   Your PR is pushed, its body is written, and the build gate passed. Someone else simply\\n' +\n            '   landed on main first. There are NO conflicts — nobody touched your lines.\\n' +\n            '   This may not even matter: \"out of date\" blocks a merge only on repos that REQUIRE\\n' +\n            '   branches be up to date. If yours does not, this PR can merge as-is.\\n';\n    }\n\n    // The one sentence to put to the human, in their terms.\n    private behindAsk(merge: MergeOutcome): string {\n        if (merge.result === MERGE_RESULT_BEHIND_CONFLICTING) {\n            return 'Someone beat me to landing on main and there are conflicts. We MUST run a\\n' +\n                '        3-point merge so I can resolve them properly.';\n        }\n        if (merge.result === MERGE_RESULT_BEHIND_UNKNOWN) {\n            return 'Someone beat me to landing on main. GitHub has not said yet whether it\\n' +\n                '        conflicts, so I have not touched anything.';\n        }\n        return 'Someone beat me to landing on main. There are no conflicts, so this is just\\n' +\n            '        a re-sync — but it costs a full rebuild.';\n    }\n\n    // The actual question. UNKNOWN gets a DIFFERENT one: with mergeability still uncomputed, proposing a\n    // full re-run is proposing work we cannot yet show is needed — a re-check is free and often ends it.\n    private behindAskClose(merge: MergeOutcome): string {\n        if (merge.result === MERGE_RESULT_BEHIND_UNKNOWN) {\n            return 'Shall I re-check in a moment, or start the wp-*-upsert-pr process over?';\n        }\n        return 'May I start the wp-*-upsert-pr process over again?';\n    }\n\n    // A short, positive \"you are free to stop\" line for the two non-merged-but-fine outcomes, so an AI\n    // reading a queued PR does not go hunting for work that is not owed.\n    private doneNote(merge: MergeOutcome): string {\n        if (merge.result === MERGE_RESULT_AUTO_QUEUED) {\n            return '   Nothing else is owed: GitHub lands it when the checks go green. You can stop here.\\n';\n        }\n        if (merge.result === MERGE_RESULT_LEFT_TO_HUMAN) {\n            return '   Nothing else is owed by the tooling — a person merges it. You can stop here.\\n';\n        }\n        return '';\n    }\n\n    /**\n     * The closing AI directive: the resolved PR's number/title/URL and an instruction to end the\n     * user-facing summary with EXACTLY `[#N title](url)` as the final line, nothing after it.\n     *\n     * The link text CARRIES the outcome. Ending on a bare cheerful link is exactly how a stranded PR got\n     * reported as finished, and the directive says the link must be last — so the truth has to live\n     * inside the link itself, not merely above it.\n     *\n     * '' when the PR could not be resolved: better to say nothing than to point at a link that is not real.\n     */\n    linkDirective(input: FinishBannerInput): string {\n        if (input.prNumber === '' || input.prUrl === '') return '';\n        const label = this.isDone(input.merge) ? input.title : `${input.title} — ${this.notDoneTag(input.merge)}`;\n        const preamble = this.isDone(input.merge)\n            ? ''\n            : `AI — this PR is NOT done (${this.notDoneTag(input.merge)}). Your summary MUST say so plainly.\\n` +\n              (input.merge.isBehind()\n                  ? `MUST END BY ASKING the human for permission to re-run the flow, and MUST NOT run any of\\n` +\n                    `the commands above until they answer. Say plainly that nothing they did caused this —\\n` +\n                    `another author landed on main first — and that the PR itself is pushed and gate-green.\\n\\n`\n                  : `MUST include the remedy commands printed above. Do not describe this run as complete.\\n\\n`);\n        return SEP + `🔗 PR #${input.prNumber}: ${input.title}\\n   ${input.prUrl}\\n\\n` + SEP + preamble +\n            `AI — the LAST line of your summary to the user MUST be EXACTLY this clickable link, with\\n` +\n            `NOTHING printed after it (no sign-off, no next steps, no blank commentary):\\n\\n` +\n            `   [#${input.prNumber} ${label}](${input.prUrl})\\n\\n`;\n    }\n\n    // The tag rides INSIDE the clickable link, which the directive above forces to be the last line the\n    // AI prints — so it is the one piece of wording guaranteed to reach the user. It says who is waiting\n    // on whom: for every BEHIND flavour the answer is \"a human\", not \"more automation\".\n    private notDoneTag(merge: MergeOutcome): string {\n        if (merge.result === MERGE_RESULT_BEHIND_CONFLICTING) return 'NOT MERGED — main moved and it conflicts, needs your OK to re-sync';\n        if (merge.result === MERGE_RESULT_BEHIND_UNKNOWN) return 'NOT MERGED — main moved, GitHub still computing mergeability';\n        if (merge.isBehind()) return 'NOT MERGED — main moved (no conflicts), needs your OK to re-sync';\n        return 'NOT MERGED';\n    }\n}\n"]}

package/src/scripts/workflow/pr-merger.d.ts

@@ -15,6 +15,25 @@ export declare const MERGE_RESULT_LEFT_TO_HUMAN = "LEFT_TO_HUMAN";
  * green "✅ PR finished" and get abandoned.
  */
 export declare const MERGE_RESULT_BEHIND = "BEHIND";
+/**
+ * BEHIND *and* GitHub says the tree merges cleanly (`mergeable: MERGEABLE`). Nobody touched the same
+ * lines — somebody simply landed on main first. One clean re-run of ①②③ converges. Split out from the
+ * conflicting case because the two need completely different sentences: this one is not the author's
+ * problem to solve, it is a queue collision, and telling them "resolve the conflict" is a lie.
+ */
+export declare const MERGE_RESULT_BEHIND_CLEAN = "BEHIND_CLEAN";
+/**
+ * BEHIND *and* `mergeable: CONFLICTING` — the landed work and this branch touch the same lines. Real
+ * human/AI judgement is owed, and if others keep landing first it genuinely repeats. That is inherent to
+ * concurrent editing, not a defect, and the banner says so rather than pretending a re-run is free.
+ */
+export declare const MERGE_RESULT_BEHIND_CONFLICTING = "BEHIND_CONFLICTING";
+/**
+ * BEHIND but `mergeable: UNKNOWN` (or unreadable). GitHub computes mergeability ASYNCHRONOUSLY and we ask
+ * moments after a force-push, so UNKNOWN is the EXPECTED answer, not an error. Diagnosing from it would be
+ * guessing, so this outcome asks for a re-check instead of prescribing a remedy.
+ */
+export declare const MERGE_RESULT_BEHIND_UNKNOWN = "BEHIND_UNKNOWN";
 /** Not merged for some other reason (config mismatch, gh error, no PR at all). Read `message`. */
 export declare const MERGE_RESULT_FAILED = "FAILED";
 export declare class MergeOutcome {
@@ -23,6 +42,7 @@ export declare class MergeOutcome {
     message: string;
     result: string;
     constructor(merged: boolean, autoMergeEnabled: boolean, message: string, result: string);
+    isBehind(): boolean;
 }
 export declare class PrMergeState {
     mergeable: string;
@@ -30,6 +50,19 @@ export declare class PrMergeState {
     state: string;
     constructor(mergeable: string, mergeStateStatus: string, state: string);
     isBehind(): boolean;
+    /**
+     * WHICH kind of BEHIND this is, from the `mergeable` field we have always fetched and never read.
+     *
+     * This is the whole point of the split. "Out of date" and "conflicting" are different situations with
+     * different costs, and collapsing them told every author the expensive story: a clean queue collision
+     * — nobody touched your lines, somebody just landed first — got reported in the same alarming words as
+     * a genuine textual conflict.
+     *
+     * UNKNOWN is its own answer, never folded into CLEAN. GitHub computes mergeability asynchronously and
+     * we ask seconds after a force-push, so UNKNOWN is the ordinary reply in exactly our situation.
+     * Treating it as "no conflicts" would promise a clean re-run we cannot see.
+     */
+    behindKind(): string;
     describe(): string;
 }
 /**
@@ -65,6 +98,14 @@ export declare class PrMerger {
      * is NOT success either, and reporting it as such is precisely the bug this whole file guards.
      */
     private fallBackToAutoMerge;
+    /**
+     * The one outcome that looks queued but is stranded. `queued` says whether auto-merge did get enabled,
+     * because "parked forever" and "not queued at all" need different sentences — but neither is done.
+     *
+     * The `result` now carries WHICH kind of behind, so the banner can stop describing a queue collision
+     * in the vocabulary of a merge conflict. The wording here is deliberately blame-free: nothing the
+     * author did caused this, and the PR itself is in perfectly good shape — pushed, bodied, gate-green.
+     */
     private behindOutcome;
     private announceDirectFailure;
     /**

package/src/scripts/workflow/pr-merger.js

@@ -1,6 +1,6 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.GhResult = exports.PrMerger = exports.PrMergeState = exports.MergeOutcome = exports.MERGE_RESULT_FAILED = exports.MERGE_RESULT_BEHIND = exports.MERGE_RESULT_LEFT_TO_HUMAN = exports.MERGE_RESULT_AUTO_QUEUED = exports.MERGE_RESULT_MERGED = void 0;
+exports.GhResult = exports.PrMerger = exports.PrMergeState = exports.MergeOutcome = exports.MERGE_RESULT_FAILED = exports.MERGE_RESULT_BEHIND_UNKNOWN = exports.MERGE_RESULT_BEHIND_CONFLICTING = exports.MERGE_RESULT_BEHIND_CLEAN = exports.MERGE_RESULT_BEHIND = exports.MERGE_RESULT_LEFT_TO_HUMAN = exports.MERGE_RESULT_AUTO_QUEUED = exports.MERGE_RESULT_MERGED = void 0;
 const tslib_1 = require("tslib");
 const child_process_1 = require("child_process");
 const rules_config_1 = require("@webpieces/rules-config");
@@ -22,10 +22,33 @@ exports.MERGE_RESULT_LEFT_TO_HUMAN = 'LEFT_TO_HUMAN';
  * green "✅ PR finished" and get abandoned.
  */
 exports.MERGE_RESULT_BEHIND = 'BEHIND';
+/**
+ * BEHIND *and* GitHub says the tree merges cleanly (`mergeable: MERGEABLE`). Nobody touched the same
+ * lines — somebody simply landed on main first. One clean re-run of ①②③ converges. Split out from the
+ * conflicting case because the two need completely different sentences: this one is not the author's
+ * problem to solve, it is a queue collision, and telling them "resolve the conflict" is a lie.
+ */
+exports.MERGE_RESULT_BEHIND_CLEAN = 'BEHIND_CLEAN';
+/**
+ * BEHIND *and* `mergeable: CONFLICTING` — the landed work and this branch touch the same lines. Real
+ * human/AI judgement is owed, and if others keep landing first it genuinely repeats. That is inherent to
+ * concurrent editing, not a defect, and the banner says so rather than pretending a re-run is free.
+ */
+exports.MERGE_RESULT_BEHIND_CONFLICTING = 'BEHIND_CONFLICTING';
+/**
+ * BEHIND but `mergeable: UNKNOWN` (or unreadable). GitHub computes mergeability ASYNCHRONOUSLY and we ask
+ * moments after a force-push, so UNKNOWN is the EXPECTED answer, not an error. Diagnosing from it would be
+ * guessing, so this outcome asks for a re-check instead of prescribing a remedy.
+ */
+exports.MERGE_RESULT_BEHIND_UNKNOWN = 'BEHIND_UNKNOWN';
 /** Not merged for some other reason (config mismatch, gh error, no PR at all). Read `message`. */
 exports.MERGE_RESULT_FAILED = 'FAILED';
 // The `mergeStateStatus` value GitHub reports for "head branch is not up to date with the base branch".
 const GH_STATE_BEHIND = 'BEHIND';
+// `mergeable` values. GitHub returns UNKNOWN while it is still computing the merge — which is most of the
+// time in the seconds after a push — so UNKNOWN must never be read as "no conflicts".
+const GH_MERGEABLE_CLEAN = 'MERGEABLE';
+const GH_MERGEABLE_CONFLICTING = 'CONFLICTING';
 // What actually happened when we tried to land the squash merge. `message` is printed VERBATIM in the
 // final wp-finish-upsert-pr summary, so a merge that did not happen can never be reported as done —
 // the old code ignored `spawnSync().status` entirely and printed "✅ PR finished" even when `gh pr
@@ -44,6 +67,16 @@ class MergeOutcome {
         this.message = message;
         this.result = result;
     }
+    // TRUE for every flavour of "the branch is out of date with main", so the banner can ask that one
+    // question once instead of listing four constants at each branch point. Kept here rather than as a
+    // module function because `no-function-outside-class` forbids the latter — and PrMergeState below
+    // already sets the precedent that a verdict class answers questions about itself.
+    isBehind() {
+        return this.result === exports.MERGE_RESULT_BEHIND
+            || this.result === exports.MERGE_RESULT_BEHIND_CLEAN
+            || this.result === exports.MERGE_RESULT_BEHIND_CONFLICTING
+            || this.result === exports.MERGE_RESULT_BEHIND_UNKNOWN;
+    }
 }
 exports.MergeOutcome = MergeOutcome;
 // GitHub's own verdict on the PR, straight from `gh pr view --json mergeable,mergeStateStatus,state`.
@@ -60,6 +93,25 @@ class PrMergeState {
     isBehind() {
         return this.mergeStateStatus === GH_STATE_BEHIND;
     }
+    /**
+     * WHICH kind of BEHIND this is, from the `mergeable` field we have always fetched and never read.
+     *
+     * This is the whole point of the split. "Out of date" and "conflicting" are different situations with
+     * different costs, and collapsing them told every author the expensive story: a clean queue collision
+     * — nobody touched your lines, somebody just landed first — got reported in the same alarming words as
+     * a genuine textual conflict.
+     *
+     * UNKNOWN is its own answer, never folded into CLEAN. GitHub computes mergeability asynchronously and
+     * we ask seconds after a force-push, so UNKNOWN is the ordinary reply in exactly our situation.
+     * Treating it as "no conflicts" would promise a clean re-run we cannot see.
+     */
+    behindKind() {
+        if (this.mergeable === GH_MERGEABLE_CLEAN)
+            return exports.MERGE_RESULT_BEHIND_CLEAN;
+        if (this.mergeable === GH_MERGEABLE_CONFLICTING)
+            return exports.MERGE_RESULT_BEHIND_CONFLICTING;
+        return exports.MERGE_RESULT_BEHIND_UNKNOWN;
+    }
     // One-line rendering for the failure message, or '' when GitHub could not be asked.
     describe() {
         if (this.mergeStateStatus === '')
@@ -155,14 +207,19 @@ let PrMerger = class PrMerger {
             return this.behindOutcome(state, true);
         return new MergeOutcome(false, true, `enabled auto-merge — it will squash-merge as "${subject}" when the checks pass`, exports.MERGE_RESULT_AUTO_QUEUED);
     }
-    // The one outcome that looks queued but is stranded. `queued` says whether auto-merge did get
-    // enabled, because "parked forever" and "not queued at all" need different sentences — but neither
-    // of them is done, so both carry MERGE_RESULT_BEHIND.
+    /**
+     * The one outcome that looks queued but is stranded. `queued` says whether auto-merge did get enabled,
+     * because "parked forever" and "not queued at all" need different sentences — but neither is done.
+     *
+     * The `result` now carries WHICH kind of behind, so the banner can stop describing a queue collision
+     * in the vocabulary of a merge conflict. The wording here is deliberately blame-free: nothing the
+     * author did caused this, and the PR itself is in perfectly good shape — pushed, bodied, gate-green.
+     */
     behindOutcome(state, queued) {
-        return new MergeOutcome(false, queued, `⛔ did NOT merge — the head branch is BEHIND its base (${state.describe()}).\n` +
-            `      BEHIND does NOT self-heal: auto-merge never updates your branch, so nothing will land\n` +
-            `      this PR until it is re-synced from main. ` +
-            (queued ? 'Auto-merge is enabled but parked.' : 'Nothing is queued.'), exports.MERGE_RESULT_BEHIND);
+        const parked = queued ? 'Auto-merge is enabled but parked.' : 'Nothing is queued.';
+        return new MergeOutcome(false, queued, `did NOT merge — someone else landed on main first, so GitHub wants this branch rebuilt on\n` +
+            `      top of theirs before it will merge (${state.describe()}).\n` +
+            `      This does NOT self-heal: auto-merge never updates your branch. ${parked}`, state.behindKind());
     }
     // Reprint the expected first-attempt failure as CONTEXT, not as a verdict. gh's own `X …` line is
     // captured (never inherited) so this framing is the only thing on screen.

package/src/scripts/workflow/pr-merger.js.map

@@ -1 +1 @@
-{"version":3,"file":"pr-merger.js","sourceRoot":"","sources":["../../../../../../../packages/tooling/pr-gate/src/scripts/workflow/pr-merger.ts"],"names":[],"mappings":"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","sourcesContent":["import { spawnSync } from 'child_process';\nimport { MERGE_MODE_AUTO, MERGE_MODE_NONE } from '@webpieces/rules-config';\nimport { injectable, bindingScopeValues } from 'inversify';\n\n/**\n * The five terminal shapes a merge attempt can take. The CALLER branches on these — a `message` string\n * is for humans to read, never for code to pattern-match, and the banner that frames it must be able to\n * tell \"done\" from \"stranded\" without parsing prose.\n */\nexport const MERGE_RESULT_MERGED = 'MERGED';\n/** Not merged YET, but queued: auto-merge is enabled and lands it when the checks pass. Self-healing. */\nexport const MERGE_RESULT_AUTO_QUEUED = 'AUTO_QUEUED';\n/** Not merged BY DESIGN: pr-gate.mergeMode is not AUTO, so a person merges. Nothing is owed here. */\nexport const MERGE_RESULT_LEFT_TO_HUMAN = 'LEFT_TO_HUMAN';\n/**\n * Not merged and it NEVER will be without action: `gh pr view --json mergeStateStatus` says BEHIND, i.e.\n * the head branch is out of date with base. Unlike BLOCKED (waiting on checks — self-healing), BEHIND\n * cannot resolve itself; the branch must be re-synced from main. This is the case that used to print a\n * green \"✅ PR finished\" and get abandoned.\n */\nexport const MERGE_RESULT_BEHIND = 'BEHIND';\n/** Not merged for some other reason (config mismatch, gh error, no PR at all). Read `message`. */\nexport const MERGE_RESULT_FAILED = 'FAILED';\n\n// The `mergeStateStatus` value GitHub reports for \"head branch is not up to date with the base branch\".\nconst GH_STATE_BEHIND = 'BEHIND';\n\n// What actually happened when we tried to land the squash merge. `message` is printed VERBATIM in the\n// final wp-finish-upsert-pr summary, so a merge that did not happen can never be reported as done —\n// the old code ignored `spawnSync().status` entirely and printed \"✅ PR finished\" even when `gh pr\n// merge` had errored out, which is what hid the auto-merge-disabled failure for weeks. `result` is the\n// machine-readable half of the same honesty: the banner picks its HEADER from it, so the frame around\n// the message can no longer say \"finished\" while the message says \"did NOT merge\".\nexport class MergeOutcome {\n    merged: boolean;\n    autoMergeEnabled: boolean;\n    message: string;\n    result: string;\n\n    // eslint-disable-next-line @typescript-eslint/max-params\n    constructor(merged: boolean, autoMergeEnabled: boolean, message: string, result: string) {\n        this.merged = merged;\n        this.autoMergeEnabled = autoMergeEnabled;\n        this.message = message;\n        this.result = result;\n    }\n}\n\n// GitHub's own verdict on the PR, straight from `gh pr view --json mergeable,mergeStateStatus,state`.\n// All '' when gh could not be asked — an unreadable answer must never be treated as a diagnosis.\nexport class PrMergeState {\n    mergeable: string;\n    mergeStateStatus: string;\n    state: string;\n\n    constructor(mergeable: string, mergeStateStatus: string, state: string) {\n        this.mergeable = mergeable;\n        this.mergeStateStatus = mergeStateStatus;\n        this.state = state;\n    }\n\n    isBehind(): boolean {\n        return this.mergeStateStatus === GH_STATE_BEHIND;\n    }\n\n    // One-line rendering for the failure message, or '' when GitHub could not be asked.\n    describe(): string {\n        if (this.mergeStateStatus === '') return '';\n        return `mergeable=${this.mergeable}, mergeStateStatus=${this.mergeStateStatus}, state=${this.state}`;\n    }\n}\n\n/**\n * Lands — or queues — the squash merge with an EXPLICIT subject/body, on BOTH kinds of repo:\n *\n * - auto-merge ALLOWED (`allow_auto_merge: true`): a PR whose checks are still running falls back to\n *   the auto-merge queue, carrying the same subject/body so it lands when the checks pass.\n * - auto-merge DISALLOWED (`allow_auto_merge: false`, a deliberate policy control in many orgs): the\n *   direct merge still works the moment the PR is mergeable, because `gh pr merge --squash --subject\n *   --body-file` does not depend on that setting at all. When the PR is NOT yet mergeable there is no\n *   queue to fall back to, so we say so loudly instead of firing a `--auto` that can only fail.\n *\n * WHICH of those a repo gets is not guessed — `pr-gate.mergeMode` is REQUIRED config. AUTO means the\n * tooling lands PRs; NONE means it only posts them and a person merges. No mode can force a queue the\n * repo has turned off, so AUTO on a repo with allow_auto_merge=false is a CONFIG error, reported as\n * one rather than papered over.\n *\n * Every `gh` status is checked. Nothing here is allowed to fail silently.\n */\n@injectable(bindingScopeValues.Singleton)\nexport class PrMerger {\n    /**\n     * @param subject       the squash-commit subject, normally `<PR title> (#N)`\n     * @param mergeBodyFile file holding the squash-commit body (risk/flags/PR link)\n     * @param mergeMode     pr-gate.mergeMode from webpieces.config.json — AUTO or NONE. Anything else\n     *                      (including a repo still on a published rules-config that predates the field)\n     *                      is treated as NONE: when the policy is unreadable, do NOT touch main.\n     */\n    merge(baseBranch: string, subject: string, mergeBodyFile: string, mergeMode: string): MergeOutcome {\n        // Anything that is not an explicit AUTO leaves the PR alone. The PR itself is already\n        // posted/updated by this point, which is the whole job in this mode.\n        if (mergeMode !== MERGE_MODE_AUTO) {\n            return new MergeOutcome(false, false,\n                `did NOT merge — pr-gate.mergeMode is ${mergeMode === MERGE_MODE_NONE ? 'NONE' : `\"${mergeMode}\"`}, so the PR is left for a human to merge.\\n` +\n                `      Subject GitHub will use is its own (squash_merge_commit_title), NOT: \"${subject}\"`,\n                MERGE_RESULT_LEFT_TO_HUMAN);\n        }\n\n        // A direct `gh pr merge --squash --subject --body-file` writes exactly this subject/body to\n        // main's history regardless of the repo's squash_merge_commit_title/message defaults — and\n        // regardless of allow_auto_merge. It is the ONLY path that guarantees the good commit message.\n        //\n        // Its output is CAPTURED, not inherited: this attempt fails BY DESIGN on any repo whose policy\n        // forbids a direct merge, and gh's raw `X Pull request #N is not mergeable: …` on the terminal\n        // read as a hard failure to every human and agent who saw it. We reprint the reason ourselves,\n        // framed as the expected first step of a two-step dance (see announceDirectFailure).\n        const direct = this.ghCapture(['pr', 'merge', baseBranch, '--squash', '--subject', subject, '--body-file', mergeBodyFile]);\n        if (direct.status === 0) {\n            process.stdout.write(direct.output);\n            return new MergeOutcome(true, false, `squash-merged the PR as: \"${subject}\"`, MERGE_RESULT_MERGED);\n        }\n\n        // Past here the PR is not mergeable yet. WHY matters enormously and gh's exit status does not\n        // say: checks-still-running (BLOCKED) is self-healing once auto-merge is on, while out-of-date\n        // (BEHIND) can NEVER land unattended. Ask GitHub itself — one cheap, failure-tolerant call, made\n        // only on the failure path, so a run whose direct merge succeeded costs no extra API call.\n        const state = this.prMergeState(baseBranch);\n        this.announceDirectFailure(direct.output, state);\n        return this.fallBackToAutoMerge(baseBranch, subject, mergeBodyFile, state);\n    }\n\n    /**\n     * The auto-merge queue: the only way to still land a not-yet-mergeable PR unattended. Returns the\n     * BEHIND outcome regardless of how queuing went whenever GitHub says the branch is out of date —\n     * queuing a BEHIND PR is not an error (a repo that auto-updates branches will still land it), but it\n     * is NOT success either, and reporting it as such is precisely the bug this whole file guards.\n     */\n    // eslint-disable-next-line @typescript-eslint/max-params\n    private fallBackToAutoMerge(baseBranch: string, subject: string, mergeBodyFile: string, state: PrMergeState): MergeOutcome {\n        if (!this.autoMergeAllowed()) {\n            if (state.isBehind()) return this.behindOutcome(state, false);\n            return new MergeOutcome(false, false,\n                '⚠️  did NOT merge, and queued NOTHING — CONFIG MISMATCH: pr-gate.mergeMode is AUTO, but\\n' +\n                '      this repo has allow_auto_merge=false, so there is no queue to fall back to and the\\n' +\n                '      PR is not mergeable yet. `gh pr merge --auto` cannot override a repo that says no.\\n' +\n                '      Fix it at ONE of the two ends: turn on \"Allow auto-merge\" in the repo settings, or\\n' +\n                '      set commands.pr-gate.mergeMode to \"NONE\" (and set that repo\\'s\\n' +\n                '      squash_merge_commit_title to PR_TITLE so a human merge still gets a real subject).',\n                MERGE_RESULT_FAILED);\n        }\n\n        process.stdout.write('   … retrying with --auto (the auto-merge queue)\\n');\n        // gh records the merge subject/body only at the moment auto-merge is FIRST enabled; a second\n        // `--auto` on an already-enabled PR silently keeps the OLD body. Disabling first re-stamps the\n        // current subject/body on every re-run (a harmless no-op when auto-merge is not enabled).\n        this.gh(['pr', 'merge', baseBranch, '--disable-auto'], true);\n        const auto = this.gh(['pr', 'merge', baseBranch, '--auto', '--squash', '--subject', subject, '--body-file', mergeBodyFile]);\n        if (auto !== 0) {\n            if (state.isBehind()) return this.behindOutcome(state, false);\n            return new MergeOutcome(false, false,\n                '⚠️  did NOT merge and could NOT enable auto-merge either (see the gh error above) —\\n' +\n                '      NOTHING is queued. Re-run once the PR is healthy.',\n                MERGE_RESULT_FAILED);\n        }\n        if (state.isBehind()) return this.behindOutcome(state, true);\n        return new MergeOutcome(false, true,\n            `enabled auto-merge — it will squash-merge as \"${subject}\" when the checks pass`,\n            MERGE_RESULT_AUTO_QUEUED);\n    }\n\n    // The one outcome that looks queued but is stranded. `queued` says whether auto-merge did get\n    // enabled, because \"parked forever\" and \"not queued at all\" need different sentences — but neither\n    // of them is done, so both carry MERGE_RESULT_BEHIND.\n    private behindOutcome(state: PrMergeState, queued: boolean): MergeOutcome {\n        return new MergeOutcome(false, queued,\n            `⛔ did NOT merge — the head branch is BEHIND its base (${state.describe()}).\\n` +\n            `      BEHIND does NOT self-heal: auto-merge never updates your branch, so nothing will land\\n` +\n            `      this PR until it is re-synced from main. ` +\n            (queued ? 'Auto-merge is enabled but parked.' : 'Nothing is queued.'),\n            MERGE_RESULT_BEHIND);\n    }\n\n    // Reprint the expected first-attempt failure as CONTEXT, not as a verdict. gh's own `X …` line is\n    // captured (never inherited) so this framing is the only thing on screen.\n    private announceDirectFailure(ghOutput: string, state: PrMergeState): void {\n        const reason = ghOutput.trim().split('\\n').filter((l: string): boolean => l.trim() !== '').pop() ?? '';\n        process.stdout.write(\n            'ℹ️  the direct squash-merge did not go through (expected while checks run, or when repo\\n' +\n            '   policy forbids direct merges):\\n' +\n            (reason === '' ? '' : `      ${reason}\\n`) +\n            (state.describe() === '' ? '' : `   GitHub says: ${state.describe()}\\n`),\n        );\n    }\n\n    /**\n     * GitHub's own verdict on the PR. AUTHORITATIVE for the BEHIND check — the alternative is\n     * pattern-matching gh's English error prose, which changes between releases. Failure-tolerant on\n     * purpose: a gh hiccup returns an all-'' state (never BEHIND) so a transient API blip can only cost\n     * us the extra diagnosis, never turn a working run into a crash.\n     */\n    protected prMergeState(baseBranch: string): PrMergeState {\n        const result = spawnSync(\n            'gh',\n            ['pr', 'view', baseBranch, '--json', 'mergeable,mergeStateStatus,state',\n                '--jq', '\"\\\\(.mergeable)\\\\t\\\\(.mergeStateStatus)\\\\t\\\\(.state)\"'],\n            { encoding: 'utf8' },\n        );\n        if (result.status !== 0) return new PrMergeState('', '', '');\n        const parts = (result.stdout ?? '').trim().split('\\t');\n        return new PrMergeState(parts[0] ?? '', parts[1] ?? '', parts[2] ?? '');\n    }\n\n    // Whether `gh pr merge --auto` is even possible on this repo. Many orgs set allow_auto_merge=false\n    // as a policy control, where `--auto` can only ever fail with `GraphQL: Auto merge is not allowed\n    // for this repository`. One API call beats discovering that from an error string. Anything other\n    // than a clean `true` counts as NOT allowed: if the setting cannot be read we must not claim the\n    // queue is available.\n    protected autoMergeAllowed(): boolean {\n        const result = spawnSync('gh', ['api', 'repos/{owner}/{repo}', '--jq', '.allow_auto_merge'], { encoding: 'utf8' });\n        return result.status === 0 && (result.stdout ?? '').trim() === 'true';\n    }\n\n    // Runs `gh`, returning its exit status (-1 when gh could not be spawned at all, which must NOT be\n    // mistaken for the 0 that means success).\n    protected gh(args: string[], quiet: boolean = false): number {\n        const result = spawnSync('gh', args, { stdio: quiet ? 'ignore' : 'inherit' });\n        return result.status ?? -1;\n    }\n\n    // Runs `gh` CAPTURING both streams instead of inheriting them, so an expected-to-fail attempt can be\n    // reported in our own words rather than dumping a raw `X …` line the reader reads as fatal.\n    protected ghCapture(args: string[]): GhResult {\n        const result = spawnSync('gh', args, { encoding: 'utf8' });\n        return new GhResult(result.status ?? -1, (result.stdout ?? '') + (result.stderr ?? ''));\n    }\n}\n\n// A captured `gh` invocation: its exit status (-1 when gh could not be spawned) and both streams\n// combined, in the order a terminal would have shown them.\nexport class GhResult {\n    status: number;\n    output: string;\n\n    constructor(status: number, output: string) {\n        this.status = status;\n        this.output = output;\n    }\n}\n"]}
+{"version":3,"file":"pr-merger.js","sourceRoot":"","sources":["../../../../../../../packages/tooling/pr-gate/src/scripts/workflow/pr-merger.ts"],"names":[],"mappings":"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","sourcesContent":["import { spawnSync } from 'child_process';\nimport { MERGE_MODE_AUTO, MERGE_MODE_NONE } from '@webpieces/rules-config';\nimport { injectable, bindingScopeValues } from 'inversify';\n\n/**\n * The five terminal shapes a merge attempt can take. The CALLER branches on these — a `message` string\n * is for humans to read, never for code to pattern-match, and the banner that frames it must be able to\n * tell \"done\" from \"stranded\" without parsing prose.\n */\nexport const MERGE_RESULT_MERGED = 'MERGED';\n/** Not merged YET, but queued: auto-merge is enabled and lands it when the checks pass. Self-healing. */\nexport const MERGE_RESULT_AUTO_QUEUED = 'AUTO_QUEUED';\n/** Not merged BY DESIGN: pr-gate.mergeMode is not AUTO, so a person merges. Nothing is owed here. */\nexport const MERGE_RESULT_LEFT_TO_HUMAN = 'LEFT_TO_HUMAN';\n/**\n * Not merged and it NEVER will be without action: `gh pr view --json mergeStateStatus` says BEHIND, i.e.\n * the head branch is out of date with base. Unlike BLOCKED (waiting on checks — self-healing), BEHIND\n * cannot resolve itself; the branch must be re-synced from main. This is the case that used to print a\n * green \"✅ PR finished\" and get abandoned.\n */\nexport const MERGE_RESULT_BEHIND = 'BEHIND';\n/**\n * BEHIND *and* GitHub says the tree merges cleanly (`mergeable: MERGEABLE`). Nobody touched the same\n * lines — somebody simply landed on main first. One clean re-run of ①②③ converges. Split out from the\n * conflicting case because the two need completely different sentences: this one is not the author's\n * problem to solve, it is a queue collision, and telling them \"resolve the conflict\" is a lie.\n */\nexport const MERGE_RESULT_BEHIND_CLEAN = 'BEHIND_CLEAN';\n/**\n * BEHIND *and* `mergeable: CONFLICTING` — the landed work and this branch touch the same lines. Real\n * human/AI judgement is owed, and if others keep landing first it genuinely repeats. That is inherent to\n * concurrent editing, not a defect, and the banner says so rather than pretending a re-run is free.\n */\nexport const MERGE_RESULT_BEHIND_CONFLICTING = 'BEHIND_CONFLICTING';\n/**\n * BEHIND but `mergeable: UNKNOWN` (or unreadable). GitHub computes mergeability ASYNCHRONOUSLY and we ask\n * moments after a force-push, so UNKNOWN is the EXPECTED answer, not an error. Diagnosing from it would be\n * guessing, so this outcome asks for a re-check instead of prescribing a remedy.\n */\nexport const MERGE_RESULT_BEHIND_UNKNOWN = 'BEHIND_UNKNOWN';\n/** Not merged for some other reason (config mismatch, gh error, no PR at all). Read `message`. */\nexport const MERGE_RESULT_FAILED = 'FAILED';\n\n// The `mergeStateStatus` value GitHub reports for \"head branch is not up to date with the base branch\".\nconst GH_STATE_BEHIND = 'BEHIND';\n// `mergeable` values. GitHub returns UNKNOWN while it is still computing the merge — which is most of the\n// time in the seconds after a push — so UNKNOWN must never be read as \"no conflicts\".\nconst GH_MERGEABLE_CLEAN = 'MERGEABLE';\nconst GH_MERGEABLE_CONFLICTING = 'CONFLICTING';\n\n// What actually happened when we tried to land the squash merge. `message` is printed VERBATIM in the\n// final wp-finish-upsert-pr summary, so a merge that did not happen can never be reported as done —\n// the old code ignored `spawnSync().status` entirely and printed \"✅ PR finished\" even when `gh pr\n// merge` had errored out, which is what hid the auto-merge-disabled failure for weeks. `result` is the\n// machine-readable half of the same honesty: the banner picks its HEADER from it, so the frame around\n// the message can no longer say \"finished\" while the message says \"did NOT merge\".\nexport class MergeOutcome {\n    merged: boolean;\n    autoMergeEnabled: boolean;\n    message: string;\n    result: string;\n\n    // eslint-disable-next-line @typescript-eslint/max-params\n    constructor(merged: boolean, autoMergeEnabled: boolean, message: string, result: string) {\n        this.merged = merged;\n        this.autoMergeEnabled = autoMergeEnabled;\n        this.message = message;\n        this.result = result;\n    }\n\n    // TRUE for every flavour of \"the branch is out of date with main\", so the banner can ask that one\n    // question once instead of listing four constants at each branch point. Kept here rather than as a\n    // module function because `no-function-outside-class` forbids the latter — and PrMergeState below\n    // already sets the precedent that a verdict class answers questions about itself.\n    isBehind(): boolean {\n        return this.result === MERGE_RESULT_BEHIND\n            || this.result === MERGE_RESULT_BEHIND_CLEAN\n            || this.result === MERGE_RESULT_BEHIND_CONFLICTING\n            || this.result === MERGE_RESULT_BEHIND_UNKNOWN;\n    }\n}\n\n// GitHub's own verdict on the PR, straight from `gh pr view --json mergeable,mergeStateStatus,state`.\n// All '' when gh could not be asked — an unreadable answer must never be treated as a diagnosis.\nexport class PrMergeState {\n    mergeable: string;\n    mergeStateStatus: string;\n    state: string;\n\n    constructor(mergeable: string, mergeStateStatus: string, state: string) {\n        this.mergeable = mergeable;\n        this.mergeStateStatus = mergeStateStatus;\n        this.state = state;\n    }\n\n    isBehind(): boolean {\n        return this.mergeStateStatus === GH_STATE_BEHIND;\n    }\n\n    /**\n     * WHICH kind of BEHIND this is, from the `mergeable` field we have always fetched and never read.\n     *\n     * This is the whole point of the split. \"Out of date\" and \"conflicting\" are different situations with\n     * different costs, and collapsing them told every author the expensive story: a clean queue collision\n     * — nobody touched your lines, somebody just landed first — got reported in the same alarming words as\n     * a genuine textual conflict.\n     *\n     * UNKNOWN is its own answer, never folded into CLEAN. GitHub computes mergeability asynchronously and\n     * we ask seconds after a force-push, so UNKNOWN is the ordinary reply in exactly our situation.\n     * Treating it as \"no conflicts\" would promise a clean re-run we cannot see.\n     */\n    behindKind(): string {\n        if (this.mergeable === GH_MERGEABLE_CLEAN) return MERGE_RESULT_BEHIND_CLEAN;\n        if (this.mergeable === GH_MERGEABLE_CONFLICTING) return MERGE_RESULT_BEHIND_CONFLICTING;\n        return MERGE_RESULT_BEHIND_UNKNOWN;\n    }\n\n    // One-line rendering for the failure message, or '' when GitHub could not be asked.\n    describe(): string {\n        if (this.mergeStateStatus === '') return '';\n        return `mergeable=${this.mergeable}, mergeStateStatus=${this.mergeStateStatus}, state=${this.state}`;\n    }\n}\n\n/**\n * Lands — or queues — the squash merge with an EXPLICIT subject/body, on BOTH kinds of repo:\n *\n * - auto-merge ALLOWED (`allow_auto_merge: true`): a PR whose checks are still running falls back to\n *   the auto-merge queue, carrying the same subject/body so it lands when the checks pass.\n * - auto-merge DISALLOWED (`allow_auto_merge: false`, a deliberate policy control in many orgs): the\n *   direct merge still works the moment the PR is mergeable, because `gh pr merge --squash --subject\n *   --body-file` does not depend on that setting at all. When the PR is NOT yet mergeable there is no\n *   queue to fall back to, so we say so loudly instead of firing a `--auto` that can only fail.\n *\n * WHICH of those a repo gets is not guessed — `pr-gate.mergeMode` is REQUIRED config. AUTO means the\n * tooling lands PRs; NONE means it only posts them and a person merges. No mode can force a queue the\n * repo has turned off, so AUTO on a repo with allow_auto_merge=false is a CONFIG error, reported as\n * one rather than papered over.\n *\n * Every `gh` status is checked. Nothing here is allowed to fail silently.\n */\n@injectable(bindingScopeValues.Singleton)\nexport class PrMerger {\n    /**\n     * @param subject       the squash-commit subject, normally `<PR title> (#N)`\n     * @param mergeBodyFile file holding the squash-commit body (risk/flags/PR link)\n     * @param mergeMode     pr-gate.mergeMode from webpieces.config.json — AUTO or NONE. Anything else\n     *                      (including a repo still on a published rules-config that predates the field)\n     *                      is treated as NONE: when the policy is unreadable, do NOT touch main.\n     */\n    merge(baseBranch: string, subject: string, mergeBodyFile: string, mergeMode: string): MergeOutcome {\n        // Anything that is not an explicit AUTO leaves the PR alone. The PR itself is already\n        // posted/updated by this point, which is the whole job in this mode.\n        if (mergeMode !== MERGE_MODE_AUTO) {\n            return new MergeOutcome(false, false,\n                `did NOT merge — pr-gate.mergeMode is ${mergeMode === MERGE_MODE_NONE ? 'NONE' : `\"${mergeMode}\"`}, so the PR is left for a human to merge.\\n` +\n                `      Subject GitHub will use is its own (squash_merge_commit_title), NOT: \"${subject}\"`,\n                MERGE_RESULT_LEFT_TO_HUMAN);\n        }\n\n        // A direct `gh pr merge --squash --subject --body-file` writes exactly this subject/body to\n        // main's history regardless of the repo's squash_merge_commit_title/message defaults — and\n        // regardless of allow_auto_merge. It is the ONLY path that guarantees the good commit message.\n        //\n        // Its output is CAPTURED, not inherited: this attempt fails BY DESIGN on any repo whose policy\n        // forbids a direct merge, and gh's raw `X Pull request #N is not mergeable: …` on the terminal\n        // read as a hard failure to every human and agent who saw it. We reprint the reason ourselves,\n        // framed as the expected first step of a two-step dance (see announceDirectFailure).\n        const direct = this.ghCapture(['pr', 'merge', baseBranch, '--squash', '--subject', subject, '--body-file', mergeBodyFile]);\n        if (direct.status === 0) {\n            process.stdout.write(direct.output);\n            return new MergeOutcome(true, false, `squash-merged the PR as: \"${subject}\"`, MERGE_RESULT_MERGED);\n        }\n\n        // Past here the PR is not mergeable yet. WHY matters enormously and gh's exit status does not\n        // say: checks-still-running (BLOCKED) is self-healing once auto-merge is on, while out-of-date\n        // (BEHIND) can NEVER land unattended. Ask GitHub itself — one cheap, failure-tolerant call, made\n        // only on the failure path, so a run whose direct merge succeeded costs no extra API call.\n        const state = this.prMergeState(baseBranch);\n        this.announceDirectFailure(direct.output, state);\n        return this.fallBackToAutoMerge(baseBranch, subject, mergeBodyFile, state);\n    }\n\n    /**\n     * The auto-merge queue: the only way to still land a not-yet-mergeable PR unattended. Returns the\n     * BEHIND outcome regardless of how queuing went whenever GitHub says the branch is out of date —\n     * queuing a BEHIND PR is not an error (a repo that auto-updates branches will still land it), but it\n     * is NOT success either, and reporting it as such is precisely the bug this whole file guards.\n     */\n    // eslint-disable-next-line @typescript-eslint/max-params\n    private fallBackToAutoMerge(baseBranch: string, subject: string, mergeBodyFile: string, state: PrMergeState): MergeOutcome {\n        if (!this.autoMergeAllowed()) {\n            if (state.isBehind()) return this.behindOutcome(state, false);\n            return new MergeOutcome(false, false,\n                '⚠️  did NOT merge, and queued NOTHING — CONFIG MISMATCH: pr-gate.mergeMode is AUTO, but\\n' +\n                '      this repo has allow_auto_merge=false, so there is no queue to fall back to and the\\n' +\n                '      PR is not mergeable yet. `gh pr merge --auto` cannot override a repo that says no.\\n' +\n                '      Fix it at ONE of the two ends: turn on \"Allow auto-merge\" in the repo settings, or\\n' +\n                '      set commands.pr-gate.mergeMode to \"NONE\" (and set that repo\\'s\\n' +\n                '      squash_merge_commit_title to PR_TITLE so a human merge still gets a real subject).',\n                MERGE_RESULT_FAILED);\n        }\n\n        process.stdout.write('   … retrying with --auto (the auto-merge queue)\\n');\n        // gh records the merge subject/body only at the moment auto-merge is FIRST enabled; a second\n        // `--auto` on an already-enabled PR silently keeps the OLD body. Disabling first re-stamps the\n        // current subject/body on every re-run (a harmless no-op when auto-merge is not enabled).\n        this.gh(['pr', 'merge', baseBranch, '--disable-auto'], true);\n        const auto = this.gh(['pr', 'merge', baseBranch, '--auto', '--squash', '--subject', subject, '--body-file', mergeBodyFile]);\n        if (auto !== 0) {\n            if (state.isBehind()) return this.behindOutcome(state, false);\n            return new MergeOutcome(false, false,\n                '⚠️  did NOT merge and could NOT enable auto-merge either (see the gh error above) —\\n' +\n                '      NOTHING is queued. Re-run once the PR is healthy.',\n                MERGE_RESULT_FAILED);\n        }\n        if (state.isBehind()) return this.behindOutcome(state, true);\n        return new MergeOutcome(false, true,\n            `enabled auto-merge — it will squash-merge as \"${subject}\" when the checks pass`,\n            MERGE_RESULT_AUTO_QUEUED);\n    }\n\n    /**\n     * The one outcome that looks queued but is stranded. `queued` says whether auto-merge did get enabled,\n     * because \"parked forever\" and \"not queued at all\" need different sentences — but neither is done.\n     *\n     * The `result` now carries WHICH kind of behind, so the banner can stop describing a queue collision\n     * in the vocabulary of a merge conflict. The wording here is deliberately blame-free: nothing the\n     * author did caused this, and the PR itself is in perfectly good shape — pushed, bodied, gate-green.\n     */\n    private behindOutcome(state: PrMergeState, queued: boolean): MergeOutcome {\n        const parked = queued ? 'Auto-merge is enabled but parked.' : 'Nothing is queued.';\n        return new MergeOutcome(false, queued,\n            `did NOT merge — someone else landed on main first, so GitHub wants this branch rebuilt on\\n` +\n            `      top of theirs before it will merge (${state.describe()}).\\n` +\n            `      This does NOT self-heal: auto-merge never updates your branch. ${parked}`,\n            state.behindKind());\n    }\n\n    // Reprint the expected first-attempt failure as CONTEXT, not as a verdict. gh's own `X …` line is\n    // captured (never inherited) so this framing is the only thing on screen.\n    private announceDirectFailure(ghOutput: string, state: PrMergeState): void {\n        const reason = ghOutput.trim().split('\\n').filter((l: string): boolean => l.trim() !== '').pop() ?? '';\n        process.stdout.write(\n            'ℹ️  the direct squash-merge did not go through (expected while checks run, or when repo\\n' +\n            '   policy forbids direct merges):\\n' +\n            (reason === '' ? '' : `      ${reason}\\n`) +\n            (state.describe() === '' ? '' : `   GitHub says: ${state.describe()}\\n`),\n        );\n    }\n\n    /**\n     * GitHub's own verdict on the PR. AUTHORITATIVE for the BEHIND check — the alternative is\n     * pattern-matching gh's English error prose, which changes between releases. Failure-tolerant on\n     * purpose: a gh hiccup returns an all-'' state (never BEHIND) so a transient API blip can only cost\n     * us the extra diagnosis, never turn a working run into a crash.\n     */\n    protected prMergeState(baseBranch: string): PrMergeState {\n        const result = spawnSync(\n            'gh',\n            ['pr', 'view', baseBranch, '--json', 'mergeable,mergeStateStatus,state',\n                '--jq', '\"\\\\(.mergeable)\\\\t\\\\(.mergeStateStatus)\\\\t\\\\(.state)\"'],\n            { encoding: 'utf8' },\n        );\n        if (result.status !== 0) return new PrMergeState('', '', '');\n        const parts = (result.stdout ?? '').trim().split('\\t');\n        return new PrMergeState(parts[0] ?? '', parts[1] ?? '', parts[2] ?? '');\n    }\n\n    // Whether `gh pr merge --auto` is even possible on this repo. Many orgs set allow_auto_merge=false\n    // as a policy control, where `--auto` can only ever fail with `GraphQL: Auto merge is not allowed\n    // for this repository`. One API call beats discovering that from an error string. Anything other\n    // than a clean `true` counts as NOT allowed: if the setting cannot be read we must not claim the\n    // queue is available.\n    protected autoMergeAllowed(): boolean {\n        const result = spawnSync('gh', ['api', 'repos/{owner}/{repo}', '--jq', '.allow_auto_merge'], { encoding: 'utf8' });\n        return result.status === 0 && (result.stdout ?? '').trim() === 'true';\n    }\n\n    // Runs `gh`, returning its exit status (-1 when gh could not be spawned at all, which must NOT be\n    // mistaken for the 0 that means success).\n    protected gh(args: string[], quiet: boolean = false): number {\n        const result = spawnSync('gh', args, { stdio: quiet ? 'ignore' : 'inherit' });\n        return result.status ?? -1;\n    }\n\n    // Runs `gh` CAPTURING both streams instead of inheriting them, so an expected-to-fail attempt can be\n    // reported in our own words rather than dumping a raw `X …` line the reader reads as fatal.\n    protected ghCapture(args: string[]): GhResult {\n        const result = spawnSync('gh', args, { encoding: 'utf8' });\n        return new GhResult(result.status ?? -1, (result.stdout ?? '') + (result.stderr ?? ''));\n    }\n}\n\n// A captured `gh` invocation: its exit status (-1 when gh could not be spawned) and both streams\n// combined, in the order a terminal would have shown them.\nexport class GhResult {\n    status: number;\n    output: string;\n\n    constructor(status: number, output: string) {\n        this.status = status;\n        this.output = output;\n    }\n}\n"]}

package/src/scripts/workflow/review-report.d.ts

@@ -29,7 +29,7 @@ export declare class ReviewReportInput {
  *
  * The invariants, enforced by review-report.spec.ts:
  *   1. `wp-finish-upsert-pr` is named as a thing to run EXACTLY ONCE in the whole block.
- *   2. The review.json instruction comes BEFORE it.
+ *   2. The review.json instruction comes BEFORE it — and BEFORE the spawn blocks (see nextSteps).
  *   3. With zero checklists the all-clear precedes any configuration guidance.
  *
  * Pure string building, no I/O. `@injectable(bindingScopeValues.Singleton)` so it is injected by type.
@@ -40,22 +40,43 @@ export declare class ReviewReport {
     constructor(checklistNotice: ChecklistNotice, reviewerInstructions: ReviewerInstructionsService);
     render(input: ReviewReportInput): string;
     private header;
-    private checklistSection;
+    /**
+     * What the SCAN found: either "nothing applies here" or the already-reviewed / unreadable-verdict lines.
+     * Verdicts, not instructions — every instruction lives in nextSteps() below, so no line up here can be
+     * mistaken for the next action.
+     */
+    private scanVerdict;
     /**
      * The ONE instruction block, and the last thing the stage prints. Numbered rather than prose-linked
      * ("Then… Finally…") so that skipping step 1 is visibly skipping a step, and worded so no earlier line
      * can be mistaken for the real next action.
      *
+     * review.json is STEP 1 and the spawn blocks are STEP 2 — that ORDER is the contract, not a preference.
+     * This block used to print the spawn blocks first and then say to write review.json "WHILE any reviewer
+     * subagents above are still running", which does not merely permit spawning first, it instructs it.
+     * Harmless for a reviewer that only reads the diff; wrong for one that judges the PR's stated INTENT —
+     * its title, summary or risk level — because review.json is the only place that intent lives. Such a
+     * reviewer either finds no file (a false RED and a wasted reviewer run) or, on a second run of this
+     * stage on the same branch, finds the PREVIOUS run's file and validates a title that no longer exists —
+     * a false GREEN, with nothing in the output saying which of the two happened. A consuming repo had to
+     * write itself a rule telling its agents to DISOBEY this block to work around it.
+     *
+     * What the old ordering bought was overlap on a single local file write, not a subagent round-trip.
+     *
      * The schema hint is rendered by ReviewJsonService — the single renderer — so the shape printed here
      * can never drift from the shape `wp-finish-upsert-pr` validates.
      */
     private nextSteps;
+    private writeReviewStep;
     /**
-     * One copy-paste block per owed reviewer. The prompt is deliberately a POINTER and nothing else: the
-     * generated instructions file is the contract, so anything restated here is a second copy that can go
-     * stale — which is exactly how a removed `success` field outlived its own removal in print.
+     * STEP 2 — one copy-paste block per owed reviewer, and nothing at all when none is owed. The prompt is
+     * deliberately a POINTER and nothing else: the generated instructions file is the contract, so anything
+     * restated here is a second copy that can go stale — which is exactly how a removed `success` field
+     * outlived its own removal in print.
      */
-    private spawnBlocks;
+    private spawnStep;
+    private finishStep;
+    private owedReviewers;
     private oneSpawnBlock;
     private why;
 }

package/src/scripts/workflow/review-report.js

@@ -45,7 +45,7 @@ exports.ReviewReportInput = ReviewReportInput;
  *
  * The invariants, enforced by review-report.spec.ts:
  *   1. `wp-finish-upsert-pr` is named as a thing to run EXACTLY ONCE in the whole block.
- *   2. The review.json instruction comes BEFORE it.
+ *   2. The review.json instruction comes BEFORE it — and BEFORE the spawn blocks (see nextSteps).
  *   3. With zero checklists the all-clear precedes any configuration guidance.
  *
  * Pure string building, no I/O. `@injectable(bindingScopeValues.Singleton)` so it is injected by type.
@@ -58,50 +58,27 @@ let ReviewReport = class ReviewReport {
         this.reviewerInstructions = reviewerInstructions;
     }
     render(input) {
-        return '\n' + SEP + this.header(input) + SEP + '\n'
-            + this.checklistSection(input)
-            + this.nextSteps(input.reviewPath);
+        return '\n' + SEP + this.header(input) + SEP
+            + this.scanVerdict(input)
+            + this.nextSteps(input);
     }
     // Name what this block is actually about. A repo with reviewers owed is being told to SPAWN; a repo
     // with none is not, and promising subagents it does not have is the same kind of noise as explaining
-    // checklist configuration to a repo that configured none.
+    // checklist configuration to a repo that configured none. Keyed on what is actually OWED rather than on
+    // the applicable count: every applicable checklist already having a verdict means nothing to spawn.
     header(input) {
-        if (input.applicableCount === 0)
+        if (this.owedReviewers(input).length === 0)
             return '② Review, then finish\n';
-        return '② Spawn Subagent Reviews, then finish\n';
-    }
-    // Either "nothing applies here" or the copy-paste spawn blocks — never both, and neither one ends with
-    // a command to run: the single next step lives in nextSteps() below.
-    checklistSection(input) {
-        if (input.applicableCount === 0)
-            return this.checklistNotice.build(input.definedCount);
-        return this.spawnBlocks(input);
-    }
-    /**
-     * The ONE instruction block, and the last thing the stage prints. Numbered rather than prose-linked
-     * ("Then… Finally…") so that skipping step 1 is visibly skipping a step, and worded so no earlier line
-     * can be mistaken for the real next action.
-     *
-     * The schema hint is rendered by ReviewJsonService — the single renderer — so the shape printed here
-     * can never drift from the shape `wp-finish-upsert-pr` validates.
-     */
-    nextSteps(reviewPath) {
-        return ('\n' + SEP +
-            '▶ NEXT — two steps, in this order. Step 1 is NOT optional:\n' + SEP + '\n' +
-            'STEP 1 — review your own changes, then write the review file (finish REFUSES without it).\n' +
-            '         Do this WHILE any reviewer subagents above are still running:\n\n' +
-            (0, rules_config_1.reviewJsonSchemaHint)(reviewPath) + '\n\n' +
-            'STEP 2 — only once that file exists, run:  pnpm wp-finish-upsert-pr\n' +
-            '         (The build gate is already green for this commit — finish reuses it unless HEAD moves.)\n\n');
+        return '② Review, spawn subagent reviewers, then finish\n';
     }
     /**
-     * One copy-paste block per owed reviewer. The prompt is deliberately a POINTER and nothing else: the
-     * generated instructions file is the contract, so anything restated here is a second copy that can go
-     * stale — which is exactly how a removed `success` field outlived its own removal in print.
+     * What the SCAN found: either "nothing applies here" or the already-reviewed / unreadable-verdict lines.
+     * Verdicts, not instructions — every instruction lives in nextSteps() below, so no line up here can be
+     * mistaken for the next action.
      */
-    spawnBlocks(input) {
-        const reviewedIds = new Set(input.reviewed.map((r) => r.id));
-        const owed = input.briefings.filter((b) => !reviewedIds.has(b.checklistId));
+    scanVerdict(input) {
+        if (input.applicableCount === 0)
+            return '\n' + this.checklistNotice.build(input.definedCount);
         const lines = [];
         for (const r of input.reviewed) {
             lines.push(`  ✓ ${r.subagent} — already reviewed on this branch (reusing its review-${r.id}.json)`);
@@ -111,15 +88,83 @@ let ReviewReport = class ReviewReport {
         // correcting the file sitting right there.
         for (const e of input.formatErrors)
             lines.push(`  ⛔ ${e}`);
-        if (owed.length === 0) {
+        if (this.owedReviewers(input).length === 0) {
             lines.push('', '✅ Every checklist that applies is already reviewed — nothing to spawn.');
-            return lines.join('\n') + '\n';
         }
-        lines.push('', `Spawn these ${owed.length} reviewer subagent(s) — a SEPARATE one each. You may NOT review your own`, 'work, and you may NOT write a reviewer\'s verdict file on its behalf.', '');
+        if (lines.length === 0)
+            return '';
+        return '\n' + lines.join('\n') + '\n';
+    }
+    /**
+     * The ONE instruction block, and the last thing the stage prints. Numbered rather than prose-linked
+     * ("Then… Finally…") so that skipping step 1 is visibly skipping a step, and worded so no earlier line
+     * can be mistaken for the real next action.
+     *
+     * review.json is STEP 1 and the spawn blocks are STEP 2 — that ORDER is the contract, not a preference.
+     * This block used to print the spawn blocks first and then say to write review.json "WHILE any reviewer
+     * subagents above are still running", which does not merely permit spawning first, it instructs it.
+     * Harmless for a reviewer that only reads the diff; wrong for one that judges the PR's stated INTENT —
+     * its title, summary or risk level — because review.json is the only place that intent lives. Such a
+     * reviewer either finds no file (a false RED and a wasted reviewer run) or, on a second run of this
+     * stage on the same branch, finds the PREVIOUS run's file and validates a title that no longer exists —
+     * a false GREEN, with nothing in the output saying which of the two happened. A consuming repo had to
+     * write itself a rule telling its agents to DISOBEY this block to work around it.
+     *
+     * What the old ordering bought was overlap on a single local file write, not a subagent round-trip.
+     *
+     * The schema hint is rendered by ReviewJsonService — the single renderer — so the shape printed here
+     * can never drift from the shape `wp-finish-upsert-pr` validates.
+     */
+    nextSteps(input) {
+        const owed = this.owedReviewers(input);
+        const stepCount = owed.length === 0 ? 2 : 3;
+        return '\n' + SEP
+            + `▶ NEXT — ${stepCount} steps, in this order. Step 1 is NOT optional:\n` + SEP + '\n'
+            + this.writeReviewStep(input.reviewPath)
+            + this.spawnStep(input, owed)
+            + this.finishStep(stepCount);
+    }
+    writeReviewStep(reviewPath) {
+        return ('STEP 1 — review your own changes, then write the review file. Write it FIRST — BEFORE you spawn\n' +
+            '         anything below. finish REFUSES without it, and a reviewer subagent may READ it: a\n' +
+            '         checklist that judges the PR title, summary or risk level reads exactly this file, so\n' +
+            '         writing it afterwards races that reviewer into seeing nothing — or, on a re-run of this\n' +
+            '         stage, into judging the PREVIOUS run\'s review of code that has since changed.\n\n' +
+            (0, rules_config_1.reviewJsonSchemaHint)(reviewPath) + '\n\n');
+    }
+    /**
+     * STEP 2 — one copy-paste block per owed reviewer, and nothing at all when none is owed. The prompt is
+     * deliberately a POINTER and nothing else: the generated instructions file is the contract, so anything
+     * restated here is a second copy that can go stale — which is exactly how a removed `success` field
+     * outlived its own removal in print.
+     */
+    spawnStep(input, owed) {
+        if (owed.length === 0)
+            return '';
+        const lines = [
+            `STEP 2 — only once that file is written, spawn these ${owed.length} reviewer subagent(s) — a SEPARATE`,
+            '         one each. You may NOT review your own work, and you may NOT write a reviewer\'s verdict',
+            '         file on its behalf.',
+            '',
+        ];
         for (const b of owed)
             lines.push(...this.oneSpawnBlock(input, b));
+        lines.push('');
         return lines.join('\n');
     }
+    finishStep(stepNumber) {
+        const precondition = stepNumber === 3
+            ? 'once every reviewer above has written its verdict file'
+            : 'once that file exists';
+        return (`STEP ${stepNumber} — only ${precondition}, run:  pnpm wp-finish-upsert-pr\n` +
+            '         (The build gate is already green for this commit — finish reuses it unless HEAD moves.)\n\n');
+    }
+    // The briefings with no passing verdict yet — the ONE definition of "owed", shared by the header, the
+    // scan verdict and the step numbering, so they cannot disagree about whether there is anything to spawn.
+    owedReviewers(input) {
+        const reviewedIds = new Set(input.reviewed.map((r) => r.id));
+        return input.briefings.filter((b) => !reviewedIds.has(b.checklistId));
+    }
     oneSpawnBlock(input, b) {
         return [
             `  ▶ ${b.subagent} — ${this.why(b)}`,

package/src/scripts/workflow/review-report.js.map

@@ -1 +1 @@
-{"version":3,"file":"review-report.js","sourceRoot":"","sources":["../../../../../../../packages/tooling/pr-gate/src/scripts/workflow/review-report.ts"],"names":[],"mappings":"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","sourcesContent":["import { injectable, bindingScopeValues } from 'inversify';\nimport { reviewJsonSchemaHint, RequiredChecklist, ReviewerBriefing, ReviewerInstructionsService } from '@webpieces/rules-config';\nimport { ChecklistNotice } from './checklist-notice';\n\nconst SEP = '━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━\\n';\n\n/**\n * Everything the closing block of `wp-review-upsert-pr` needs. Data-only, and a class rather than an\n * object literal per CLAUDE.md. The three identifying paths are constructor args; the rest are optional\n * facts about the scan that default to \"nothing\", so a repo with no checklists constructs it in one line.\n */\nexport class ReviewReportInput {\n    repoRoot: string;\n    featureName: string;\n    reviewPath: string;             // the branch's review.json — the file the AI must write next\n    definedCount: number;           // how many checklists pr-gate.checklists defines\n    applicableCount: number;        // how many of them apply to THIS diff (0 ⇒ the notice, not spawn blocks)\n    reviewed: RequiredChecklist[];  // already have a passing verdict on this branch\n    formatErrors: string[];         // verdict files that exist but cannot be read as verdicts\n    briefings: ReviewerBriefing[];  // one per applicable checklist, already written to disk\n\n    constructor(repoRoot: string, featureName: string, reviewPath: string) {\n        this.repoRoot = repoRoot;\n        this.featureName = featureName;\n        this.reviewPath = reviewPath;\n        this.definedCount = 0;\n        this.applicableCount = 0;\n        this.reviewed = [];\n        this.formatErrors = [];\n        this.briefings = [];\n    }\n}\n\n/**\n * Renders the closing block of `wp-review-upsert-pr` — the checklist verdict, then EXACTLY ONE \"what to do\n * next\".\n *\n * Extracted from the command so it can be asserted on as a rendered string, because the ordering IS the\n * contract. The bug it was extracted to fix: the zero-checklist notice ended with \"Carry on and run: pnpm\n * wp-finish-upsert-pr\", and the block printed directly beneath it said to write review.json first and\n * finish afterwards. Two next-steps, in the wrong order, and an agent that follows instructions literally —\n * which is the entire reason this command prints them — took the first one and opened a PR with no review.\n * That is precisely the failure the three-stage flow exists to prevent (reported on PR #519).\n *\n * The invariants, enforced by review-report.spec.ts:\n *   1. `wp-finish-upsert-pr` is named as a thing to run EXACTLY ONCE in the whole block.\n *   2. The review.json instruction comes BEFORE it.\n *   3. With zero checklists the all-clear precedes any configuration guidance.\n *\n * Pure string building, no I/O. `@injectable(bindingScopeValues.Singleton)` so it is injected by type.\n */\n@injectable(bindingScopeValues.Singleton)\nexport class ReviewReport {\n    constructor(\n        private readonly checklistNotice: ChecklistNotice,\n        private readonly reviewerInstructions: ReviewerInstructionsService,\n    ) {}\n\n    render(input: ReviewReportInput): string {\n        return '\\n' + SEP + this.header(input) + SEP + '\\n'\n            + this.checklistSection(input)\n            + this.nextSteps(input.reviewPath);\n    }\n\n    // Name what this block is actually about. A repo with reviewers owed is being told to SPAWN; a repo\n    // with none is not, and promising subagents it does not have is the same kind of noise as explaining\n    // checklist configuration to a repo that configured none.\n    private header(input: ReviewReportInput): string {\n        if (input.applicableCount === 0) return '② Review, then finish\\n';\n        return '② Spawn Subagent Reviews, then finish\\n';\n    }\n\n    // Either \"nothing applies here\" or the copy-paste spawn blocks — never both, and neither one ends with\n    // a command to run: the single next step lives in nextSteps() below.\n    private checklistSection(input: ReviewReportInput): string {\n        if (input.applicableCount === 0) return this.checklistNotice.build(input.definedCount);\n        return this.spawnBlocks(input);\n    }\n\n    /**\n     * The ONE instruction block, and the last thing the stage prints. Numbered rather than prose-linked\n     * (\"Then… Finally…\") so that skipping step 1 is visibly skipping a step, and worded so no earlier line\n     * can be mistaken for the real next action.\n     *\n     * The schema hint is rendered by ReviewJsonService — the single renderer — so the shape printed here\n     * can never drift from the shape `wp-finish-upsert-pr` validates.\n     */\n    private nextSteps(reviewPath: string): string {\n        return (\n            '\\n' + SEP +\n            '▶ NEXT — two steps, in this order. Step 1 is NOT optional:\\n' + SEP + '\\n' +\n            'STEP 1 — review your own changes, then write the review file (finish REFUSES without it).\\n' +\n            '         Do this WHILE any reviewer subagents above are still running:\\n\\n' +\n            reviewJsonSchemaHint(reviewPath) + '\\n\\n' +\n            'STEP 2 — only once that file exists, run:  pnpm wp-finish-upsert-pr\\n' +\n            '         (The build gate is already green for this commit — finish reuses it unless HEAD moves.)\\n\\n'\n        );\n    }\n\n    /**\n     * One copy-paste block per owed reviewer. The prompt is deliberately a POINTER and nothing else: the\n     * generated instructions file is the contract, so anything restated here is a second copy that can go\n     * stale — which is exactly how a removed `success` field outlived its own removal in print.\n     */\n    private spawnBlocks(input: ReviewReportInput): string {\n        const reviewedIds = new Set(input.reviewed.map((r: RequiredChecklist): string => r.id));\n        const owed = input.briefings.filter((b: ReviewerBriefing): boolean => !reviewedIds.has(b.checklistId));\n        const lines: string[] = [];\n        for (const r of input.reviewed) {\n            lines.push(`  ✓ ${r.subagent} — already reviewed on this branch (reusing its review-${r.id}.json)`);\n        }\n        // A verdict file that EXISTS but is unreadable as a verdict is called out here. Without it this\n        // reports the checklist as simply owed, and the AI re-runs a reviewer that already ran instead of\n        // correcting the file sitting right there.\n        for (const e of input.formatErrors) lines.push(`  ⛔ ${e}`);\n        if (owed.length === 0) {\n            lines.push('', '✅ Every checklist that applies is already reviewed — nothing to spawn.');\n            return lines.join('\\n') + '\\n';\n        }\n        lines.push('',\n            `Spawn these ${owed.length} reviewer subagent(s) — a SEPARATE one each. You may NOT review your own`,\n            'work, and you may NOT write a reviewer\\'s verdict file on its behalf.',\n            '');\n        for (const b of owed) lines.push(...this.oneSpawnBlock(input, b));\n        return lines.join('\\n');\n    }\n\n    private oneSpawnBlock(input: ReviewReportInput, b: ReviewerBriefing): string[] {\n        return [\n            `  ▶ ${b.subagent} — ${this.why(b)}`,\n            `      subagent_type: ${b.subagent}`,\n            '      prompt:        Read your instructions file FIRST and follow it exactly:',\n            `                     ${this.reviewerInstructions.pathFor(input.repoRoot, input.featureName, b.subagent)}`,\n            '',\n        ];\n    }\n\n    // Why this one is in scope. A patternless checklist is NOT \"matched\" — it always runs, over the whole\n    // diff, and saying so is what tells a repo its checklist is firing on docs-only PRs by design.\n    private why(b: ReviewerBriefing): string {\n        if (b.matchedPatterns.length === 0) {\n            return `ALWAYS RUNS (no \"patterns\" configured), whole diff in scope — ${b.myFiles.length} file(s)`;\n        }\n        return `${b.myFiles.length} file(s) matched ${b.matchedPatterns.map((p: string): string => `\"${p}\"`).join(', ')}`;\n    }\n}\n"]}
+{"version":3,"file":"review-report.js","sourceRoot":"","sources":["../../../../../../../packages/tooling/pr-gate/src/scripts/workflow/review-report.ts"],"names":[],"mappings":";;;;AAAA,yCAA2D;AAC3D,0DAAiI;AACjI,yDAAqD;AAErD,MAAM,GAAG,GAAG,0DAA0D,CAAC;AAEvE;;;;GAIG;AACH,MAAa,iBAAiB;IAC1B,QAAQ,CAAS;IACjB,WAAW,CAAS;IACpB,UAAU,CAAS,CAAa,6DAA6D;IAC7F,YAAY,CAAS,CAAW,iDAAiD;IACjF,eAAe,CAAS,CAAQ,yEAAyE;IACzG,QAAQ,CAAsB,CAAE,gDAAgD;IAChF,YAAY,CAAW,CAAS,0DAA0D;IAC1F,SAAS,CAAqB,CAAE,wDAAwD;IAExF,YAAY,QAAgB,EAAE,WAAmB,EAAE,UAAkB;QACjE,IAAI,CAAC,QAAQ,GAAG,QAAQ,CAAC;QACzB,IAAI,CAAC,WAAW,GAAG,WAAW,CAAC;QAC/B,IAAI,CAAC,UAAU,GAAG,UAAU,CAAC;QAC7B,IAAI,CAAC,YAAY,GAAG,CAAC,CAAC;QACtB,IAAI,CAAC,eAAe,GAAG,CAAC,CAAC;QACzB,IAAI,CAAC,QAAQ,GAAG,EAAE,CAAC;QACnB,IAAI,CAAC,YAAY,GAAG,EAAE,CAAC;QACvB,IAAI,CAAC,SAAS,GAAG,EAAE,CAAC;IACxB,CAAC;CACJ;AApBD,8CAoBC;AAED;;;;;;;;;;;;;;;;;GAiBG;AAEI,IAAM,YAAY,GAAlB,MAAM,YAAY;IAEA;IACA;IAFrB,YACqB,eAAgC,EAChC,oBAAiD;QADjD,oBAAe,GAAf,eAAe,CAAiB;QAChC,yBAAoB,GAApB,oBAAoB,CAA6B;IACnE,CAAC;IAEJ,MAAM,CAAC,KAAwB;QAC3B,OAAO,IAAI,GAAG,GAAG,GAAG,IAAI,CAAC,MAAM,CAAC,KAAK,CAAC,GAAG,GAAG;cACtC,IAAI,CAAC,WAAW,CAAC,KAAK,CAAC;cACvB,IAAI,CAAC,SAAS,CAAC,KAAK,CAAC,CAAC;IAChC,CAAC;IAED,oGAAoG;IACpG,qGAAqG;IACrG,wGAAwG;IACxG,oGAAoG;IAC5F,MAAM,CAAC,KAAwB;QACnC,IAAI,IAAI,CAAC,aAAa,CAAC,KAAK,CAAC,CAAC,MAAM,KAAK,CAAC;YAAE,OAAO,yBAAyB,CAAC;QAC7E,OAAO,mDAAmD,CAAC;IAC/D,CAAC;IAED;;;;OAIG;IACK,WAAW,CAAC,KAAwB;QACxC,IAAI,KAAK,CAAC,eAAe,KAAK,CAAC;YAAE,OAAO,IAAI,GAAG,IAAI,CAAC,eAAe,CAAC,KAAK,CAAC,KAAK,CAAC,YAAY,CAAC,CAAC;QAC9F,MAAM,KAAK,GAAa,EAAE,CAAC;QAC3B,KAAK,MAAM,CAAC,IAAI,KAAK,CAAC,QAAQ,EAAE,CAAC;YAC7B,KAAK,CAAC,IAAI,CAAC,OAAO,CAAC,CAAC,QAAQ,0DAA0D,CAAC,CAAC,EAAE,QAAQ,CAAC,CAAC;QACxG,CAAC;QACD,gGAAgG;QAChG,kGAAkG;QAClG,2CAA2C;QAC3C,KAAK,MAAM,CAAC,IAAI,KAAK,CAAC,YAAY;YAAE,KAAK,CAAC,IAAI,CAAC,OAAO,CAAC,EAAE,CAAC,CAAC;QAC3D,IAAI,IAAI,CAAC,aAAa,CAAC,KAAK,CAAC,CAAC,MAAM,KAAK,CAAC,EAAE,CAAC;YACzC,KAAK,CAAC,IAAI,CAAC,EAAE,EAAE,wEAAwE,CAAC,CAAC;QAC7F,CAAC;QACD,IAAI,KAAK,CAAC,MAAM,KAAK,CAAC;YAAE,OAAO,EAAE,CAAC;QAClC,OAAO,IAAI,GAAG,KAAK,CAAC,IAAI,CAAC,IAAI,CAAC,GAAG,IAAI,CAAC;IAC1C,CAAC;IAED;;;;;;;;;;;;;;;;;;;OAmBG;IACK,SAAS,CAAC,KAAwB;QACtC,MAAM,IAAI,GAAG,IAAI,CAAC,aAAa,CAAC,KAAK,CAAC,CAAC;QACvC,MAAM,SAAS,GAAG,IAAI,CAAC,MAAM,KAAK,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC;QAC5C,OAAO,IAAI,GAAG,GAAG;cACX,YAAY,SAAS,kDAAkD,GAAG,GAAG,GAAG,IAAI;cACpF,IAAI,CAAC,eAAe,CAAC,KAAK,CAAC,UAAU,CAAC;cACtC,IAAI,CAAC,SAAS,CAAC,KAAK,EAAE,IAAI,CAAC;cAC3B,IAAI,CAAC,UAAU,CAAC,SAAS,CAAC,CAAC;IACrC,CAAC;IAEO,eAAe,CAAC,UAAkB;QACtC,OAAO,CACH,mGAAmG;YACnG,8FAA8F;YAC9F,kGAAkG;YAClG,oGAAoG;YACpG,6FAA6F;YAC7F,IAAA,mCAAoB,EAAC,UAAU,CAAC,GAAG,MAAM,CAC5C,CAAC;IACN,CAAC;IAED;;;;;OAKG;IACK,SAAS,CAAC,KAAwB,EAAE,IAAiC;QACzE,IAAI,IAAI,CAAC,MAAM,KAAK,CAAC;YAAE,OAAO,EAAE,CAAC;QACjC,MAAM,KAAK,GAAa;YACpB,wDAAwD,IAAI,CAAC,MAAM,oCAAoC;YACvG,kGAAkG;YAClG,8BAA8B;YAC9B,EAAE;SACL,CAAC;QACF,KAAK,MAAM,CAAC,IAAI,IAAI;YAAE,KAAK,CAAC,IAAI,CAAC,GAAG,IAAI,CAAC,aAAa,CAAC,KAAK,EAAE,CAAC,CAAC,CAAC,CAAC;QAClE,KAAK,CAAC,IAAI,CAAC,EAAE,CAAC,CAAC;QACf,OAAO,KAAK,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC;IAC5B,CAAC;IAEO,UAAU,CAAC,UAAkB;QACjC,MAAM,YAAY,GAAG,UAAU,KAAK,CAAC;YACjC,CAAC,CAAC,wDAAwD;YAC1D,CAAC,CAAC,uBAAuB,CAAC;QAC9B,OAAO,CACH,QAAQ,UAAU,WAAW,YAAY,oCAAoC;YAC7E,sGAAsG,CACzG,CAAC;IACN,CAAC;IAED,sGAAsG;IACtG,yGAAyG;IACjG,aAAa,CAAC,KAAwB;QAC1C,MAAM,WAAW,GAAG,IAAI,GAAG,CAAC,KAAK,CAAC,QAAQ,CAAC,GAAG,CAAC,CAAC,CAAoB,EAAU,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC;QACxF,OAAO,KAAK,CAAC,SAAS,CAAC,MAAM,CAAC,CAAC,CAAmB,EAAW,EAAE,CAAC,CAAC,WAAW,CAAC,GAAG,CAAC,CAAC,CAAC,WAAW,CAAC,CAAC,CAAC;IACrG,CAAC;IAEO,aAAa,CAAC,KAAwB,EAAE,CAAmB;QAC/D,OAAO;YACH,OAAO,CAAC,CAAC,QAAQ,MAAM,IAAI,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE;YACpC,wBAAwB,CAAC,CAAC,QAAQ,EAAE;YACpC,+EAA+E;YAC/E,wBAAwB,IAAI,CAAC,oBAAoB,CAAC,OAAO,CAAC,KAAK,CAAC,QAAQ,EAAE,KAAK,CAAC,WAAW,EAAE,CAAC,CAAC,QAAQ,CAAC,EAAE;YAC1G,EAAE;SACL,CAAC;IACN,CAAC;IAED,sGAAsG;IACtG,+FAA+F;IACvF,GAAG,CAAC,CAAmB;QAC3B,IAAI,CAAC,CAAC,eAAe,CAAC,MAAM,KAAK,CAAC,EAAE,CAAC;YACjC,OAAO,iEAAiE,CAAC,CAAC,OAAO,CAAC,MAAM,UAAU,CAAC;QACvG,CAAC;QACD,OAAO,GAAG,CAAC,CAAC,OAAO,CAAC,MAAM,oBAAoB,CAAC,CAAC,eAAe,CAAC,GAAG,CAAC,CAAC,CAAS,EAAU,EAAE,CAAC,IAAI,CAAC,GAAG,CAAC,CAAC,IAAI,CAAC,IAAI,CAAC,EAAE,CAAC;IACtH,CAAC;CACJ,CAAA;AA1IY,oCAAY;uBAAZ,YAAY;IADxB,IAAA,sBAAU,EAAC,8BAAkB,CAAC,SAAS,CAAC;6CAGC,kCAAe;QACV,0CAA2B;GAH7D,YAAY,CA0IxB","sourcesContent":["import { injectable, bindingScopeValues } from 'inversify';\nimport { reviewJsonSchemaHint, RequiredChecklist, ReviewerBriefing, ReviewerInstructionsService } from '@webpieces/rules-config';\nimport { ChecklistNotice } from './checklist-notice';\n\nconst SEP = '━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━\\n';\n\n/**\n * Everything the closing block of `wp-review-upsert-pr` needs. Data-only, and a class rather than an\n * object literal per CLAUDE.md. The three identifying paths are constructor args; the rest are optional\n * facts about the scan that default to \"nothing\", so a repo with no checklists constructs it in one line.\n */\nexport class ReviewReportInput {\n    repoRoot: string;\n    featureName: string;\n    reviewPath: string;             // the branch's review.json — the file the AI must write next\n    definedCount: number;           // how many checklists pr-gate.checklists defines\n    applicableCount: number;        // how many of them apply to THIS diff (0 ⇒ the notice, not spawn blocks)\n    reviewed: RequiredChecklist[];  // already have a passing verdict on this branch\n    formatErrors: string[];         // verdict files that exist but cannot be read as verdicts\n    briefings: ReviewerBriefing[];  // one per applicable checklist, already written to disk\n\n    constructor(repoRoot: string, featureName: string, reviewPath: string) {\n        this.repoRoot = repoRoot;\n        this.featureName = featureName;\n        this.reviewPath = reviewPath;\n        this.definedCount = 0;\n        this.applicableCount = 0;\n        this.reviewed = [];\n        this.formatErrors = [];\n        this.briefings = [];\n    }\n}\n\n/**\n * Renders the closing block of `wp-review-upsert-pr` — the checklist verdict, then EXACTLY ONE \"what to do\n * next\".\n *\n * Extracted from the command so it can be asserted on as a rendered string, because the ordering IS the\n * contract. The bug it was extracted to fix: the zero-checklist notice ended with \"Carry on and run: pnpm\n * wp-finish-upsert-pr\", and the block printed directly beneath it said to write review.json first and\n * finish afterwards. Two next-steps, in the wrong order, and an agent that follows instructions literally —\n * which is the entire reason this command prints them — took the first one and opened a PR with no review.\n * That is precisely the failure the three-stage flow exists to prevent (reported on PR #519).\n *\n * The invariants, enforced by review-report.spec.ts:\n *   1. `wp-finish-upsert-pr` is named as a thing to run EXACTLY ONCE in the whole block.\n *   2. The review.json instruction comes BEFORE it — and BEFORE the spawn blocks (see nextSteps).\n *   3. With zero checklists the all-clear precedes any configuration guidance.\n *\n * Pure string building, no I/O. `@injectable(bindingScopeValues.Singleton)` so it is injected by type.\n */\n@injectable(bindingScopeValues.Singleton)\nexport class ReviewReport {\n    constructor(\n        private readonly checklistNotice: ChecklistNotice,\n        private readonly reviewerInstructions: ReviewerInstructionsService,\n    ) {}\n\n    render(input: ReviewReportInput): string {\n        return '\\n' + SEP + this.header(input) + SEP\n            + this.scanVerdict(input)\n            + this.nextSteps(input);\n    }\n\n    // Name what this block is actually about. A repo with reviewers owed is being told to SPAWN; a repo\n    // with none is not, and promising subagents it does not have is the same kind of noise as explaining\n    // checklist configuration to a repo that configured none. Keyed on what is actually OWED rather than on\n    // the applicable count: every applicable checklist already having a verdict means nothing to spawn.\n    private header(input: ReviewReportInput): string {\n        if (this.owedReviewers(input).length === 0) return '② Review, then finish\\n';\n        return '② Review, spawn subagent reviewers, then finish\\n';\n    }\n\n    /**\n     * What the SCAN found: either \"nothing applies here\" or the already-reviewed / unreadable-verdict lines.\n     * Verdicts, not instructions — every instruction lives in nextSteps() below, so no line up here can be\n     * mistaken for the next action.\n     */\n    private scanVerdict(input: ReviewReportInput): string {\n        if (input.applicableCount === 0) return '\\n' + this.checklistNotice.build(input.definedCount);\n        const lines: string[] = [];\n        for (const r of input.reviewed) {\n            lines.push(`  ✓ ${r.subagent} — already reviewed on this branch (reusing its review-${r.id}.json)`);\n        }\n        // A verdict file that EXISTS but is unreadable as a verdict is called out here. Without it this\n        // reports the checklist as simply owed, and the AI re-runs a reviewer that already ran instead of\n        // correcting the file sitting right there.\n        for (const e of input.formatErrors) lines.push(`  ⛔ ${e}`);\n        if (this.owedReviewers(input).length === 0) {\n            lines.push('', '✅ Every checklist that applies is already reviewed — nothing to spawn.');\n        }\n        if (lines.length === 0) return '';\n        return '\\n' + lines.join('\\n') + '\\n';\n    }\n\n    /**\n     * The ONE instruction block, and the last thing the stage prints. Numbered rather than prose-linked\n     * (\"Then… Finally…\") so that skipping step 1 is visibly skipping a step, and worded so no earlier line\n     * can be mistaken for the real next action.\n     *\n     * review.json is STEP 1 and the spawn blocks are STEP 2 — that ORDER is the contract, not a preference.\n     * This block used to print the spawn blocks first and then say to write review.json \"WHILE any reviewer\n     * subagents above are still running\", which does not merely permit spawning first, it instructs it.\n     * Harmless for a reviewer that only reads the diff; wrong for one that judges the PR's stated INTENT —\n     * its title, summary or risk level — because review.json is the only place that intent lives. Such a\n     * reviewer either finds no file (a false RED and a wasted reviewer run) or, on a second run of this\n     * stage on the same branch, finds the PREVIOUS run's file and validates a title that no longer exists —\n     * a false GREEN, with nothing in the output saying which of the two happened. A consuming repo had to\n     * write itself a rule telling its agents to DISOBEY this block to work around it.\n     *\n     * What the old ordering bought was overlap on a single local file write, not a subagent round-trip.\n     *\n     * The schema hint is rendered by ReviewJsonService — the single renderer — so the shape printed here\n     * can never drift from the shape `wp-finish-upsert-pr` validates.\n     */\n    private nextSteps(input: ReviewReportInput): string {\n        const owed = this.owedReviewers(input);\n        const stepCount = owed.length === 0 ? 2 : 3;\n        return '\\n' + SEP\n            + `▶ NEXT — ${stepCount} steps, in this order. Step 1 is NOT optional:\\n` + SEP + '\\n'\n            + this.writeReviewStep(input.reviewPath)\n            + this.spawnStep(input, owed)\n            + this.finishStep(stepCount);\n    }\n\n    private writeReviewStep(reviewPath: string): string {\n        return (\n            'STEP 1 — review your own changes, then write the review file. Write it FIRST — BEFORE you spawn\\n' +\n            '         anything below. finish REFUSES without it, and a reviewer subagent may READ it: a\\n' +\n            '         checklist that judges the PR title, summary or risk level reads exactly this file, so\\n' +\n            '         writing it afterwards races that reviewer into seeing nothing — or, on a re-run of this\\n' +\n            '         stage, into judging the PREVIOUS run\\'s review of code that has since changed.\\n\\n' +\n            reviewJsonSchemaHint(reviewPath) + '\\n\\n'\n        );\n    }\n\n    /**\n     * STEP 2 — one copy-paste block per owed reviewer, and nothing at all when none is owed. The prompt is\n     * deliberately a POINTER and nothing else: the generated instructions file is the contract, so anything\n     * restated here is a second copy that can go stale — which is exactly how a removed `success` field\n     * outlived its own removal in print.\n     */\n    private spawnStep(input: ReviewReportInput, owed: readonly ReviewerBriefing[]): string {\n        if (owed.length === 0) return '';\n        const lines: string[] = [\n            `STEP 2 — only once that file is written, spawn these ${owed.length} reviewer subagent(s) — a SEPARATE`,\n            '         one each. You may NOT review your own work, and you may NOT write a reviewer\\'s verdict',\n            '         file on its behalf.',\n            '',\n        ];\n        for (const b of owed) lines.push(...this.oneSpawnBlock(input, b));\n        lines.push('');\n        return lines.join('\\n');\n    }\n\n    private finishStep(stepNumber: number): string {\n        const precondition = stepNumber === 3\n            ? 'once every reviewer above has written its verdict file'\n            : 'once that file exists';\n        return (\n            `STEP ${stepNumber} — only ${precondition}, run:  pnpm wp-finish-upsert-pr\\n` +\n            '         (The build gate is already green for this commit — finish reuses it unless HEAD moves.)\\n\\n'\n        );\n    }\n\n    // The briefings with no passing verdict yet — the ONE definition of \"owed\", shared by the header, the\n    // scan verdict and the step numbering, so they cannot disagree about whether there is anything to spawn.\n    private owedReviewers(input: ReviewReportInput): ReviewerBriefing[] {\n        const reviewedIds = new Set(input.reviewed.map((r: RequiredChecklist): string => r.id));\n        return input.briefings.filter((b: ReviewerBriefing): boolean => !reviewedIds.has(b.checklistId));\n    }\n\n    private oneSpawnBlock(input: ReviewReportInput, b: ReviewerBriefing): string[] {\n        return [\n            `  ▶ ${b.subagent} — ${this.why(b)}`,\n            `      subagent_type: ${b.subagent}`,\n            '      prompt:        Read your instructions file FIRST and follow it exactly:',\n            `                     ${this.reviewerInstructions.pathFor(input.repoRoot, input.featureName, b.subagent)}`,\n            '',\n        ];\n    }\n\n    // Why this one is in scope. A patternless checklist is NOT \"matched\" — it always runs, over the whole\n    // diff, and saying so is what tells a repo its checklist is firing on docs-only PRs by design.\n    private why(b: ReviewerBriefing): string {\n        if (b.matchedPatterns.length === 0) {\n            return `ALWAYS RUNS (no \"patterns\" configured), whole diff in scope — ${b.myFiles.length} file(s)`;\n        }\n        return `${b.myFiles.length} file(s) matched ${b.matchedPatterns.map((p: string): string => `\"${p}\"`).join(', ')}`;\n    }\n}\n"]}