@webpieces/pr-gate 0.4.564 → 0.4.565

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

@@ -62,7 +62,17 @@ export declare class ChecklistScan {
      * message, which is exactly the loop this field exists to break.
      */
     results: ChecklistResult[];
-    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[]);
+    /**
+     * The OPTIONAL (`required: false`) applicable checklists carrying no verdict file — i.e. nobody ran them.
+     *
+     * Deliberately NOT in `outstanding` when filtering: that is the exemption that makes `required: false`
+     * mean something. Carried out as its own set rather than merely subtracted, because both readers need it
+     * BY NAME and neither can recover it from what is left: stage ② offers exactly these to the human, and
+     * the PR dashboard must publish them as "not run" rather than let a shorter roster imply everything
+     * 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[]);
 }
 /**
  * The ONE computation of which reviewer subagents a branch owes, shared by `wp-review-upsert-pr` (which lists) and
@@ -101,6 +111,16 @@ export declare class ChecklistScanner {
      * here leaves this a function of its inputs rather than of the filesystem.
      */
     scan(repoRoot: string, defined: ChecklistDefinition[], opts: ChecklistScanOptions): ChecklistScan;
+    /**
+     * What `wp-finish-upsert-pr` actually REFUSES on: everything still owing a verdict, minus the optional
+     * checklists nobody ran.
+     *
+     * The subtraction happens HERE — in the one place `outstanding` is computed — and not in the gate, so
+     * there is a single answer to "does this branch owe review?". When the gate did its own filtering, the
+     * command that lists and the command that blocks were two implementations of the same question, which is
+     * exactly the divergence this class's docstring exists to prevent.
+     */
+    private blocking;
     /**
      * Every file changed since the fork point, INCLUDING uncommitted and untracked ones. Two non-default
      * options, both load-bearing:

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

@@ -77,11 +77,21 @@ class ChecklistScan {
      * message, which is exactly the loop this field exists to break.
      */
     results;
+    /**
+     * The OPTIONAL (`required: false`) applicable checklists carrying no verdict file — i.e. nobody ran them.
+     *
+     * Deliberately NOT in `outstanding` when filtering: that is the exemption that makes `required: false`
+     * mean something. Carried out as its own set rather than merely subtracted, because both readers need it
+     * BY NAME and neither can recover it from what is left: stage ② offers exactly these to the human, and
+     * the PR dashboard must publish them as "not run" rather than let a shorter roster imply everything
+     * passed. An optional checklist that ran and went RED is absent from here and stays in `outstanding`.
+     */
+    optionalNotRun;
     // 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 = [], 
     // 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 = []) {
+    results = [], optionalNotRun = []) {
         this.defined = defined;
         this.applicable = applicable;
         this.reviewed = reviewed;
@@ -94,6 +104,7 @@ class ChecklistScan {
         this.basis = basis;
         this.changedFiles = changedFiles;
         this.results = results;
+        this.optionalNotRun = optionalNotRun;
     }
 }
 exports.ChecklistScan = ChecklistScan;
