@webpieces/rules-config 0.4.481 → 0.4.482

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@webpieces/rules-config",
-  "version": "0.4.481",
+  "version": "0.4.482",
   "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

@@ -5,9 +5,40 @@ export declare class ChecklistDefinition {
     patterns: string[];
     constructor(id: string, subagent: string, doc: string, patterns: string[]);
 }
+/**
+ * WHERE a repo's checklists come from. Exactly one of the two is populated (an array in
+ * webpieces.config.json wins when both are present, and validation says so), and both are empty for the
+ * common case of a repo with no checklists at all. Data-only.
+ */
+export declare class ChecklistSource {
+    inline: ChecklistDefinition[];
+    doc: string;
+    constructor(inline?: ChecklistDefinition[], doc?: string);
+    isEmpty(): boolean;
+    describe(): string;
+}
 export interface RawChecklistItem {
     subagent?: string;
     doc?: string;
     patterns?: string[];
 }
-export declare function toChecklist(raw: RawChecklistItem): ChecklistDefinition;
+/**
+ * Build a ChecklistDefinition from an omitting-friendly raw entry. `id` defaults to the subagent name (the
+ * only stable, human-meaningful key we have). `docBaseRel` is the repo-relative DIRECTORY that a relative
+ * `raw.doc` resolves against: '' for the array-in-config form (repo root), `dirname(manifestDoc)` for the
+ * legacy manifest form. The stored `doc` is always repo-relative — see ChecklistDefinition.doc.
+ */
+export declare function toChecklist(raw: RawChecklistItem, docBaseRel?: string): ChecklistDefinition;
+export declare const MATCHED_FILES_CAP = 6;
+/**
+ * Render a file list for a message, NEVER silently. A truncated list that looks complete is how a reviewer
+ * gets pointed at 4 of 40 changed files and reports success having reviewed a tenth of the diff, so the
+ * dropped count is always stated and the caller is expected to name the file holding the full set.
+ */
+export declare function formatFileList(files: readonly string[], cap?: number): string;
+/**
+ * Resolve a checklist entry's `doc` to a repo-relative POSIX path. This is the fix for a reviewer subagent
+ * being handed a bare `deploy-infra.md` that exists nowhere relative to its CWD: the resolution against the
+ * manifest doc's directory happens ONCE, here, instead of being re-derived (or forgotten) at each print site.
+ */
+export declare function resolveChecklistDoc(doc: string, docBaseRel: string): string;

package/src/checklist-config.js

@@ -1,4 +1,11 @@
 "use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.MATCHED_FILES_CAP = exports.ChecklistSource = exports.ChecklistDefinition = void 0;
+exports.toChecklist = toChecklist;
+exports.formatFileList = formatFileList;
+exports.resolveChecklistDoc = resolveChecklistDoc;
+const tslib_1 = require("tslib");
+const path = tslib_1.__importStar(require("path"));
 // 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
@@ -6,16 +13,21 @@
 // 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.
 //
-// The checklist SET is NOT defined in webpieces.config.json — that only points at ONE manifest doc
-// (`checklists: { "doc": "..." }`). The manifest lives in the doc so the review process is content, not
-// config. This is a SURFACING + AUDIT extension point; webpieces owns only the mechanism. Data-only.
-Object.defineProperty(exports, "__esModule", { value: true });
-exports.ChecklistDefinition = void 0;
-exports.toChecklist = toChecklist;
+// TWO config shapes are supported (see ChecklistSource):
+//   PRIMARY  — `checklists: [ { subagent, doc?, patterns? } ]` in webpieces.config.json. `patterns` is a
+//              path-glob dispatch table and `subagent` is a name binding: both are config, so they live
+//              where every tool that reads webpieces.config.json can see, grep, and schema them.
+//   LEGACY   — `checklists: { "doc": "..." }`, where the array lives in an HTML comment inside that doc.
+//              Still loaded (it is shipped and consumers depend on it), but no longer the recommended form.
+// 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
-    doc; // repo-relative guidance doc the reviewer reads (may be '' — then it reads the manifest doc)
+    // REPO-RELATIVE guidance doc the reviewer reads (may be '' — then it reads the manifest doc). Always
+    // repo-relative by the time it reaches here, whichever config shape it came from, because this value is
+    // printed verbatim to a reviewer subagent as "the file to open" — a path relative to some other file's
+    // directory is unresolvable from where that subagent stands.
+    doc;
     patterns; // path globs (isPathExcluded semantics); [] = matches any changed file (always runs)
     constructor(id, subagent, doc, patterns) {
         this.id = id;
@@ -25,11 +37,74 @@ class ChecklistDefinition {
     }
 }
 exports.ChecklistDefinition = ChecklistDefinition;
