@webpieces/rules-config 0.4.774 → 0.4.776

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@webpieces/rules-config",
-  "version": "0.4.774",
+  "version": "0.4.776",
   "description": "Shared webpieces.config.json loader. Single source of truth for validation rule configuration consumed by @webpieces/ai-hook-rules, @webpieces/code-rules, and @webpieces/nx-webpieces-rules.",
   "type": "commonjs",
   "main": "./src/index.js",

package/src/checklist-config.d.ts

@@ -1,6 +1,38 @@
+/** The {@link ReviewerAgentPolicy.maxAgents} value meaning "`reviewerAgents` is not configured". */
+export declare const REVIEWER_AGENTS_ONE_PER_CHECKLIST = 0;
+/** The generic reviewer agent webpieces ships, and the value the config error tells a repo to add. */
+export declare const DEFAULT_REVIEWER_AGENT_NAME = "webpieces-reviewer";
+/**
+ * WHICH reviewer agent the gate briefs, and HOW MANY of them one round may use — straight from
+ * `commands.pr-gate.reviewerAgentName` / `commands.pr-gate.reviewerAgents`. Data-only.
+ *
+ * One instance per loaded config, shared by every {@link ChecklistDefinition} and copied onto every matched
+ * checklist, because the answer is repo-wide: a checklist no longer names an agent type of its own. It used
+ * to — a per-entry key pointing at its own `.claude/agents/<name>.md` — and those files added almost nothing
+ * over the checklist `doc` while forcing one subagent per checklist, so a PR matching four checklists paid
+ * for four agents re-reading the same diff (issue #938).
+ */
+export declare class ReviewerAgentPolicy {
+    /**
+     * The `subagent_type` every reviewer briefing names, e.g. `webpieces-reviewer` — the generic,
+     * checklist-agnostic agent webpieces ships (`.claude/agents/webpieces-reviewer.md`, written by
+     * `wp-install-ai-hooks` / `wp-upgrade-shim`). A repo may point it at its own agent instead.
+     */
+    agentName: string;
+    /**
+     * The most reviewer subagents one stage-② round may use, or {@link REVIEWER_AGENTS_ONE_PER_CHECKLIST}
+     * when `reviewerAgents` is not configured — which keeps the original contract: one separate subagent per
+     * checklist. When set, the main AI groups the owed checklists across at most this many subagents, and
+     * each subagent still writes one verdict file per checklist it covers.
+     */
+    maxAgents: number;
+    constructor(agentName: string, maxAgents: number);
+    /** true when `reviewerAgents` is configured, i.e. one subagent may cover several checklists. */
+    grouped(): boolean;
+}
 export declare class ChecklistDefinition {
     id: string;
-    subagent: string;
+    reviewer: ReviewerAgentPolicy;
     doc: string;
     patterns: string[];
     /**
@@ -20,24 +52,23 @@ export declare class ChecklistDefinition {
      * that the coding agent reading the error applies in a single pass.
      */
     required: boolean;
-    constructor(id: string, subagent: string, doc: string, patterns: string[], required: boolean);
+    constructor(id: string, reviewer: ReviewerAgentPolicy, doc: string, patterns: string[], required: boolean);
 }
 export interface RawChecklistItem {
-    subagent?: string;
+    id?: string;
     doc?: string;
     patterns?: string[];
     required?: boolean;
 }
 /**
- * Build a ChecklistDefinition from an omitting-friendly raw entry. `id` defaults to the subagent name (the
- * only stable, human-meaningful key we have).
+ * Build a ChecklistDefinition from a raw entry, bound to the repo's reviewer policy.
  *
  * `required` is coerced with `=== true` rather than defaulted, and that is not a default in disguise:
  * `validateChecklistArray` has already REJECTED any entry that omitted it or gave a non-boolean, so the
  * only values that reach here are real booleans. The coercion exists so a validator that runs without a
  * repoRoot (structure-only) still produces a well-typed def instead of `undefined` leaking through.
  */
-export declare function toChecklist(raw: RawChecklistItem): ChecklistDefinition;
+export declare function toChecklist(raw: RawChecklistItem, reviewer: ReviewerAgentPolicy): ChecklistDefinition;
 /** Normalize a checklist entry's repo-relative `doc` to a POSIX path, so every printed path matches. */
 export declare function normalizeChecklistDoc(doc: string): string;
 export declare const MATCHED_FILES_CAP = 6;

package/src/checklist-config.js

@@ -1,28 +1,66 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.MATCHED_FILES_CAP = exports.ChecklistDefinition = void 0;
+exports.MATCHED_FILES_CAP = exports.ChecklistDefinition = exports.ReviewerAgentPolicy = exports.DEFAULT_REVIEWER_AGENT_NAME = exports.REVIEWER_AGENTS_ONE_PER_CHECKLIST = void 0;
 exports.toChecklist = toChecklist;
 exports.normalizeChecklistDoc = normalizeChecklistDoc;
 exports.formatFileList = formatFileList;
 const tslib_1 = require("tslib");
 const path = tslib_1.__importStar(require("path"));
+/** The {@link ReviewerAgentPolicy.maxAgents} value meaning "`reviewerAgents` is not configured". */
+exports.REVIEWER_AGENTS_ONE_PER_CHECKLIST = 0;
+/** The generic reviewer agent webpieces ships, and the value the config error tells a repo to add. */
+exports.DEFAULT_REVIEWER_AGENT_NAME = 'webpieces-reviewer';
+/**
+ * WHICH reviewer agent the gate briefs, and HOW MANY of them one round may use — straight from
+ * `commands.pr-gate.reviewerAgentName` / `commands.pr-gate.reviewerAgents`. Data-only.
+ *
+ * One instance per loaded config, shared by every {@link ChecklistDefinition} and copied onto every matched
+ * checklist, because the answer is repo-wide: a checklist no longer names an agent type of its own. It used
+ * to — a per-entry key pointing at its own `.claude/agents/<name>.md` — and those files added almost nothing
+ * over the checklist `doc` while forcing one subagent per checklist, so a PR matching four checklists paid
+ * for four agents re-reading the same diff (issue #938).
+ */
+class ReviewerAgentPolicy {
+    /**
+     * The `subagent_type` every reviewer briefing names, e.g. `webpieces-reviewer` — the generic,
+     * checklist-agnostic agent webpieces ships (`.claude/agents/webpieces-reviewer.md`, written by
+     * `wp-install-ai-hooks` / `wp-upgrade-shim`). A repo may point it at its own agent instead.
+     */
+    agentName;
+    /**
+     * The most reviewer subagents one stage-② round may use, or {@link REVIEWER_AGENTS_ONE_PER_CHECKLIST}
+     * when `reviewerAgents` is not configured — which keeps the original contract: one separate subagent per
+     * checklist. When set, the main AI groups the owed checklists across at most this many subagents, and
+     * each subagent still writes one verdict file per checklist it covers.
+     */
+    maxAgents;
+    constructor(agentName, maxAgents) {
+        this.agentName = agentName;
+        this.maxAgents = maxAgents;
+    }
+    /** true when `reviewerAgents` is configured, i.e. one subagent may cover several checklists. */
+    grouped() {
+        return this.maxAgents !== exports.REVIEWER_AGENTS_ONE_PER_CHECKLIST;
+    }
+}
+exports.ReviewerAgentPolicy = ReviewerAgentPolicy;
 // A company review checklist: a diff-triggered extension point that lets a CONSUMER inject its own
-// PR-time review process into the webpieces gated flow WITHOUT forking the tooling. Each checklist names
-// a reviewer SUBAGENT (a `.claude/agents/<subagent>.md`) and the doc that reviewer reads; when the diff
-// matches the checklist's `patterns`, wp-review-upsert-pr tells the AI to spawn that subagent to review it, and
-// wp-finish-upsert-pr refuses to open the PR until a well-formed, passing review-<id>.json exists AND that
-// named subagent is proven (from the harness's own artifacts) to have actually run.
+// PR-time review process into the webpieces gated flow WITHOUT forking the tooling. Each checklist has an
+// `id` and the doc its reviewer reads; when the diff matches the checklist's `patterns`,
+// wp-review-upsert-pr tells the AI to spawn the repo's reviewer agent (`commands.pr-gate.reviewerAgentName`)
+// over it, and wp-finish-upsert-pr refuses to open the PR until a well-formed, passing review-<id>.json
+// exists AND a reviewer subagent is proven (from the harness's own artifacts) to have actually run.
 //
 // Checklists are configured as an ARRAY in `pr-gate.checklists` in webpieces.config.json — the ONLY