@@ -155,10 +166,27 @@ let ChecklistScanner = class ChecklistScanner {
         const results = this.reviewJsonService.loadChecklistResults(reviewPath, applicable);
         const stillOwed = this.reviewJsonService.pendingChecklists(applicable, results);
         const owedIds = new Set(stillOwed.map((r) => r.id));
+        // NOT `!owedIds.has(...)`-with-the-optional-exemption-folded-in: an optional checklist nobody ran is
+        // neither reviewed nor blocking, and calling it "reviewed" would put a ✓ on the dashboard for a review
+        // that never happened.
         const reviewed = applicable.filter((r) => !owedIds.has(r.id));
-        return new ChecklistScan(defined, applicable, reviewed, opts.filterAlreadyReviewed ? stillOwed : applicable, opts.contextStage === ''
+        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);
+            : this.prContextWriter.ensure(repoRoot, featureName, basis, opts.contextStage, changedFiles), reviewPath, base, roster, this.reviewJsonService.checklistFormatErrors(applicable, results), basis, changedFiles, results, optionalNotRun);
+    }
+    /**
+     * What `wp-finish-upsert-pr` actually REFUSES on: everything still owing a verdict, minus the optional
+     * checklists nobody ran.
+     *
+     * The subtraction happens HERE — in the one place `outstanding` is computed — and not in the gate, so
+     * there is a single answer to "does this branch owe review?". When the gate did its own filtering, the
+     * command that lists and the command that blocks were two implementations of the same question, which is
+     * exactly the divergence this class's docstring exists to prevent.
+     */
+    blocking(stillOwed, optionalNotRun) {
+        const skipped = new Set(optionalNotRun.map((r) => r.id));
+        return stillOwed.filter((r) => !skipped.has(r.id));
     }
     /**
      * Every file changed since the fork point, INCLUDING uncommitted and untracked ones. Two non-default

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":"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","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    // 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    ) {\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    }\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        const reviewed = applicable.filter((r: RequiredChecklist): boolean => !owedIds.has(r.id));\n        return new ChecklistScan(\n            defined,\n            applicable,\n            reviewed,\n            opts.filterAlreadyReviewed ? stillOwed : 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        );\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    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"]}

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

@@ -33,6 +33,12 @@ export declare class ReviewReportInput {
     formatErrors: string[];
     briefings: ReviewerBriefing[];
     refused: RefusedReviewer[];
+    /**
+     * `--no-optional` was passed: the human has already said to submit without the optional reviews, so the
+     * block that offers them is replaced by a one-line statement that they were skipped. It never suppresses
+     * a REQUIRED reviewer, and it is not a gate — nothing about what blocks the PR changes.
+     */
+    skipOptional: boolean;
     constructor(repoRoot: string, featureName: string, reviewPath: string);
 }
 /**
@@ -50,6 +56,9 @@ export declare class ReviewReportInput {
  *   1. `wp-finish-upsert-pr` is named as a thing to run EXACTLY ONCE in the whole block.
  *   2. The review.json instruction comes BEFORE it — and BEFORE the spawn blocks (see nextSteps).
  *   3. With zero checklists the all-clear precedes any configuration guidance.
+ *   4. REQUIRED reviewers are spawned unasked; OPTIONAL ones are only ever OFFERED, in one batched
+ *      question. The two never share a step, because one instruction says "do it" and the other says
+ *      "ask first", and an agent reading a merged list will act on the stronger of the two.
  *
  * Pure string building, no I/O. `@injectable(bindingScopeValues.Singleton)` so it is injected by type.
  */
@@ -58,6 +67,17 @@ export declare class ReviewReport {
     private readonly reviewerInstructions;
     constructor(checklistNotice: ChecklistNotice, reviewerInstructions: ReviewerInstructionsService);
     render(input: ReviewReportInput): string;
+    /**
+     * Name what this block is actually about. A repo with reviewers owed is being told to SPAWN; a repo with
+     * none is not, and promising subagents it does not have is the same kind of noise as explaining checklist
+     * configuration to a repo that configured none. Keyed on what is actually ACTIONABLE rather than on the
+     * applicable count: every applicable checklist already having a verdict means nothing to spawn, and so
+     * does a branch whose only outstanding reviews are optional ones the human already waved off.
+     *
+     * "spawn" and "ask about" are separate headings because they are separate obligations. A branch owing
+     * only optional reviews has nothing the AI may do unilaterally, and a heading that says SPAWN is the
+     * single line most likely to make it do exactly that.
+     */
     private header;
     /**
      * What the SCAN found: either "nothing applies here" or the already-reviewed / unreadable-verdict lines.
@@ -65,6 +85,13 @@ export declare class ReviewReport {
      * mistaken for the next action.
      */
     private scanVerdict;
+    /**
+     * `--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
+     * catch "wait, not THAT one" is to see which ones went unreviewed.
+     */
+    private skippedLines;
+    private allClear;
     /**
      * The ONE instruction block, and the last thing the stage prints. Numbered rather than prose-linked
      * ("Then… Finally…") so that skipping step 1 is visibly skipping a step, and worded so no earlier line
@@ -88,14 +115,40 @@ export declare class ReviewReport {
     private nextSteps;
     private writeReviewStep;
     /**
-     * STEP 2 — one copy-paste block per owed reviewer, and nothing at all when none is owed. The prompt is
+     * The REQUIRED reviewers — one copy-paste block each, and nothing at all when none is owed. The prompt is
      * deliberately a POINTER and nothing else: the generated instructions file is the contract, so anything
      * restated here is a second copy that can go stale — which is exactly how a removed `success` field
      * outlived its own removal in print.
+     *
+     * These are spawned WITHOUT asking. They are the checklists the repo declared `required: true`, which is
+     * the repo saying the decision was already made; putting them to the human again would re-open a question
+     * the config exists to settle.
      */
     private spawnStep;
+    /**
+     * STEP n — the OPTIONAL reviewers: listed, never spawned unasked.
+     *
+     * This is the whole point of `required: false`. A one-line bug fix in a repo whose checklists key on a
+     * glob as broad as every TypeScript file otherwise pays for a dozen subagent reviews, and the only party
+     * who can judge whether this particular diff is worth them is the human looking at it.
+     *
+     * ONE batched multi-select question, explicitly. Asked one at a time, a human answering "no" nine times
+     * is being worn down rather than consulted, and by the third question the cheap thing is to say yes to
+     * everything — which is the state this feature exists to leave. The "None" option has to be spelled out
+     * too: an agent that offers a list without an explicit way to decline it has not really offered a choice.
+     *
+     * The blocking consequence is stated because it is the one non-obvious part of the contract: `required`
+     * governs whether a reviewer must RUN, not whether its answer counts. Choosing to run one and then
+     * shrugging off a red verdict would make the whole exercise theater.
+     */
+    private offerStep;
+    private refusedWarning;
     private finishStep;
     private owedReviewers;
+    private requiredOwed;
+    private optionalOwed;
+    private offerableOwed;
+    private actionableOwed;
     /**
      * One reviewer's block. A reviewer that already REFUSED gets the SAME spawn coordinates but a different
      * lead-in, because the action before spawning is different: its own words are printed, and the spawn is
@@ -108,5 +161,13 @@ export declare class ReviewReport {
      */
     private oneSpawnBlock;
     private leadIn;
+    /**
+     * The checklist's guidance doc, for OPTIONAL reviewers only.
+     *
+     * "4 file(s) matched" plus a broad glob does not tell a human what the review would actually look AT,
+     * and they are being asked to decide exactly that. Omitted for required reviewers: there is no decision
+     * to inform there — the reviewer runs either way, and the doc is already in its instructions file.
+     */
+    private docLine;
     private why;
 }

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