-// Build a ChecklistDefinition from an omitting-friendly raw manifest entry. id defaults to the subagent
-// name (the only stable, human-meaningful key we have).
+/**
+ * WHERE a repo's checklists come from. Exactly one of the two is populated (an array in
+ * webpieces.config.json wins when both are present, and validation says so), and both are empty for the
+ * common case of a repo with no checklists at all. Data-only.
+ */
+class ChecklistSource {
+    // The array form straight from `pr-gate.checklists` in webpieces.config.json (PRIMARY). Already
+    // narrowed + repo-relative-resolved. [] when the repo uses the legacy `{ doc }` form or has none.
+    inline;
+    // Repo-relative path of the ONE doc carrying a `<!-- webpieces:checklists [...] -->` manifest (LEGACY).
+    // '' when the repo uses the array form or has no checklists.
+    doc;
+    constructor(inline = [], doc = '') {
+        this.inline = inline;
+        this.doc = doc;
+    }
+    // True when this repo configured no checklists at all (neither shape).
+    isEmpty() {
+        return this.inline.length === 0 && this.doc.trim() === '';
+    }
+    // How to NAME this source in a message: the config key for the array form, the doc path for the
+    // manifest form. Every checklist error/notice cites one of these so a reader knows what file to open.
+    describe() {
+        if (this.doc.trim() !== '')
+            return this.doc;
+        return 'pr-gate.checklists in webpieces.config.json';
+    }
+}
+exports.ChecklistSource = ChecklistSource;
+/**
+ * Build a ChecklistDefinition from an omitting-friendly raw entry. `id` defaults to the subagent name (the
+ * only stable, human-meaningful key we have). `docBaseRel` is the repo-relative DIRECTORY that a relative
+ * `raw.doc` resolves against: '' for the array-in-config form (repo root), `dirname(manifestDoc)` for the
+ * legacy manifest form. The stored `doc` is always repo-relative — see ChecklistDefinition.doc.
+ */
 // webpieces-disable no-function-outside-class -- pure config transform beside its data class
