@webpieces/pr-gate 0.4.497 → 0.4.499

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

@@ -0,0 +1,244 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.ReviewUpsertPrCommand = void 0;
+const tslib_1 = require("tslib");
+const fs = tslib_1.__importStar(require("fs"));
+const path = tslib_1.__importStar(require("path"));
+const rules_config_1 = require("@webpieces/rules-config");
+const inversify_1 = require("inversify");
+const git_readAiBranchName_1 = require("../workflow/git-readAiBranchName");
+const build_affected_1 = require("../workflow/build-affected");
+const checklist_notice_1 = require("../workflow/checklist-notice");
+const checklist_scanner_1 = require("../workflow/checklist-scanner");
+const diff_materializer_1 = require("../workflow/diff-materializer");
+const git_exec_1 = require("../workflow/git-exec");
+const merge_start_1 = require("../workflow/merge-start");
+const merge_end_1 = require("../workflow/merge-end");
+const merge_state_1 = require("../workflow/merge-state");
+const reviewer_briefing_builder_1 = require("../workflow/reviewer-briefing-builder");
+const review_stage_receipt_1 = require("../workflow/review-stage-receipt");
+const SEP = '━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━\n';
+/**
+ * `wp-review-upsert-pr` — STAGE ② of the three-stage PR flow, between `wp-start-upsert-pr` (sync from main)
+ * and `wp-finish-upsert-pr` (post the PR).
+ *
+ * It exists because reviewing came before verifying. Under the old two-command flow the 3-point merge was
+ * finalized and the build gate ran inside `wp-finish-upsert-pr` — i.e. AFTER the reviewers had already run.
+ * A reviewer could therefore spend a full review on an unresolved merge, or on code that does not compile,
+ * and only afterwards would the branch be checked. This command puts the verification first:
+ *
+ *   1. finalize + VALIDATE any in-progress 3-point merge  (moved here from finish)
+ *   2. assert a clean tree                                 (meaningful now — step 1 committed the resolution)
+ *   3. run the build gate                                  (on the merged, committed tree)
+ *   4. scan the checklists, EXTRACT the diff, BRIEF the reviewers
+ *   5. write the stage receipt, then print what to spawn + the review.json schema
+ *
+ * Unlike the report-only command it replaces — which always exited 0, because reporting is not gating — this
+ * command CAN FAIL, at steps 1, 2 and 3. That is the point: it fails BEFORE any reviewer is spawned, so a
+ * branch with an unresolved merge or a broken build costs zero reviewer tokens.
+ *
+ * The ordering of 1 → 2 → 3 is load-bearing. MergeEnd stages and commits the conflict resolution, so the
+ * tree is clean by the time the build runs; building first would either build a dirty tree (proving nothing
+ * about what ships) or refuse a tree that is legitimately mid-resolution.
+ */
+let ReviewUpsertPrCommand = class ReviewUpsertPrCommand {
+    repoRootFinder;
+    aiBranchName;
+    gitExec;
+    buildAffected;
+    mergeState;
+    mergeEnd;
+    checklistScanner;
+    checklistNotice;
+    instructions;
+    materializer;
+    briefingBuilder;
+    reviewerInstructions;
+    receipts;
+    // eslint-disable-next-line @typescript-eslint/max-params
+    constructor(repoRootFinder, aiBranchName, gitExec, buildAffected, mergeState, mergeEnd, checklistScanner, checklistNotice, instructions, materializer, briefingBuilder, reviewerInstructions, receipts) {
+        this.repoRootFinder = repoRootFinder;
+        this.aiBranchName = aiBranchName;
+        this.gitExec = gitExec;
+        this.buildAffected = buildAffected;
+        this.mergeState = mergeState;
+        this.mergeEnd = mergeEnd;
+        this.checklistScanner = checklistScanner;
+        this.checklistNotice = checklistNotice;
+        this.instructions = instructions;
+        this.materializer = materializer;
+        this.briefingBuilder = briefingBuilder;
+        this.reviewerInstructions = reviewerInstructions;
+        this.receipts = receipts;
+    }
+    async run() {
+        const repoRoot = this.repoRootFinder.resolveRepoRoot(process.cwd());
+        (0, rules_config_1.writeTemplate)(repoRoot, 'webpieces.git-workflow.md');
+        (0, rules_config_1.writeTemplate)(repoRoot, 'webpieces.review-checklists.md');
+        const featureName = this.aiBranchName.getFeatureName();
+        const config = (0, rules_config_1.loadAndValidate)(repoRoot).prGate;
+        const mergeValidated = await this.finalizeAnyInProgressMerge(repoRoot);
+        this.gitExec.assertCleanTree(repoRoot);
+        const buildPassedAt = this.runBuildGate(repoRoot);
+        const scan = this.checklistScanner.scan(repoRoot, config.checklists, new checklist_scanner_1.ChecklistScanOptions(false));
+        const briefings = this.briefReviewers(repoRoot, featureName, scan, config);
+        this.receipts.write(repoRoot, featureName, new review_stage_receipt_1.ReviewStageReceipt(scan.basis.headSha, mergeValidated, this.buildAffected.resolveBuildCommand(repoRoot), buildPassedAt, briefings.map((b) => b.subagent)));
+        this.report(repoRoot, featureName, scan, briefings);
+    }
+    /**
+     * Validate + commit + finalize a conflict resolution, if one is in flight. MOVED here from
+     * `wp-finish-upsert-pr` so that exactly one command owns merge finalization — two owners is the drift
+     * failure `PrContextWriter`'s own docstring records having already happened once in this codebase.
+     *
+     * MergeEnd's three checks are what "did the AI do the 3-point merge right?" means concretely: no
+     * conflict markers left in the scoped files, `git diff --diff-filter=U` empty, and a non-empty
+     * merge-explanation.md beside every conflicted file.
+     *
+     * Returns true when a merge was finalized OR there was none to finalize; it throws rather than returning
+     * false when validation fails, so the receipt can never record an unvalidated merge as validated.
+     */
+    async finalizeAnyInProgressMerge(repoRoot) {
+        const home = this.mergeState.mergeDirFor(repoRoot, this.aiBranchName.getFeatureName());
+        const activeDir = this.mergeState.findActiveMergeRunDir(home);
+        const marker = activeDir ? this.mergeState.readMergeMarker(activeDir) : null;
+        if (!activeDir || !marker || marker.validated)
+            return true;
+        process.stdout.write('\n' + SEP + '① Validating your 3-point merge\n' + SEP + '\n');
+        // pushRemote:false — finish still owns the single push.
+        await this.mergeEnd.mergeEnd(repoRoot, 'wp-review-upsert-pr', activeDir, new merge_start_1.MergeContext(marker.currentBranch, marker.squashBranch, marker.backupBranch, marker.prNumber), new merge_end_1.MergeEndOptions(marker.conflictedFiles, false));
+        return true;
+    }
+    /**
+     * The build gate, run BEFORE any reviewer is briefed. Returns the ISO time it passed, for the receipt —
+     * which is what lets `wp-finish-upsert-pr` skip its own gate when HEAD has not moved, so moving the gate
+     * earlier did not turn one build into two.
+     */
+    runBuildGate(repoRoot) {
+        this.buildAffected.runBuildGate(repoRoot, new build_affected_1.BuildGateOptions('🛠️  Build gate (pre-review)', 'pnpm wp-review-upsert-pr', 'Build failed — NO reviewer was briefed and no diff was extracted. Fix it, then re-run.'));
+        return new Date().toISOString();
+    }
+    /**
+     * Extract the diff once, then write one instructions file per reviewer.
+     *
+     * The changed-file set and the basis both come off the SCAN rather than being recomputed, so the diff a
+     * reviewer reads covers exactly the files its checklist matched against.
+     */
+    briefReviewers(repoRoot, featureName, scan, config) {
+        if (scan.basis.unresolved)
+            return [];
+        const manifest = this.materializer.materialize(repoRoot, featureName, scan.basis, scan.changedFiles, config.reviewDiffExclude);
+        const diffDir = this.materializer.diffDirFor(repoRoot, featureName);
+        // Re-point pr-context.json at the extracted diff now that there is one — the scan wrote it before
+        // materialization, so without this the reviewers' own context file would not mention the diff dir.
+        this.rewritePrContext(repoRoot, featureName, diffDir);
+        const briefings = this.briefingBuilder.build(repoRoot, scan, manifest, diffDir, config);
+        const dir = this.reviewerInstructions.instructionsDirFor(repoRoot, featureName);
+        fs.rmSync(dir, { recursive: true, force: true }); // stale instructions read as current are worse than none
+        fs.mkdirSync(dir, { recursive: true });
+        for (const b of briefings) {
+            fs.writeFileSync(this.reviewerInstructions.pathFor(repoRoot, featureName, b.subagent), this.reviewerInstructions.render(b));
+        }
+        this.printDiffSummary(manifest, diffDir);
+        return briefings;
+    }
+    // pr-context.json is written by the scan (before the diff exists). Patch in the dir rather than
+    // re-deriving the whole context: re-deriving means a second basis resolution, which is the drift.
+    rewritePrContext(repoRoot, featureName, diffDir) {
+        const p = path.join(repoRoot, '.webpieces', 'pr-review', featureName, 'pr-context.json');
+        if (!fs.existsSync(p))
+            return;
+        // webpieces-disable no-unmanaged-exceptions -- chokepoint: an unreadable context is left as-is, never fatal
+        // eslint-disable-next-line @webpieces/no-unmanaged-exceptions
+        try {
+            // webpieces-disable no-any-unknown -- opaque parsed JSON, one key added
+            const raw = JSON.parse(fs.readFileSync(p, 'utf8'));
+            raw['diffDir'] = diffDir;
+            fs.writeFileSync(p, JSON.stringify(raw, null, 2) + '\n');
+        }
+        catch (err) {
+            const error = (0, rules_config_1.toError)(err);
+            void error; // leave the file as-is — the instructions files carry the same paths directly
+        }
+    }
+    printDiffSummary(manifest, diffDir) {
+        process.stdout.write('\n' + SEP + '② Diff extracted for the reviewers\n' + SEP + '\n');
+        process.stdout.write(`   ${manifest.entries.length} file(s) → ${diffDir}\n`);
+        if (manifest.excluded.length > 0) {
+            process.stdout.write(`   ${manifest.excluded.length} excluded by pr-gate.reviewDiffExclude (stubbed, still matched)\n`);
+        }
+        const truncated = manifest.entries.filter((e) => e.truncated).length;
+        if (truncated > 0)
+            process.stdout.write(`   ${truncated} truncated at the per-file cap (each says so in its footer)\n`);
+    }
+    /** What the AI must do next: spawn each reviewer, then write review.json. */
+    report(repoRoot, featureName, scan, briefings) {
+        process.stdout.write('\n' + SEP + '③ Review, then finish\n' + SEP + '\n');
+        if (scan.applicable.length === 0) {
+            process.stdout.write(this.checklistNotice.build(scan.defined.length, 'wp-finish-upsert-pr'));
+        }
+        else {
+            process.stdout.write(this.spawnBlocks(repoRoot, featureName, scan, briefings));
+        }
+        process.stdout.write(`\nThen review your own changes and\n${(0, rules_config_1.reviewJsonSchemaHint)(scan.reviewPath)}\n\n` +
+            `Finally run:  pnpm wp-finish-upsert-pr\n` +
+            `(The build gate is already green for this commit — finish reuses it unless HEAD moves.)\n\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.
+     */
+    // eslint-disable-next-line @typescript-eslint/max-params
+    spawnBlocks(repoRoot, featureName, scan, briefings) {
+        const reviewedIds = new Set(scan.reviewed.map((r) => r.id));
+        const owed = briefings.filter((b) => !reviewedIds.has(b.checklistId));
+        const lines = [];
+        for (const r of scan.reviewed) {
+            lines.push(`  ✓ ${r.subagent} — already reviewed on this branch (reusing its review-${r.id}.json)`);
+        }
+        // A verdict file that EXISTS but is unreadable as a verdict is called out here. Without it this
+        // reports the checklist as simply owed, and the AI re-runs a reviewer that already ran instead of
+        // correcting the file sitting right there.
+        for (const e of scan.formatErrors)
+            lines.push(`  ⛔ ${e}`);
+        if (owed.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.', '');
+        for (const b of owed) {
+            lines.push(`  ▶ ${b.subagent} — ${this.why(b)}`);
+            lines.push(`      subagent_type: ${b.subagent}`);
+            lines.push('      prompt:        Read your instructions file FIRST and follow it exactly:');
+            lines.push(`                     ${this.reviewerInstructions.pathFor(repoRoot, featureName, b.subagent)}`);
+            lines.push('');
+        }
+        return lines.join('\n');
+    }
+    // Why this one is in scope. A patternless checklist is NOT "matched" — it always runs, over the whole
+    // diff, and saying so is what tells a repo its checklist is firing on docs-only PRs by design.
+    why(b) {
+        if (b.matchedPatterns.length === 0) {
+            return `ALWAYS RUNS (no "patterns" configured), whole diff in scope — ${b.myFiles.length} file(s)`;
+        }
+        return `${b.myFiles.length} file(s) matched ${b.matchedPatterns.map((p) => `"${p}"`).join(', ')}`;
+    }
+};
+exports.ReviewUpsertPrCommand = ReviewUpsertPrCommand;
+exports.ReviewUpsertPrCommand = ReviewUpsertPrCommand = tslib_1.__decorate([
+    (0, inversify_1.injectable)(inversify_1.bindingScopeValues.Singleton),
+    tslib_1.__metadata("design:paramtypes", [rules_config_1.RepoRootFinder,
+        git_readAiBranchName_1.AiBranchName,
+        git_exec_1.GitExec,
+        build_affected_1.BuildAffected,
+        merge_state_1.MergeState,
+        merge_end_1.MergeEnd,
+        checklist_scanner_1.ChecklistScanner,
+        checklist_notice_1.ChecklistNotice,
+        rules_config_1.ChecklistInstructionsService,
+        diff_materializer_1.DiffMaterializer,
+        reviewer_briefing_builder_1.ReviewerBriefingBuilder,
+        rules_config_1.ReviewerInstructionsService,
+        review_stage_receipt_1.ReviewStageReceiptService])
+], ReviewUpsertPrCommand);
+//# sourceMappingURL=review-upsert-pr-command.js.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"review-upsert-pr-command.js","sourceRoot":"","sources":["../../../../../../../packages/tooling/pr-gate/src/scripts/commands/review-upsert-pr-command.ts"],"names":[],"mappings":"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","sourcesContent":["import * as fs from 'fs';\nimport * as path from 'path';\nimport {\n    loadAndValidate, reviewJsonSchemaHint, writeTemplate, PrGateConfig, RepoRootFinder,\n    ChecklistInstructionsService, RequiredChecklist, ReviewerBriefing, ReviewerInstructionsService, toError,\n} from '@webpieces/rules-config';\nimport { injectable, bindingScopeValues } from 'inversify';\nimport { AiBranchName } from '../workflow/git-readAiBranchName';\nimport { BuildAffected, BuildGateOptions } from '../workflow/build-affected';\nimport { ChecklistNotice } from '../workflow/checklist-notice';\nimport { ChecklistScan, ChecklistScanOptions, ChecklistScanner } from '../workflow/checklist-scanner';\nimport { DiffManifest, DiffManifestEntry, DiffMaterializer } from '../workflow/diff-materializer';\nimport { GitExec } from '../workflow/git-exec';\nimport { MergeContext } from '../workflow/merge-start';\nimport { MergeEnd, MergeEndOptions } from '../workflow/merge-end';\nimport { MergeState } from '../workflow/merge-state';\nimport { ReviewerBriefingBuilder } from '../workflow/reviewer-briefing-builder';\nimport { ReviewStageReceipt, ReviewStageReceiptService } from '../workflow/review-stage-receipt';\n\nconst SEP = '━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━\\n';\n\n/**\n * `wp-review-upsert-pr` — STAGE ② of the three-stage PR flow, between `wp-start-upsert-pr` (sync from main)\n * and `wp-finish-upsert-pr` (post the PR).\n *\n * It exists because reviewing came before verifying. Under the old two-command flow the 3-point merge was\n * finalized and the build gate ran inside `wp-finish-upsert-pr` — i.e. AFTER the reviewers had already run.\n * A reviewer could therefore spend a full review on an unresolved merge, or on code that does not compile,\n * and only afterwards would the branch be checked. This command puts the verification first:\n *\n *   1. finalize + VALIDATE any in-progress 3-point merge  (moved here from finish)\n *   2. assert a clean tree                                 (meaningful now — step 1 committed the resolution)\n *   3. run the build gate                                  (on the merged, committed tree)\n *   4. scan the checklists, EXTRACT the diff, BRIEF the reviewers\n *   5. write the stage receipt, then print what to spawn + the review.json schema\n *\n * Unlike the report-only command it replaces — which always exited 0, because reporting is not gating — this\n * command CAN FAIL, at steps 1, 2 and 3. That is the point: it fails BEFORE any reviewer is spawned, so a\n * branch with an unresolved merge or a broken build costs zero reviewer tokens.\n *\n * The ordering of 1 → 2 → 3 is load-bearing. MergeEnd stages and commits the conflict resolution, so the\n * tree is clean by the time the build runs; building first would either build a dirty tree (proving nothing\n * about what ships) or refuse a tree that is legitimately mid-resolution.\n */\n@injectable(bindingScopeValues.Singleton)\nexport class ReviewUpsertPrCommand {\n    // eslint-disable-next-line @typescript-eslint/max-params\n    constructor(\n        private readonly repoRootFinder: RepoRootFinder,\n        private readonly aiBranchName: AiBranchName,\n        private readonly gitExec: GitExec,\n        private readonly buildAffected: BuildAffected,\n        private readonly mergeState: MergeState,\n        private readonly mergeEnd: MergeEnd,\n        private readonly checklistScanner: ChecklistScanner,\n        private readonly checklistNotice: ChecklistNotice,\n        private readonly instructions: ChecklistInstructionsService,\n        private readonly materializer: DiffMaterializer,\n        private readonly briefingBuilder: ReviewerBriefingBuilder,\n        private readonly reviewerInstructions: ReviewerInstructionsService,\n        private readonly receipts: ReviewStageReceiptService,\n    ) {}\n\n    async run(): Promise<void> {\n        const repoRoot = this.repoRootFinder.resolveRepoRoot(process.cwd());\n        writeTemplate(repoRoot, 'webpieces.git-workflow.md');\n        writeTemplate(repoRoot, 'webpieces.review-checklists.md');\n        const featureName = this.aiBranchName.getFeatureName();\n        const config = loadAndValidate(repoRoot).prGate;\n\n        const mergeValidated = await this.finalizeAnyInProgressMerge(repoRoot);\n        this.gitExec.assertCleanTree(repoRoot);\n        const buildPassedAt = this.runBuildGate(repoRoot);\n\n        const scan = this.checklistScanner.scan(repoRoot, config.checklists, new ChecklistScanOptions(false));\n        const briefings = this.briefReviewers(repoRoot, featureName, scan, config);\n        this.receipts.write(repoRoot, featureName, new ReviewStageReceipt(\n            scan.basis.headSha, mergeValidated, this.buildAffected.resolveBuildCommand(repoRoot), buildPassedAt,\n            briefings.map((b: ReviewerBriefing): string => b.subagent),\n        ));\n        this.report(repoRoot, featureName, scan, briefings);\n    }\n\n    /**\n     * Validate + commit + finalize a conflict resolution, if one is in flight. MOVED here from\n     * `wp-finish-upsert-pr` so that exactly one command owns merge finalization — two owners is the drift\n     * failure `PrContextWriter`'s own docstring records having already happened once in this codebase.\n     *\n     * MergeEnd's three checks are what \"did the AI do the 3-point merge right?\" means concretely: no\n     * conflict markers left in the scoped files, `git diff --diff-filter=U` empty, and a non-empty\n     * merge-explanation.md beside every conflicted file.\n     *\n     * Returns true when a merge was finalized OR there was none to finalize; it throws rather than returning\n     * false when validation fails, so the receipt can never record an unvalidated merge as validated.\n     */\n    private async finalizeAnyInProgressMerge(repoRoot: string): Promise<boolean> {\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 true;\n        process.stdout.write('\\n' + SEP + '① Validating your 3-point merge\\n' + SEP + '\\n');\n        // pushRemote:false — finish still owns the single push.\n        await this.mergeEnd.mergeEnd(\n            repoRoot, 'wp-review-upsert-pr', activeDir,\n            new MergeContext(marker.currentBranch, marker.squashBranch, marker.backupBranch, marker.prNumber),\n            new MergeEndOptions(marker.conflictedFiles, false),\n        );\n        return true;\n    }\n\n    /**\n     * The build gate, run BEFORE any reviewer is briefed. Returns the ISO time it passed, for the receipt —\n     * which is what lets `wp-finish-upsert-pr` skip its own gate when HEAD has not moved, so moving the gate\n     * earlier did not turn one build into two.\n     */\n    private runBuildGate(repoRoot: string): string {\n        this.buildAffected.runBuildGate(repoRoot, new BuildGateOptions(\n            '🛠️  Build gate (pre-review)',\n            'pnpm wp-review-upsert-pr',\n            'Build failed — NO reviewer was briefed and no diff was extracted. Fix it, then re-run.',\n        ));\n        return new Date().toISOString();\n    }\n\n    /**\n     * Extract the diff once, then write one instructions file per reviewer.\n     *\n     * The changed-file set and the basis both come off the SCAN rather than being recomputed, so the diff a\n     * reviewer reads covers exactly the files its checklist matched against.\n     */\n    private briefReviewers(repoRoot: string, featureName: string, scan: ChecklistScan, config: PrGateConfig): ReviewerBriefing[] {\n        if (scan.basis.unresolved) return [];\n        const manifest = this.materializer.materialize(\n            repoRoot, featureName, scan.basis, scan.changedFiles, config.reviewDiffExclude);\n        const diffDir = this.materializer.diffDirFor(repoRoot, featureName);\n        // Re-point pr-context.json at the extracted diff now that there is one — the scan wrote it before\n        // materialization, so without this the reviewers' own context file would not mention the diff dir.\n        this.rewritePrContext(repoRoot, featureName, diffDir);\n        const briefings = this.briefingBuilder.build(repoRoot, scan, manifest, diffDir, config);\n        const dir = this.reviewerInstructions.instructionsDirFor(repoRoot, featureName);\n        fs.rmSync(dir, { recursive: true, force: true }); // stale instructions read as current are worse than none\n        fs.mkdirSync(dir, { recursive: true });\n        for (const b of briefings) {\n            fs.writeFileSync(this.reviewerInstructions.pathFor(repoRoot, featureName, b.subagent),\n                this.reviewerInstructions.render(b));\n        }\n        this.printDiffSummary(manifest, diffDir);\n        return briefings;\n    }\n\n    // pr-context.json is written by the scan (before the diff exists). Patch in the dir rather than\n    // re-deriving the whole context: re-deriving means a second basis resolution, which is the drift.\n    private rewritePrContext(repoRoot: string, featureName: string, diffDir: string): void {\n        const p = path.join(repoRoot, '.webpieces', 'pr-review', featureName, 'pr-context.json');\n        if (!fs.existsSync(p)) return;\n        // webpieces-disable no-unmanaged-exceptions -- chokepoint: an unreadable context is left as-is, never fatal\n        // eslint-disable-next-line @webpieces/no-unmanaged-exceptions\n        try {\n            // webpieces-disable no-any-unknown -- opaque parsed JSON, one key added\n            const raw = JSON.parse(fs.readFileSync(p, 'utf8')) as Record<string, unknown>;\n            raw['diffDir'] = diffDir;\n            fs.writeFileSync(p, JSON.stringify(raw, null, 2) + '\\n');\n        } catch (err: unknown) {\n            const error = toError(err);\n            void error; // leave the file as-is — the instructions files carry the same paths directly\n        }\n    }\n\n    private printDiffSummary(manifest: DiffManifest, diffDir: string): void {\n        process.stdout.write('\\n' + SEP + '② Diff extracted for the reviewers\\n' + SEP + '\\n');\n        process.stdout.write(`   ${manifest.entries.length} file(s) → ${diffDir}\\n`);\n        if (manifest.excluded.length > 0) {\n            process.stdout.write(`   ${manifest.excluded.length} excluded by pr-gate.reviewDiffExclude (stubbed, still matched)\\n`);\n        }\n        const truncated = manifest.entries.filter((e: DiffManifestEntry): boolean => e.truncated).length;\n        if (truncated > 0) process.stdout.write(`   ${truncated} truncated at the per-file cap (each says so in its footer)\\n`);\n    }\n\n    /** What the AI must do next: spawn each reviewer, then write review.json. */\n    private report(repoRoot: string, featureName: string, scan: ChecklistScan, briefings: readonly ReviewerBriefing[]): void {\n        process.stdout.write('\\n' + SEP + '③ Review, then finish\\n' + SEP + '\\n');\n        if (scan.applicable.length === 0) {\n            process.stdout.write(this.checklistNotice.build(scan.defined.length, 'wp-finish-upsert-pr'));\n        } else {\n            process.stdout.write(this.spawnBlocks(repoRoot, featureName, scan, briefings));\n        }\n        process.stdout.write(\n            `\\nThen review your own changes and\\n${reviewJsonSchemaHint(scan.reviewPath)}\\n\\n` +\n            `Finally 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     * 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    // eslint-disable-next-line @typescript-eslint/max-params\n    private spawnBlocks(repoRoot: string, featureName: string, scan: ChecklistScan, briefings: readonly ReviewerBriefing[]): string {\n        const reviewedIds = new Set(scan.reviewed.map((r: RequiredChecklist): string => r.id));\n        const owed = briefings.filter((b: ReviewerBriefing): boolean => !reviewedIds.has(b.checklistId));\n        const lines: string[] = [];\n        for (const r of scan.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 scan.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) {\n            lines.push(`  ▶ ${b.subagent} — ${this.why(b)}`);\n            lines.push(`      subagent_type: ${b.subagent}`);\n            lines.push('      prompt:        Read your instructions file FIRST and follow it exactly:');\n            lines.push(`                     ${this.reviewerInstructions.pathFor(repoRoot, featureName, b.subagent)}`);\n            lines.push('');\n        }\n        return lines.join('\\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"]}

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

@@ -1,8 +1,8 @@
 import { RepoRootFinder } from '@webpieces/rules-config';
 import { AiBranchName } from '../workflow/git-readAiBranchName';
 import { BranchNaming } from '../workflow/branch-naming';
+import { DiffBasisResolver } from '../workflow/diff-basis';
 import { GitExec } from '../workflow/git-exec';
-import { ForkPoint } from '../workflow/git-findForkPoint';
 import { PrContextWriter } from '../workflow/pr-context-writer';
 import { RunUpdate } from '../workflow/run-update';
 export declare class StartUpsertPrCommand {
@@ -11,26 +11,21 @@ export declare class StartUpsertPrCommand {
     private readonly branchNaming;
     private readonly gitExec;
     private readonly runUpdate;
-    private readonly forkPoint;
+    private readonly diffBasisResolver;
     private readonly prContextWriter;
-    constructor(repoRootFinder: RepoRootFinder, aiBranchName: AiBranchName, branchNaming: BranchNaming, gitExec: GitExec, runUpdate: RunUpdate, forkPoint: ForkPoint, prContextWriter: PrContextWriter);
+    constructor(repoRootFinder: RepoRootFinder, aiBranchName: AiBranchName, branchNaming: BranchNaming, gitExec: GitExec, runUpdate: RunUpdate, diffBasisResolver: DiffBasisResolver, prContextWriter: PrContextWriter);
     run(): Promise<void>;
     /**
-     * Hand the AI its next step: run `wp-checklist`, write review.json, then run finish (which posts the PR).
+     * Hand the AI its ONE next step: `wp-review-upsert-pr`.
      *
-     * This USED to compute the matched checklists and print every reviewer's full instructions inline — twice,
-     * in two blocks that could drift. That detail now lives in ONE command, `wp-checklist`, which wp-finish
-     * validates against; here we only point at it. Keeping this section short is the point: it is the block
-     * the AI must actually act on, and burying the three steps in forty lines of reviewer detail is how a
-     * step gets skipped.
+     * This prints exactly one command on purpose. It used to print three (run the checklist, write
+     * review.json, then finish), and a three-item list is a list with a step to skip. Stage ② now owns all
+     * of it — it validates the 3-point merge, builds, materializes the diff, briefs the reviewers, AND
+     * prints the review.json schema — so there is nothing here to enumerate. Notably review.json is NOT
+     * requested here any more: asking for a written review before the branch is known to compile invites
+     * one that describes code that does not build.
      */
     private handOffToReview;
-    /**
-     * Step 1 of the review: find out what review this diff owes. A repo with checklists gets pointed at
-     * `wp-checklist`; a repo with none is told plainly that it has none, because printing "run wp-checklist"
-     * forever at a repo that will never have one is noise, and silence reads as "a checklist passed".
-     */
-    private checklistPointer;
     private contextLines;
     private scaffoldCiWorkflow;
     private updateBranchFromMain;

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

@@ -6,32 +6,37 @@ const rules_config_1 = require("@webpieces/rules-config");
 const inversify_1 = require("inversify");
 const git_readAiBranchName_1 = require("../workflow/git-readAiBranchName");
 const branch_naming_1 = require("../workflow/branch-naming");
+const diff_basis_1 = require("../workflow/diff-basis");
 const git_exec_1 = require("../workflow/git-exec");
-const git_findForkPoint_1 = require("../workflow/git-findForkPoint");
 const pr_context_writer_1 = require("../workflow/pr-context-writer");
 const run_update_1 = require("../workflow/run-update");
 const SEP = '━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━\n';
-// START of the AI-first PR flow: the deterministic setup — update from main — then hand the AI
-// instructions to run `wp-checklist`, WRITE review.json, and run `wp-finish-upsert-pr` (which reads it
-// and posts the PR). It runs NO build gate: start's job is the update / 3-point merge, and the SINGLE
-// build gate is authoritative and lives in wp-finish-upsert-pr (so `pr-gate.buildCommand` is a
-// finish-only knob). This command NEVER creates/updates a PR and NEVER pushes: all `gh` posting and the
-// ONE push live in finish, behind review.json + the checklists + the authoritative build gate.
+// STAGE ① of the AI-first PR flow: the deterministic setup — update from main / drive the 3-point merge —
+// then hand the AI ONE next command, `wp-review-upsert-pr`.
+//
+// It runs NO build gate, and that is still deliberate, but the reason has changed. It is not that the build
+// belongs only at the end: it is that at THIS point a conflicted 3-point merge may still be unresolved, so
+// there is nothing worth building yet. The gate moved FORWARD, not away — stage ② finalizes the merge and
+// then builds, so reviewers never judge a branch that does not compile, and wp-finish-upsert-pr skips the
+// rebuild when HEAD has not moved since. `pr-gate.buildCommand` is therefore no longer a finish-only knob.
+//
+// This command NEVER creates/updates a PR and NEVER pushes: all `gh` posting and the ONE push live in
+// finish, behind review.json + the checklists + the build gate.
 let StartUpsertPrCommand = class StartUpsertPrCommand {
     repoRootFinder;
     aiBranchName;
     branchNaming;
     gitExec;
     runUpdate;
-    forkPoint;
+    diffBasisResolver;
     prContextWriter;
-    constructor(repoRootFinder, aiBranchName, branchNaming, gitExec, runUpdate, forkPoint, prContextWriter) {
+    constructor(repoRootFinder, aiBranchName, branchNaming, gitExec, runUpdate, diffBasisResolver, prContextWriter) {
         this.repoRootFinder = repoRootFinder;
         this.aiBranchName = aiBranchName;
         this.branchNaming = branchNaming;
         this.gitExec = gitExec;
         this.runUpdate = runUpdate;
-        this.forkPoint = forkPoint;
+        this.diffBasisResolver = diffBasisResolver;
         this.prContextWriter = prContextWriter;
     }
     async run() {
@@ -51,54 +56,41 @@ let StartUpsertPrCommand = class StartUpsertPrCommand {
         // every BLOCK checklist, and the authoritative build gate — so no unreviewed commit reaches the
         // remote, and there is no early `synchronize` firing against a PR body with a stale gate token.
         await this.updateBranchFromMain(repoRoot);
-        // No build gate here — start only updates from main / drives the 3-point merge. The one build
-        // gate is authoritative and runs in wp-finish-upsert-pr, after review.json + every checklist.
+        // No build gate here — a conflicted merge may still be unresolved, so there is nothing worth
+        // building. Stage ② finalizes the merge FIRST, then builds; see the class comment.
         this.handOffToReview(repoRoot);
     }
     /**
-     * Hand the AI its next step: run `wp-checklist`, write review.json, then run finish (which posts the PR).
+     * Hand the AI its ONE next step: `wp-review-upsert-pr`.
      *
-     * This USED to compute the matched checklists and print every reviewer's full instructions inline — twice,
-     * in two blocks that could drift. That detail now lives in ONE command, `wp-checklist`, which wp-finish
-     * validates against; here we only point at it. Keeping this section short is the point: it is the block
-     * the AI must actually act on, and burying the three steps in forty lines of reviewer detail is how a
-     * step gets skipped.
+     * This prints exactly one command on purpose. It used to print three (run the checklist, write
+     * review.json, then finish), and a three-item list is a list with a step to skip. Stage ② now owns all
+     * of it — it validates the 3-point merge, builds, materializes the diff, briefs the reviewers, AND
+     * prints the review.json schema — so there is nothing here to enumerate. Notably review.json is NOT
+     * requested here any more: asking for a written review before the branch is known to compile invites
+     * one that describes code that does not build.
      */
     handOffToReview(repoRoot) {
-        const reviewPath = (0, rules_config_1.reviewJsonPath)(repoRoot, this.aiBranchName.getFeatureName());
         // Persist the review-format + process instructions where any failure message can cite them.
         (0, rules_config_1.writeTemplate)(repoRoot, 'webpieces.review-checklists.md');
-        // Persist the PR diff context (base sha + the full changed-file set) — wp-checklist and every reviewer
-        // subagent read it, so it must exist before either runs.
-        const context = this.prContextWriter.ensure(repoRoot, this.aiBranchName.getFeatureName(), this.forkPoint.resolveForkPoint(repoRoot));
+        // Persist the PR diff context (base sha + the full changed-file set) so it exists even if the AI
+        // stops here. Stage ② rewrites it with the materialized-diff dir once it has one.
+        const context = this.prContextWriter.ensure(repoRoot, this.aiBranchName.getFeatureName(), this.diffBasisResolver.resolve(repoRoot));
         process.stdout.write('\n' + SEP + '② Review the PR, then finish\n' + SEP + '\n');
         process.stdout.write(`Branch is updated (nothing pushed yet — finish does the one push, behind the build gate).\n` +
             `${this.contextLines(context)}\n` +
-            `${this.checklistPointer(repoRoot)}\n` +
-            `Then review your own changes and\n` +
-            `${(0, rules_config_1.reviewJsonSchemaHint)(reviewPath)}\n\n` +
-            `Finally run:  pnpm wp-finish-upsert-pr\n` +
-            `(It re-validates the build, re-checks every checklist, renders the dashboard, and creates/updates the PR.)\n\n`);
+            `▶ NEXT run:  pnpm wp-review-upsert-pr\n` +
+            `   It validates the 3-point merge, runs the build gate, extracts this branch's diff for the\n` +
+            `   reviewers, and prints what to spawn plus the review.json schema. Everything else waits on it —\n` +
+            `   wp-finish-upsert-pr refuses to open a PR until it has run.\n\n`);
     }
-    /**
-     * Step 1 of the review: find out what review this diff owes. A repo with checklists gets pointed at
-     * `wp-checklist`; a repo with none is told plainly that it has none, because printing "run wp-checklist"
-     * forever at a repo that will never have one is noise, and silence reads as "a checklist passed".
-     */
-    checklistPointer(repoRoot) {
-        if ((0, rules_config_1.loadAndValidate)(repoRoot).prGate.checklists.length === 0) {
-            return '📋 Review checklists: NONE CONFIGURED for this repo — nothing to run, and that is fine.\n';
-        }
-        return ('📋 FIRST run:  pnpm wp-checklist\n' +
-            '   It validates this repo\'s checklist patterns against your diff and prints WHICH reviewer\n' +
-            '   subagents you must spawn, plus the exact review-<id>.json each must write. Do that BEFORE\n' +
-            '   finishing — wp-finish-upsert-pr refuses to open the PR until every one of them has run.\n');
-    }
-    // The diff facts, stated where the instruction to use them is — not in a separate block above it.
+    // The diff facts, stated where the instruction to use them is — not in a separate block above it. The
+    // command comes from the resolved basis; hand-writing `<base> HEAD` here is empty on a dirty tree.
     contextLines(context) {
         if (context.baseSha.trim() === '')
             return '';
-        return (`Your diff:  git diff ${context.baseSha} HEAD\n` +
+        const cmd = context.fileDiffCommand.replace(' -- <file>', '');
+        return (`${cmd === '' ? '' : `Your diff:  ${cmd}\n`}` +
             `Full changed-file set + base/head sha:  ${context.prContextPath}\n`);
     }
     // Scaffold the server-side CI check when (and only when) this repo set a gateSalt. Written to the
@@ -113,13 +105,15 @@ let StartUpsertPrCommand = class StartUpsertPrCommand {
             `   • mark the "webpieces-pr-gate" check REQUIRED in branch protection (repo admin only)\n`);
     }
     // Bring the branch up to date with main via the shared 3-point engine (in-process). On conflict the
-    // merge process doc it writes names `wp-finish-upsert-pr` as the finish command.
+    // merge process doc it writes names `wp-review-upsert-pr` as the finish command — that is the command
+    // that now validates and commits a conflict resolution, so it is what the doc must send the AI to.
     async updateBranchFromMain(repoRoot) {
         process.stdout.write('\n' + SEP + '① Updating branch from main\n' + SEP + '\n');
         // pushRemote=false — finish owns the single push (see MergeEndOptions).
-        const outcome = await this.runUpdate.runUpdateFromMain(repoRoot, 'wp-start-upsert-pr', 'wp-finish-upsert-pr', false);
+        const outcome = await this.runUpdate.runUpdateFromMain(repoRoot, 'wp-start-upsert-pr', 'wp-review-upsert-pr', false);
         if (outcome === 'conflict' || outcome === 'unvalidatedResume') {
-            throw new rules_config_1.CliExitError(2, '\n⏸️  Conflicts — resolve them, then run pnpm wp-finish-upsert-pr (it validates the merge AND finishes the PR).');
+            throw new rules_config_1.CliExitError(2, '\n⏸️  Conflicts — resolve them, then run pnpm wp-review-upsert-pr (it validates the merge, builds it,\n' +
+                '   and only then briefs the reviewers).');
         }
     }
 };
@@ -131,7 +125,7 @@ exports.StartUpsertPrCommand = StartUpsertPrCommand = tslib_1.__decorate([
         branch_naming_1.BranchNaming,
         git_exec_1.GitExec,
         run_update_1.RunUpdate,
-        git_findForkPoint_1.ForkPoint,
+        diff_basis_1.DiffBasisResolver,
         pr_context_writer_1.PrContextWriter])
 ], StartUpsertPrCommand);
 //# sourceMappingURL=start-upsert-pr-command.js.map

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

@@ -1 +1 @@
-{"version":3,"file":"start-upsert-pr-command.js","sourceRoot":"","sources":["../../../../../../../packages/tooling/pr-gate/src/scripts/commands/start-upsert-pr-command.ts"],"names":[],"mappings":"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","sourcesContent":["import { execSync } from 'child_process';\nimport { loadAndValidate, reviewJsonPath, reviewJsonSchemaHint, writeTemplate, writeTemplateIfMissing, CliExitError, RepoRootFinder, ChecklistReviewContext } from '@webpieces/rules-config';\nimport { injectable, bindingScopeValues } from 'inversify';\nimport { AiBranchName } from '../workflow/git-readAiBranchName';\nimport { BranchNaming } from '../workflow/branch-naming';\nimport { GitExec } from '../workflow/git-exec';\nimport { ForkPoint } from '../workflow/git-findForkPoint';\nimport { PrContextWriter } from '../workflow/pr-context-writer';\nimport { RunUpdate } from '../workflow/run-update';\n\nconst SEP = '━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━\\n';\n\n// START of the AI-first PR flow: the deterministic setup — update from main — then hand the AI\n// instructions to run `wp-checklist`, WRITE review.json, and run `wp-finish-upsert-pr` (which reads it\n// and posts the PR). It runs NO build gate: start's job is the update / 3-point merge, and the SINGLE\n// build gate is authoritative and lives in wp-finish-upsert-pr (so `pr-gate.buildCommand` is a\n// finish-only knob). This command NEVER creates/updates a PR and NEVER pushes: all `gh` posting and the\n// ONE push live in finish, behind review.json + the checklists + the authoritative build gate.\n@injectable(bindingScopeValues.Singleton)\nexport class StartUpsertPrCommand {\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 runUpdate: RunUpdate,\n        private readonly forkPoint: ForkPoint,\n        private readonly prContextWriter: PrContextWriter,\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        // When this repo has opted into server-side enforcement (a committed gateSalt), scaffold the CI\n        // workflow into the gitignored instruct-ai dir (never .github directly — that would dirty the tree\n        // before the clean-tree check) and tell the human to copy + require it. IfMissing so it is written\n        // once and never clobbers a customized copy.\n        this.scaffoldCiWorkflow(repoRoot);\n\n        // Precondition: a fully-committed tree. This flow squash-updates the branch and builds it — the\n        // tooling must not commit your work for you, and building a dirty working tree would let an\n        // uncommitted change build green over a different commit than the one that ships. Fail if dirty.\n        this.gitExec.assertCleanTree(repoRoot);\n\n        // Nothing here pushes. This command reviews; wp-finish-upsert-pr pushes ONCE, after review.json,\n        // every BLOCK checklist, and the authoritative build gate — so no unreviewed commit reaches the\n        // remote, and there is no early `synchronize` firing against a PR body with a stale gate token.\n        await this.updateBranchFromMain(repoRoot);\n\n        // No build gate here — start only updates from main / drives the 3-point merge. The one build\n        // gate is authoritative and runs in wp-finish-upsert-pr, after review.json + every checklist.\n        this.handOffToReview(repoRoot);\n    }\n\n    /**\n     * Hand the AI its next step: run `wp-checklist`, write review.json, then run finish (which posts the PR).\n     *\n     * This USED to compute the matched checklists and print every reviewer's full instructions inline — twice,\n     * in two blocks that could drift. That detail now lives in ONE command, `wp-checklist`, which wp-finish\n     * validates against; here we only point at it. Keeping this section short is the point: it is the block\n     * the AI must actually act on, and burying the three steps in forty lines of reviewer detail is how a\n     * step gets skipped.\n     */\n    private handOffToReview(repoRoot: string): void {\n        const reviewPath = reviewJsonPath(repoRoot, this.aiBranchName.getFeatureName());\n        // Persist the review-format + process instructions where any failure message can cite them.\n        writeTemplate(repoRoot, 'webpieces.review-checklists.md');\n        // Persist the PR diff context (base sha + the full changed-file set) — wp-checklist and every reviewer\n        // subagent read it, so it must exist before either runs.\n        const context = this.prContextWriter.ensure(repoRoot, this.aiBranchName.getFeatureName(), this.forkPoint.resolveForkPoint(repoRoot));\n        process.stdout.write('\\n' + SEP + '② Review the PR, then finish\\n' + SEP + '\\n');\n        process.stdout.write(\n            `Branch is updated (nothing pushed yet — finish does the one push, behind the build gate).\\n` +\n            `${this.contextLines(context)}\\n` +\n            `${this.checklistPointer(repoRoot)}\\n` +\n            `Then review your own changes and\\n` +\n            `${reviewJsonSchemaHint(reviewPath)}\\n\\n` +\n            `Finally run:  pnpm wp-finish-upsert-pr\\n` +\n            `(It re-validates the build, re-checks every checklist, renders the dashboard, and creates/updates the PR.)\\n\\n`,\n        );\n    }\n\n    /**\n     * Step 1 of the review: find out what review this diff owes. A repo with checklists gets pointed at\n     * `wp-checklist`; a repo with none is told plainly that it has none, because printing \"run wp-checklist\"\n     * forever at a repo that will never have one is noise, and silence reads as \"a checklist passed\".\n     */\n    private checklistPointer(repoRoot: string): string {\n        if (loadAndValidate(repoRoot).prGate.checklists.length === 0) {\n            return '📋 Review checklists: NONE CONFIGURED for this repo — nothing to run, and that is fine.\\n';\n        }\n        return (\n            '📋 FIRST run:  pnpm wp-checklist\\n' +\n            '   It validates this repo\\'s checklist patterns against your diff and prints WHICH reviewer\\n' +\n            '   subagents you must spawn, plus the exact review-<id>.json each must write. Do that BEFORE\\n' +\n            '   finishing — wp-finish-upsert-pr refuses to open the PR until every one of them has run.\\n'\n        );\n    }\n\n    // The diff facts, stated where the instruction to use them is — not in a separate block above it.\n    private contextLines(context: ChecklistReviewContext): string {\n        if (context.baseSha.trim() === '') return '';\n        return (\n            `Your diff:  git diff ${context.baseSha} HEAD\\n` +\n            `Full changed-file set + base/head sha:  ${context.prContextPath}\\n`\n        );\n    }\n\n    // Scaffold the server-side CI check when (and only when) this repo set a gateSalt. Written to the\n    // gitignored instruct-ai dir so it never dirties the tree; the human copies it to .github/workflows\n    // and marks it required (webpieces can't set branch protection). No-op for repos with no gateSalt.\n    private scaffoldCiWorkflow(repoRoot: string): void {\n        if (loadAndValidate(repoRoot).prGate.gateSalt.trim() === '') return;\n        writeTemplateIfMissing(repoRoot, 'webpieces-pr-gate.yml');\n        process.stdout.write(\n            `\\nℹ️  Server-side gate enforcement is ON (gateSalt set). If you have not already:\\n` +\n            `   • copy  .webpieces/instruct-ai/webpieces-pr-gate.yml  → .github/workflows/  and commit it\\n` +\n            `   • mark the \"webpieces-pr-gate\" check REQUIRED in branch protection (repo admin only)\\n`,\n        );\n    }\n\n    // Bring the branch up to date with main via the shared 3-point engine (in-process). On conflict the\n    // merge process doc it writes names `wp-finish-upsert-pr` as the finish command.\n    private async updateBranchFromMain(repoRoot: string): Promise<void> {\n        process.stdout.write('\\n' + SEP + '① Updating branch from main\\n' + SEP + '\\n');\n        // pushRemote=false — finish owns the single push (see MergeEndOptions).\n        const outcome = await this.runUpdate.runUpdateFromMain(repoRoot, 'wp-start-upsert-pr', 'wp-finish-upsert-pr', false);\n        if (outcome === 'conflict' || outcome === 'unvalidatedResume') {\n            throw new CliExitError(2,\n                '\\n⏸️  Conflicts — resolve them, then run pnpm wp-finish-upsert-pr (it validates the merge AND finishes the PR).',\n            );\n        }\n    }\n}\n"]}
+{"version":3,"file":"start-upsert-pr-command.js","sourceRoot":"","sources":["../../../../../../../packages/tooling/pr-gate/src/scripts/commands/start-upsert-pr-command.ts"],"names":[],"mappings":"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","sourcesContent":["import { execSync } from 'child_process';\nimport { loadAndValidate, writeTemplate, writeTemplateIfMissing, CliExitError, RepoRootFinder, ChecklistReviewContext } from '@webpieces/rules-config';\nimport { injectable, bindingScopeValues } from 'inversify';\nimport { AiBranchName } from '../workflow/git-readAiBranchName';\nimport { BranchNaming } from '../workflow/branch-naming';\nimport { DiffBasisResolver } from '../workflow/diff-basis';\nimport { GitExec } from '../workflow/git-exec';\nimport { PrContextWriter } from '../workflow/pr-context-writer';\nimport { RunUpdate } from '../workflow/run-update';\n\nconst SEP = '━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━\\n';\n\n// STAGE ① of the AI-first PR flow: the deterministic setup — update from main / drive the 3-point merge —\n// then hand the AI ONE next command, `wp-review-upsert-pr`.\n//\n// It runs NO build gate, and that is still deliberate, but the reason has changed. It is not that the build\n// belongs only at the end: it is that at THIS point a conflicted 3-point merge may still be unresolved, so\n// there is nothing worth building yet. The gate moved FORWARD, not away — stage ② finalizes the merge and\n// then builds, so reviewers never judge a branch that does not compile, and wp-finish-upsert-pr skips the\n// rebuild when HEAD has not moved since. `pr-gate.buildCommand` is therefore no longer a finish-only knob.\n//\n// This command NEVER creates/updates a PR and NEVER pushes: all `gh` posting and the ONE push live in\n// finish, behind review.json + the checklists + the build gate.\n@injectable(bindingScopeValues.Singleton)\nexport class StartUpsertPrCommand {\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 runUpdate: RunUpdate,\n        private readonly diffBasisResolver: DiffBasisResolver,\n        private readonly prContextWriter: PrContextWriter,\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        // When this repo has opted into server-side enforcement (a committed gateSalt), scaffold the CI\n        // workflow into the gitignored instruct-ai dir (never .github directly — that would dirty the tree\n        // before the clean-tree check) and tell the human to copy + require it. IfMissing so it is written\n        // once and never clobbers a customized copy.\n        this.scaffoldCiWorkflow(repoRoot);\n\n        // Precondition: a fully-committed tree. This flow squash-updates the branch and builds it — the\n        // tooling must not commit your work for you, and building a dirty working tree would let an\n        // uncommitted change build green over a different commit than the one that ships. Fail if dirty.\n        this.gitExec.assertCleanTree(repoRoot);\n\n        // Nothing here pushes. This command reviews; wp-finish-upsert-pr pushes ONCE, after review.json,\n        // every BLOCK checklist, and the authoritative build gate — so no unreviewed commit reaches the\n        // remote, and there is no early `synchronize` firing against a PR body with a stale gate token.\n        await this.updateBranchFromMain(repoRoot);\n\n        // No build gate here — a conflicted merge may still be unresolved, so there is nothing worth\n        // building. Stage ② finalizes the merge FIRST, then builds; see the class comment.\n        this.handOffToReview(repoRoot);\n    }\n\n    /**\n     * Hand the AI its ONE next step: `wp-review-upsert-pr`.\n     *\n     * This prints exactly one command on purpose. It used to print three (run the checklist, write\n     * review.json, then finish), and a three-item list is a list with a step to skip. Stage ② now owns all\n     * of it — it validates the 3-point merge, builds, materializes the diff, briefs the reviewers, AND\n     * prints the review.json schema — so there is nothing here to enumerate. Notably review.json is NOT\n     * requested here any more: asking for a written review before the branch is known to compile invites\n     * one that describes code that does not build.\n     */\n    private handOffToReview(repoRoot: string): void {\n        // Persist the review-format + process instructions where any failure message can cite them.\n        writeTemplate(repoRoot, 'webpieces.review-checklists.md');\n        // Persist the PR diff context (base sha + the full changed-file set) so it exists even if the AI\n        // stops here. Stage ② rewrites it with the materialized-diff dir once it has one.\n        const context = this.prContextWriter.ensure(\n            repoRoot, this.aiBranchName.getFeatureName(), this.diffBasisResolver.resolve(repoRoot));\n        process.stdout.write('\\n' + SEP + '② Review the PR, then finish\\n' + SEP + '\\n');\n        process.stdout.write(\n            `Branch is updated (nothing pushed yet — finish does the one push, behind the build gate).\\n` +\n            `${this.contextLines(context)}\\n` +\n            `▶ NEXT run:  pnpm wp-review-upsert-pr\\n` +\n            `   It validates the 3-point merge, runs the build gate, extracts this branch's diff for the\\n` +\n            `   reviewers, and prints what to spawn plus the review.json schema. Everything else waits on it —\\n` +\n            `   wp-finish-upsert-pr refuses to open a PR until it has run.\\n\\n`,\n        );\n    }\n\n    // The diff facts, stated where the instruction to use them is — not in a separate block above it. The\n    // command comes from the resolved basis; hand-writing `<base> HEAD` here is empty on a dirty tree.\n    private contextLines(context: ChecklistReviewContext): string {\n        if (context.baseSha.trim() === '') return '';\n        const cmd = context.fileDiffCommand.replace(' -- <file>', '');\n        return (\n            `${cmd === '' ? '' : `Your diff:  ${cmd}\\n`}` +\n            `Full changed-file set + base/head sha:  ${context.prContextPath}\\n`\n        );\n    }\n\n    // Scaffold the server-side CI check when (and only when) this repo set a gateSalt. Written to the\n    // gitignored instruct-ai dir so it never dirties the tree; the human copies it to .github/workflows\n    // and marks it required (webpieces can't set branch protection). No-op for repos with no gateSalt.\n    private scaffoldCiWorkflow(repoRoot: string): void {\n        if (loadAndValidate(repoRoot).prGate.gateSalt.trim() === '') return;\n        writeTemplateIfMissing(repoRoot, 'webpieces-pr-gate.yml');\n        process.stdout.write(\n            `\\nℹ️  Server-side gate enforcement is ON (gateSalt set). If you have not already:\\n` +\n            `   • copy  .webpieces/instruct-ai/webpieces-pr-gate.yml  → .github/workflows/  and commit it\\n` +\n            `   • mark the \"webpieces-pr-gate\" check REQUIRED in branch protection (repo admin only)\\n`,\n        );\n    }\n\n    // Bring the branch up to date with main via the shared 3-point engine (in-process). On conflict the\n    // merge process doc it writes names `wp-review-upsert-pr` as the finish command — that is the command\n    // that now validates and commits a conflict resolution, so it is what the doc must send the AI to.\n    private async updateBranchFromMain(repoRoot: string): Promise<void> {\n        process.stdout.write('\\n' + SEP + '① Updating branch from main\\n' + SEP + '\\n');\n        // pushRemote=false — finish owns the single push (see MergeEndOptions).\n        const outcome = await this.runUpdate.runUpdateFromMain(repoRoot, 'wp-start-upsert-pr', 'wp-review-upsert-pr', false);\n        if (outcome === 'conflict' || outcome === 'unvalidatedResume') {\n            throw new CliExitError(2,\n                '\\n⏸️  Conflicts — resolve them, then run pnpm wp-review-upsert-pr (it validates the merge, builds it,\\n' +\n                '   and only then briefs the reviewers).',\n            );\n        }\n    }\n}\n"]}

package/src/scripts/commands/worktree-cleanup.d.ts

@@ -0,0 +1,45 @@
+import { MutationVerb, DeletableWorktree, MergedBranchesService, WorktreeReapResult, WorktreeReaper } from '@webpieces/rules-config';
+/**
+ * The WORKTREE half of `wp-cleanup` — the verdicts, the reap and the human-facing text.
+ *
+ * Split out of CleanupCommand rather than bolted onto it because the two halves answer different
+ * questions: a branch is a ref, a worktree is a DIRECTORY OF FILES, and the second one needs its own
+ * report (paths, not just names), its own restore command (`git worktree add`, not `git checkout -b`)
+ * and its own spared vocabulary (locked, detached, "you are standing in it"). Keeping them in one class
+ * meant every string had to hedge about which kind of thing it was talking about.
+ *
+ * WHY worktrees are reaped BEFORE branches in wp-cleanup: a worktree HOLDS its branch, so that branch
+ * is spared as `in-use` with "remove that worktree before deleting the branch". Reaping the worktree
+ * first is what makes the branch reapable — the reap takes the branch with it, and the branch pass that
+ * follows recomputes its verdicts against the post-removal truth. Run the other way round, every
+ * worktree-held branch survives forever, which is exactly the deadlock this change exists to break.
+ */
+export declare class WorktreeCleanupSection {
+    private readonly mergedBranches;
+    private readonly reaper;
+    constructor(mergedBranches: MergedBranchesService, reaper: WorktreeReaper);
+    /**
+     * FRESH verdicts — never the cache on disk. Same rule the branch half follows: the cached file is
+     * deliberately allowed to go stale, which is fine for BLOCKING a `git worktree add` and never fine
+     * for removing a directory, since the tree may have gained uncommitted work since it was written.
+     */
+    verdicts(repoRoot: string): DeletableWorktree[];
+    provablyDead(verdicts: DeletableWorktree[]): DeletableWorktree[];
+    /**
+     * The spared worktrees a human can meaningfully rule on, grouped most-safe first — the same
+     * classification order the branch prompt uses, because it is literally the same verdict on the
+     * branch the worktree holds.
+     *
+     * Deliberately excluded: LOCKED (a human already said do not touch), CURRENT (removing your own cwd
+     * is not a thing to offer), DETACHED (no branch, so nothing to archive and nothing to judge) and
+     * PRUNABLE (already provably dead — it is in the auto-reap list, not this one).
+     */
+    promptable(verdicts: DeletableWorktree[]): DeletableWorktree[];
+    reap(repoRoot: string, verb: MutationVerb, targets: DeletableWorktree[], retention: string): WorktreeReapResult;
+    report(result: WorktreeReapResult): string;
+    private reapedLine;
+    /** The spared worktrees, with WHY — including the ones nobody will ever be asked about. */
+    sparedBlock(verdicts: DeletableWorktree[], removed: DeletableWorktree[]): string;
+    private isMechanical;
+    promptBlock(promptable: DeletableWorktree[]): string;
+}