-// accepted shape. `patterns` is a path-glob dispatch table and `subagent` is a name binding: both are
+// accepted shape. `patterns` is a path-glob dispatch table and `id` is the checklist's name: both are
 // config, so they live where every tool that reads webpieces.config.json can see, grep and schema them.
 // Data-only.
 class ChecklistDefinition {
-    id; // = the subagent name; keys review-<id>.json and the dashboard row
-    subagent; // reviewer agent name → .claude/agents/<subagent>.md; the agentType the harness stamps
-    // REPO-RELATIVE guidance doc the reviewer reads (may be '' — then it just reads the diff). Repo-relative
-    // because this value is printed verbatim to a reviewer subagent as "the file to open", and a path
-    // relative to anything else is unresolvable from where that subagent stands.
+    id; // keys review-<id>.json, its instructions file and its dashboard row
+    reviewer; // repo-wide: which agent type reviews it, and the per-round cap
+    // REPO-RELATIVE guidance doc the reviewer reads. REQUIRED: with one generic reviewer agent the doc is
+    // the whole checklist. Repo-relative because this value is printed verbatim to a reviewer subagent as
+    // "the file to open", and a path relative to anything else is unresolvable from where it stands.
     doc;
     patterns; // path globs (isPathExcluded semantics); [] = matches any changed file (always runs)
     /**
@@ -43,9 +81,9 @@ class ChecklistDefinition {
      */
     required;
     // eslint-disable-next-line @typescript-eslint/max-params
-    constructor(id, subagent, doc, patterns, required) {
+    constructor(id, reviewer, doc, patterns, required) {
         this.id = id;
-        this.subagent = subagent;
+        this.reviewer = reviewer;
         this.doc = doc;
         this.patterns = patterns;
         this.required = required;
@@ -53,8 +91,7 @@ class ChecklistDefinition {
 }
 exports.ChecklistDefinition = ChecklistDefinition;
 /**
- * Build a ChecklistDefinition from an omitting-friendly raw entry. `id` defaults to the subagent name (the
- * only stable, human-meaningful key we have).
+ * Build a ChecklistDefinition from a raw entry, bound to the repo's reviewer policy.
  *
  * `required` is coerced with `=== true` rather than defaulted, and that is not a default in disguise:
  * `validateChecklistArray` has already REJECTED any entry that omitted it or gave a non-boolean, so the
@@ -62,9 +99,8 @@ exports.ChecklistDefinition = ChecklistDefinition;
  * repoRoot (structure-only) still produces a well-typed def instead of `undefined` leaking through.
  */
 // webpieces-disable no-function-outside-class -- pure config transform beside its data class
-function toChecklist(raw) {
-    const subagent = raw.subagent ?? '';
-    return new ChecklistDefinition(subagent, subagent, normalizeChecklistDoc(raw.doc ?? ''), raw.patterns ?? [], raw.required === true);
+function toChecklist(raw, reviewer) {
+    return new ChecklistDefinition((raw.id ?? '').trim(), reviewer, normalizeChecklistDoc(raw.doc ?? ''), raw.patterns ?? [], raw.required === true);
 }
 /** Normalize a checklist entry's repo-relative `doc` to a POSIX path, so every printed path matches. */
 // webpieces-disable no-function-outside-class -- pure path transform beside its data class

package/src/checklist-config.js.map

@@ -1 +1 @@
-{"version":3,"file":"checklist-config.js","sourceRoot":"","sources":["../../../../../packages/tooling/rules-config/src/checklist-config.ts"],"names":[],"mappings":";;;AAmEA,kCAIC;AAID,sDAIC;AAYD,wCAIC;;AA/FD,mDAA6B;AAE7B,mGAAmG;AACnG,yGAAyG;AACzG,wGAAwG;AACxG,gHAAgH;AAChH,2GAA2G;AAC3G,oFAAoF;AACpF,EAAE;AACF,oGAAoG;AACpG,sGAAsG;AACtG,wGAAwG;AACxG,aAAa;AACb,MAAa,mBAAmB;IAC5B,EAAE,CAAS,CAAS,mEAAmE;IACvF,QAAQ,CAAS,CAAG,uFAAuF;IAC3G,yGAAyG;IACzG,kGAAkG;IAClG,6EAA6E;IAC7E,GAAG,CAAS;IACZ,QAAQ,CAAW,CAAC,qFAAqF;IACzG;;;;;;;;;;;;;;;OAeG;IACH,QAAQ,CAAU;IAElB,yDAAyD;IACzD,YAAY,EAAU,EAAE,QAAgB,EAAE,GAAW,EAAE,QAAkB,EAAE,QAAiB;QACxF,IAAI,CAAC,EAAE,GAAG,EAAE,CAAC;QACb,IAAI,CAAC,QAAQ,GAAG,QAAQ,CAAC;QACzB,IAAI,CAAC,GAAG,GAAG,GAAG,CAAC;QACf,IAAI,CAAC,QAAQ,GAAG,QAAQ,CAAC;QACzB,IAAI,CAAC,QAAQ,GAAG,QAAQ,CAAC;IAC7B,CAAC;CACJ;AAlCD,kDAkCC;AAUD;;;;;;;;GAQG;AACH,6FAA6F;AAC7F,SAAgB,WAAW,CAAC,GAAqB;IAC7C,MAAM,QAAQ,GAAG,GAAG,CAAC,QAAQ,IAAI,EAAE,CAAC;IACpC,OAAO,IAAI,mBAAmB,CAC1B,QAAQ,EAAE,QAAQ,EAAE,qBAAqB,CAAC,GAAG,CAAC,GAAG,IAAI,EAAE,CAAC,EAAE,GAAG,CAAC,QAAQ,IAAI,EAAE,EAAE,GAAG,CAAC,QAAQ,KAAK,IAAI,CAAC,CAAC;AAC7G,CAAC;AAED,wGAAwG;AACxG,2FAA2F;AAC3F,SAAgB,qBAAqB,CAAC,GAAW;IAC7C,MAAM,OAAO,GAAG,GAAG,CAAC,IAAI,EAAE,CAAC;IAC3B,IAAI,OAAO,KAAK,EAAE;QAAE,OAAO,EAAE,CAAC;IAC9B,OAAO,IAAI,CAAC,KAAK,CAAC,SAAS,CAAC,OAAO,CAAC,KAAK,CAAC,IAAI,CAAC,GAAG,CAAC,CAAC,IAAI,CAAC,GAAG,CAAC,CAAC,CAAC;AACnE,CAAC;AAED,0GAA0G;AAC1G,+FAA+F;AAClF,QAAA,iBAAiB,GAAG,CAAC,CAAC;AAEnC;;;;GAIG;AACH,mGAAmG;AACnG,SAAgB,cAAc,CAAC,KAAwB,EAAE,MAAc,yBAAiB;IACpF,IAAI,KAAK,CAAC,MAAM,KAAK,CAAC;QAAE,OAAO,QAAQ,CAAC;IACxC,IAAI,KAAK,CAAC,MAAM,IAAI,GAAG;QAAE,OAAO,KAAK,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC;IACjD,OAAO,GAAG,KAAK,CAAC,KAAK,CAAC,CAAC,EAAE,GAAG,CAAC,CAAC,IAAI,CAAC,IAAI,CAAC,MAAM,KAAK,CAAC,MAAM,GAAG,GAAG,UAAU,KAAK,CAAC,MAAM,SAAS,CAAC;AACpG,CAAC","sourcesContent":["import * as path from 'path';\n\n// A company review checklist: a diff-triggered extension point that lets a CONSUMER inject its own\n// PR-time review process into the webpieces gated flow WITHOUT forking the tooling. Each checklist names\n// a reviewer SUBAGENT (a `.claude/agents/<subagent>.md`) and the doc that reviewer reads; when the diff\n// matches the checklist's `patterns`, wp-review-upsert-pr tells the AI to spawn that subagent to review it, and\n// wp-finish-upsert-pr refuses to open the PR until a well-formed, passing review-<id>.json exists AND that\n// named subagent is proven (from the harness's own artifacts) to have actually run.\n//\n// Checklists are configured as an ARRAY in `pr-gate.checklists` in webpieces.config.json — the ONLY\n// accepted shape. `patterns` is a path-glob dispatch table and `subagent` is a name binding: both are\n// config, so they live where every tool that reads webpieces.config.json can see, grep and schema them.\n// Data-only.\nexport class ChecklistDefinition {\n    id: string;         // = the subagent name; keys review-<id>.json and the dashboard row\n    subagent: string;   // reviewer agent name → .claude/agents/<subagent>.md; the agentType the harness stamps\n    // REPO-RELATIVE guidance doc the reviewer reads (may be '' — then it just reads the diff). Repo-relative\n    // because this value is printed verbatim to a reviewer subagent as \"the file to open\", and a path\n    // relative to anything else is unresolvable from where that subagent stands.\n    doc: string;\n    patterns: string[]; // path globs (isPathExcluded semantics); [] = matches any changed file (always runs)\n    /**\n     * true  — BLOCKING. `wp-finish-upsert-pr` refuses the PR until this checklist has a passing verdict.\n     * false — OPTIONAL. When it matches, stage ② OFFERS it: the AI asks the human which optional reviewers\n     *         to run, and the human may decline every one of them. A declined optional checklist never\n     *         blocks.\n     *\n     * This governs whether the reviewer must RUN — NOT whether its verdict counts. An optional reviewer\n     * that is actually spawned and comes back red blocks finish exactly like a required one; otherwise\n     * running it would be theater.\n     *\n     * There is deliberately NO default (see the validator): a review process is the last thing that should\n     * acquire a scope silently, in either direction. Defaulting to true would leave the all-blocking status\n     * quo in place for anyone who did not read the release note; defaulting to false would quietly\n     * DOWNGRADE every existing consumer's gate on upgrade. Both are worse than one mechanical config edit\n     * that the coding agent reading the error applies in a single pass.\n     */\n    required: boolean;\n\n    // eslint-disable-next-line @typescript-eslint/max-params\n    constructor(id: string, subagent: string, doc: string, patterns: string[], required: boolean) {\n        this.id = id;\n        this.subagent = subagent;\n        this.doc = doc;\n        this.patterns = patterns;\n        this.required = required;\n    }\n}\n\n// One config entry straight from JSON, before it is validated + narrowed into a class.\nexport interface RawChecklistItem {\n    subagent?: string;\n    doc?: string;\n    patterns?: string[];\n    required?: boolean;\n}\n\n/**\n * Build a ChecklistDefinition from an omitting-friendly raw entry. `id` defaults to the subagent name (the\n * only stable, human-meaningful key we have).\n *\n * `required` is coerced with `=== true` rather than defaulted, and that is not a default in disguise:\n * `validateChecklistArray` has already REJECTED any entry that omitted it or gave a non-boolean, so the\n * only values that reach here are real booleans. The coercion exists so a validator that runs without a\n * repoRoot (structure-only) still produces a well-typed def instead of `undefined` leaking through.\n */\n// webpieces-disable no-function-outside-class -- pure config transform beside its data class\nexport function toChecklist(raw: RawChecklistItem): ChecklistDefinition {\n    const subagent = raw.subagent ?? '';\n    return new ChecklistDefinition(\n        subagent, subagent, normalizeChecklistDoc(raw.doc ?? ''), raw.patterns ?? [], raw.required === true);\n}\n\n/** Normalize a checklist entry's repo-relative `doc` to a POSIX path, so every printed path matches. */\n// webpieces-disable no-function-outside-class -- pure path transform beside its data class\nexport function normalizeChecklistDoc(doc: string): string {\n    const trimmed = doc.trim();\n    if (trimmed === '') return '';\n    return path.posix.normalize(trimmed.split(path.sep).join('/'));\n}\n\n// The ONE cap for every printed matched-file list. Two print sites once used to slice to 4 and to 5 — two\n// different caps for the same list, neither chosen deliberately, and both without an ellipsis.\nexport const MATCHED_FILES_CAP = 6;\n\n/**\n * Render a file list for a message, NEVER silently. A truncated list that looks complete is how a reviewer\n * gets pointed at 4 of 40 changed files and reports success having reviewed a tenth of the diff, so the\n * dropped count is always stated and the caller is expected to name the file holding the full set.\n */\n// webpieces-disable no-function-outside-class -- pure display formatter beside the data it formats\nexport function formatFileList(files: readonly string[], cap: number = MATCHED_FILES_CAP): string {\n    if (files.length === 0) return '(none)';\n    if (files.length <= cap) return files.join(', ');\n    return `${files.slice(0, cap).join(', ')}, +${files.length - cap} more (${files.length} total)`;\n}\n"]}
+{"version":3,"file":"checklist-config.js","sourceRoot":"","sources":["../../../../../packages/tooling/rules-config/src/checklist-config.ts"],"names":[],"mappings":"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","sourcesContent":["import * as path from 'path';\n\n/** The {@link ReviewerAgentPolicy.maxAgents} value meaning \"`reviewerAgents` is not configured\". */\nexport const REVIEWER_AGENTS_ONE_PER_CHECKLIST = 0;\n\n/** The generic reviewer agent webpieces ships, and the value the config error tells a repo to add. */\nexport const DEFAULT_REVIEWER_AGENT_NAME = 'webpieces-reviewer';\n\n/**\n * WHICH reviewer agent the gate briefs, and HOW MANY of them one round may use — straight from\n * `commands.pr-gate.reviewerAgentName` / `commands.pr-gate.reviewerAgents`. Data-only.\n *\n * One instance per loaded config, shared by every {@link ChecklistDefinition} and copied onto every matched\n * checklist, because the answer is repo-wide: a checklist no longer names an agent type of its own. It used\n * to — a per-entry key pointing at its own `.claude/agents/<name>.md` — and those files added almost nothing\n * over the checklist `doc` while forcing one subagent per checklist, so a PR matching four checklists paid\n * for four agents re-reading the same diff (issue #938).\n */\nexport class ReviewerAgentPolicy {\n    /**\n     * The `subagent_type` every reviewer briefing names, e.g. `webpieces-reviewer` — the generic,\n     * checklist-agnostic agent webpieces ships (`.claude/agents/webpieces-reviewer.md`, written by\n     * `wp-install-ai-hooks` / `wp-upgrade-shim`). A repo may point it at its own agent instead.\n     */\n    agentName: string;\n    /**\n     * The most reviewer subagents one stage-② round may use, or {@link REVIEWER_AGENTS_ONE_PER_CHECKLIST}\n     * when `reviewerAgents` is not configured — which keeps the original contract: one separate subagent per\n     * checklist. When set, the main AI groups the owed checklists across at most this many subagents, and\n     * each subagent still writes one verdict file per checklist it covers.\n     */\n    maxAgents: number;\n\n    constructor(agentName: string, maxAgents: number) {\n        this.agentName = agentName;\n        this.maxAgents = maxAgents;\n    }\n\n    /** true when `reviewerAgents` is configured, i.e. one subagent may cover several checklists. */\n    grouped(): boolean {\n        return this.maxAgents !== REVIEWER_AGENTS_ONE_PER_CHECKLIST;\n    }\n}\n\n// A company review checklist: a diff-triggered extension point that lets a CONSUMER inject its own\n// PR-time review process into the webpieces gated flow WITHOUT forking the tooling. Each checklist has an\n// `id` and the doc its reviewer reads; when the diff matches the checklist's `patterns`,\n// wp-review-upsert-pr tells the AI to spawn the repo's reviewer agent (`commands.pr-gate.reviewerAgentName`)\n// over it, and wp-finish-upsert-pr refuses to open the PR until a well-formed, passing review-<id>.json\n// exists AND a reviewer subagent is proven (from the harness's own artifacts) to have actually run.\n//\n// Checklists are configured as an ARRAY in `pr-gate.checklists` in webpieces.config.json — the ONLY\n// accepted shape. `patterns` is a path-glob dispatch table and `id` is the checklist's name: both are\n// config, so they live where every tool that reads webpieces.config.json can see, grep and schema them.\n// Data-only.\nexport class ChecklistDefinition {\n    id: string;                    // keys review-<id>.json, its instructions file and its dashboard row\n    reviewer: ReviewerAgentPolicy; // repo-wide: which agent type reviews it, and the per-round cap\n    // REPO-RELATIVE guidance doc the reviewer reads. REQUIRED: with one generic reviewer agent the doc is\n    // the whole checklist. Repo-relative because this value is printed verbatim to a reviewer subagent as\n    // \"the file to open\", and a path relative to anything else is unresolvable from where it stands.\n    doc: string;\n    patterns: string[]; // path globs (isPathExcluded semantics); [] = matches any changed file (always runs)\n    /**\n     * true  — BLOCKING. `wp-finish-upsert-pr` refuses the PR until this checklist has a passing verdict.\n     * false — OPTIONAL. When it matches, stage ② OFFERS it: the AI asks the human which optional reviewers\n     *         to run, and the human may decline every one of them. A declined optional checklist never\n     *         blocks.\n     *\n     * This governs whether the reviewer must RUN — NOT whether its verdict counts. An optional reviewer\n     * that is actually spawned and comes back red blocks finish exactly like a required one; otherwise\n     * running it would be theater.\n     *\n     * There is deliberately NO default (see the validator): a review process is the last thing that should\n     * acquire a scope silently, in either direction. Defaulting to true would leave the all-blocking status\n     * quo in place for anyone who did not read the release note; defaulting to false would quietly\n     * DOWNGRADE every existing consumer's gate on upgrade. Both are worse than one mechanical config edit\n     * that the coding agent reading the error applies in a single pass.\n     */\n    required: boolean;\n\n    // eslint-disable-next-line @typescript-eslint/max-params\n    constructor(id: string, reviewer: ReviewerAgentPolicy, doc: string, patterns: string[], required: boolean) {\n        this.id = id;\n        this.reviewer = reviewer;\n        this.doc = doc;\n        this.patterns = patterns;\n        this.required = required;\n    }\n}\n\n// One config entry straight from JSON, before it is validated + narrowed into a class.\nexport interface RawChecklistItem {\n    id?: string;\n    doc?: string;\n    patterns?: string[];\n    required?: boolean;\n}\n\n/**\n * Build a ChecklistDefinition from a raw entry, bound to the repo's reviewer policy.\n *\n * `required` is coerced with `=== true` rather than defaulted, and that is not a default in disguise:\n * `validateChecklistArray` has already REJECTED any entry that omitted it or gave a non-boolean, so the\n * only values that reach here are real booleans. The coercion exists so a validator that runs without a\n * repoRoot (structure-only) still produces a well-typed def instead of `undefined` leaking through.\n */\n// webpieces-disable no-function-outside-class -- pure config transform beside its data class\nexport function toChecklist(raw: RawChecklistItem, reviewer: ReviewerAgentPolicy): ChecklistDefinition {\n    return new ChecklistDefinition(\n        (raw.id ?? '').trim(), reviewer, normalizeChecklistDoc(raw.doc ?? ''), raw.patterns ?? [], raw.required === true);\n}\n\n/** Normalize a checklist entry's repo-relative `doc` to a POSIX path, so every printed path matches. */\n// webpieces-disable no-function-outside-class -- pure path transform beside its data class\nexport function normalizeChecklistDoc(doc: string): string {\n    const trimmed = doc.trim();\n    if (trimmed === '') return '';\n    return path.posix.normalize(trimmed.split(path.sep).join('/'));\n}\n\n// The ONE cap for every printed matched-file list. Two print sites once used to slice to 4 and to 5 — two\n// different caps for the same list, neither chosen deliberately, and both without an ellipsis.\nexport const MATCHED_FILES_CAP = 6;\n\n/**\n * Render a file list for a message, NEVER silently. A truncated list that looks complete is how a reviewer\n * gets pointed at 4 of 40 changed files and reports success having reviewed a tenth of the diff, so the\n * dropped count is always stated and the caller is expected to name the file holding the full set.\n */\n// webpieces-disable no-function-outside-class -- pure display formatter beside the data it formats\nexport function formatFileList(files: readonly string[], cap: number = MATCHED_FILES_CAP): string {\n    if (files.length === 0) return '(none)';\n    if (files.length <= cap) return files.join(', ');\n    return `${files.slice(0, cap).join(', ')}, +${files.length - cap} more (${files.length} total)`;\n}\n"]}

package/src/checklist-docs-validator.d.ts

@@ -1,7 +1,7 @@
 /**
  * Validate ONLY the pr-gate `checklists` array, in isolation — that it IS an array (the removed `{ doc }`
- * manifest shape is rejected with its migration steps), each entry's subagent is present, distinct, and
- * names a real `.claude/agents/<subagent>.md`, each entry's repo-relative doc exists, and patterns are
+ * manifest shape is rejected with its migration steps), each entry's id is present, distinct and
+ * file-safe, each entry's repo-relative doc exists, a retired `subagent` key is rejected, and patterns are
  * string[]. Same logic loadAndValidate runs, but callable directly so broken checklists fail as their OWN
  * `validate-checklist-docs` check (clear owner) instead of surfacing as an unrelated validator's banner.
  * Returns errors; never throws.

package/src/checklist-docs-validator.js

@@ -9,8 +9,8 @@ const validate_config_1 = require("./validate-config");
 const to_error_1 = require("./to-error");
 /**
  * Validate ONLY the pr-gate `checklists` array, in isolation — that it IS an array (the removed `{ doc }`
- * manifest shape is rejected with its migration steps), each entry's subagent is present, distinct, and
- * names a real `.claude/agents/<subagent>.md`, each entry's repo-relative doc exists, and patterns are
+ * manifest shape is rejected with its migration steps), each entry's id is present, distinct and
+ * file-safe, each entry's repo-relative doc exists, a retired `subagent` key is rejected, and patterns are
  * string[]. Same logic loadAndValidate runs, but callable directly so broken checklists fail as their OWN
  * `validate-checklist-docs` check (clear owner) instead of surfacing as an unrelated validator's banner.
  * Returns errors; never throws.

package/src/checklist-docs-validator.js.map

@@ -1 +1 @@
-{"version":3,"file":"checklist-docs-validator.js","sourceRoot":"","sources":["../../../../../packages/tooling/rules-config/src/checklist-docs-validator.ts"],"names":[],"mappings":";;AAeA,sDAwBC;;AAvCD,+CAAyB;AACzB,mDAA6B;AAC7B,+CAA+C;AAC/C,uDAA8D;AAC9D,yCAAqC;AAErC;;;;;;;GAOG;AACH,2GAA2G;AAC3G,SAAgB,qBAAqB,CAAC,GAAW;IAC7C,MAAM,UAAU,GAAG,IAAA,4BAAc,EAAC,GAAG,CAAC,CAAC;IACvC,IAAI,CAAC,UAAU;QAAE,OAAO,EAAE,CAAC;IAC3B,wFAAwF;IACxF,IAAI,GAA4B,CAAC;IACjC,6GAA6G;IAC7G,8DAA8D;IAC9D,IAAI,CAAC;QACD,wFAAwF;QACxF,GAAG,GAAG,IAAI,CAAC,KAAK,CAAC,EAAE,CAAC,YAAY,CAAC,UAAU,EAAE,MAAM,CAAC,CAA4B,CAAC;IACrF,CAAC;IAAC,OAAO,GAAY,EAAE,CAAC;QACpB,MAAM,KAAK,GAAG,IAAA,kBAAO,EAAC,GAAG,CAAC,CAAC;QAC3B,OAAO,CAAC,aAAa,IAAI,CAAC,QAAQ,CAAC,UAAU,CAAC,uBAAuB,KAAK,CAAC,OAAO,EAAE,CAAC,CAAC;IAC1F,CAAC;IACD,MAAM,QAAQ,GAAG,IAAI,CAAC,OAAO,CAAC,UAAU,CAAC,CAAC;IAC1C,sGAAsG;IACtG,yGAAyG;IACzG,wGAAwG;IACxG,2EAA2E;IAC3E,MAAM,QAAQ,GAAG,GAAG,CAAC,UAAU,CAAwC,CAAC;IACxE,2EAA2E;IAC3E,MAAM,MAAM,GAAG,QAAQ,EAAE,CAAC,SAAS,CAAwC,CAAC;IAC5E,IAAI,CAAC,MAAM,IAAI,CAAC,CAAC,YAAY,IAAI,MAAM,CAAC;QAAE,OAAO,EAAE,CAAC;IACpD,OAAO,IAAA,2CAAyB,EAAC,MAAM,CAAC,YAAY,CAAC,EAAE,QAAQ,CAAC,CAAC;AACrE,CAAC","sourcesContent":["import * as fs from 'fs';\nimport * as path from 'path';\nimport { findConfigFile } from './config-file';\nimport { validateChecklistsSection } from './validate-config';\nimport { toError } from './to-error';\n\n/**\n * Validate ONLY the pr-gate `checklists` array, in isolation — that it IS an array (the removed `{ doc }`\n * manifest shape is rejected with its migration steps), each entry's subagent is present, distinct, and\n * names a real `.claude/agents/<subagent>.md`, each entry's repo-relative doc exists, and patterns are\n * string[]. Same logic loadAndValidate runs, but callable directly so broken checklists fail as their OWN\n * `validate-checklist-docs` check (clear owner) instead of surfacing as an unrelated validator's banner.\n * Returns errors; never throws.\n */\n// webpieces-disable no-function-outside-class -- module-level config validator, matches validate-config.ts\nexport function validateChecklistDocs(cwd: string): string[] {\n    const configPath = findConfigFile(cwd);\n    if (!configPath) return [];\n    // webpieces-disable no-any-unknown -- parsed config JSON is opaque until narrowed below\n    let raw: Record<string, unknown>;\n    // webpieces-disable no-unmanaged-exceptions -- chokepoint: a malformed config surfaces as one readable error\n    // eslint-disable-next-line @webpieces/no-unmanaged-exceptions\n    try {\n        // webpieces-disable no-any-unknown -- parsed config JSON is opaque until narrowed below\n        raw = JSON.parse(fs.readFileSync(configPath, 'utf8')) as Record<string, unknown>;\n    } catch (err: unknown) {\n        const error = toError(err);\n        return [`[pr-gate] ${path.basename(configPath)} is not valid JSON: ${error.message}`];\n    }\n    const repoRoot = path.dirname(configPath);\n    // ONE location: commands[\"pr-gate\"]. This function parses the config itself rather than going through\n    // loadAndValidate, so it used to also read the retired top-level `pr-gate` — which meant a config on the\n    // dead layout validated its checklists silently here while loadAndValidate rejected it everywhere else.\n    // webpieces-disable no-any-unknown -- narrowing the opaque command section\n    const commands = raw['commands'] as Record<string, unknown> | undefined;\n    // webpieces-disable no-any-unknown -- narrowing the opaque pr-gate section\n    const prGate = commands?.['pr-gate'] as Record<string, unknown> | undefined;\n    if (!prGate || !('checklists' in prGate)) return [];\n    return validateChecklistsSection(prGate['checklists'], repoRoot);\n}\n"]}
+{"version":3,"file":"checklist-docs-validator.js","sourceRoot":"","sources":["../../../../../packages/tooling/rules-config/src/checklist-docs-validator.ts"],"names":[],"mappings":";;AAeA,sDAwBC;;AAvCD,+CAAyB;AACzB,mDAA6B;AAC7B,+CAA+C;AAC/C,uDAA8D;AAC9D,yCAAqC;AAErC;;;;;;;GAOG;AACH,2GAA2G;AAC3G,SAAgB,qBAAqB,CAAC,GAAW;IAC7C,MAAM,UAAU,GAAG,IAAA,4BAAc,EAAC,GAAG,CAAC,CAAC;IACvC,IAAI,CAAC,UAAU;QAAE,OAAO,EAAE,CAAC;IAC3B,wFAAwF;IACxF,IAAI,GAA4B,CAAC;IACjC,6GAA6G;IAC7G,8DAA8D;IAC9D,IAAI,CAAC;QACD,wFAAwF;QACxF,GAAG,GAAG,IAAI,CAAC,KAAK,CAAC,EAAE,CAAC,YAAY,CAAC,UAAU,EAAE,MAAM,CAAC,CAA4B,CAAC;IACrF,CAAC;IAAC,OAAO,GAAY,EAAE,CAAC;QACpB,MAAM,KAAK,GAAG,IAAA,kBAAO,EAAC,GAAG,CAAC,CAAC;QAC3B,OAAO,CAAC,aAAa,IAAI,CAAC,QAAQ,CAAC,UAAU,CAAC,uBAAuB,KAAK,CAAC,OAAO,EAAE,CAAC,CAAC;IAC1F,CAAC;IACD,MAAM,QAAQ,GAAG,IAAI,CAAC,OAAO,CAAC,UAAU,CAAC,CAAC;IAC1C,sGAAsG;IACtG,yGAAyG;IACzG,wGAAwG;IACxG,2EAA2E;IAC3E,MAAM,QAAQ,GAAG,GAAG,CAAC,UAAU,CAAwC,CAAC;IACxE,2EAA2E;IAC3E,MAAM,MAAM,GAAG,QAAQ,EAAE,CAAC,SAAS,CAAwC,CAAC;IAC5E,IAAI,CAAC,MAAM,IAAI,CAAC,CAAC,YAAY,IAAI,MAAM,CAAC;QAAE,OAAO,EAAE,CAAC;IACpD,OAAO,IAAA,2CAAyB,EAAC,MAAM,CAAC,YAAY,CAAC,EAAE,QAAQ,CAAC,CAAC;AACrE,CAAC","sourcesContent":["import * as fs from 'fs';\nimport * as path from 'path';\nimport { findConfigFile } from './config-file';\nimport { validateChecklistsSection } from './validate-config';\nimport { toError } from './to-error';\n\n/**\n * Validate ONLY the pr-gate `checklists` array, in isolation — that it IS an array (the removed `{ doc }`\n * manifest shape is rejected with its migration steps), each entry's id is present, distinct and\n * file-safe, each entry's repo-relative doc exists, a retired `subagent` key is rejected, and patterns are\n * string[]. Same logic loadAndValidate runs, but callable directly so broken checklists fail as their OWN\n * `validate-checklist-docs` check (clear owner) instead of surfacing as an unrelated validator's banner.\n * Returns errors; never throws.\n */\n// webpieces-disable no-function-outside-class -- module-level config validator, matches validate-config.ts\nexport function validateChecklistDocs(cwd: string): string[] {\n    const configPath = findConfigFile(cwd);\n    if (!configPath) return [];\n    // webpieces-disable no-any-unknown -- parsed config JSON is opaque until narrowed below\n    let raw: Record<string, unknown>;\n    // webpieces-disable no-unmanaged-exceptions -- chokepoint: a malformed config surfaces as one readable error\n    // eslint-disable-next-line @webpieces/no-unmanaged-exceptions\n    try {\n        // webpieces-disable no-any-unknown -- parsed config JSON is opaque until narrowed below\n        raw = JSON.parse(fs.readFileSync(configPath, 'utf8')) as Record<string, unknown>;\n    } catch (err: unknown) {\n        const error = toError(err);\n        return [`[pr-gate] ${path.basename(configPath)} is not valid JSON: ${error.message}`];\n    }\n    const repoRoot = path.dirname(configPath);\n    // ONE location: commands[\"pr-gate\"]. This function parses the config itself rather than going through\n    // loadAndValidate, so it used to also read the retired top-level `pr-gate` — which meant a config on the\n    // dead layout validated its checklists silently here while loadAndValidate rejected it everywhere else.\n    // webpieces-disable no-any-unknown -- narrowing the opaque command section\n    const commands = raw['commands'] as Record<string, unknown> | undefined;\n    // webpieces-disable no-any-unknown -- narrowing the opaque pr-gate section\n    const prGate = commands?.['pr-gate'] as Record<string, unknown> | undefined;\n    if (!prGate || !('checklists' in prGate)) return [];\n    return validateChecklistsSection(prGate['checklists'], repoRoot);\n}\n"]}

package/src/checklist-instructions.d.ts

@@ -22,6 +22,17 @@ export declare class ChecklistInstructionsService {
      * `reviewPath` is the branch's review.json — each verdict file sits beside it as review-<id>.json.
      */
     render(pending: readonly RequiredChecklist[], reviewPath: string, context: ChecklistReviewContext): string;
+    /**
+     * HOW MANY subagents, of WHICH type. Without `reviewerAgents` that is one separate subagent per checklist;
+     * with it, at most N subagents with the checklists grouped across them as the AI judges best. Either way
+     * every subagent is the repo's ONE reviewer agent type, and every checklist still gets its own verdict.
+     */
+    spawnRule(pending: readonly RequiredChecklist[]): string[];
+    /**
+     * The grouping sentence, with an example that fits THIS round's numbers — a cap of 1 has no choice to
+     * make, and saying "group them as you judge best" there would invite a second subagent.
+     */
+    groupingHint(count: number, cap: number): string;
     names(pending: readonly RequiredChecklist[]): string;
     private oneReviewer;
     /**

package/src/checklist-instructions.js

@@ -36,24 +36,56 @@ let ChecklistInstructionsService = class ChecklistInstructionsService {
     render(pending, reviewPath, context) {
         if (pending.length === 0)
             return '';
-        const lines = [
-            `You MUST run these ${pending.length} reviewer subagent(s) — a SEPARATE one for each. You may NOT review`,
-            `your own work, and you may NOT write a reviewer's verdict file on its behalf.`,
-            '',
-        ];
+        const lines = [...this.spawnRule(pending), ''];
         for (const req of pending)
             lines.push(...this.oneReviewer(req, reviewPath));
         lines.push('', ...this.verdictFormat());
         lines.push('', ...this.diffLines(context));
         return lines.join('\n');
     }
-    // Just the reviewer NAMES, for a caller that wants a one-line summary rather than the whole block.
+    /**
+     * HOW MANY subagents, of WHICH type. Without `reviewerAgents` that is one separate subagent per checklist;
+     * with it, at most N subagents with the checklists grouped across them as the AI judges best. Either way
+     * every subagent is the repo's ONE reviewer agent type, and every checklist still gets its own verdict.
+     */
+    spawnRule(pending) {
+        const reviewer = pending[0].reviewer;
+        const own = [
+            'You may NOT review your own work, and you may NOT write a reviewer\'s verdict file on its behalf.',
+        ];
+        if (!reviewer.grouped()) {
+            return [
+                `You MUST run these ${pending.length} checklist review(s) — a SEPARATE \`${reviewer.agentName}\` subagent for each.`,
+                ...own,
+            ];
+        }
+        const cap = Math.min(reviewer.maxAgents, pending.length);
+        return [
+            `You MUST run these ${pending.length} checklist review(s) using AT MOST ${cap} \`${reviewer.agentName}\` subagent(s)`,
+            `(commands.pr-gate.reviewerAgents = ${reviewer.maxAgents}). ${this.groupingHint(pending.length, cap)}`,
+            'Give each subagent every checklist it covers (doc, in-scope files, verdict path); it writes ONE verdict',
+            'file per checklist it covers, and never one for a checklist it was not given.',
+            ...own,
+        ];
+    }
+    /**
+     * The grouping sentence, with an example that fits THIS round's numbers — a cap of 1 has no choice to
+     * make, and saying "group them as you judge best" there would invite a second subagent.
+     */
+    groupingHint(count, cap) {
+        if (cap <= 1)
+            return 'Use ONE subagent for all of them.';
+        const per = Math.ceil(count / cap);
+        return `Group the checklists across them as you judge best — e.g. one subagent for all of them, or ${cap} with about ${per} each.`;
+    }
+    // Just the checklist IDS, for a caller that wants a one-line summary rather than the whole block.
     names(pending) {
-        return pending.map((r) => r.subagent).join(', ');
+        return pending.map((r) => r.id).join(', ');
     }
-    // What ONE subagent must be given: its doc, why it is running + over what, and the file it must write.
+    // What the subagent reviewing ONE checklist must be given: its doc, why it is running + over what, and
+    // the file it must write.
     oneReviewer(req, reviewPath) {
-        const lines = [`  • ${req.subagent}`];
+        const lines = [`  • checklist ${req.id}`];
         // The doc is REPO-relative by the time it reaches here (see ChecklistDefinition.doc), so a subagent
         // handed this string can actually open it. Printing the raw config value would not resolve.
         if (req.doc.trim() !== '')
@@ -88,9 +120,9 @@ let ChecklistInstructionsService = class ChecklistInstructionsService {
     // hand-written agent .md.)
     verdictFormat() {
         return [
-            'TELL EACH subagent to write that file with EXACTLY this format (there is NO "success" field —',
+            'TELL EACH subagent to write each of its verdict files with EXACTLY this format (there is NO "success" field —',
             'it was removed; "status" is a tri-state so a reviewer can pass a change AND still raise a concern):',
-            ...this.reviewJsonService.verdictSchemaFor('<its own subagent name>', '', '  ').split('\n'),
+            ...this.reviewJsonService.verdictSchemaFor('<the checklist id>', '', '  ').split('\n'),
         ];
     }
     // The diff every reviewer judges. Stated once, here, because path matching is deliberately coarse and a

package/src/checklist-instructions.js.map

@@ -1 +1 @@
-{"version":3,"file":"checklist-instructions.js","sourceRoot":"","sources":["../../../../../packages/tooling/rules-config/src/checklist-instructions.ts"],"names":[],"mappings":"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","sourcesContent":["import { injectable, bindingScopeValues } from 'inversify';\nimport { formatFileList } from './checklist-config';\nimport {\n    ChecklistReviewContext, RequiredChecklist, ReviewJsonService,\n} from './review-json';\n\n/**\n * Renders the ONE block that tells the coding agent which reviewer subagents it must run and exactly what\n * to tell them. There is a single renderer because three callers need the identical text and any drift\n * between them is a correctness bug, not a cosmetic one:\n *\n *   - `wp-review-upsert-pr`            — the AI asks \"what review do I owe on this diff?\"\n *   - `wp-finish-upsert-pr`     — fails fast, listing ONLY the reviewers that still have not run\n *   - `ReviewJsonService`       — the same list appended to a review.json validation failure\n *\n * Callers pass ONLY the checklists still needing a verdict. A checklist already reviewed on this branch is\n * never re-listed — re-instructing it invites a redundant second run, and (worse) reads as though the\n * earlier verdict did not count.\n *\n * `@injectable(bindingScopeValues.Singleton)` so it is injected by type and drawn in the DI design.\n */\n@injectable(bindingScopeValues.Singleton)\nexport class ChecklistInstructionsService {\n    // Injected so the verdict path comes from the ONE place that knows it. This class used to hand-roll\n    // dirname with a regex and a hardcoded '/', a second implementation of ReviewJsonService's\n    // checklistResultPath that agreed on POSIX and disagreed on Windows — the same duplicate-logic trap as\n    // the two different matched-file truncation caps.\n    constructor(private readonly reviewJsonService: ReviewJsonService) {}\n\n    /**\n     * The full instruction block, or '' when nothing is pending (so a caller can concatenate it blindly).\n     * `reviewPath` is the branch's review.json — each verdict file sits beside it as review-<id>.json.\n     */\n    render(pending: readonly RequiredChecklist[], reviewPath: string, context: ChecklistReviewContext): string {\n        if (pending.length === 0) return '';\n        const lines: string[] = [\n            `You MUST run these ${pending.length} reviewer subagent(s) — a SEPARATE one for each. You may NOT review`,\n            `your own work, and you may NOT write a reviewer's verdict file on its behalf.`,\n            '',\n        ];\n        for (const req of pending) lines.push(...this.oneReviewer(req, reviewPath));\n        lines.push('', ...this.verdictFormat());\n        lines.push('', ...this.diffLines(context));\n        return lines.join('\\n');\n    }\n\n    // Just the reviewer NAMES, for a caller that wants a one-line summary rather than the whole block.\n    names(pending: readonly RequiredChecklist[]): string {\n        return pending.map((r: RequiredChecklist): string => r.subagent).join(', ');\n    }\n\n    // What ONE subagent must be given: its doc, why it is running + over what, and the file it must write.\n    private oneReviewer(req: RequiredChecklist, reviewPath: string): string[] {\n        const lines = [`  • ${req.subagent}`];\n        // The doc is REPO-relative by the time it reaches here (see ChecklistDefinition.doc), so a subagent\n        // handed this string can actually open it. Printing the raw config value would not resolve.\n        if (req.doc.trim() !== '') lines.push(`      doc to read:  ${req.doc}`);\n        for (const scopeLine of this.scope(req)) lines.push(`      ${scopeLine}`);\n        lines.push(`      must write:   ${this.reviewJsonService.checklistResultPath(reviewPath, req.id)}`);\n        return lines;\n    }\n\n    /**\n     * WHY this reviewer is running, and over what. NOT every checklist is pattern-matched: one with no\n     * `patterns` runs on EVERY PR, and calling its file list \"matched\" implies the list is a narrow,\n     * pre-filtered slice of the diff when it is in fact the whole thing. When patterns DID fire, they are\n     * named — the reviewer cannot otherwise tell a precise migrations-only glob from a blanket match-all one.\n     */\n    private scope(req: RequiredChecklist): string[] {\n        if (req.matchedPatterns.length === 0) {\n            return [\n                `in scope:     ALWAYS RUNS — this checklist has no patterns, so the WHOLE diff is in scope`,\n                `              all ${req.matchedFiles.length} changed file(s): ${formatFileList(req.matchedFiles)}`,\n            ];\n        }\n        const globs = req.matchedPatterns.map((p: string): string => `\"${p}\"`).join(', ');\n        return [\n            `in scope:     ${req.matchedFiles.length} file(s) matched ${globs}`,\n            `              ${formatFileList(req.matchedFiles)}`,\n        ];\n    }\n\n    // ONE shared format block for every reviewer, rather than repeating the schema under each name — and\n    // the schema itself comes from ReviewJsonService, the single renderer, so a change to the verdict shape\n    // cannot leave a stale copy in print. (It did once: `success` outlived its own removal in every\n    // hand-written agent .md.)\n    private verdictFormat(): string[] {\n        return [\n            'TELL EACH subagent to write that file with EXACTLY this format (there is NO \"success\" field —',\n            'it was removed; \"status\" is a tri-state so a reviewer can pass a change AND still raise a concern):',\n            ...this.reviewJsonService.verdictSchemaFor('<its own subagent name>', '', '  ').split('\\n'),\n        ];\n    }\n\n    // The diff every reviewer judges. Stated once, here, because path matching is deliberately coarse and a\n    // reviewer that only sees filenames cannot make the content-level call the checklist is asking for.\n    private diffLines(context: ChecklistReviewContext): string[] {\n        // NEVER omit these lines quietly. A reviewer given filenames but no way to read the change cannot make\n        // the content-level judgment the checklist asks for, and a silently shorter instruction block is\n        // indistinguishable from a complete one — so an unresolvable base is stated as the problem it is.\n        if (context.baseSha.trim() === '') {\n            return [\n                '⚠️  No diff base resolved for this branch, so the exact `git diff` command could not be given.',\n                '    Tell each reviewer to diff against main itself (`git diff $(git merge-base origin/main HEAD) HEAD -- <file>`)',\n                '    and note that path matching is COARSE — judge the real change, not the path.',\n            ];\n        }\n        const lines = ['Also give EACH one the real diff — path matching is COARSE, so judge the change, not the path:'];\n        // The MATERIALIZED diff when it exists: it cannot go empty the way a hand-assembled range can. The\n        // MANIFEST leads, and ALL.diff follows it, for the same reason the per-reviewer instructions were\n        // reordered: whichever one is printed first and framed as \"everything\" is the only one that gets\n        // opened — measured 4/4 — and ALL.diff is the one that can be silently incomplete.\n        if (context.diffDir.trim() !== '') {\n            lines.push(`  path map, AUTHORITATIVE:        ${context.diffDir}/manifest.json`);\n            lines.push('                                  per file: status, bytes, absolute source + diff paths,');\n            lines.push('                                  plus what was truncated or excluded');\n            lines.push(`  per-file diffs:                 ${context.diffDir}/files/`);\n            lines.push(`  combined view (may be capped):  ${context.diffDir}/ALL.diff`);\n        }\n        // NEVER hand-assemble `<baseSha> HEAD` here. On a dirty tree the changed-file set is base→working\n        // tree, so that range is empty and the reviewer is handed a command that shows it nothing — the\n        // failure this whole class of field exists to prevent. The command is derived from the same basis\n        // the file set was; when it is absent (an older pr-gate wrote the context), say so instead.\n        if (context.fileDiffCommand.trim() !== '') {\n            lines.push(`  reproduce one file:             ${context.fileDiffCommand}`);\n        } else {\n            lines.push(`  ⚠️  no reproduce command recorded — derive it yourself from base ${context.baseSha},`);\n            lines.push('      and check `git status` first: uncommitted work needs `git diff <base>` with NO head.');\n        }\n        if (context.dirty) {\n            lines.push('  ⚠️  this diff INCLUDES uncommitted + untracked work, so it is not what a commit-to-commit');\n            lines.push('      range would show. Judge it anyway — it is what the checklist matched against.');\n        }\n        if (context.prContextPath.trim() !== '') {\n            lines.push(`  full changed-file set + base/head sha:  ${context.prContextPath}`);\n        }\n        return lines;\n    }\n\n}\n"]}
+{"version":3,"file":"checklist-instructions.js","sourceRoot":"","sources":["../../../../../packages/tooling/rules-config/src/checklist-instructions.ts"],"names":[],"mappings":"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","sourcesContent":["import { injectable, bindingScopeValues } from 'inversify';\nimport { formatFileList } from './checklist-config';\nimport {\n    ChecklistReviewContext, RequiredChecklist, ReviewJsonService,\n} from './review-json';\n\n/**\n * Renders the ONE block that tells the coding agent which reviewer subagents it must run and exactly what\n * to tell them. There is a single renderer because three callers need the identical text and any drift\n * between them is a correctness bug, not a cosmetic one:\n *\n *   - `wp-review-upsert-pr`            — the AI asks \"what review do I owe on this diff?\"\n *   - `wp-finish-upsert-pr`     — fails fast, listing ONLY the reviewers that still have not run\n *   - `ReviewJsonService`       — the same list appended to a review.json validation failure\n *\n * Callers pass ONLY the checklists still needing a verdict. A checklist already reviewed on this branch is\n * never re-listed — re-instructing it invites a redundant second run, and (worse) reads as though the\n * earlier verdict did not count.\n *\n * `@injectable(bindingScopeValues.Singleton)` so it is injected by type and drawn in the DI design.\n */\n@injectable(bindingScopeValues.Singleton)\nexport class ChecklistInstructionsService {\n    // Injected so the verdict path comes from the ONE place that knows it. This class used to hand-roll\n    // dirname with a regex and a hardcoded '/', a second implementation of ReviewJsonService's\n    // checklistResultPath that agreed on POSIX and disagreed on Windows — the same duplicate-logic trap as\n    // the two different matched-file truncation caps.\n    constructor(private readonly reviewJsonService: ReviewJsonService) {}\n\n    /**\n     * The full instruction block, or '' when nothing is pending (so a caller can concatenate it blindly).\n     * `reviewPath` is the branch's review.json — each verdict file sits beside it as review-<id>.json.\n     */\n    render(pending: readonly RequiredChecklist[], reviewPath: string, context: ChecklistReviewContext): string {\n        if (pending.length === 0) return '';\n        const lines: string[] = [...this.spawnRule(pending), ''];\n        for (const req of pending) lines.push(...this.oneReviewer(req, reviewPath));\n        lines.push('', ...this.verdictFormat());\n        lines.push('', ...this.diffLines(context));\n        return lines.join('\\n');\n    }\n\n    /**\n     * HOW MANY subagents, of WHICH type. Without `reviewerAgents` that is one separate subagent per checklist;\n     * with it, at most N subagents with the checklists grouped across them as the AI judges best. Either way\n     * every subagent is the repo's ONE reviewer agent type, and every checklist still gets its own verdict.\n     */\n    spawnRule(pending: readonly RequiredChecklist[]): string[] {\n        const reviewer = pending[0].reviewer;\n        const own = [\n            'You may NOT review your own work, and you may NOT write a reviewer\\'s verdict file on its behalf.',\n        ];\n        if (!reviewer.grouped()) {\n            return [\n                `You MUST run these ${pending.length} checklist review(s) — a SEPARATE \\`${reviewer.agentName}\\` subagent for each.`,\n                ...own,\n            ];\n        }\n        const cap = Math.min(reviewer.maxAgents, pending.length);\n        return [\n            `You MUST run these ${pending.length} checklist review(s) using AT MOST ${cap} \\`${reviewer.agentName}\\` subagent(s)`,\n            `(commands.pr-gate.reviewerAgents = ${reviewer.maxAgents}). ${this.groupingHint(pending.length, cap)}`,\n            'Give each subagent every checklist it covers (doc, in-scope files, verdict path); it writes ONE verdict',\n            'file per checklist it covers, and never one for a checklist it was not given.',\n            ...own,\n        ];\n    }\n\n    /**\n     * The grouping sentence, with an example that fits THIS round's numbers — a cap of 1 has no choice to\n     * make, and saying \"group them as you judge best\" there would invite a second subagent.\n     */\n    groupingHint(count: number, cap: number): string {\n        if (cap <= 1) return 'Use ONE subagent for all of them.';\n        const per = Math.ceil(count / cap);\n        return `Group the checklists across them as you judge best — e.g. one subagent for all of them, or ${cap} with about ${per} each.`;\n    }\n\n    // Just the checklist IDS, for a caller that wants a one-line summary rather than the whole block.\n    names(pending: readonly RequiredChecklist[]): string {\n        return pending.map((r: RequiredChecklist): string => r.id).join(', ');\n    }\n\n    // What the subagent reviewing ONE checklist must be given: its doc, why it is running + over what, and\n    // the file it must write.\n    private oneReviewer(req: RequiredChecklist, reviewPath: string): string[] {\n        const lines = [`  • checklist ${req.id}`];\n        // The doc is REPO-relative by the time it reaches here (see ChecklistDefinition.doc), so a subagent\n        // handed this string can actually open it. Printing the raw config value would not resolve.\n        if (req.doc.trim() !== '') lines.push(`      doc to read:  ${req.doc}`);\n        for (const scopeLine of this.scope(req)) lines.push(`      ${scopeLine}`);\n        lines.push(`      must write:   ${this.reviewJsonService.checklistResultPath(reviewPath, req.id)}`);\n        return lines;\n    }\n\n    /**\n     * WHY this reviewer is running, and over what. NOT every checklist is pattern-matched: one with no\n     * `patterns` runs on EVERY PR, and calling its file list \"matched\" implies the list is a narrow,\n     * pre-filtered slice of the diff when it is in fact the whole thing. When patterns DID fire, they are\n     * named — the reviewer cannot otherwise tell a precise migrations-only glob from a blanket match-all one.\n     */\n    private scope(req: RequiredChecklist): string[] {\n        if (req.matchedPatterns.length === 0) {\n            return [\n                `in scope:     ALWAYS RUNS — this checklist has no patterns, so the WHOLE diff is in scope`,\n                `              all ${req.matchedFiles.length} changed file(s): ${formatFileList(req.matchedFiles)}`,\n            ];\n        }\n        const globs = req.matchedPatterns.map((p: string): string => `\"${p}\"`).join(', ');\n        return [\n            `in scope:     ${req.matchedFiles.length} file(s) matched ${globs}`,\n            `              ${formatFileList(req.matchedFiles)}`,\n        ];\n    }\n\n    // ONE shared format block for every reviewer, rather than repeating the schema under each name — and\n    // the schema itself comes from ReviewJsonService, the single renderer, so a change to the verdict shape\n    // cannot leave a stale copy in print. (It did once: `success` outlived its own removal in every\n    // hand-written agent .md.)\n    private verdictFormat(): string[] {\n        return [\n            'TELL EACH subagent to write each of its verdict files with EXACTLY this format (there is NO \"success\" field —',\n            'it was removed; \"status\" is a tri-state so a reviewer can pass a change AND still raise a concern):',\n            ...this.reviewJsonService.verdictSchemaFor('<the checklist id>', '', '  ').split('\\n'),\n        ];\n    }\n\n    // The diff every reviewer judges. Stated once, here, because path matching is deliberately coarse and a\n    // reviewer that only sees filenames cannot make the content-level call the checklist is asking for.\n    private diffLines(context: ChecklistReviewContext): string[] {\n        // NEVER omit these lines quietly. A reviewer given filenames but no way to read the change cannot make\n        // the content-level judgment the checklist asks for, and a silently shorter instruction block is\n        // indistinguishable from a complete one — so an unresolvable base is stated as the problem it is.\n        if (context.baseSha.trim() === '') {\n            return [\n                '⚠️  No diff base resolved for this branch, so the exact `git diff` command could not be given.',\n                '    Tell each reviewer to diff against main itself (`git diff $(git merge-base origin/main HEAD) HEAD -- <file>`)',\n                '    and note that path matching is COARSE — judge the real change, not the path.',\n            ];\n        }\n        const lines = ['Also give EACH one the real diff — path matching is COARSE, so judge the change, not the path:'];\n        // The MATERIALIZED diff when it exists: it cannot go empty the way a hand-assembled range can. The\n        // MANIFEST leads, and ALL.diff follows it, for the same reason the per-reviewer instructions were\n        // reordered: whichever one is printed first and framed as \"everything\" is the only one that gets\n        // opened — measured 4/4 — and ALL.diff is the one that can be silently incomplete.\n        if (context.diffDir.trim() !== '') {\n            lines.push(`  path map, AUTHORITATIVE:        ${context.diffDir}/manifest.json`);\n            lines.push('                                  per file: status, bytes, absolute source + diff paths,');\n            lines.push('                                  plus what was truncated or excluded');\n            lines.push(`  per-file diffs:                 ${context.diffDir}/files/`);\n            lines.push(`  combined view (may be capped):  ${context.diffDir}/ALL.diff`);\n        }\n        // NEVER hand-assemble `<baseSha> HEAD` here. On a dirty tree the changed-file set is base→working\n        // tree, so that range is empty and the reviewer is handed a command that shows it nothing — the\n        // failure this whole class of field exists to prevent. The command is derived from the same basis\n        // the file set was; when it is absent (an older pr-gate wrote the context), say so instead.\n        if (context.fileDiffCommand.trim() !== '') {\n            lines.push(`  reproduce one file:             ${context.fileDiffCommand}`);\n        } else {\n            lines.push(`  ⚠️  no reproduce command recorded — derive it yourself from base ${context.baseSha},`);\n            lines.push('      and check `git status` first: uncommitted work needs `git diff <base>` with NO head.');\n        }\n        if (context.dirty) {\n            lines.push('  ⚠️  this diff INCLUDES uncommitted + untracked work, so it is not what a commit-to-commit');\n            lines.push('      range would show. Judge it anyway — it is what the checklist matched against.');\n        }\n        if (context.prContextPath.trim() !== '') {\n            lines.push(`  full changed-file set + base/head sha:  ${context.prContextPath}`);\n        }\n        return lines;\n    }\n\n}\n"]}

package/src/checklist-validator.d.ts

@@ -1,4 +1,4 @@
-import { ChecklistDefinition } from './checklist-config';
+import { ChecklistDefinition, ReviewerAgentPolicy } from './checklist-config';
 /**
  * Validates the review checklists declared in `pr-gate.checklists`. The array in webpieces.config.json is
  * the ONLY accepted shape: there is deliberately no fallback, no second location, and no back-compat path
@@ -7,22 +7,23 @@ import { ChecklistDefinition } from './checklist-config';
  * strictly better than carrying two code paths forever so that nobody has to read an error message.
  *
  * Deliberately NOT `@injectable`: config validation runs from module-level functions in validate-config.ts,
- * before any container exists, so this is constructed directly. It previously carried an @injectable
- * decorator plus a comment claiming it was "injected by type and drawn in the DI design" — while nothing
- * injected it and it appeared nowhere in design.json. A false claim the next reader would have trusted.
+ * before any container exists, so this is constructed directly.
  */
 export declare class ChecklistValidator {
     /**
      * Human-readable errors for the configured checklists, or [] when they are valid. Never throws.
-     * `defs` are already narrowed by buildPrGateConfig; this checks what only the filesystem can answer.
+     * `defs` are already narrowed by buildPrGateConfig; this checks ids plus what only the filesystem can
+     * answer (each doc exists — skipped when `repoRoot` is undefined, i.e. a structure-only validation).
      */
-    validate(repoRoot: string, defs: readonly ChecklistDefinition[]): string[];
-    private validateSubagent;
+    validate(repoRoot: string | undefined, defs: readonly ChecklistDefinition[]): string[];
     /**
-     * The check this validator once lacked: nothing confirmed `subagent` named a real agent. A typo used to
-     * validate clean, then get printed to the coding agent as "spawn this" — and since wp-finish blocks on
-     * `review-<that-typo>.json`, the path of least resistance became writing the reviewer's verdict itself,
-     * which is the exact self-certification the distinct-subagent rule exists to prevent. Reject at load.
+     * The reviewer agent file named by `commands.pr-gate.reviewerAgentName`, checked ONCE for the repo.
+     *
+     * Only enforced when this repo HAS a `.claude/agents` dir — a non-Claude-Code consumer that drives the
+     * gate some other way must not be broken by a check for a directory it never has. Without it a typo
+     * validates clean, gets printed to the coding agent as "spawn this", and the path of least resistance
+     * becomes writing the verdicts itself — the self-certification the gate exists to prevent.
      */
-    private validateSubagentExists;
+    validateReviewerAgent(repoRoot: string, reviewer: ReviewerAgentPolicy): string[];
+    private validateId;
 }

package/src/checklist-validator.js

@@ -4,11 +4,16 @@ exports.ChecklistValidator = void 0;
 const tslib_1 = require("tslib");
 const fs = tslib_1.__importStar(require("fs"));
 const path = tslib_1.__importStar(require("path"));
+const checklist_config_1 = require("./checklist-config");
+const constants_1 = require("./constants");
 // Where a reviewer subagent's definition must live for Claude Code to be able to spawn it.
 const AGENTS_DIR = path.join('.claude', 'agents');
 // Every checklist error names this, so a reader always knows which file and key to open. There is exactly
 // ONE place checklists can be configured, so there is exactly one label.
 const SOURCE = 'pr-gate.checklists in webpieces.config.json';
+// A checklist id becomes a FILE NAME (review-<id>.json, <id>.instructions.md), so it is held to a
+// file-name-safe alphabet rather than trusted to not contain a slash.
+const CHECKLIST_ID = /^[A-Za-z0-9][A-Za-z0-9._-]*$/;
 /**
  * Validates the review checklists declared in `pr-gate.checklists`. The array in webpieces.config.json is
  * the ONLY accepted shape: there is deliberately no fallback, no second location, and no back-compat path
@@ -17,61 +22,68 @@ const SOURCE = 'pr-gate.checklists in webpieces.config.json';
  * strictly better than carrying two code paths forever so that nobody has to read an error message.
  *
  * Deliberately NOT `@injectable`: config validation runs from module-level functions in validate-config.ts,
- * before any container exists, so this is constructed directly. It previously carried an @injectable
- * decorator plus a comment claiming it was "injected by type and drawn in the DI design" — while nothing
- * injected it and it appeared nowhere in design.json. A false claim the next reader would have trusted.
+ * before any container exists, so this is constructed directly.
  */
 class ChecklistValidator {
     /**
      * Human-readable errors for the configured checklists, or [] when they are valid. Never throws.
-     * `defs` are already narrowed by buildPrGateConfig; this checks what only the filesystem can answer.
+     * `defs` are already narrowed by buildPrGateConfig; this checks ids plus what only the filesystem can
+     * answer (each doc exists — skipped when `repoRoot` is undefined, i.e. a structure-only validation).
      */
     validate(repoRoot, defs) {
         const errors = [];
         const seen = new Set();
-        // Only enforce the reviewer-agent file when this repo HAS an agents dir — a non-Claude-Code consumer
-        // that drives the gate some other way must not be broken by a check for a directory it never has.
-        const agentsDir = path.join(repoRoot, AGENTS_DIR);
-        const checkAgents = fs.existsSync(agentsDir);
         defs.forEach((def, i) => {
-            const label = def.subagent !== '' ? `"${def.subagent}"` : `checklists[${i}]`;
-            errors.push(...this.validateSubagent(def, i, seen, checkAgents, agentsDir));
-            if (def.doc !== '' && !fs.existsSync(path.join(repoRoot, def.doc))) {
+            errors.push(...this.validateId(def, i, seen));
+            const label = def.id !== '' ? `"${def.id}"` : `checklists[${i}]`;
+            if (def.doc === '') {
+                errors.push(`[pr-gate] ${SOURCE} ${label}.doc is required — the REPO-relative guidance doc the reviewer ` +
+                    `reviews against (e.g. ".claude/review/${def.id !== '' ? def.id : 'my-checklist'}.md"). The reviewer ` +
+                    `agent is generic, so the doc IS the checklist.`);
+            }
+            else if (repoRoot !== undefined && !fs.existsSync(path.join(repoRoot, def.doc))) {
                 errors.push(`[pr-gate] ${SOURCE} ${label}.doc "${def.doc}" does not exist (paths are REPO-relative).`);
             }
         });
         return errors;
     }
-    // `subagent` is the ONE required field and the whole distinct-reviewer guarantee rests on it.
-    // eslint-disable-next-line @typescript-eslint/max-params
-    validateSubagent(def, i, seen, checkAgents, agentsDir) {
-        const label = def.subagent !== '' ? `"${def.subagent}"` : `checklists[${i}]`;
-        if (def.subagent.trim() === '') {
-            return [`[pr-gate] ${SOURCE} checklists[${i}].subagent must be a non-empty string (the reviewer agent name, matching ${AGENTS_DIR}/<subagent>.md).`];
-        }
-        if (seen.has(def.subagent)) {
-            return [`[pr-gate] ${SOURCE} duplicate subagent "${def.subagent}" — each checklist must use a DISTINCT reviewer subagent (that is how independent review is enforced).`];
-        }
-        seen.add(def.subagent);
-        return this.validateSubagentExists(def.subagent, label, checkAgents, agentsDir);
-    }
     /**
-     * The check this validator once lacked: nothing confirmed `subagent` named a real agent. A typo used to
-     * validate clean, then get printed to the coding agent as "spawn this" — and since wp-finish blocks on
-     * `review-<that-typo>.json`, the path of least resistance became writing the reviewer's verdict itself,
-     * which is the exact self-certification the distinct-subagent rule exists to prevent. Reject at load.
+     * The reviewer agent file named by `commands.pr-gate.reviewerAgentName`, checked ONCE for the repo.
+     *
+     * Only enforced when this repo HAS a `.claude/agents` dir — a non-Claude-Code consumer that drives the
+     * gate some other way must not be broken by a check for a directory it never has. Without it a typo
+     * validates clean, gets printed to the coding agent as "spawn this", and the path of least resistance
+     * becomes writing the verdicts itself — the self-certification the gate exists to prevent.
      */
-    validateSubagentExists(subagent, label, checkAgents, agentsDir) {
-        if (!checkAgents)
+    validateReviewerAgent(repoRoot, reviewer) {
+        const agentsDir = path.join(repoRoot, AGENTS_DIR);
+        if (reviewer.agentName === '' || !fs.existsSync(agentsDir))
             return [];
-        if (fs.existsSync(path.join(agentsDir, `${subagent}.md`)))
+        if (fs.existsSync(path.join(agentsDir, `${reviewer.agentName}.md`)))
             return [];
+        const cure = reviewer.agentName === checklist_config_1.DEFAULT_REVIEWER_AGENT_NAME
+            ? `Run \`${constants_1.UPGRADE_SHIM_COMMAND}\` — it writes that webpieces-owned file.`
+            : 'Create that agent file, or set "reviewerAgentName" to an agent that exists.';
         return [
-            `[pr-gate] ${SOURCE} ${label}.subagent names no reviewer — ${AGENTS_DIR}/${subagent}.md does not exist, ` +
-                `so nothing can spawn it and wp-finish-upsert-pr would block forever on a review-${subagent}.json that no reviewer can write. ` +
-                `Create that agent file or fix the name.`,
+            `[pr-gate] commands.pr-gate.reviewerAgentName "${reviewer.agentName}" names no reviewer — ` +
+                `${AGENTS_DIR}/${reviewer.agentName}.md does not exist, so nothing can spawn it and wp-finish-upsert-pr ` +
+                `would block forever on verdicts no reviewer can write. ${cure}`,
         ];
     }
+    // `id` keys every per-checklist file and the dashboard row, so it must be present, unique and file-safe.
+    validateId(def, i, seen) {
+        if (def.id === '') {
+            return [`[pr-gate] ${SOURCE} checklists[${i}].id must be a non-empty string — the checklist's name; it keys review-<id>.json.`];
+        }
+        if (!CHECKLIST_ID.test(def.id)) {
+            return [`[pr-gate] ${SOURCE} checklists[${i}].id "${def.id}" must use only letters, digits, ".", "_" and "-" (it becomes a file name).`];
+        }
+        if (seen.has(def.id)) {
+            return [`[pr-gate] ${SOURCE} duplicate id "${def.id}" — every checklist needs its own id, because each writes its own review-<id>.json.`];
+        }
+        seen.add(def.id);
+        return [];
+    }
 }
 exports.ChecklistValidator = ChecklistValidator;
 //# sourceMappingURL=checklist-validator.js.map