@@ -43,6 +43,12 @@ class ReviewReportInput {
     formatErrors; // verdict files that exist but cannot be read as verdicts
     briefings; // one per applicable checklist, already written to disk
     refused; // of the owed ones, those that already ran and said no (see RefusedReviewer)
+    /**
+     * `--no-optional` was passed: the human has already said to submit without the optional reviews, so the
+     * block that offers them is replaced by a one-line statement that they were skipped. It never suppresses
+     * a REQUIRED reviewer, and it is not a gate — nothing about what blocks the PR changes.
+     */
+    skipOptional;
     constructor(repoRoot, featureName, reviewPath) {
         this.repoRoot = repoRoot;
         this.featureName = featureName;
@@ -53,6 +59,7 @@ class ReviewReportInput {
         this.formatErrors = [];
         this.briefings = [];
         this.refused = [];
+        this.skipOptional = false;
     }
 }
 exports.ReviewReportInput = ReviewReportInput;
@@ -71,6 +78,9 @@ exports.ReviewReportInput = ReviewReportInput;
  *   1. `wp-finish-upsert-pr` is named as a thing to run EXACTLY ONCE in the whole block.
  *   2. The review.json instruction comes BEFORE it — and BEFORE the spawn blocks (see nextSteps).
  *   3. With zero checklists the all-clear precedes any configuration guidance.
+ *   4. REQUIRED reviewers are spawned unasked; OPTIONAL ones are only ever OFFERED, in one batched
+ *      question. The two never share a step, because one instruction says "do it" and the other says
+ *      "ask first", and an agent reading a merged list will act on the stronger of the two.
  *
  * Pure string building, no I/O. `@injectable(bindingScopeValues.Singleton)` so it is injected by type.
  */
@@ -86,14 +96,23 @@ let ReviewReport = class ReviewReport {
             + this.scanVerdict(input)
             + this.nextSteps(input);
     }
-    // Name what this block is actually about. A repo with reviewers owed is being told to SPAWN; a repo
-    // with none is not, and promising subagents it does not have is the same kind of noise as explaining
-    // checklist configuration to a repo that configured none. Keyed on what is actually OWED rather than on
-    // the applicable count: every applicable checklist already having a verdict means nothing to spawn.
+    /**
+     * Name what this block is actually about. A repo with reviewers owed is being told to SPAWN; a repo with
+     * none is not, and promising subagents it does not have is the same kind of noise as explaining checklist
+     * configuration to a repo that configured none. Keyed on what is actually ACTIONABLE rather than on the
+     * applicable count: every applicable checklist already having a verdict means nothing to spawn, and so
+     * does a branch whose only outstanding reviews are optional ones the human already waved off.
+     *
+     * "spawn" and "ask about" are separate headings because they are separate obligations. A branch owing
+     * only optional reviews has nothing the AI may do unilaterally, and a heading that says SPAWN is the
+     * single line most likely to make it do exactly that.
+     */
     header(input) {
-        if (this.owedReviewers(input).length === 0)
-            return '② Review, then finish\n';
-        return '② Review, spawn subagent reviewers, then finish\n';
+        if (this.requiredOwed(input).length > 0)
+            return '② Review, spawn subagent reviewers, then finish\n';
+        if (this.offerableOwed(input).length > 0)
+            return '② Review, offer the optional reviewers, then finish\n';
+        return '② Review, then finish\n';
     }
     /**
      * What the SCAN found: either "nothing applies here" or the already-reviewed / unreadable-verdict lines.
@@ -112,13 +131,37 @@ let ReviewReport = class ReviewReport {
         // correcting the file sitting right there.
         for (const e of input.formatErrors)
             lines.push(`  ⛔ ${e}`);
-        if (this.owedReviewers(input).length === 0) {
-            lines.push('', '✅ Every checklist that applies is already reviewed — nothing to spawn.');
-        }
+        lines.push(...this.skippedLines(input));
+        if (this.actionableOwed(input).length === 0)
+            lines.push('', this.allClear(input));
         if (lines.length === 0)
             return '';
         return '\n' + 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
+     * catch "wait, not THAT one" is to see which ones went unreviewed.
+     */
+    skippedLines(input) {
+        const skipped = this.optionalOwed(input);
+        if (!input.skipOptional || skipped.length === 0)
+            return [];
+        return [
+            '',
+            `  ⏭️  ${skipped.length} OPTIONAL checklist(s) matched this diff and were SKIPPED (--no-optional):`,
+            ...skipped.map((b) => `       ${b.subagent} — ${this.why(b)}`),
+            '      Not blocking. Drop the flag and re-run this command to offer them after all.',
+        ];
+    }
+    // The all-clear. It must NOT claim everything was reviewed when optional reviews were skipped — that is
+    // the one sentence that would turn a deliberate skip into a false record of a review that happened.
+    allClear(input) {
+        if (input.skipOptional && this.optionalOwed(input).length > 0) {
+            return '✅ Nothing left to spawn — every REQUIRED checklist is reviewed (optional ones skipped above).';
+        }
+        return '✅ Every checklist that applies is already reviewed — nothing to spawn.';
+    }
     /**
      * The ONE instruction block, and the last thing the stage prints. Numbered rather than prose-linked
      * ("Then… Finally…") so that skipping step 1 is visibly skipping a step, and worded so no earlier line
@@ -140,16 +183,20 @@ let ReviewReport = class ReviewReport {
      * can never drift from the shape `wp-finish-upsert-pr` validates.
      */
     nextSteps(input) {
-        const owed = this.owedReviewers(input);
-        const stepCount = owed.length === 0 ? 2 : 3;
+        const required = this.requiredOwed(input);
+        const offerable = this.offerableOwed(input);
+        // Numbered by what is actually PRINTED, so the numbers a reader sees are 1..n with no gaps: write
+        // review.json, then a spawn step only if anything must run, then an offer step only if anything may.
+        let step = 1;
+        const write = this.writeReviewStep(input.reviewPath, step++);
+        const spawn = required.length === 0 ? '' : this.spawnStep(input, required, step++);
+        const offer = offerable.length === 0 ? '' : this.offerStep(input, offerable, step++);
         return '\n' + SEP
-            + `▶ NEXT — ${stepCount} steps, in this order. Step 1 is NOT optional:\n` + SEP + '\n'
-            + this.writeReviewStep(input.reviewPath)
-            + this.spawnStep(input, owed)
-            + this.finishStep(stepCount);
+            + `▶ NEXT — ${step} steps, in this order. Step 1 is NOT optional:\n` + SEP + '\n'
+            + write + spawn + offer + this.finishStep(step, required.length + offerable.length > 0);
     }
-    writeReviewStep(reviewPath) {
-        return ('STEP 1 — review your own changes, then write the review file. Write it FIRST — BEFORE you spawn\n' +
+    writeReviewStep(reviewPath, step) {
+        return (`STEP ${step} — review your own changes, then write the review file. Write it FIRST — BEFORE you spawn\n` +
             '         anything below. finish REFUSES without it, and a reviewer subagent may READ it: a\n' +
             '         checklist that judges the PR title, summary or risk level reads exactly this file, so\n' +
             '         writing it afterwards races that reviewer into seeing nothing — or, on a re-run of this\n' +
@@ -157,33 +204,87 @@ let ReviewReport = class ReviewReport {
             (0, rules_config_1.reviewJsonSchemaHint)(reviewPath) + '\n\n');
     }
     /**
-     * STEP 2 — one copy-paste block per owed reviewer, and nothing at all when none is owed. The prompt is
+     * The REQUIRED reviewers — one copy-paste block each, and nothing at all when none is owed. The prompt is
      * deliberately a POINTER and nothing else: the generated instructions file is the contract, so anything
      * restated here is a second copy that can go stale — which is exactly how a removed `success` field
      * outlived its own removal in print.
+     *
+     * These are spawned WITHOUT asking. They are the checklists the repo declared `required: true`, which is
+     * the repo saying the decision was already made; putting them to the human again would re-open a question
+     * the config exists to settle.
      */
-    spawnStep(input, owed) {
-        if (owed.length === 0)
-            return '';
+    spawnStep(input, owed, step) {
         const lines = [
-            `STEP 2 — only once that file is written, spawn these ${owed.length} reviewer subagent(s) — a SEPARATE`,
-            '         one each. You may NOT review your own work, and you may NOT write a reviewer\'s verdict',
-            '         file on its behalf.',
+            `STEP ${step} — only once that file is written, spawn these ${owed.length} REQUIRED reviewer subagent(s) — a`,
+            '         SEPARATE one each. They block the PR, so do NOT ask whether to run them. You may NOT',
+            '         review your own work, and you may NOT write a reviewer\'s verdict file on its behalf.',
             '',
         ];
-        // Said up front, not only beside the block: an agent that has decided to spawn everything listed here
-        // needs to know BEFORE it starts that one of these entries is not a spawn-shaped task.
-        if (input.refused.length > 0) {
-            lines.push(`         ${input.refused.length} of them already ANSWERED and refused (marked ⛔ below). Do not spawn`, '         those against unchanged code — fix what they found first; the fix is the prerequisite.', '');
-        }
+        lines.push(...this.refusedWarning(input, owed));
         for (const b of owed)
             lines.push(...this.oneSpawnBlock(input, b));
         lines.push('');
         return lines.join('\n');
     }
-    finishStep(stepNumber) {
-        const precondition = stepNumber === 3
-            ? 'once every reviewer above has written its verdict file'
+    /**
+     * STEP n — the OPTIONAL reviewers: listed, never spawned unasked.
+     *
+     * This is the whole point of `required: false`. A one-line bug fix in a repo whose checklists key on a
+     * glob as broad as every TypeScript file otherwise pays for a dozen subagent reviews, and the only party
+     * who can judge whether this particular diff is worth them is the human looking at it.
+     *
+     * ONE batched multi-select question, explicitly. Asked one at a time, a human answering "no" nine times
+     * is being worn down rather than consulted, and by the third question the cheap thing is to say yes to
+     * everything — which is the state this feature exists to leave. The "None" option has to be spelled out
+     * too: an agent that offers a list without an explicit way to decline it has not really offered a choice.
+     *
+     * The blocking consequence is stated because it is the one non-obvious part of the contract: `required`
+     * governs whether a reviewer must RUN, not whether its answer counts. Choosing to run one and then
+     * shrugging off a red verdict would make the whole exercise theater.
+     */
+    offerStep(input, offerable, step) {
+        const lines = [
+            `STEP ${step} — these ${offerable.length} OPTIONAL review checklist(s) matched this diff. They do NOT block the`,
+            '         PR, and you may NOT decide for the human whether to run them.',
+            '',
+            '         ASK THE HUMAN, in ONE multi-select question listing all of them plus an explicit',
+            '         "None — required only" choice. Do not ask one question per reviewer. Then spawn ONLY',
+            '         what they picked, the same way as any other reviewer.',
+            '',
+            '         If they pick none, that is a complete answer: go straight to the final step. If they',
+            '         told you up front to submit without reviews, re-run this stage as',
+            '         `pnpm wp-review-upsert-pr --no-optional` and this step disappears.',
+            '',
+            '         NOTE: whichever ones you DO run, their verdicts count in full — a red verdict from an',
+            '         optional reviewer blocks the PR exactly like a required one.',
+            '',
+        ];
+        lines.push(...this.refusedWarning(input, offerable));
+        for (const b of offerable)
+            lines.push(...this.oneSpawnBlock(input, b));
+        lines.push('');
+        return lines.join('\n');
+    }
+    // Said up front, not only beside the block: an agent that has decided to spawn everything listed here
+    // needs to know BEFORE it starts that one of these entries is not a spawn-shaped task. Scoped to the
+    // group being printed — a refusal among the REQUIRED reviewers is not a caveat on the optional list.
+    refusedWarning(input, group) {
+        const ids = new Set(group.map((b) => b.checklistId));
+        const n = input.refused.filter((r) => ids.has(r.checklistId)).length;
+        if (n === 0)
+            return [];
+        return [
+            `         ${n} of them already ANSWERED and refused (marked ⛔ below). Do not spawn`,
+            '         those against unchanged code — fix what they found first; the fix is the prerequisite.',
+            '',
+        ];
+    }
+    finishStep(stepNumber, anyReviewers) {
+        // "every reviewer you ran" rather than "every reviewer above": with an optional list the human may
+        // legitimately have run none of them, and a precondition naming reviewers that were declined reads as
+        // an unmeetable one.
+        const precondition = anyReviewers
+            ? 'once every reviewer you ran has written its verdict file'
             : 'once that file exists';
         return (`STEP ${stepNumber} — only ${precondition}, run:  pnpm wp-finish-upsert-pr\n` +
             '         (The build gate is already green for this commit — finish reuses it unless HEAD moves.)\n\n');
@@ -194,6 +295,24 @@ let ReviewReport = class ReviewReport {
         const reviewedIds = new Set(input.reviewed.map((r) => r.id));
         return input.briefings.filter((b) => !reviewedIds.has(b.checklistId));
     }
+    // Owed AND blocking — spawned without asking.
+    requiredOwed(input) {
+        return this.owedReviewers(input).filter((b) => b.required);
+    }
+    // Owed and optional. Still listed under `--no-optional` (as a skip verdict), just never as a step.
+    optionalOwed(input) {
+        return this.owedReviewers(input).filter((b) => !b.required);
+    }
+    // The optional ones the human is actually to be ASKED about — none, once they have already answered.
+    offerableOwed(input) {
+        return input.skipOptional ? [] : this.optionalOwed(input);
+    }
+    // Everything the AI still has to act on. Distinct from `owedReviewers`: a skipped optional checklist is
+    // owed a verdict it will never get, and treating it as pending work is what would print a spawn
+    // instruction for a review the human just declined.
+    actionableOwed(input) {
+        return [...this.requiredOwed(input), ...this.offerableOwed(input)];
+    }
     /**
      * One reviewer's block. A reviewer that already REFUSED gets the SAME spawn coordinates but a different
      * lead-in, because the action before spawning is different: its own words are printed, and the spawn is
@@ -219,7 +338,7 @@ let ReviewReport = class ReviewReport {
     leadIn(input, b) {
         const refusal = input.refused.find((r) => r.checklistId === b.checklistId);
         if (!refusal)
-            return [`  ▶ ${b.subagent} — ${this.why(b)}`];
+            return [`  ▶ ${b.subagent} — ${this.why(b)}`, ...this.docLine(b)];
         return [
             `  ⛔ ${b.subagent} — ALREADY REVIEWED THIS BRANCH AND REFUSED. It will refuse again on unchanged code.`,
             `      ${refusal.message}`,
@@ -227,6 +346,18 @@ let ReviewReport = class ReviewReport {
             '      write a fresh verdict:',
         ];
     }
+    /**
+     * The checklist's guidance doc, for OPTIONAL reviewers only.
+     *
+     * "4 file(s) matched" plus a broad glob does not tell a human what the review would actually look AT,
+     * and they are being asked to decide exactly that. Omitted for required reviewers: there is no decision
+     * to inform there — the reviewer runs either way, and the doc is already in its instructions file.
+     */
+    docLine(b) {
+        if (b.required || b.docPath === '')
+            return [];
+        return [`      reviews against: ${b.docPath}`];
+    }
     // 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) {