@webpieces/pr-gate 0.4.741 → 0.4.743

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

@@ -1 +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 {\n    loadAndValidate, writeTemplate, PrGateConfig, RepoRootFinder, RequiredChecklist,\n    ReviewerBriefing, ReviewerInstructionsService, ReviewJsonService,\n} from '@webpieces/rules-config';\nimport { injectable, bindingScopeValues } from 'inversify';\nimport { ActiveHatch, ActiveHatchReport } from '../workflow/active-hatches';\nimport { AiBranchName } from '../workflow/git-readAiBranchName';\nimport { BuildAffected, BuildGateOptions } from '../workflow/build-affected';\nimport { REVIEW_STAGE } from '../workflow/build-gate-log';\nimport { BuildArtifactGate } from '../workflow/build-artifact-gate';\nimport { ChecklistScan, ChecklistScanOptions, ChecklistScanner } from '../workflow/checklist-scanner';\nimport { 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 { PrContextWriter } from '../workflow/pr-context-writer';\nimport { ReviewerBriefingBuilder } from '../workflow/reviewer-briefing-builder';\nimport { RefusedReviewer, ReviewReport, ReviewReportInput } from '../workflow/review-report';\nimport { ReviewStageReceipt, ReviewStageReceiptService } from '../workflow/review-stage-receipt';\nimport { StageOutputLog, REVIEW_CONSOLE_LOG } from '../workflow/stage-output-log';\n\nconst SEP = '━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━\\n';\n\n/** The `--no-optional` decision, as data (per CLAUDE.md) rather than a bare boolean parameter. */\nexport class ReviewUpsertPrOptions {\n    /**\n     * true ⇒ the human ALREADY said to submit without the optional reviews, so stage ② must not print the\n     * block telling the AI to offer them. It changes nothing about what BLOCKS: required checklists are\n     * unaffected, and an optional checklist that already has a red verdict on this branch still refuses the\n     * PR at finish. This only suppresses the offer.\n     */\n    skipOptional: boolean;\n\n    constructor(skipOptional = false) {\n        this.skipOptional = skipOptional;\n    }\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 buildArtifactGate: BuildArtifactGate,\n        private readonly mergeState: MergeState,\n        private readonly mergeEnd: MergeEnd,\n        private readonly checklistScanner: ChecklistScanner,\n        private readonly reviewReport: ReviewReport,\n        private readonly materializer: DiffMaterializer,\n        private readonly prContextWriter: PrContextWriter,\n        private readonly briefingBuilder: ReviewerBriefingBuilder,\n        private readonly reviewerInstructions: ReviewerInstructionsService,\n        private readonly receipts: ReviewStageReceiptService,\n        private readonly activeHatchReport: ActiveHatchReport,\n        // Injected only to RESOLVE + RENDER refusals (see refusals()). This stage never archives a verdict.\n        private readonly reviewJsonService: ReviewJsonService,\n        private readonly stageConsole: StageOutputLog,\n    ) {}\n\n    /**\n     * Everything below runs with this stage's console CAPTURED to a file (see StageOutputLog). Only the\n     * lines an agent must act on before it can do anything else reach the terminal — the build heartbeat\n     * and result, and the closing instruction block. The merge validation, the hatch report, the checklist\n     * scan and the diff extraction are all in the file, one `grep` away.\n     *\n     * This is the FIRST half of the fix for the piped-command watchdog kill: an agent pipes a command it\n     * expects to flood, a pipe withholds every byte until exit, and the harness kills a command that has\n     * printed nothing for 600 seconds — after a full build. Guarding the pipe without first shrinking the\n     * output would only have traded that kill for a flooded context.\n     */\n    async run(opts: ReviewUpsertPrOptions = new ReviewUpsertPrOptions()): Promise<void> {\n        const repoRoot = this.repoRootFinder.resolveRepoRoot(process.cwd());\n        await this.stageConsole.withCapture(\n            repoRoot, REVIEW_CONSOLE_LOG, (): Promise<void> => this.runStage(repoRoot, opts));\n    }\n\n    private async runStage(repoRoot: string, opts: ReviewUpsertPrOptions): Promise<void> {\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 = await this.runBuildGate(repoRoot);\n\n        const scan = this.checklistScanner.scan(repoRoot, config.checklists, new ChecklistScanOptions(false, ''));  // '' — THIS command writes the context itself, after materializing\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.reportActiveHatches(repoRoot);\n        this.report(repoRoot, featureName, scan, briefings, opts);\n    }\n\n    /**\n     * List every rule that is currently switched off in webpieces.config.json. NON-BLOCKING and printed\n     * before the instruction block, because it is context for the review rather than a step in it.\n     *\n     * A hatch is the one config change that makes the build QUIETER, so no gate, reviewer or red check\n     * will ever mention it — which is how a repo ends up with rules off for weeks that nobody chose to\n     * leave off. This is the only place in the flow that says so out loud.\n     */\n    private reportActiveHatches(repoRoot: string): void {\n        const hatches: ActiveHatch[] = this.activeHatchReport.scan(repoRoot);\n        process.stdout.write(this.activeHatchReport.render(hatches));\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 async runBuildGate(repoRoot: string): Promise<string> {\n        await this.buildAffected.runBuildGate(repoRoot, new BuildGateOptions(\n            '🛠️  Build gate',\n            'pnpm wp-review-upsert-pr',\n            'Build failed — NO reviewer was briefed and no diff was extracted. Fix it, then re-run.',\n            REVIEW_STAGE,\n        ));\n        // Repo-wide: the build must not have left anything uncommitted AND unstaged. Runs HERE, not in\n        // finish, because this is the stage that ran buildCommand and is therefore holding the dirty\n        // tree at the exact moment the question is answerable. Replaces the per-project\n        // validate-di-graph-unchanged nx target — see BuildArtifactGate for why that one had to go.\n        this.buildArtifactGate.assertBuildLeftNothingUncommitted(repoRoot);\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        // Write pr-context.json ONCE, here — after materializing, so `diffDir` is populated on the first\n        // write. The scan deliberately did not write it (ChecklistScanOptions.contextStage === ''); it used\n        // to, which meant this command wrote the same file twice, the first time with an empty diffDir.\n        // `scan.changedFiles` is passed through so the context is not recomputed from a second git call.\n        scan.context = this.prContextWriter.ensure(\n            repoRoot, featureName, scan.basis, 'stage2-review', scan.changedFiles, 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        return briefings;\n    }\n\n    /**\n     * What the AI must do next — rendered by `ReviewReport`, which owns the ordering.\n     *\n     * The rendering moved OUT of this command so the ordering could be asserted on as a string. It had a\n     * real bug: the zero-checklist notice signed off with \"Carry on and run: pnpm wp-finish-upsert-pr\"\n     * while the block right beneath it said to write review.json first. An agent that reads top to bottom\n     * obeyed the first line and posted a PR with no review at all.\n     */\n    // eslint-disable-next-line @typescript-eslint/max-params\n    private report(\n        repoRoot: string, featureName: string, scan: ChecklistScan, briefings: readonly ReviewerBriefing[],\n        opts: ReviewUpsertPrOptions,\n    ): void {\n        const input = new ReviewReportInput(repoRoot, featureName, scan.reviewPath);\n        input.definedCount = scan.defined.length;\n        input.applicableCount = scan.applicable.length;\n        input.reviewed = scan.reviewed.slice();\n        input.formatErrors = scan.formatErrors.slice();\n        input.briefings = briefings.slice();\n        input.refused = this.refusals(scan);\n        input.skipOptional = opts.skipOptional;\n        // `say`: this block IS the next action — which reviewers to spawn, where review.json goes, and\n        // the command after that. Capturing it into the log would leave the terminal with a pointer and\n        // no instruction, which is the one thing this stage may never do.\n        this.stageConsole.say(this.reviewReport.render(input));\n    }\n\n    /**\n     * The applicable checklists that ALREADY ANSWERED and refused, each with its refusal rendered by the ONE\n     * renderer `wp-finish-upsert-pr` also uses.\n     *\n     * Stage ② had the identical defect finish did: a refused checklist has no passing verdict, so it is not\n     * in `scan.reviewed`, so it was printed as an ordinary owed reviewer and re-instructed word for word —\n     * and an agent that obeys spawns it against unchanged code, gets the same refusal, and loops one stage\n     * earlier than the loop that was reported.\n     *\n     * NO archive path is passed, deliberately, and this stage moves nothing. Retiring a verdict is finish's\n     * act on the refusal it is actually enforcing; doing it here would delete the live verdict of a branch\n     * that has not even been asked to finish yet, and `refusalError`'s un-archived wording — \"fix it, then\n     * re-run\" — is only correct while that verdict file is still there, which here it is.\n     *\n     * The review path IS passed, because the ship-anyway route the refusal prints is a command that writes\n     * `override-<id>.json` beside it. That command is as correct at this stage as at finish: the override\n     * is a separate file with its own writer, so nothing about it depends on the verdict having been moved.\n     */\n    private refusals(scan: ChecklistScan): RefusedReviewer[] {\n        const refused = this.reviewJsonService.refusedChecklists(scan.applicable, scan.results);\n        return refused.map((req: RequiredChecklist): RefusedReviewer => new RefusedReviewer(\n            req.id,\n            this.reviewJsonService.refusalError(\n                req, this.reviewJsonService.resolveVerdict(req, scan.results), scan.reviewPath)));\n    }\n}\n"]}
+{"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 {\n    loadAndValidate, writeTemplate, PrGateConfig, RepoRootFinder, RequiredChecklist,\n    ReviewerBriefing, ReviewerInstructionsService, ReviewJsonService,\n} from '@webpieces/rules-config';\nimport { injectable, bindingScopeValues } from 'inversify';\nimport { ActiveHatch, ActiveHatchReport } from '../workflow/active-hatches';\nimport { AiBranchName } from '../workflow/git-readAiBranchName';\nimport { BuildAffected, BuildGateOptions } from '../workflow/build-affected';\nimport { REVIEW_STAGE } from '../workflow/build-gate-log';\nimport { BuildArtifactGate } from '../workflow/build-artifact-gate';\nimport { ChecklistScan, ChecklistScanOptions, ChecklistScanner } from '../workflow/checklist-scanner';\nimport { 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 { PrContextWriter } from '../workflow/pr-context-writer';\nimport { ReviewerBriefingBuilder } from '../workflow/reviewer-briefing-builder';\nimport { RefusedReviewer, ReviewReport, ReviewReportInput } from '../workflow/review-report';\nimport { ReviewStageReceipt, ReviewStageReceiptService } from '../workflow/review-stage-receipt';\nimport { StageOutputLog, REVIEW_CONSOLE_LOG } from '../workflow/stage-output-log';\n\nconst SEP = '━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━\\n';\n\n/** The `--no-optional` decision, as data (per CLAUDE.md) rather than a bare boolean parameter. */\nexport class ReviewUpsertPrOptions {\n    /**\n     * true ⇒ the human ALREADY said to submit without the optional reviews, so stage ② must not print the\n     * block telling the AI to offer them. It changes nothing about what BLOCKS: required checklists are\n     * unaffected, and an optional checklist that already has a red verdict on this branch still refuses the\n     * PR at finish. This only suppresses the offer.\n     */\n    skipOptional: boolean;\n\n    constructor(skipOptional = false) {\n        this.skipOptional = skipOptional;\n    }\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 buildArtifactGate: BuildArtifactGate,\n        private readonly mergeState: MergeState,\n        private readonly mergeEnd: MergeEnd,\n        private readonly checklistScanner: ChecklistScanner,\n        private readonly reviewReport: ReviewReport,\n        private readonly materializer: DiffMaterializer,\n        private readonly prContextWriter: PrContextWriter,\n        private readonly briefingBuilder: ReviewerBriefingBuilder,\n        private readonly reviewerInstructions: ReviewerInstructionsService,\n        private readonly receipts: ReviewStageReceiptService,\n        private readonly activeHatchReport: ActiveHatchReport,\n        // Injected only to RESOLVE + RENDER refusals (see refusals()). This stage never archives a verdict.\n        private readonly reviewJsonService: ReviewJsonService,\n        private readonly stageConsole: StageOutputLog,\n    ) {}\n\n    /**\n     * Everything below runs with this stage's console CAPTURED to a file (see StageOutputLog). Only the\n     * lines an agent must act on before it can do anything else reach the terminal — the build heartbeat\n     * and result, and the closing instruction block. The merge validation, the hatch report, the checklist\n     * scan and the diff extraction are all in the file, one `grep` away.\n     *\n     * This is the FIRST half of the fix for the piped-command watchdog kill: an agent pipes a command it\n     * expects to flood, a pipe withholds every byte until exit, and the harness kills a command that has\n     * printed nothing for 600 seconds — after a full build. Guarding the pipe without first shrinking the\n     * output would only have traded that kill for a flooded context.\n     */\n    async run(opts: ReviewUpsertPrOptions = new ReviewUpsertPrOptions()): Promise<void> {\n        const repoRoot = this.repoRootFinder.resolveRepoRoot(process.cwd());\n        await this.stageConsole.withCapture(\n            repoRoot, REVIEW_CONSOLE_LOG, (): Promise<void> => this.runStage(repoRoot, opts));\n    }\n\n    private async runStage(repoRoot: string, opts: ReviewUpsertPrOptions): Promise<void> {\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 = await this.runBuildGate(repoRoot);\n\n        const scan = this.checklistScanner.scan(repoRoot, config.checklists, new ChecklistScanOptions(false, ''));  // '' — THIS command writes the context itself, after materializing\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.reportActiveHatches(repoRoot);\n        this.report(repoRoot, featureName, scan, briefings, opts);\n    }\n\n    /**\n     * List every rule that is currently switched off in webpieces.config.json. NON-BLOCKING and printed\n     * before the instruction block, because it is context for the review rather than a step in it.\n     *\n     * A hatch is the one config change that makes the build QUIETER, so no gate, reviewer or red check\n     * will ever mention it — which is how a repo ends up with rules off for weeks that nobody chose to\n     * leave off. This is the only place in the flow that says so out loud.\n     */\n    private reportActiveHatches(repoRoot: string): void {\n        const hatches: ActiveHatch[] = this.activeHatchReport.scan(repoRoot);\n        process.stdout.write(this.activeHatchReport.render(hatches));\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 async runBuildGate(repoRoot: string): Promise<string> {\n        await this.buildAffected.runBuildGate(repoRoot, new BuildGateOptions(\n            '🛠️  Build gate',\n            'pnpm wp-review-upsert-pr',\n            'Build failed — NO reviewer was briefed and no diff was extracted. Fix it, then re-run.',\n            REVIEW_STAGE,\n        ));\n        // Repo-wide: the build must not have left anything uncommitted AND unstaged. Runs HERE, not in\n        // finish, because this is the stage that ran buildCommand and is therefore holding the dirty\n        // tree at the exact moment the question is answerable. Replaces the per-project\n        // validate-di-graph-unchanged nx target — see BuildArtifactGate for why that one had to go.\n        this.buildArtifactGate.assertBuildLeftNothingUncommitted(repoRoot);\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        // Write pr-context.json ONCE, here — after materializing, so `diffDir` is populated on the first\n        // write. The scan deliberately did not write it (ChecklistScanOptions.contextStage === ''); it used\n        // to, which meant this command wrote the same file twice, the first time with an empty diffDir.\n        // `scan.changedFiles` is passed through so the context is not recomputed from a second git call.\n        scan.context = this.prContextWriter.ensure(\n            repoRoot, featureName, scan.basis, 'stage2-review', scan.changedFiles, 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        return briefings;\n    }\n\n    /**\n     * What the AI must do next — rendered by `ReviewReport`, which owns the ordering.\n     *\n     * The rendering moved OUT of this command so the ordering could be asserted on as a string. It had a\n     * real bug: the zero-checklist notice signed off with \"Carry on and run: pnpm wp-finish-upsert-pr\"\n     * while the block right beneath it said to write review.json first. An agent that reads top to bottom\n     * obeyed the first line and posted a PR with no review at all.\n     */\n    // eslint-disable-next-line @typescript-eslint/max-params\n    private report(\n        repoRoot: string, featureName: string, scan: ChecklistScan, briefings: readonly ReviewerBriefing[],\n        opts: ReviewUpsertPrOptions,\n    ): void {\n        const input = new ReviewReportInput(repoRoot, featureName, scan.reviewPath);\n        input.definedCount = scan.defined.length;\n        input.applicableCount = scan.applicable.length;\n        input.reviewed = scan.reviewed.slice();\n        input.formatErrors = scan.formatErrors.slice();\n        input.briefings = briefings.slice();\n        input.refused = this.refusals(scan);\n        input.skipOptional = opts.skipOptional;\n        // Straight off the SCAN — the one place `experimental.turnOffAllReviewers` is read. This command\n        // deliberately does NOT consult the home config itself: a second read is a second answer, and the\n        // command that lists and the command that blocks would be free to disagree about whether a branch\n        // was reviewed. See ChecklistScanner.\n        input.reviewersSuppressed = scan.reviewersDisabled;\n        input.suppressed = scan.suppressed.slice();\n        // `say`: this block IS the next action — which reviewers to spawn, where review.json goes, and\n        // the command after that. Capturing it into the log would leave the terminal with a pointer and\n        // no instruction, which is the one thing this stage may never do.\n        this.stageConsole.say(this.reviewReport.render(input));\n    }\n\n    /**\n     * The applicable checklists that ALREADY ANSWERED and refused, each with its refusal rendered by the ONE\n     * renderer `wp-finish-upsert-pr` also uses.\n     *\n     * Stage ② had the identical defect finish did: a refused checklist has no passing verdict, so it is not\n     * in `scan.reviewed`, so it was printed as an ordinary owed reviewer and re-instructed word for word —\n     * and an agent that obeys spawns it against unchanged code, gets the same refusal, and loops one stage\n     * earlier than the loop that was reported.\n     *\n     * NO archive path is passed, deliberately, and this stage moves nothing. Retiring a verdict is finish's\n     * act on the refusal it is actually enforcing; doing it here would delete the live verdict of a branch\n     * that has not even been asked to finish yet, and `refusalError`'s un-archived wording — \"fix it, then\n     * re-run\" — is only correct while that verdict file is still there, which here it is.\n     *\n     * The review path IS passed, because the ship-anyway route the refusal prints is a command that writes\n     * `override-<id>.json` beside it. That command is as correct at this stage as at finish: the override\n     * is a separate file with its own writer, so nothing about it depends on the verdict having been moved.\n     */\n    private refusals(scan: ChecklistScan): RefusedReviewer[] {\n        const refused = this.reviewJsonService.refusedChecklists(scan.applicable, scan.results);\n        return refused.map((req: RequiredChecklist): RefusedReviewer => new RefusedReviewer(\n            req.id,\n            this.reviewJsonService.refusalError(\n                req, this.reviewJsonService.resolveVerdict(req, scan.results), scan.reviewPath)));\n    }\n}\n"]}

package/src/scripts/workflow/checklist-scanner.d.ts

@@ -1,4 +1,4 @@
-import { ChecklistDefinition, ChecklistResult, ChecklistReviewContext, DiffScope, RequiredChecklist, ReviewJsonService } from '@webpieces/rules-config';
+import { ChecklistDefinition, ChecklistResult, ChecklistReviewContext, DiffScope, HomeConfigService, RequiredChecklist, ReviewJsonService } from '@webpieces/rules-config';
 import { AiBranchName } from './git-readAiBranchName';
 import { ChecklistDetector, ChecklistRoster } from './checklist-detector';
 import { DiffBasis, DiffBasisResolver } from './diff-basis';
@@ -72,7 +72,34 @@ export declare class ChecklistScan {
      * passed. An optional checklist that ran and went RED is absent from here and stays in `outstanding`.
      */
     optionalNotRun: RequiredChecklist[];
-    constructor(defined: ChecklistDefinition[], applicable: RequiredChecklist[], reviewed: RequiredChecklist[], outstanding: RequiredChecklist[], context: ChecklistReviewContext, reviewPath: string, forkPoint: string, roster: ChecklistRoster, formatErrors: string[], basis?: DiffBasis, changedFiles?: string[], results?: ChecklistResult[], optionalNotRun?: RequiredChecklist[]);
+    /**
+     * TRUE when this machine's `~/.webpieces/config.json` carries
+     * `experimental.turnOffAllReviewers: true`, and therefore when `applicable`, `reviewed`,
+     * `outstanding`, `results`, `optionalNotRun` and `formatErrors` above are ALL EMPTY BY DECREE rather
+     * than because nothing matched. Those two states are indistinguishable from the empty lists alone,
+     * and telling them apart is the entire reason this field exists: an unreviewed PR must never render
+     * as a reviewed one.
+     *
+     * `defined`, `roster`, `basis`, `changedFiles` and `context` are deliberately left INTACT under
+     * suppression, so every reader can still say WHAT was switched off — including which REQUIRED
+     * checklists would otherwise have run.
+     *
+     * See `HOME_KEY_TURN_OFF_ALL_REVIEWERS` in rules-config for the flag's contract; it is an
+     * `experimental.*` flag, so only a human ever ends it.
+     */
+    reviewersDisabled: boolean;
+    /**
+     * The checklists that WOULD have been `applicable` had the reviewers not been suppressed — required
+     * ones included. EMPTY on every ordinary run, and empty is not ambiguous there because
+     * `reviewersDisabled` is false.
+     *
+     * Carried by NAME and not as a count because every reader needs a different slice of it: stage ②
+     * prints them so a human can see exactly which required reviewer was killed, the dashboard names them
+     * in the 1st comment, and the compact PR body needs only `.length`. Recomputing any of that
+     * downstream would mean a second changed-file computation that can disagree with this one.
+     */
+    suppressed: RequiredChecklist[];
+    constructor(defined: ChecklistDefinition[], applicable: RequiredChecklist[], reviewed: RequiredChecklist[], outstanding: RequiredChecklist[], context: ChecklistReviewContext, reviewPath: string, forkPoint: string, roster: ChecklistRoster, formatErrors: string[], reviewersDisabled: boolean, suppressed: RequiredChecklist[], basis?: DiffBasis, changedFiles?: string[], results?: ChecklistResult[], optionalNotRun?: RequiredChecklist[]);
 }
 /**
  * The ONE computation of which reviewer subagents a branch owes, shared by `wp-review-upsert-pr` (which lists) and
@@ -102,7 +129,8 @@ export declare class ChecklistScanner {
     private readonly diffBasisResolver;
     private readonly prContextWriter;
     private readonly reviewJsonService;
-    constructor(aiBranchName: AiBranchName, checklistDetector: ChecklistDetector, diffScope: DiffScope, diffBasisResolver: DiffBasisResolver, prContextWriter: PrContextWriter, reviewJsonService: ReviewJsonService);
+    private readonly homeConfig;
+    constructor(aiBranchName: AiBranchName, checklistDetector: ChecklistDetector, diffScope: DiffScope, diffBasisResolver: DiffBasisResolver, prContextWriter: PrContextWriter, reviewJsonService: ReviewJsonService, homeConfig: HomeConfigService);
     /**
      * `defined` is the caller's ALREADY-VALIDATED `prGate.checklists`. The scanner deliberately does not load
      * config itself: `loadAndValidate` is the one gate on the checklist set (it rejects a non-array

package/src/scripts/workflow/checklist-scanner.js

@@ -87,8 +87,40 @@ class ChecklistScan {
      * passed. An optional checklist that ran and went RED is absent from here and stays in `outstanding`.
      */
     optionalNotRun;
+    /**
+     * TRUE when this machine's `~/.webpieces/config.json` carries
+     * `experimental.turnOffAllReviewers: true`, and therefore when `applicable`, `reviewed`,
+     * `outstanding`, `results`, `optionalNotRun` and `formatErrors` above are ALL EMPTY BY DECREE rather
+     * than because nothing matched. Those two states are indistinguishable from the empty lists alone,
+     * and telling them apart is the entire reason this field exists: an unreviewed PR must never render
+     * as a reviewed one.
+     *
+     * `defined`, `roster`, `basis`, `changedFiles` and `context` are deliberately left INTACT under
+     * suppression, so every reader can still say WHAT was switched off — including which REQUIRED
+     * checklists would otherwise have run.
+     *
+     * See `HOME_KEY_TURN_OFF_ALL_REVIEWERS` in rules-config for the flag's contract; it is an
+     * `experimental.*` flag, so only a human ever ends it.
+     */
+    reviewersDisabled;
+    /**
+     * The checklists that WOULD have been `applicable` had the reviewers not been suppressed — required
+     * ones included. EMPTY on every ordinary run, and empty is not ambiguous there because
+     * `reviewersDisabled` is false.
+     *
+     * Carried by NAME and not as a count because every reader needs a different slice of it: stage ②
+     * prints them so a human can see exactly which required reviewer was killed, the dashboard names them
+     * in the 1st comment, and the compact PR body needs only `.length`. Recomputing any of that
+     * downstream would mean a second changed-file computation that can disagree with this one.
+     */
+    suppressed;
     // eslint-disable-next-line @typescript-eslint/max-params
-    constructor(defined, applicable, reviewed, outstanding, context, reviewPath, forkPoint, roster, formatErrors, basis = new diff_basis_1.DiffBasis(), changedFiles = [], 
+    constructor(defined, applicable, reviewed, outstanding, context, reviewPath, forkPoint, roster, formatErrors, 
+    // REQUIRED, and placed BEFORE the defaulted tail deliberately. A defaulted `reviewersDisabled =
+    // false` would let every existing construction keep compiling while asserting, silently, that no
+    // reviewer was switched off — the widening-by-omission `.claude/rules/no-backwards-compat.md`
+    // rejects, and on the one field whose whole job is to stop an unreviewed PR reading as reviewed.
+    reviewersDisabled, suppressed, basis = new diff_basis_1.DiffBasis(), changedFiles = [], 
     // Defaulted so a caller that only cares about the X/N/Z counts (and every existing test construction)
     // stays a one-liner; the scanner itself always passes the real set.
     results = [], optionalNotRun = []) {
@@ -101,6 +133,8 @@ class ChecklistScan {
         this.forkPoint = forkPoint;
         this.roster = roster;
         this.formatErrors = formatErrors;
+        this.reviewersDisabled = reviewersDisabled;
+        this.suppressed = suppressed;
         this.basis = basis;
         this.changedFiles = changedFiles;
         this.results = results;
@@ -136,13 +170,18 @@ let ChecklistScanner = class ChecklistScanner {
     diffBasisResolver;
     prContextWriter;
     reviewJsonService;
-    constructor(aiBranchName, checklistDetector, diffScope, diffBasisResolver, prContextWriter, reviewJsonService) {
+    homeConfig;
+    constructor(aiBranchName, checklistDetector, diffScope, diffBasisResolver, prContextWriter, reviewJsonService, 
+    // Injected BY TYPE (no Symbol token, per CLAUDE.md) so the ONE reviewer kill switch is read in the
+    // ONE place that computes what a branch owes — see the suppression note on `scan`.
+    homeConfig) {
         this.aiBranchName = aiBranchName;
         this.checklistDetector = checklistDetector;
         this.diffScope = diffScope;
         this.diffBasisResolver = diffBasisResolver;
         this.prContextWriter = prContextWriter;
         this.reviewJsonService = reviewJsonService;
+        this.homeConfig = homeConfig;
     }
     /**
      * `defined` is the caller's ALREADY-VALIDATED `prGate.checklists`. The scanner deliberately does not load
@@ -162,7 +201,21 @@ let ChecklistScanner = class ChecklistScanner {
         // pure and defined as the roster minus its empty entries, so the two cannot disagree about a match.
         const changedFiles = this.changedFiles(repoRoot, base);
         const roster = new checklist_detector_1.ChecklistRoster(this.checklistDetector.roster(defined, changedFiles), changedFiles.length, base !== '');
-        const applicable = this.checklistDetector.toRequired(this.checklistDetector.detect(defined, changedFiles));
+        const matched = this.checklistDetector.toRequired(this.checklistDetector.detect(defined, changedFiles));
+        // THE ONE CHOKE POINT for `experimental.turnOffAllReviewers`. Suppressing HERE — rather than in
+        // `wp-review-upsert-pr` and again in `wp-finish-upsert-pr` — is what keeps the command that LISTS
+        // and the command that BLOCKS in agreement by construction, which is this class's whole reason for
+        // existing. A second check in either command would be a second answer to one question.
+        const context = opts.contextStage === ''
+            ? this.prContextWriter.contextFor(repoRoot, featureName, basis)
+            : this.prContextWriter.ensure(repoRoot, featureName, basis, opts.contextStage, changedFiles);
+        if (this.homeConfig.load().turnOffAllReviewers) {
+            // EMPTY: applicable, reviewed, outstanding, formatErrors, results, optionalNotRun. INTACT:
+            // defined, roster, basis, changedFiles, context — so every downstream reader can still say
+            // WHAT was suppressed, which is the difference between an honest record and a silent one.
+            return new ChecklistScan(defined, [], [], [], context, reviewPath, base, roster, [], true, matched, basis, changedFiles, [], []);
+        }
+        const applicable = matched;
         const results = this.reviewJsonService.loadChecklistResults(reviewPath, applicable);
         const stillOwed = this.reviewJsonService.pendingChecklists(applicable, results);
         const owedIds = new Set(stillOwed.map((r) => r.id));
@@ -171,9 +224,7 @@ let ChecklistScanner = class ChecklistScanner {
         // that never happened.
         const reviewed = applicable.filter((r) => !owedIds.has(r.id));
         const optionalNotRun = this.reviewJsonService.optionalWithoutVerdict(applicable, results);
-        return new ChecklistScan(defined, applicable, reviewed, opts.filterAlreadyReviewed ? this.blocking(stillOwed, optionalNotRun) : applicable, opts.contextStage === ''
-            ? this.prContextWriter.contextFor(repoRoot, featureName, basis)
-            : this.prContextWriter.ensure(repoRoot, featureName, basis, opts.contextStage, changedFiles), reviewPath, base, roster, this.reviewJsonService.checklistFormatErrors(applicable, results), basis, changedFiles, results, optionalNotRun);
+        return new ChecklistScan(defined, applicable, reviewed, opts.filterAlreadyReviewed ? this.blocking(stillOwed, optionalNotRun) : applicable, context, reviewPath, base, roster, this.reviewJsonService.checklistFormatErrors(applicable, results), false, [], basis, changedFiles, results, optionalNotRun);
     }
     /**
      * What `wp-finish-upsert-pr` actually REFUSES on: everything still owing a verdict, minus the optional
@@ -216,6 +267,7 @@ exports.ChecklistScanner = ChecklistScanner = tslib_1.__decorate([
         rules_config_1.DiffScope,
         diff_basis_1.DiffBasisResolver,
         pr_context_writer_1.PrContextWriter,
-        rules_config_1.ReviewJsonService])
+        rules_config_1.ReviewJsonService,
+        rules_config_1.HomeConfigService])
 ], ChecklistScanner);
 //# sourceMappingURL=checklist-scanner.js.map

package/src/scripts/workflow/checklist-scanner.js.map

@@ -1 +1 @@
-{"version":3,"file":"checklist-scanner.js","sourceRoot":"","sources":["../../../../../../../packages/tooling/pr-gate/src/scripts/workflow/checklist-scanner.ts"],"names":[],"mappings":";;;;AAAA,0DAGiC;AACjC,yCAA2D;AAC3D,iEAAsD;AACtD,6DAA0E;AAC1E,6CAA4D;AAC5D,2DAAsD;AAEtD,uEAAuE;AACvE,MAAa,oBAAoB;IAC7B;;;;OAIG;IACH,qBAAqB,CAAU;IAC/B;;;;;;;;;;;;OAYG;IACH,YAAY,CAAS;IAErB,YAAY,qBAAqB,GAAG,KAAK,EAAE,YAAY,GAAG,YAAY;QAClE,IAAI,CAAC,qBAAqB,GAAG,qBAAqB,CAAC;QACnD,IAAI,CAAC,YAAY,GAAG,YAAY,CAAC;IACrC,CAAC;CACJ;AA1BD,oDA0BC;AAED;;;;;;GAMG;AACH,MAAa,aAAa;IACtB,OAAO,CAAwB,CAAM,IAAI;IACzC,UAAU,CAAsB,CAAK,IAAI;IACzC,QAAQ,CAAsB,CAAO,mEAAmE;IACxG,WAAW,CAAsB,CAAI,uCAAuC;IAC5E,OAAO,CAAyB,CAAK,wCAAwC;IAC7E,UAAU,CAAS,CAAkB,wDAAwD;IAC7F,SAAS,CAAS,CAAmB,iCAAiC;IACtE,wGAAwG;IACxG,+FAA+F;IAC/F,6EAA6E;IAC7E,MAAM,CAAkB;IACxB,qGAAqG;IACrG,qGAAqG;IACrG,2EAA2E;IAC3E,YAAY,CAAW;IACvB;;;;OAIG;IACH,KAAK,CAAY;IACjB,YAAY,CAAW,CAAc,qDAAqD;IAC1F;;;;;;;;;OASG;IACH,OAAO,CAAoB;IAC3B;;;;;;;;OAQG;IACH,cAAc,CAAsB;IAEpC,yDAAyD;IACzD,YACI,OAA8B,EAC9B,UAA+B,EAC/B,QAA6B,EAC7B,WAAgC,EAChC,OAA+B,EAC/B,UAAkB,EAClB,SAAiB,EACjB,MAAuB,EACvB,YAAsB,EACtB,QAAmB,IAAI,sBAAS,EAAE,EAClC,eAAyB,EAAE;IAC3B,sGAAsG;IACtG,oEAAoE;IACpE,UAA6B,EAAE,EAC/B,iBAAsC,EAAE;QAExC,IAAI,CAAC,OAAO,GAAG,OAAO,CAAC;QACvB,IAAI,CAAC,UAAU,GAAG,UAAU,CAAC;QAC7B,IAAI,CAAC,QAAQ,GAAG,QAAQ,CAAC;QACzB,IAAI,CAAC,WAAW,GAAG,WAAW,CAAC;QAC/B,IAAI,CAAC,OAAO,GAAG,OAAO,CAAC;QACvB,IAAI,CAAC,UAAU,GAAG,UAAU,CAAC;QAC7B,IAAI,CAAC,SAAS,GAAG,SAAS,CAAC;QAC3B,IAAI,CAAC,MAAM,GAAG,MAAM,CAAC;QACrB,IAAI,CAAC,YAAY,GAAG,YAAY,CAAC;QACjC,IAAI,CAAC,KAAK,GAAG,KAAK,CAAC;QACnB,IAAI,CAAC,YAAY,GAAG,YAAY,CAAC;QACjC,IAAI,CAAC,OAAO,GAAG,OAAO,CAAC;QACvB,IAAI,CAAC,cAAc,GAAG,cAAc,CAAC;IACzC,CAAC;CACJ;AA7ED,sCA6EC;AAED;;;;;;;;;;;;;;;;;;;;GAoBG;AAEI,IAAM,gBAAgB,GAAtB,MAAM,gBAAgB;IAEJ;IACA;IACA;IACA;IACA;IACA;IANrB,YACqB,YAA0B,EAC1B,iBAAoC,EACpC,SAAoB,EACpB,iBAAoC,EACpC,eAAgC,EAChC,iBAAoC;QALpC,iBAAY,GAAZ,YAAY,CAAc;QAC1B,sBAAiB,GAAjB,iBAAiB,CAAmB;QACpC,cAAS,GAAT,SAAS,CAAW;QACpB,sBAAiB,GAAjB,iBAAiB,CAAmB;QACpC,oBAAe,GAAf,eAAe,CAAiB;QAChC,sBAAiB,GAAjB,iBAAiB,CAAmB;IACtD,CAAC;IAEJ;;;;;;OAMG;IACH,IAAI,CAAC,QAAgB,EAAE,OAA8B,EAAE,IAA0B;QAC7E,MAAM,WAAW,GAAG,IAAI,CAAC,YAAY,CAAC,cAAc,EAAE,CAAC;QACvD,MAAM,UAAU,GAAG,IAAA,6BAAc,EAAC,QAAQ,EAAE,WAAW,CAAC,CAAC;QACzD,iGAAiG;QACjG,iGAAiG;QACjG,MAAM,KAAK,GAAG,IAAI,CAAC,iBAAiB,CAAC,OAAO,CAAC,QAAQ,CAAC,CAAC;QACvD,MAAM,IAAI,GAAG,KAAK,CAAC,IAAI,CAAC;QACxB,qGAAqG;QACrG,oGAAoG;QACpG,MAAM,YAAY,GAAG,IAAI,CAAC,YAAY,CAAC,QAAQ,EAAE,IAAI,CAAC,CAAC;QACvD,MAAM,MAAM,GAAG,IAAI,oCAAe,CAC9B,IAAI,CAAC,iBAAiB,CAAC,MAAM,CAAC,OAAO,EAAE,YAAY,CAAC,EAAE,YAAY,CAAC,MAAM,EAAE,IAAI,KAAK,EAAE,CAAC,CAAC;QAC5F,MAAM,UAAU,GAAG,IAAI,CAAC,iBAAiB,CAAC,UAAU,CAAC,IAAI,CAAC,iBAAiB,CAAC,MAAM,CAAC,OAAO,EAAE,YAAY,CAAC,CAAC,CAAC;QAC3G,MAAM,OAAO,GAAG,IAAI,CAAC,iBAAiB,CAAC,oBAAoB,CAAC,UAAU,EAAE,UAAU,CAAC,CAAC;QACpF,MAAM,SAAS,GAAG,IAAI,CAAC,iBAAiB,CAAC,iBAAiB,CAAC,UAAU,EAAE,OAAO,CAAC,CAAC;QAChF,MAAM,OAAO,GAAG,IAAI,GAAG,CAAC,SAAS,CAAC,GAAG,CAAC,CAAC,CAAoB,EAAU,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC;QAC/E,qGAAqG;QACrG,uGAAuG;QACvG,uBAAuB;QACvB,MAAM,QAAQ,GAAG,UAAU,CAAC,MAAM,CAAC,CAAC,CAAoB,EAAW,EAAE,CAAC,CAAC,OAAO,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC;QAC1F,MAAM,cAAc,GAAG,IAAI,CAAC,iBAAiB,CAAC,sBAAsB,CAAC,UAAU,EAAE,OAAO,CAAC,CAAC;QAC1F,OAAO,IAAI,aAAa,CACpB,OAAO,EACP,UAAU,EACV,QAAQ,EACR,IAAI,CAAC,qBAAqB,CAAC,CAAC,CAAC,IAAI,CAAC,QAAQ,CAAC,SAAS,EAAE,cAAc,CAAC,CAAC,CAAC,CAAC,UAAU,EAClF,IAAI,CAAC,YAAY,KAAK,EAAE;YACpB,CAAC,CAAC,IAAI,CAAC,eAAe,CAAC,UAAU,CAAC,QAAQ,EAAE,WAAW,EAAE,KAAK,CAAC;YAC/D,CAAC,CAAC,IAAI,CAAC,eAAe,CAAC,MAAM,CAAC,QAAQ,EAAE,WAAW,EAAE,KAAK,EAAE,IAAI,CAAC,YAAY,EAAE,YAAY,CAAC,EAChG,UAAU,EACV,IAAI,EACJ,MAAM,EACN,IAAI,CAAC,iBAAiB,CAAC,qBAAqB,CAAC,UAAU,EAAE,OAAO,CAAC,EACjE,KAAK,EACL,YAAY,EACZ,OAAO,EACP,cAAc,CACjB,CAAC;IACN,CAAC;IAED;;;;;;;;OAQG;IACK,QAAQ,CAAC,SAAuC,EAAE,cAA4C;QAClG,MAAM,OAAO,GAAG,IAAI,GAAG,CAAC,cAAc,CAAC,GAAG,CAAC,CAAC,CAAoB,EAAU,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC;QACpF,OAAO,SAAS,CAAC,MAAM,CAAC,CAAC,CAAoB,EAAW,EAAE,CAAC,CAAC,OAAO,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC;IACnF,CAAC;IAED;;;;;;;;;OASG;IACK,YAAY,CAAC,QAAgB,EAAE,IAAY;QAC/C,IAAI,IAAI,KAAK,EAAE;YAAE,OAAO,EAAE,CAAC;QAC3B,MAAM,IAAI,GAAG,IAAI,kCAAmB,EAAE,CAAC;QACvC,IAAI,CAAC,MAAM,GAAG,KAAK,CAAC;QACpB,IAAI,CAAC,gBAAgB,GAAG,IAAI,CAAC;QAC7B,oFAAoF;QACpF,OAAO,IAAI,CAAC,SAAS,CAAC,eAAe,CAAC,QAAQ,EAAE,IAAI,EAAE,SAAS,EAAE,IAAI,CAAC,CAAC;IAC3E,CAAC;CACJ,CAAA;AAzFY,4CAAgB;2BAAhB,gBAAgB;IAD5B,IAAA,sBAAU,EAAC,8BAAkB,CAAC,SAAS,CAAC;6CAGF,mCAAY;QACP,sCAAiB;QACzB,wBAAS;QACD,8BAAiB;QACnB,mCAAe;QACb,gCAAiB;GAPhD,gBAAgB,CAyF5B","sourcesContent":["import {\n    ChangedFilesOptions, ChecklistDefinition, ChecklistResult, ChecklistReviewContext, DiffScope,\n    RequiredChecklist, ReviewJsonService, reviewJsonPath,\n} from '@webpieces/rules-config';\nimport { injectable, bindingScopeValues } from 'inversify';\nimport { AiBranchName } from './git-readAiBranchName';\nimport { ChecklistDetector, ChecklistRoster } from './checklist-detector';\nimport { DiffBasis, DiffBasisResolver } from './diff-basis';\nimport { PrContextWriter } from './pr-context-writer';\n\n/** How a caller wants the scan filtered. Data-only (per CLAUDE.md). */\nexport class ChecklistScanOptions {\n    /**\n     * false — `outstanding` is every applicable checklist (what `wp-review-upsert-pr` LISTS).\n     * true  — `outstanding` drops the ones already carrying a passing/overridden verdict, leaving only what\n     *         still owes review (what `wp-finish-upsert-pr` BLOCKS on).\n     */\n    filterAlreadyReviewed: boolean;\n    /**\n     * Which per-stage snapshot this scan should persist ('stage3-finish', …), or '' for \"do not write\n     * pr-context.json here\".\n     *\n     * '' exists for stage ②, which cannot write yet: the context records `diffDir`, and the diff has not\n     * been materialized at scan time. Letting the scan write anyway meant stage ② wrote the file twice,\n     * ~60 lines apart, the first time with an empty diffDir. Now it writes once, after materializing.\n     *\n     * The DEFAULT is deliberately non-empty, so writing is what you get by NOT thinking about it. A\n     * reviewer block that lost its diff command because nobody had written pr-context.json is a bug this\n     * codebase has already shipped once (see PrContextWriter's docstring); opting out must be an explicit,\n     * visible act by a caller that takes responsibility for writing it later — not an omission.\n     */\n    contextStage: string;\n\n    constructor(filterAlreadyReviewed = false, contextStage = 'stage-scan') {\n        this.filterAlreadyReviewed = filterAlreadyReviewed;\n        this.contextStage = contextStage;\n    }\n}\n\n/**\n * The answer to \"what review does this branch owe?\", in the X → N → Z terms the commands report:\n *   X = `defined`     — every checklist in pr-gate.checklists\n *   N = `applicable`  — those whose patterns matched (or that have no patterns, so always run)\n *   Z = `outstanding` — of N, those still owing a verdict (only when filterAlreadyReviewed)\n * Data-only.\n */\nexport class ChecklistScan {\n    defined: ChecklistDefinition[];      // X\n    applicable: RequiredChecklist[];     // N\n    reviewed: RequiredChecklist[];       // N − Z: already have a passing/warned/overridden review-<id>.json\n    outstanding: RequiredChecklist[];    // Z (== applicable when not filtering)\n    context: ChecklistReviewContext;     // fork-point sha + pr-context.json path\n    reviewPath: string;                  // the branch's review.json; verdict files sit beside it\n    forkPoint: string;                   // '' when no fork point resolved\n    // ALL X, matched or not, with why — what the PR comment publishes as its roster. Skipped checklists are\n    // absent from `applicable` by construction, and recovering them downstream would mean a second\n    // changed-file computation with different semantics (see the class comment).\n    roster: ChecklistRoster;\n    // Verdict files that exist but cannot be read as a verdict (e.g. still using the removed `success`).\n    // Carried on the SCAN because wp-finish-upsert-pr refuses on missing reviewers before it ever parses\n    // review.json — a complaint raised only in there would never reach the AI.\n    formatErrors: string[];\n    /**\n     * The basis the matching ACTUALLY ran against. Carried out so a caller that materializes the diff\n     * (stage ②) reuses the identical range instead of resolving its own — two independent resolutions is\n     * exactly how the changed-file set and the printed `git diff` command came to disagree.\n     */\n    basis: DiffBasis;\n    changedFiles: string[];              // the full changed-file set the matching ran against\n    /**\n     * The verdict files the scan ALREADY read, carried out rather than dropped.\n     *\n     * `outstanding` answers \"who still owes a verdict?\" but not \"why\" — and the two reasons demand opposite\n     * actions from the reader: a reviewer that never ran must be SPAWNED, a reviewer that ran and REFUSED\n     * must not be (it will refuse again; the finding has to be fixed first). Telling them apart means\n     * resolving each checklist's verdict, and without the results here every caller either re-reads the same\n     * files off disk — a second read that can disagree with this one — or merges the two cases into one\n     * message, which is exactly the loop this field exists to break.\n     */\n    results: ChecklistResult[];\n    /**\n     * The OPTIONAL (`required: false`) applicable checklists carrying no verdict file — i.e. nobody ran them.\n     *\n     * Deliberately NOT in `outstanding` when filtering: that is the exemption that makes `required: false`\n     * mean something. Carried out as its own set rather than merely subtracted, because both readers need it\n     * BY NAME and neither can recover it from what is left: stage ② offers exactly these to the human, and\n     * the PR dashboard must publish them as \"not run\" rather than let a shorter roster imply everything\n     * passed. An optional checklist that ran and went RED is absent from here and stays in `outstanding`.\n     */\n    optionalNotRun: RequiredChecklist[];\n\n    // eslint-disable-next-line @typescript-eslint/max-params\n    constructor(\n        defined: ChecklistDefinition[],\n        applicable: RequiredChecklist[],\n        reviewed: RequiredChecklist[],\n        outstanding: RequiredChecklist[],\n        context: ChecklistReviewContext,\n        reviewPath: string,\n        forkPoint: string,\n        roster: ChecklistRoster,\n        formatErrors: string[],\n        basis: DiffBasis = new DiffBasis(),\n        changedFiles: string[] = [],\n        // Defaulted so a caller that only cares about the X/N/Z counts (and every existing test construction)\n        // stays a one-liner; the scanner itself always passes the real set.\n        results: ChecklistResult[] = [],\n        optionalNotRun: RequiredChecklist[] = [],\n    ) {\n        this.defined = defined;\n        this.applicable = applicable;\n        this.reviewed = reviewed;\n        this.outstanding = outstanding;\n        this.context = context;\n        this.reviewPath = reviewPath;\n        this.forkPoint = forkPoint;\n        this.roster = roster;\n        this.formatErrors = formatErrors;\n        this.basis = basis;\n        this.changedFiles = changedFiles;\n        this.results = results;\n        this.optionalNotRun = optionalNotRun;\n    }\n}\n\n/**\n * The ONE computation of which reviewer subagents a branch owes, shared by `wp-review-upsert-pr` (which lists) and\n * `wp-finish-upsert-pr` (which blocks). They previously each assembled this from the same parts in slightly\n * different ways, and any divergence means the command that reports and the command that gates disagree.\n *\n * Two properties are deliberate and load-bearing:\n *\n * 1. **The base is the FORK POINT of main, computed directly** — never `DiffScope.resolveBase`, which\n *    overlays `NX_BASE`/`NX_HEAD` from the environment. That made review coverage depend on an env var.\n *    It now arrives via {@link DiffBasisResolver}, which injects ForkPoint; same sha, one resolution.\n * 2. **UNCOMMITTED work counts.** `getChangedFiles` is called with NO head, which is the branch of it that\n *    diffs base → WORKING TREE and unions in untracked files. Passing a head would diff commit-to-commit and\n *    silently miss staged, unstaged and untracked changes — so a checklist matching only uncommitted files\n *    would never fire and its reviewer would never be listed.\n * 3. **The range and the command it prints are the SAME basis.** Property 2 used to be true of the file set\n *    only: reviewers were handed `git diff <base> HEAD`, which on a dirty tree covers a different range and\n *    prints nothing. Both now derive from one {@link DiffBasis}, carried on the scan so a materializing\n *    caller cannot re-resolve and drift.\n *\n * `@injectable(bindingScopeValues.Singleton)` so it is injected by type and drawn in the DI design.\n */\n@injectable(bindingScopeValues.Singleton)\nexport class ChecklistScanner {\n    constructor(\n        private readonly aiBranchName: AiBranchName,\n        private readonly checklistDetector: ChecklistDetector,\n        private readonly diffScope: DiffScope,\n        private readonly diffBasisResolver: DiffBasisResolver,\n        private readonly prContextWriter: PrContextWriter,\n        private readonly reviewJsonService: ReviewJsonService,\n    ) {}\n\n    /**\n     * `defined` is the caller's ALREADY-VALIDATED `prGate.checklists`. The scanner deliberately does not load\n     * config itself: `loadAndValidate` is the one gate on the checklist set (it rejects a non-array\n     * `checklists`, including the removed `{ doc }` manifest shape, and verifies every guidance doc and\n     * reviewer-agent file exists), both callers already run it for other fields, and keeping the read out of\n     * here leaves this a function of its inputs rather than of the filesystem.\n     */\n    scan(repoRoot: string, defined: ChecklistDefinition[], opts: ChecklistScanOptions): ChecklistScan {\n        const featureName = this.aiBranchName.getFeatureName();\n        const reviewPath = reviewJsonPath(repoRoot, featureName);\n        // ONE basis for the file set, the reproduce command and any downstream materialization. The fork\n        // point still comes from ForkPoint (never DiffScope.resolveBase) — DiffBasisResolver injects it.\n        const basis = this.diffBasisResolver.resolve(repoRoot);\n        const base = basis.base;\n        // ONE changed-file computation feeds both the roster (all X) and the applicable set (N). `detect` is\n        // pure and defined as the roster minus its empty entries, so the two cannot disagree about a match.\n        const changedFiles = this.changedFiles(repoRoot, base);\n        const roster = new ChecklistRoster(\n            this.checklistDetector.roster(defined, changedFiles), changedFiles.length, base !== '');\n        const applicable = this.checklistDetector.toRequired(this.checklistDetector.detect(defined, changedFiles));\n        const results = this.reviewJsonService.loadChecklistResults(reviewPath, applicable);\n        const stillOwed = this.reviewJsonService.pendingChecklists(applicable, results);\n        const owedIds = new Set(stillOwed.map((r: RequiredChecklist): string => r.id));\n        // NOT `!owedIds.has(...)`-with-the-optional-exemption-folded-in: an optional checklist nobody ran is\n        // neither reviewed nor blocking, and calling it \"reviewed\" would put a ✓ on the dashboard for a review\n        // that never happened.\n        const reviewed = applicable.filter((r: RequiredChecklist): boolean => !owedIds.has(r.id));\n        const optionalNotRun = this.reviewJsonService.optionalWithoutVerdict(applicable, results);\n        return new ChecklistScan(\n            defined,\n            applicable,\n            reviewed,\n            opts.filterAlreadyReviewed ? this.blocking(stillOwed, optionalNotRun) : applicable,\n            opts.contextStage === ''\n                ? this.prContextWriter.contextFor(repoRoot, featureName, basis)\n                : this.prContextWriter.ensure(repoRoot, featureName, basis, opts.contextStage, changedFiles),\n            reviewPath,\n            base,\n            roster,\n            this.reviewJsonService.checklistFormatErrors(applicable, results),\n            basis,\n            changedFiles,\n            results,\n            optionalNotRun,\n        );\n    }\n\n    /**\n     * What `wp-finish-upsert-pr` actually REFUSES on: everything still owing a verdict, minus the optional\n     * checklists nobody ran.\n     *\n     * The subtraction happens HERE — in the one place `outstanding` is computed — and not in the gate, so\n     * there is a single answer to \"does this branch owe review?\". When the gate did its own filtering, the\n     * command that lists and the command that blocks were two implementations of the same question, which is\n     * exactly the divergence this class's docstring exists to prevent.\n     */\n    private blocking(stillOwed: readonly RequiredChecklist[], optionalNotRun: readonly RequiredChecklist[]): RequiredChecklist[] {\n        const skipped = new Set(optionalNotRun.map((r: RequiredChecklist): string => r.id));\n        return stillOwed.filter((r: RequiredChecklist): boolean => !skipped.has(r.id));\n    }\n\n    /**\n     * Every file changed since the fork point, INCLUDING uncommitted and untracked ones. Two non-default\n     * options, both load-bearing:\n     *\n     * `tsOnly:false`        — the default drops every *.sql / Dockerfile / .env* file a checklist most wants\n     *                         to key on, which would silently shrink the set a reviewer is pointed at.\n     * `includeDeletions:true` — the default is `--diff-filter=d`, so a DELETED file is invisible. A PR that\n     *                         deletes a migration, an auth check or a terraform rule changed exactly what a\n     *                         checklist exists to catch, and under the default no checklist fires at all.\n     */\n    private changedFiles(repoRoot: string, base: string): string[] {\n        if (base === '') return [];\n        const opts = new ChangedFilesOptions();\n        opts.tsOnly = false;\n        opts.includeDeletions = true;\n        // No head argument — see the class comment. This is what includes the working tree.\n        return this.diffScope.getChangedFiles(repoRoot, base, undefined, opts);\n    }\n}\n"]}
+{"version":3,"file":"checklist-scanner.js","sourceRoot":"","sources":["../../../../../../../packages/tooling/pr-gate/src/scripts/workflow/checklist-scanner.ts"],"names":[],"mappings":"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","sourcesContent":["import {\n    ChangedFilesOptions, ChecklistDefinition, ChecklistResult, ChecklistReviewContext, DiffScope,\n    HomeConfigService, RequiredChecklist, ReviewJsonService, reviewJsonPath,\n} from '@webpieces/rules-config';\nimport { injectable, bindingScopeValues } from 'inversify';\nimport { AiBranchName } from './git-readAiBranchName';\nimport { ChecklistDetector, ChecklistRoster } from './checklist-detector';\nimport { DiffBasis, DiffBasisResolver } from './diff-basis';\nimport { PrContextWriter } from './pr-context-writer';\n\n/** How a caller wants the scan filtered. Data-only (per CLAUDE.md). */\nexport class ChecklistScanOptions {\n    /**\n     * false — `outstanding` is every applicable checklist (what `wp-review-upsert-pr` LISTS).\n     * true  — `outstanding` drops the ones already carrying a passing/overridden verdict, leaving only what\n     *         still owes review (what `wp-finish-upsert-pr` BLOCKS on).\n     */\n    filterAlreadyReviewed: boolean;\n    /**\n     * Which per-stage snapshot this scan should persist ('stage3-finish', …), or '' for \"do not write\n     * pr-context.json here\".\n     *\n     * '' exists for stage ②, which cannot write yet: the context records `diffDir`, and the diff has not\n     * been materialized at scan time. Letting the scan write anyway meant stage ② wrote the file twice,\n     * ~60 lines apart, the first time with an empty diffDir. Now it writes once, after materializing.\n     *\n     * The DEFAULT is deliberately non-empty, so writing is what you get by NOT thinking about it. A\n     * reviewer block that lost its diff command because nobody had written pr-context.json is a bug this\n     * codebase has already shipped once (see PrContextWriter's docstring); opting out must be an explicit,\n     * visible act by a caller that takes responsibility for writing it later — not an omission.\n     */\n    contextStage: string;\n\n    constructor(filterAlreadyReviewed = false, contextStage = 'stage-scan') {\n        this.filterAlreadyReviewed = filterAlreadyReviewed;\n        this.contextStage = contextStage;\n    }\n}\n\n/**\n * The answer to \"what review does this branch owe?\", in the X → N → Z terms the commands report:\n *   X = `defined`     — every checklist in pr-gate.checklists\n *   N = `applicable`  — those whose patterns matched (or that have no patterns, so always run)\n *   Z = `outstanding` — of N, those still owing a verdict (only when filterAlreadyReviewed)\n * Data-only.\n */\nexport class ChecklistScan {\n    defined: ChecklistDefinition[];      // X\n    applicable: RequiredChecklist[];     // N\n    reviewed: RequiredChecklist[];       // N − Z: already have a passing/warned/overridden review-<id>.json\n    outstanding: RequiredChecklist[];    // Z (== applicable when not filtering)\n    context: ChecklistReviewContext;     // fork-point sha + pr-context.json path\n    reviewPath: string;                  // the branch's review.json; verdict files sit beside it\n    forkPoint: string;                   // '' when no fork point resolved\n    // ALL X, matched or not, with why — what the PR comment publishes as its roster. Skipped checklists are\n    // absent from `applicable` by construction, and recovering them downstream would mean a second\n    // changed-file computation with different semantics (see the class comment).\n    roster: ChecklistRoster;\n    // Verdict files that exist but cannot be read as a verdict (e.g. still using the removed `success`).\n    // Carried on the SCAN because wp-finish-upsert-pr refuses on missing reviewers before it ever parses\n    // review.json — a complaint raised only in there would never reach the AI.\n    formatErrors: string[];\n    /**\n     * The basis the matching ACTUALLY ran against. Carried out so a caller that materializes the diff\n     * (stage ②) reuses the identical range instead of resolving its own — two independent resolutions is\n     * exactly how the changed-file set and the printed `git diff` command came to disagree.\n     */\n    basis: DiffBasis;\n    changedFiles: string[];              // the full changed-file set the matching ran against\n    /**\n     * The verdict files the scan ALREADY read, carried out rather than dropped.\n     *\n     * `outstanding` answers \"who still owes a verdict?\" but not \"why\" — and the two reasons demand opposite\n     * actions from the reader: a reviewer that never ran must be SPAWNED, a reviewer that ran and REFUSED\n     * must not be (it will refuse again; the finding has to be fixed first). Telling them apart means\n     * resolving each checklist's verdict, and without the results here every caller either re-reads the same\n     * files off disk — a second read that can disagree with this one — or merges the two cases into one\n     * message, which is exactly the loop this field exists to break.\n     */\n    results: ChecklistResult[];\n    /**\n     * The OPTIONAL (`required: false`) applicable checklists carrying no verdict file — i.e. nobody ran them.\n     *\n     * Deliberately NOT in `outstanding` when filtering: that is the exemption that makes `required: false`\n     * mean something. Carried out as its own set rather than merely subtracted, because both readers need it\n     * BY NAME and neither can recover it from what is left: stage ② offers exactly these to the human, and\n     * the PR dashboard must publish them as \"not run\" rather than let a shorter roster imply everything\n     * passed. An optional checklist that ran and went RED is absent from here and stays in `outstanding`.\n     */\n    optionalNotRun: RequiredChecklist[];\n    /**\n     * TRUE when this machine's `~/.webpieces/config.json` carries\n     * `experimental.turnOffAllReviewers: true`, and therefore when `applicable`, `reviewed`,\n     * `outstanding`, `results`, `optionalNotRun` and `formatErrors` above are ALL EMPTY BY DECREE rather\n     * than because nothing matched. Those two states are indistinguishable from the empty lists alone,\n     * and telling them apart is the entire reason this field exists: an unreviewed PR must never render\n     * as a reviewed one.\n     *\n     * `defined`, `roster`, `basis`, `changedFiles` and `context` are deliberately left INTACT under\n     * suppression, so every reader can still say WHAT was switched off — including which REQUIRED\n     * checklists would otherwise have run.\n     *\n     * See `HOME_KEY_TURN_OFF_ALL_REVIEWERS` in rules-config for the flag's contract; it is an\n     * `experimental.*` flag, so only a human ever ends it.\n     */\n    reviewersDisabled: boolean;\n    /**\n     * The checklists that WOULD have been `applicable` had the reviewers not been suppressed — required\n     * ones included. EMPTY on every ordinary run, and empty is not ambiguous there because\n     * `reviewersDisabled` is false.\n     *\n     * Carried by NAME and not as a count because every reader needs a different slice of it: stage ②\n     * prints them so a human can see exactly which required reviewer was killed, the dashboard names them\n     * in the 1st comment, and the compact PR body needs only `.length`. Recomputing any of that\n     * downstream would mean a second changed-file computation that can disagree with this one.\n     */\n    suppressed: RequiredChecklist[];\n\n    // eslint-disable-next-line @typescript-eslint/max-params\n    constructor(\n        defined: ChecklistDefinition[],\n        applicable: RequiredChecklist[],\n        reviewed: RequiredChecklist[],\n        outstanding: RequiredChecklist[],\n        context: ChecklistReviewContext,\n        reviewPath: string,\n        forkPoint: string,\n        roster: ChecklistRoster,\n        formatErrors: string[],\n        // REQUIRED, and placed BEFORE the defaulted tail deliberately. A defaulted `reviewersDisabled =\n        // false` would let every existing construction keep compiling while asserting, silently, that no\n        // reviewer was switched off — the widening-by-omission `.claude/rules/no-backwards-compat.md`\n        // rejects, and on the one field whose whole job is to stop an unreviewed PR reading as reviewed.\n        reviewersDisabled: boolean,\n        suppressed: RequiredChecklist[],\n        basis: DiffBasis = new DiffBasis(),\n        changedFiles: string[] = [],\n        // Defaulted so a caller that only cares about the X/N/Z counts (and every existing test construction)\n        // stays a one-liner; the scanner itself always passes the real set.\n        results: ChecklistResult[] = [],\n        optionalNotRun: RequiredChecklist[] = [],\n    ) {\n        this.defined = defined;\n        this.applicable = applicable;\n        this.reviewed = reviewed;\n        this.outstanding = outstanding;\n        this.context = context;\n        this.reviewPath = reviewPath;\n        this.forkPoint = forkPoint;\n        this.roster = roster;\n        this.formatErrors = formatErrors;\n        this.reviewersDisabled = reviewersDisabled;\n        this.suppressed = suppressed;\n        this.basis = basis;\n        this.changedFiles = changedFiles;\n        this.results = results;\n        this.optionalNotRun = optionalNotRun;\n    }\n}\n\n/**\n * The ONE computation of which reviewer subagents a branch owes, shared by `wp-review-upsert-pr` (which lists) and\n * `wp-finish-upsert-pr` (which blocks). They previously each assembled this from the same parts in slightly\n * different ways, and any divergence means the command that reports and the command that gates disagree.\n *\n * Two properties are deliberate and load-bearing:\n *\n * 1. **The base is the FORK POINT of main, computed directly** — never `DiffScope.resolveBase`, which\n *    overlays `NX_BASE`/`NX_HEAD` from the environment. That made review coverage depend on an env var.\n *    It now arrives via {@link DiffBasisResolver}, which injects ForkPoint; same sha, one resolution.\n * 2. **UNCOMMITTED work counts.** `getChangedFiles` is called with NO head, which is the branch of it that\n *    diffs base → WORKING TREE and unions in untracked files. Passing a head would diff commit-to-commit and\n *    silently miss staged, unstaged and untracked changes — so a checklist matching only uncommitted files\n *    would never fire and its reviewer would never be listed.\n * 3. **The range and the command it prints are the SAME basis.** Property 2 used to be true of the file set\n *    only: reviewers were handed `git diff <base> HEAD`, which on a dirty tree covers a different range and\n *    prints nothing. Both now derive from one {@link DiffBasis}, carried on the scan so a materializing\n *    caller cannot re-resolve and drift.\n *\n * `@injectable(bindingScopeValues.Singleton)` so it is injected by type and drawn in the DI design.\n */\n@injectable(bindingScopeValues.Singleton)\nexport class ChecklistScanner {\n    constructor(\n        private readonly aiBranchName: AiBranchName,\n        private readonly checklistDetector: ChecklistDetector,\n        private readonly diffScope: DiffScope,\n        private readonly diffBasisResolver: DiffBasisResolver,\n        private readonly prContextWriter: PrContextWriter,\n        private readonly reviewJsonService: ReviewJsonService,\n        // Injected BY TYPE (no Symbol token, per CLAUDE.md) so the ONE reviewer kill switch is read in the\n        // ONE place that computes what a branch owes — see the suppression note on `scan`.\n        private readonly homeConfig: HomeConfigService,\n    ) {}\n\n    /**\n     * `defined` is the caller's ALREADY-VALIDATED `prGate.checklists`. The scanner deliberately does not load\n     * config itself: `loadAndValidate` is the one gate on the checklist set (it rejects a non-array\n     * `checklists`, including the removed `{ doc }` manifest shape, and verifies every guidance doc and\n     * reviewer-agent file exists), both callers already run it for other fields, and keeping the read out of\n     * here leaves this a function of its inputs rather than of the filesystem.\n     */\n    scan(repoRoot: string, defined: ChecklistDefinition[], opts: ChecklistScanOptions): ChecklistScan {\n        const featureName = this.aiBranchName.getFeatureName();\n        const reviewPath = reviewJsonPath(repoRoot, featureName);\n        // ONE basis for the file set, the reproduce command and any downstream materialization. The fork\n        // point still comes from ForkPoint (never DiffScope.resolveBase) — DiffBasisResolver injects it.\n        const basis = this.diffBasisResolver.resolve(repoRoot);\n        const base = basis.base;\n        // ONE changed-file computation feeds both the roster (all X) and the applicable set (N). `detect` is\n        // pure and defined as the roster minus its empty entries, so the two cannot disagree about a match.\n        const changedFiles = this.changedFiles(repoRoot, base);\n        const roster = new ChecklistRoster(\n            this.checklistDetector.roster(defined, changedFiles), changedFiles.length, base !== '');\n        const matched = this.checklistDetector.toRequired(this.checklistDetector.detect(defined, changedFiles));\n        // THE ONE CHOKE POINT for `experimental.turnOffAllReviewers`. Suppressing HERE — rather than in\n        // `wp-review-upsert-pr` and again in `wp-finish-upsert-pr` — is what keeps the command that LISTS\n        // and the command that BLOCKS in agreement by construction, which is this class's whole reason for\n        // existing. A second check in either command would be a second answer to one question.\n        const context = opts.contextStage === ''\n            ? this.prContextWriter.contextFor(repoRoot, featureName, basis)\n            : this.prContextWriter.ensure(repoRoot, featureName, basis, opts.contextStage, changedFiles);\n        if (this.homeConfig.load().turnOffAllReviewers) {\n            // EMPTY: applicable, reviewed, outstanding, formatErrors, results, optionalNotRun. INTACT:\n            // defined, roster, basis, changedFiles, context — so every downstream reader can still say\n            // WHAT was suppressed, which is the difference between an honest record and a silent one.\n            return new ChecklistScan(\n                defined, [], [], [], context, reviewPath, base, roster, [], true, matched, basis,\n                changedFiles, [], []);\n        }\n        const applicable = matched;\n        const results = this.reviewJsonService.loadChecklistResults(reviewPath, applicable);\n        const stillOwed = this.reviewJsonService.pendingChecklists(applicable, results);\n        const owedIds = new Set(stillOwed.map((r: RequiredChecklist): string => r.id));\n        // NOT `!owedIds.has(...)`-with-the-optional-exemption-folded-in: an optional checklist nobody ran is\n        // neither reviewed nor blocking, and calling it \"reviewed\" would put a ✓ on the dashboard for a review\n        // that never happened.\n        const reviewed = applicable.filter((r: RequiredChecklist): boolean => !owedIds.has(r.id));\n        const optionalNotRun = this.reviewJsonService.optionalWithoutVerdict(applicable, results);\n        return new ChecklistScan(\n            defined,\n            applicable,\n            reviewed,\n            opts.filterAlreadyReviewed ? this.blocking(stillOwed, optionalNotRun) : applicable,\n            context,\n            reviewPath,\n            base,\n            roster,\n            this.reviewJsonService.checklistFormatErrors(applicable, results),\n            false,\n            [],\n            basis,\n            changedFiles,\n            results,\n            optionalNotRun,\n        );\n    }\n\n    /**\n     * What `wp-finish-upsert-pr` actually REFUSES on: everything still owing a verdict, minus the optional\n     * checklists nobody ran.\n     *\n     * The subtraction happens HERE — in the one place `outstanding` is computed — and not in the gate, so\n     * there is a single answer to \"does this branch owe review?\". When the gate did its own filtering, the\n     * command that lists and the command that blocks were two implementations of the same question, which is\n     * exactly the divergence this class's docstring exists to prevent.\n     */\n    private blocking(stillOwed: readonly RequiredChecklist[], optionalNotRun: readonly RequiredChecklist[]): RequiredChecklist[] {\n        const skipped = new Set(optionalNotRun.map((r: RequiredChecklist): string => r.id));\n        return stillOwed.filter((r: RequiredChecklist): boolean => !skipped.has(r.id));\n    }\n\n    /**\n     * Every file changed since the fork point, INCLUDING uncommitted and untracked ones. Two non-default\n     * options, both load-bearing:\n     *\n     * `tsOnly:false`        — the default drops every *.sql / Dockerfile / .env* file a checklist most wants\n     *                         to key on, which would silently shrink the set a reviewer is pointed at.\n     * `includeDeletions:true` — the default is `--diff-filter=d`, so a DELETED file is invisible. A PR that\n     *                         deletes a migration, an auth check or a terraform rule changed exactly what a\n     *                         checklist exists to catch, and under the default no checklist fires at all.\n     */\n    private changedFiles(repoRoot: string, base: string): string[] {\n        if (base === '') return [];\n        const opts = new ChangedFilesOptions();\n        opts.tsOnly = false;\n        opts.includeDeletions = true;\n        // No head argument — see the class comment. This is what includes the working tree.\n        return this.diffScope.getChangedFiles(repoRoot, base, undefined, opts);\n    }\n}\n"]}

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

@@ -40,6 +40,23 @@ export declare class ReviewReportInput {
      * a REQUIRED reviewer, and it is not a gate — nothing about what blocks the PR changes.
      */
     skipOptional: boolean;
+    /**
+     * `experimental.turnOffAllReviewers` is TRUE in `~/.webpieces/config.json`, so NO reviewer ran and
+     * none will — the REQUIRED ones included. Nothing else in this class may be read as evidence of that:
+     * `applicableCount` is 0 under suppression exactly as it is on a docs-only PR that matched nothing,
+     * and those two must never print the same thing.
+     *
+     * When true this stage prints a LOUD banner naming the flag, the file and every suppressed checklist,
+     * and prints NO spawn block. Reviewers cannot be spawned — there are no briefings and no instructions
+     * files — so a block telling an agent to spawn them would be an instruction it cannot obey.
+     */
+    reviewersSuppressed: boolean;
+    /**
+     * The checklists that WOULD have applied, had they not been suppressed. Empty unless
+     * `reviewersSuppressed`. Named, not counted, because the one thing a human must be able to see is
+     * WHICH required reviewer was killed.
+     */
+    suppressed: RequiredChecklist[];
     constructor(repoRoot: string, featureName: string, reviewPath: string);
 }
 /**
@@ -86,6 +103,19 @@ export declare class ReviewReport {
      * mistaken for the next action.
      */
     private scanVerdict;
+    /**
+     * THE LOUD BANNER. The one output in this whole flow that says an unreviewed PR is about to be posted.
+     *
+     * Everything in it is there because a reader has to be able to act on it or audit it: the FLAG name and
+     * the FILE it was read from (the only actionable thing — nothing in any repo turns this off), the COUNT
+     * split by required/optional, and every suppressed checklist BY NAME with REQUIRED marked. A count
+     * alone would leave "which required reviewer did I just skip?" unanswerable at the one moment it is
+     * being answered.
+     *
+     * It deliberately does NOT name `wp-finish-upsert-pr` — the closing step already does, exactly once,
+     * and that "exactly once" is an invariant this class's docstring records having been bought with a bug.
+     */
+    private suppressionBanner;
     /**
      * `--no-optional`, stated as a VERDICT rather than left silent. Named individually, not just counted: the
      * whole reason the human is allowed to skip these is that they know this diff, and the only way they can

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

@@ -50,6 +50,23 @@ class ReviewReportInput {
      * a REQUIRED reviewer, and it is not a gate — nothing about what blocks the PR changes.
      */
     skipOptional;
+    /**
+     * `experimental.turnOffAllReviewers` is TRUE in `~/.webpieces/config.json`, so NO reviewer ran and
+     * none will — the REQUIRED ones included. Nothing else in this class may be read as evidence of that:
+     * `applicableCount` is 0 under suppression exactly as it is on a docs-only PR that matched nothing,
+     * and those two must never print the same thing.
+     *
+     * When true this stage prints a LOUD banner naming the flag, the file and every suppressed checklist,
+     * and prints NO spawn block. Reviewers cannot be spawned — there are no briefings and no instructions
+     * files — so a block telling an agent to spawn them would be an instruction it cannot obey.
+     */
+    reviewersSuppressed;
+    /**
+     * The checklists that WOULD have applied, had they not been suppressed. Empty unless
+     * `reviewersSuppressed`. Named, not counted, because the one thing a human must be able to see is
+     * WHICH required reviewer was killed.
+     */
+    suppressed;
     constructor(repoRoot, featureName, reviewPath) {
         this.repoRoot = repoRoot;
         this.featureName = featureName;
@@ -61,6 +78,8 @@ class ReviewReportInput {
         this.briefings = [];
         this.refused = [];
         this.skipOptional = false;
+        this.reviewersSuppressed = false;
+        this.suppressed = [];
     }
 }
 exports.ReviewReportInput = ReviewReportInput;
@@ -109,6 +128,11 @@ let ReviewReport = class ReviewReport {
      * single line most likely to make it do exactly that.
      */
     header(input) {
+        // FIRST, and unconditional: with the kill switch on there is nothing to spawn and nothing to
+        // offer, so every heading below would be true-but-misleading. The one thing a reader must take
+        // from the first line of this block is that no reviewer looked at this branch.
+        if (input.reviewersSuppressed)
+            return '② ⚫ ALL REVIEWERS SUPPRESSED — review, then finish\n';
         if (this.requiredOwed(input).length > 0)
             return '② Review, spawn subagent reviewers, then finish\n';
         if (this.offerableOwed(input).length > 0)
@@ -121,6 +145,11 @@ let ReviewReport = class ReviewReport {
      * mistaken for the next action.
      */
     scanVerdict(input) {
+        // BEFORE the zero-applicable notice, which would otherwise say "nothing matched this diff" — the
+        // single most misleading sentence available here, because plenty matched and every one of them was
+        // switched off.
+        if (input.reviewersSuppressed)
+            return '\n' + this.suppressionBanner(input);
         if (input.applicableCount === 0)
             return '\n' + this.checklistNotice.build(input.definedCount);
         const lines = [];
@@ -142,6 +171,32 @@ let ReviewReport = class ReviewReport {
             return '';
         return '\n' + lines.join('\n') + '\n';
     }
+    /**
+     * THE LOUD BANNER. The one output in this whole flow that says an unreviewed PR is about to be posted.
+     *
+     * Everything in it is there because a reader has to be able to act on it or audit it: the FLAG name and
+     * the FILE it was read from (the only actionable thing — nothing in any repo turns this off), the COUNT
+     * split by required/optional, and every suppressed checklist BY NAME with REQUIRED marked. A count
+     * alone would leave "which required reviewer did I just skip?" unanswerable at the one moment it is
+     * being answered.
+     *
+     * It deliberately does NOT name `wp-finish-upsert-pr` — the closing step already does, exactly once,
+     * and that "exactly once" is an invariant this class's docstring records having been bought with a bug.
+     */
+    suppressionBanner(input) {
+        const required = input.suppressed.filter((r) => r.required);
+        const lines = [
+            '⚫ ALL REVIEWER SUBAGENTS ARE SWITCHED OFF ON THIS MACHINE. Nothing reviewed this branch.',
+            '',
+            `   ${input.suppressed.length} checklist(s) matched this diff and were SUPPRESSED — `
+                + `${required.length} of them REQUIRED:`,
+        ];
+        for (const r of input.suppressed) {
+            lines.push(`     • ${r.subagent}${r.required ? '  (REQUIRED — suppressed anyway)' : '  (optional)'}`);
+        }
+        lines.push('', `   Switched off by:  experimental.${rules_config_1.HOME_KEY_TURN_OFF_ALL_REVIEWERS}: true`, `   Read from:        ~/${rules_config_1.HOME_CONFIG_DIR}/${rules_config_1.HOME_CONFIG_FILE}  (machine-local; no repo config can set this)`, '', '   There is NOTHING to spawn — no reviewer was briefed and no instructions file was written,', '   so any attempt to spawn one has nothing to read. Do NOT hand-write a verdict file in their', '   place: a fabricated verdict is worse than the absent one this flag deliberately produces.', '', '   The dashboard is the whole review product for this PR, and the suppression is carried into', '   the PR body — which is the squash-merge commit body — so main\'s history records it.', '   To get the reviewers back, set that key to false (or delete it) and re-run this command.');
+        return lines.join('\n') + '\n';
+    }
     /**
      * `--no-optional`, stated as a VERDICT rather than left silent. Named individually, not just counted: the
      * whole reason the human is allowed to skip these is that they know this diff, and the only way they can