-function toChecklist(raw) {
+function toChecklist(raw, docBaseRel = '') {
     const subagent = raw.subagent ?? '';
-    return new ChecklistDefinition(subagent, subagent, raw.doc ?? '', raw.patterns ?? []);
+    return new ChecklistDefinition(subagent, subagent, resolveChecklistDoc(raw.doc ?? '', docBaseRel), raw.patterns ?? []);
+}
+// The ONE cap for every printed matched-file list. Two print sites used to slice to 4 and to 5 — two
+// different caps for the same list, neither chosen deliberately, and both without an ellipsis.
+exports.MATCHED_FILES_CAP = 6;
+/**
+ * Render a file list for a message, NEVER silently. A truncated list that looks complete is how a reviewer
+ * gets pointed at 4 of 40 changed files and reports success having reviewed a tenth of the diff, so the
+ * dropped count is always stated and the caller is expected to name the file holding the full set.
+ */
+// webpieces-disable no-function-outside-class -- pure display formatter beside the data it formats
+function formatFileList(files, cap = exports.MATCHED_FILES_CAP) {
+    if (files.length === 0)
+        return '(none)';
+    if (files.length <= cap)
+        return files.join(', ');
+    return `${files.slice(0, cap).join(', ')}, +${files.length - cap} more (${files.length} total)`;
+}
+/**
+ * Resolve a checklist entry's `doc` to a repo-relative POSIX path. This is the fix for a reviewer subagent
+ * being handed a bare `deploy-infra.md` that exists nowhere relative to its CWD: the resolution against the
+ * manifest doc's directory happens ONCE, here, instead of being re-derived (or forgotten) at each print site.
+ */
+// webpieces-disable no-function-outside-class -- pure path transform beside its data class
+function resolveChecklistDoc(doc, docBaseRel) {
+    const trimmed = doc.trim();
+    if (trimmed === '')
+        return '';
+    const base = docBaseRel.trim();
+    const joined = base === '' || base === '.' ? trimmed : `${base}/${trimmed}`;
+    return path.posix.normalize(joined.split(path.sep).join('/'));
 }
 //# sourceMappingURL=checklist-config.js.map

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":";AAAA,mGAAmG;AACnG,yGAAyG;AACzG,wGAAwG;AACxG,uGAAuG;AACvG,0GAA0G;AAC1G,6FAA6F;AAC7F,EAAE;AACF,mGAAmG;AACnG,wGAAwG;AACxG,qGAAqG;;;AA0BrG,kCAGC;AA3BD,MAAa,mBAAmB;IAC5B,EAAE,CAAS,CAAS,mEAAmE;IACvF,QAAQ,CAAS,CAAG,uFAAuF;IAC3G,GAAG,CAAS,CAAQ,6FAA6F;IACjH,QAAQ,CAAW,CAAC,qFAAqF;IAEzG,YAAY,EAAU,EAAE,QAAgB,EAAE,GAAW,EAAE,QAAkB;QACrE,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;IAC7B,CAAC;CACJ;AAZD,kDAYC;AASD,wGAAwG;AACxG,wDAAwD;AACxD,6FAA6F;AAC7F,SAAgB,WAAW,CAAC,GAAqB;IAC7C,MAAM,QAAQ,GAAG,GAAG,CAAC,QAAQ,IAAI,EAAE,CAAC;IACpC,OAAO,IAAI,mBAAmB,CAAC,QAAQ,EAAE,QAAQ,EAAE,GAAG,CAAC,GAAG,IAAI,EAAE,EAAE,GAAG,CAAC,QAAQ,IAAI,EAAE,CAAC,CAAC;AAC1F,CAAC","sourcesContent":["// 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-start-upsert-pr tells the AI to spawn that subagent to review\n// it, and wp-finish-upsert-pr refuses to open the PR until a well-formed, passing review-<id>.json exists\n// AND that named subagent is proven (from the harness's own artifacts) to have actually run.\n//\n// The checklist SET is NOT defined in webpieces.config.json — that only points at ONE manifest doc\n// (`checklists: { \"doc\": \"...\" }`). The manifest lives in the doc so the review process is content, not\n// config. This is a SURFACING + AUDIT extension point; webpieces owns only the mechanism. Data-only.\n\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    doc: string;        // repo-relative guidance doc the reviewer reads (may be '' — then it reads the manifest doc)\n    patterns: string[]; // path globs (isPathExcluded semantics); [] = matches any changed file (always runs)\n\n    constructor(id: string, subagent: string, doc: string, patterns: string[]) {\n        this.id = id;\n        this.subagent = subagent;\n        this.doc = doc;\n        this.patterns = patterns;\n    }\n}\n\n// One manifest entry straight from the doc's JSON block, before it is validated + narrowed into a class.\nexport interface RawChecklistItem {\n    subagent?: string;\n    doc?: string;\n    patterns?: string[];\n}\n\n// Build a ChecklistDefinition from an omitting-friendly raw manifest entry. id defaults to the subagent\n// name (the only stable, human-meaningful key we have).\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(subagent, subagent, raw.doc ?? '', raw.patterns ?? []);\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// 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-start-upsert-pr tells the AI to spawn that subagent to review\n// it, and wp-finish-upsert-pr refuses to open the PR until a well-formed, passing review-<id>.json exists\n// AND that named subagent is proven (from the harness's own artifacts) to have actually run.\n//\n// TWO config shapes are supported (see ChecklistSource):\n//   PRIMARY  — `checklists: [ { subagent, doc?, patterns? } ]` in webpieces.config.json. `patterns` is a\n//              path-glob dispatch table and `subagent` is a name binding: both are config, so they live\n//              where every tool that reads webpieces.config.json can see, grep, and schema them.\n//   LEGACY   — `checklists: { \"doc\": \"...\" }`, where the array lives in an HTML comment inside that doc.\n//              Still loaded (it is shipped and consumers depend on it), but no longer the recommended form.\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 reads the manifest doc). Always\n    // repo-relative by the time it reaches here, whichever config shape it came from, because this value is\n    // printed verbatim to a reviewer subagent as \"the file to open\" — a path relative to some other file's\n    // directory 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    constructor(id: string, subagent: string, doc: string, patterns: string[]) {\n        this.id = id;\n        this.subagent = subagent;\n        this.doc = doc;\n        this.patterns = patterns;\n    }\n}\n\n/**\n * WHERE a repo's checklists come from. Exactly one of the two is populated (an array in\n * webpieces.config.json wins when both are present, and validation says so), and both are empty for the\n * common case of a repo with no checklists at all. Data-only.\n */\nexport class ChecklistSource {\n    // The array form straight from `pr-gate.checklists` in webpieces.config.json (PRIMARY). Already\n    // narrowed + repo-relative-resolved. [] when the repo uses the legacy `{ doc }` form or has none.\n    inline: ChecklistDefinition[];\n    // Repo-relative path of the ONE doc carrying a `<!-- webpieces:checklists [...] -->` manifest (LEGACY).\n    // '' when the repo uses the array form or has no checklists.\n    doc: string;\n\n    constructor(inline: ChecklistDefinition[] = [], doc = '') {\n        this.inline = inline;\n        this.doc = doc;\n    }\n\n    // True when this repo configured no checklists at all (neither shape).\n    isEmpty(): boolean {\n        return this.inline.length === 0 && this.doc.trim() === '';\n    }\n\n    // How to NAME this source in a message: the config key for the array form, the doc path for the\n    // manifest form. Every checklist error/notice cites one of these so a reader knows what file to open.\n    describe(): string {\n        if (this.doc.trim() !== '') return this.doc;\n        return 'pr-gate.checklists in webpieces.config.json';\n    }\n}\n\n// One manifest/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}\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). `docBaseRel` is the repo-relative DIRECTORY that a relative\n * `raw.doc` resolves against: '' for the array-in-config form (repo root), `dirname(manifestDoc)` for the\n * legacy manifest form. The stored `doc` is always repo-relative — see ChecklistDefinition.doc.\n */\n// webpieces-disable no-function-outside-class -- pure config transform beside its data class\nexport function toChecklist(raw: RawChecklistItem, docBaseRel = ''): ChecklistDefinition {\n    const subagent = raw.subagent ?? '';\n    return new ChecklistDefinition(subagent, subagent, resolveChecklistDoc(raw.doc ?? '', docBaseRel), raw.patterns ?? []);\n}\n\n// The ONE cap for every printed matched-file list. Two print sites 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\n/**\n * Resolve a checklist entry's `doc` to a repo-relative POSIX path. This is the fix for a reviewer subagent\n * being handed a bare `deploy-infra.md` that exists nowhere relative to its CWD: the resolution against the\n * manifest doc's directory happens ONCE, here, instead of being re-derived (or forgotten) at each print site.\n */\n// webpieces-disable no-function-outside-class -- pure path transform beside its data class\nexport function resolveChecklistDoc(doc: string, docBaseRel: string): string {\n    const trimmed = doc.trim();\n    if (trimmed === '') return '';\n    const base = docBaseRel.trim();\n    const joined = base === '' || base === '.' ? trimmed : `${base}/${trimmed}`;\n    return path.posix.normalize(joined.split(path.sep).join('/'));\n}\n"]}

package/src/checklist-instructions.d.ts

@@ -0,0 +1,35 @@
+import { ChecklistReviewContext, RequiredChecklist } from './review-json';
+/**
+ * Renders the ONE block that tells the coding agent which reviewer subagents it must run and exactly what
+ * to tell them. There is a single renderer because three callers need the identical text and any drift
+ * between them is a correctness bug, not a cosmetic one:
+ *
+ *   - `wp-checklist`            — the AI asks "what review do I owe on this diff?"
+ *   - `wp-finish-upsert-pr`     — fails fast, listing ONLY the reviewers that still have not run
+ *   - `ReviewJsonService`       — the same list appended to a review.json validation failure
+ *
+ * Callers pass ONLY the checklists still needing a verdict. A checklist already reviewed on this branch is
+ * never re-listed — re-instructing it invites a redundant second run, and (worse) reads as though the
+ * earlier verdict did not count.
+ *
+ * `@injectable(bindingScopeValues.Singleton)` so it is injected by type and drawn in the DI design.
+ */
+export declare class ChecklistInstructionsService {
+    /**
+     * The full instruction block, or '' when nothing is pending (so a caller can concatenate it blindly).
+     * `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;
+    names(pending: readonly RequiredChecklist[]): string;
+    private oneReviewer;
+    /**
+     * WHY this reviewer is running, and over what. NOT every checklist is pattern-matched: one with no
+     * `patterns` runs on EVERY PR, and calling its file list "matched" implies the list is a narrow,
+     * pre-filtered slice of the diff when it is in fact the whole thing. When patterns DID fire, they are
+     * named — the reviewer cannot otherwise tell a precise migrations-only glob from a blanket match-all one.
+     */
+    private scope;
+    private verdictFormat;
+    private diffLines;
+    private verdictPath;
+}

package/src/checklist-instructions.js

@@ -0,0 +1,110 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.ChecklistInstructionsService = void 0;
+const tslib_1 = require("tslib");
+const inversify_1 = require("inversify");
+const checklist_config_1 = require("./checklist-config");
+/**
+ * Renders the ONE block that tells the coding agent which reviewer subagents it must run and exactly what
+ * to tell them. There is a single renderer because three callers need the identical text and any drift
+ * between them is a correctness bug, not a cosmetic one:
+ *
+ *   - `wp-checklist`            — the AI asks "what review do I owe on this diff?"
+ *   - `wp-finish-upsert-pr`     — fails fast, listing ONLY the reviewers that still have not run
+ *   - `ReviewJsonService`       — the same list appended to a review.json validation failure
+ *
+ * Callers pass ONLY the checklists still needing a verdict. A checklist already reviewed on this branch is
+ * never re-listed — re-instructing it invites a redundant second run, and (worse) reads as though the
+ * earlier verdict did not count.
+ *
+ * `@injectable(bindingScopeValues.Singleton)` so it is injected by type and drawn in the DI design.
+ */
+let ChecklistInstructionsService = class ChecklistInstructionsService {
+    /**
+     * The full instruction block, or '' when nothing is pending (so a caller can concatenate it blindly).
+     * `reviewPath` is the branch's review.json — each verdict file sits beside it as review-<id>.json.
+     */
+    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.`,
+            '',
+        ];
+        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.
+    names(pending) {
+        return pending.map((r) => r.subagent).join(', ');
+    }
+    // What ONE subagent must be given: its doc, why it is running + over what, and the file it must write.
+    oneReviewer(req, reviewPath) {
+        const lines = [`  • ${req.subagent}`];
+        // 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() !== '')
+            lines.push(`      doc to read:  ${req.doc}`);
+        for (const scopeLine of this.scope(req))
+            lines.push(`      ${scopeLine}`);
+        lines.push(`      must write:   ${this.verdictPath(reviewPath, req.id)}`);
+        return lines;
+    }
+    /**
+     * WHY this reviewer is running, and over what. NOT every checklist is pattern-matched: one with no
+     * `patterns` runs on EVERY PR, and calling its file list "matched" implies the list is a narrow,
+     * pre-filtered slice of the diff when it is in fact the whole thing. When patterns DID fire, they are
+     * named — the reviewer cannot otherwise tell a precise migrations-only glob from a blanket match-all one.
+     */
+    scope(req) {
+        if (req.matchedPatterns.length === 0) {
+            return [
+                `in scope:     ALWAYS RUNS — this checklist has no patterns, so the WHOLE diff is in scope`,
+                `              all ${req.matchedFiles.length} changed file(s): ${(0, checklist_config_1.formatFileList)(req.matchedFiles)}`,
+            ];
+        }
+        const globs = req.matchedPatterns.map((p) => `"${p}"`).join(', ');
+        return [
+            `in scope:     ${req.matchedFiles.length} file(s) matched ${globs}`,
+            `              ${(0, checklist_config_1.formatFileList)(req.matchedFiles)}`,
+        ];
+    }
+    // ONE shared format block for every reviewer, rather than repeating the schema under each name.
+    verdictFormat() {
+        return [
+            'TELL EACH subagent to write that file with EXACTLY this format:',
+            '  { "id": "<its own subagent name>", "success": true, "output": "what you checked / found", "override": "" }',
+            '    success:false + empty "override"      → REFUSES the PR; the reviewer\'s "output" is printed verbatim',
+            '    success:false + non-empty "override"  → ships anyway as 🟡; the justification is published on the PR',
+        ];
+    }
+    // The diff every reviewer judges. Stated once, here, because path matching is deliberately coarse and a
+    // reviewer that only sees filenames cannot make the content-level call the checklist is asking for.
+    diffLines(context) {
+        if (context.baseSha.trim() === '')
+            return ['Also tell each one that path matching is COARSE — judge the real change, not the path.'];
+        const lines = [
+            'Also give EACH one the real diff — path matching is COARSE, so judge the change, not the path:',
+            `  git diff ${context.baseSha} HEAD -- <file>`,
+        ];
+        if (context.prContextPath.trim() !== '') {
+            lines.push(`  full changed-file set + base/head sha:  ${context.prContextPath}`);
+        }
+        return lines;
+    }
+    // review-<id>.json beside the branch's review.json — one file per checklist so N concurrent reviewer
+    // subagents never clobber a shared file.
+    verdictPath(reviewPath, checklistId) {
+        const dir = reviewPath.replace(/[/\\][^/\\]*$/, '');
+        return `${dir}/review-${checklistId}.json`;
+    }
+};
+exports.ChecklistInstructionsService = ChecklistInstructionsService;
+exports.ChecklistInstructionsService = ChecklistInstructionsService = tslib_1.__decorate([
+    (0, inversify_1.injectable)(inversify_1.bindingScopeValues.Singleton)
+], ChecklistInstructionsService);
+//# sourceMappingURL=checklist-instructions.js.map

package/src/checklist-instructions.js.map

@@ -0,0 +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 { ChecklistReviewContext, RequiredChecklist } 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-checklist`            — 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    /**\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.verdictPath(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.\n    private verdictFormat(): string[] {\n        return [\n            'TELL EACH subagent to write that file with EXACTLY this format:',\n            '  { \"id\": \"<its own subagent name>\", \"success\": true, \"output\": \"what you checked / found\", \"override\": \"\" }',\n            '    success:false + empty \"override\"      → REFUSES the PR; the reviewer\\'s \"output\" is printed verbatim',\n            '    success:false + non-empty \"override\"  → ships anyway as 🟡; the justification is published on the PR',\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        if (context.baseSha.trim() === '') return ['Also tell each one that path matching is COARSE — judge the real change, not the path.'];\n        const lines = [\n            'Also give EACH one the real diff — path matching is COARSE, so judge the change, not the path:',\n            `  git diff ${context.baseSha} HEAD -- <file>`,\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    // review-<id>.json beside the branch's review.json — one file per checklist so N concurrent reviewer\n    // subagents never clobber a shared file.\n    private verdictPath(reviewPath: string, checklistId: string): string {\n        const dir = reviewPath.replace(/[/\\\\][^/\\\\]*$/, '');\n        return `${dir}/review-${checklistId}.json`;\n    }\n}\n"]}

package/src/checklist-manifest.d.ts

@@ -1,15 +1,34 @@
-import { ChecklistDefinition } from './checklist-config';
+import { ChecklistDefinition, ChecklistSource } from './checklist-config';
 /**
- * Loads + validates the checklist manifest embedded in the single doc `pr-gate.checklists.doc` points at.
- * The set of checklists lives in the DOC (content), not webpieces.config.json (config) — the config only
- * carries the doc path. `@injectable(bindingScopeValues.Singleton)` so it is injected by type + drawn in
- * the DI design.
+ * Loads + validates a repo's review checklists from EITHER shape (see {@link ChecklistSource}): the
+ * `pr-gate.checklists` array in webpieces.config.json (primary) or the `<!-- webpieces:checklists -->`
+ * manifest embedded in the doc that `pr-gate.checklists.doc` points at (legacy).
+ *
+ * `@injectable(bindingScopeValues.Singleton)` so it is injected by type + drawn in the DI design.
  */
 export declare class ChecklistManifestService {
     manifestDocPath(repoRoot: string, docRel: string): string;
-    load(repoRoot: string, docRel: string): ChecklistDefinition[];
-    validate(repoRoot: string, docRel: string): string[];
+    /**
+     * The repo's checklists, or [] when there are none / the manifest doc is missing / malformed. Callers
+     * that need to REPORT those problems use validate(); this one is the tolerant runtime read.
+     */
+    load(repoRoot: string, source: ChecklistSource): ChecklistDefinition[];
+    validate(repoRoot: string, source: ChecklistSource): string[];
     private validateItems;
+    /**
+     * The checks that are the SAME for both config shapes, run against already-narrowed definitions:
+     * subagent present + distinct + actually resolves to a spawnable agent, and the guidance doc exists.
+     */
+    private validateResolved;
+    /**
+     * The check this validator was missing: `subagent` is the ONE required field and the whole
+     * distinct-reviewer guarantee rests on it, yet nothing confirmed it names 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.
+     */
+    private validateSubagentExists;
+    private usable;
     private readItems;
     private extractManifest;
     private parse;

package/src/checklist-manifest.js

@@ -7,38 +7,55 @@ const path = tslib_1.__importStar(require("path"));
 const inversify_1 = require("inversify");
 const checklist_config_1 = require("./checklist-config");
 const to_error_1 = require("./to-error");
-// The delimited JSON manifest embedded in the review doc. An HTML comment so it does NOT render in the
-// markdown a human reads, but is trivially + robustly parseable (JSON.parse — no YAML dependency, no
-// hand-rolled frontmatter parser). Example, at the top of `.claude/review/index.md`:
+// The delimited JSON manifest embedded in the review doc — the LEGACY shape, kept working because it is
+// shipped. An HTML comment so it does NOT render in the markdown a human reads, but is trivially +
+// robustly parseable (JSON.parse — no YAML dependency, no hand-rolled frontmatter parser). Example, at the
+// top of `.claude/review/index.md`:
 //
 //   <!-- webpieces:checklists
 //   [ { "subagent": "morpheus-envvars-reviewer", "doc": "morpheus-envvars.md",
 //       "patterns": ["**/.env*", "**/Dockerfile*"] } ]
 //   -->
+//
+// New repos should put the SAME array directly in `pr-gate.checklists` in webpieces.config.json instead —
+// see ChecklistSource. A JSON array inside an HTML comment is reachable only by this regex: no JSON Schema
+// covers it, no editor completes it, no `jq` reads it.
 const MANIFEST_RE = /<!--\s*webpieces:checklists\s*([\s\S]*?)-->/;
+// Where a reviewer subagent's definition must live for Claude Code to be able to spawn it.
+const AGENTS_DIR = path.join('.claude', 'agents');
 /**
- * Loads + validates the checklist manifest embedded in the single doc `pr-gate.checklists.doc` points at.
- * The set of checklists lives in the DOC (content), not webpieces.config.json (config) — the config only
- * carries the doc path. `@injectable(bindingScopeValues.Singleton)` so it is injected by type + drawn in
- * the DI design.
+ * Loads + validates a repo's review checklists from EITHER shape (see {@link ChecklistSource}): the
+ * `pr-gate.checklists` array in webpieces.config.json (primary) or the `<!-- webpieces:checklists -->`
+ * manifest embedded in the doc that `pr-gate.checklists.doc` points at (legacy).
+ *
+ * `@injectable(bindingScopeValues.Singleton)` so it is injected by type + drawn in the DI design.
  */
 let ChecklistManifestService = class ChecklistManifestService {
     // Absolute path of the manifest doc under repoRoot.
     manifestDocPath(repoRoot, docRel) {
         return path.join(repoRoot, docRel);
     }
-    // The parsed checklists, or [] when the doc is missing / has no manifest block / is malformed. Callers
-    // that need to REPORT those problems use validate(); this one is the tolerant runtime read.
-    load(repoRoot, docRel) {
-        if (docRel.trim() === '')
+    /**
+     * The repo's checklists, or [] when there are none / the manifest doc is missing / malformed. Callers
+     * that need to REPORT those problems use validate(); this one is the tolerant runtime read.
+     */
+    load(repoRoot, source) {
+        if (source.inline.length > 0)
+            return this.usable(source.inline);
+        if (source.doc.trim() === '')
+            return [];
+        const items = this.readItems(this.manifestDocPath(repoRoot, source.doc));
+        if (items === null)
             return [];
-        const items = this.readItems(this.manifestDocPath(repoRoot, docRel));
-        return items === null ? [] : items.map(checklist_config_1.toChecklist).filter((d) => d.subagent !== '');
+        return this.usable(items.map((raw) => (0, checklist_config_1.toChecklist)(raw, path.posix.dirname(source.doc))));
     }
-    // Human-readable errors for the manifest doc, or [] when it is valid. Never throws.
-    validate(repoRoot, docRel) {
-        if (docRel.trim() === '')
+    // Human-readable errors for the repo's checklist config, or [] when valid. Never throws.
+    validate(repoRoot, source) {
+        if (source.inline.length > 0)
+            return this.validateResolved(source.inline, repoRoot, source.describe());
+        if (source.doc.trim() === '')
             return [];
+        const docRel = source.doc;
         const docPath = this.manifestDocPath(repoRoot, docRel);
         if (!fs.existsSync(docPath)) {
             return [`[pr-gate] checklists.doc "${docRel}" does not exist — it must be a markdown doc carrying a <!-- webpieces:checklists [...] --> manifest.`];
@@ -53,30 +70,73 @@ let ChecklistManifestService = class ChecklistManifestService {
         }
         return this.validateItems(parsed, repoRoot, docRel);
     }
+    // Validate raw manifest entries (legacy shape): narrow each to a ChecklistDefinition with its doc
+    // resolved against the manifest doc's directory, then run the SAME checks the array form gets.
     validateItems(items, repoRoot, docRel) {
         const errors = [];
-        const seen = new Set();
-        const docDir = path.dirname(this.manifestDocPath(repoRoot, docRel));
+        const docBase = path.posix.dirname(docRel);
         items.forEach((item, i) => {
             const label = typeof item.subagent === 'string' && item.subagent !== '' ? `"${item.subagent}"` : `checklists[${i}]`;
-            if (typeof item.subagent !== 'string' || item.subagent.trim() === '') {
-                errors.push(`[pr-gate] ${docRel} checklists[${i}].subagent must be a non-empty string (the reviewer agent name, matching .claude/agents/<subagent>.md).`);
+            if (item.patterns !== undefined && !this.isStringArray(item.patterns)) {
+                errors.push(`[pr-gate] ${docRel} ${label}.patterns must be a string[] of path globs (omit or [] to run on every PR).`);
             }
-            else if (seen.has(item.subagent)) {
-                errors.push(`[pr-gate] ${docRel} duplicate subagent "${item.subagent}" — each checklist must use a DISTINCT reviewer subagent (that is how independent review is enforced).`);
+        });
+        const defs = items.map((item) => (0, checklist_config_1.toChecklist)(item, docBase));
+        return [...errors, ...this.validateResolved(defs, repoRoot, docRel)];
+    }
+    /**
+     * The checks that are the SAME for both config shapes, run against already-narrowed definitions:
+     * subagent present + distinct + actually resolves to a spawnable agent, and the guidance doc exists.
+     */
+    validateResolved(defs, repoRoot, sourceLabel) {
+        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}]`;
+            if (def.subagent.trim() === '') {
+                errors.push(`[pr-gate] ${sourceLabel} checklists[${i}].subagent must be a non-empty string (the reviewer agent name, matching .claude/agents/<subagent>.md).`);
             }
-            else {
-                seen.add(item.subagent);
+            else if (seen.has(def.subagent)) {
+                errors.push(`[pr-gate] ${sourceLabel} duplicate subagent "${def.subagent}" — each checklist must use a DISTINCT reviewer subagent (that is how independent review is enforced).`);
             }
-            if (item.doc !== undefined && item.doc !== '' && !fs.existsSync(path.join(docDir, item.doc))) {
-                errors.push(`[pr-gate] ${docRel} ${label}.doc "${item.doc}" does not exist (resolved relative to the manifest doc).`);
+            else {
+                seen.add(def.subagent);
+                errors.push(...this.validateSubagentExists(def.subagent, label, checkAgents, agentsDir, sourceLabel));
             }
-            if (item.patterns !== undefined && !this.isStringArray(item.patterns)) {
-                errors.push(`[pr-gate] ${docRel} ${label}.patterns must be a string[] of path globs (omit or [] to run on every PR).`);
+            if (def.doc !== '' && !fs.existsSync(path.join(repoRoot, def.doc))) {
+                errors.push(`[pr-gate] ${sourceLabel} ${label}.doc "${def.doc}" does not exist (resolved repo-relative).`);
             }
         });
         return errors;
     }
+    /**
+     * The check this validator was missing: `subagent` is the ONE required field and the whole
+     * distinct-reviewer guarantee rests on it, yet nothing confirmed it names 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.
+     */
+    // eslint-disable-next-line @typescript-eslint/max-params
+    validateSubagentExists(subagent, label, checkAgents, agentsDir, sourceLabel) {
+        if (!checkAgents)
+            return [];
+        if (fs.existsSync(path.join(agentsDir, `${subagent}.md`)))
+            return [];
+        return [
+            `[pr-gate] ${sourceLabel} ${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.`,
+        ];
+    }
+    // Drop entries with no subagent — they have no id, so they can key neither review-<id>.json nor a
+    // dashboard row. validate() reports them; the tolerant load() just skips them.
+    usable(defs) {
+        return defs.filter((d) => d.subagent !== '');
+    }
     // Read the manifest doc and return its parsed items, or null on any problem (missing/no block/bad JSON).
     readItems(docPath) {
         if (!fs.existsSync(docPath))