@webpieces/rules-config 0.4.564 → 0.4.565

package/package.json

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

@@ -3,16 +3,39 @@ export declare class ChecklistDefinition {
     subagent: string;
     doc: string;
     patterns: string[];
-    constructor(id: string, subagent: string, doc: string, patterns: string[]);
+    /**
+     * true  — BLOCKING. `wp-finish-upsert-pr` refuses the PR until this checklist has a passing verdict.
+     * false — OPTIONAL. When it matches, stage ② OFFERS it: the AI asks the human which optional reviewers
+     *         to run, and the human may decline every one of them. A declined optional checklist never
+     *         blocks.
+     *
+     * This governs whether the reviewer must RUN — NOT whether its verdict counts. An optional reviewer
+     * that is actually spawned and comes back red blocks finish exactly like a required one; otherwise
+     * running it would be theater.
+     *
+     * There is deliberately NO default (see the validator): a review process is the last thing that should
+     * acquire a scope silently, in either direction. Defaulting to true would leave the all-blocking status
+     * quo in place for anyone who did not read the release note; defaulting to false would quietly
+     * DOWNGRADE every existing consumer's gate on upgrade. Both are worse than one mechanical config edit
+     * 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);
 }
 export interface RawChecklistItem {
     subagent?: 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).
+ *
+ * `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;
 /** Normalize a checklist entry's repo-relative `doc` to a POSIX path, so every printed path matches. */

package/src/checklist-config.js

@@ -25,22 +25,46 @@ class ChecklistDefinition {
     // relative to anything else is unresolvable from where that subagent stands.
     doc;
     patterns; // path globs (isPathExcluded semantics); [] = matches any changed file (always runs)
-    constructor(id, subagent, doc, patterns) {
+    /**
+     * true  — BLOCKING. `wp-finish-upsert-pr` refuses the PR until this checklist has a passing verdict.
+     * false — OPTIONAL. When it matches, stage ② OFFERS it: the AI asks the human which optional reviewers
+     *         to run, and the human may decline every one of them. A declined optional checklist never
+     *         blocks.
+     *
+     * This governs whether the reviewer must RUN — NOT whether its verdict counts. An optional reviewer
+     * that is actually spawned and comes back red blocks finish exactly like a required one; otherwise
+     * running it would be theater.
+     *
+     * There is deliberately NO default (see the validator): a review process is the last thing that should
+     * acquire a scope silently, in either direction. Defaulting to true would leave the all-blocking status
+     * quo in place for anyone who did not read the release note; defaulting to false would quietly
+     * DOWNGRADE every existing consumer's gate on upgrade. Both are worse than one mechanical config edit
+     * that the coding agent reading the error applies in a single pass.
+     */
+    required;
+    // eslint-disable-next-line @typescript-eslint/max-params
+    constructor(id, subagent, doc, patterns, required) {
         this.id = id;
         this.subagent = subagent;
         this.doc = doc;
         this.patterns = patterns;
+        this.required = required;
     }
 }
 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).
+ *
+ * `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.
  */
 // 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 ?? []);
+    return new ChecklistDefinition(subagent, subagent, 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":";;;AA0CA,kCAGC;AAID,sDAIC;AAYD,wCAIC;;AArED,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;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;AAfD,kDAeC;AASD;;;GAGG;AACH,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,qBAAqB,CAAC,GAAG,CAAC,GAAG,IAAI,EAAE,CAAC,EAAE,GAAG,CAAC,QAAQ,IAAI,EAAE,CAAC,CAAC;AACjH,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    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 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).\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(subagent, subagent, normalizeChecklistDoc(raw.doc ?? ''), raw.patterns ?? []);\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":";;;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"]}

package/src/cli-args.d.ts

@@ -1,11 +1,35 @@
 /**
- * Usage descriptor for a `wp-*` bin. Data-only (classes-over-interfaces): a command name and its
- * one-line summary. `CliArgs.classify` turns it into the `--help` / unknown-arg message.
+ * One optional `--flag` a command accepts. Data-only. The description is printed in `--help`, so it is
+ * written for the reader who has to DECIDE whether to pass it, not as a restatement of the name.
+ */
+export declare class CliFlag {
+    name: string;
+    description: string;
+    constructor(name: string, description: string);
+}
+/**
+ * Usage descriptor for a `wp-*` bin. Data-only (classes-over-interfaces): a command name, its one-line
+ * summary, and the flags it accepts. `CliArgs.classify` turns it into the `--help` / unknown-arg message.
+ *
+ * `flags` defaults to [] — the no-argument case stays a two-arg construction, which is what eight of the
+ * nine `wp-*` bins are. A flag a command does not DECLARE here is still rejected with exit 2: that guard is
+ * the reason this class exists (`wp-start-upsert-pr --help` once launched a squash-merge), and making it
+ * flag-aware must not soften it.
  */
 export declare class CliUsage {
     command: string;
     summary: string;
-    constructor(command: string, summary: string);
+    flags: CliFlag[];
+    constructor(command: string, summary: string, flags?: CliFlag[]);
+}
+/**
+ * Which declared flags argv actually carried. Data-only (a class, per CLAUDE.md), with a `has()` accessor
+ * so every consumer asks the question the same way instead of open-coding `includes` against a raw array.
+ */
+export declare class CliArgSet {
+    present: string[];
+    constructor(present?: string[]);
+    has(flag: string): boolean;
 }
 /**
  * Data-only outcome of checking argv against a no-argument command. `ok` true → run normally; else
@@ -22,11 +46,20 @@ export declare class CliArgsCheck {
 export declare class CliArgs {
     private usageText;
     /**
-     * Pure argv classifier for a no-argument command. No args → ok. `--help`/`-h` → not-ok, exit 0
-     * with the usage block. Anything else → not-ok, exit 2 naming the offending token(s). Split out
-     * from `assertNoArgs` so the decision is unit-testable without a thrown exception.
+     * Pure argv classifier. No args → ok. `--help`/`-h` → not-ok, exit 0 with the usage block. Any token
+     * the command did not DECLARE → not-ok, exit 2 naming the offending one(s). Split out from
+     * `assertNoArgs`/`parse` so the decision is unit-testable without a thrown exception.
+     *
+     * An undeclared token is still fatal even for a command that accepts flags — a mistyped `--no-optionl`
+     * must never be silently ignored and then run the flow WITH the reviews the caller meant to skip.
      */
     classify(args: string[], usage: CliUsage): CliArgsCheck;
+    /**
+     * The flag-accepting sibling of {@link assertNoArgs}: same guard, but it RETURNS which declared flags
+     * were passed. Call it in exactly the same place — first thing inside `runMain`, before the app touches
+     * git.
+     */
+    parse(usage: CliUsage): CliArgSet;
     /**
      * Call it as the FIRST thing inside `runMain`, BEFORE the app touches git — a bogus flag must
      * never start a mutation flow (the `wp-start-upsert-pr --help` incident: an ignored flag silently

package/src/cli-args.js

@@ -1,22 +1,56 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.CliArgs = exports.CliArgsCheck = exports.CliUsage = void 0;
+exports.CliArgs = exports.CliArgsCheck = exports.CliArgSet = exports.CliUsage = exports.CliFlag = void 0;
 const tslib_1 = require("tslib");
 const inversify_1 = require("inversify");
 const cli_exit_error_1 = require("./cli-exit-error");
 /**
- * Usage descriptor for a `wp-*` bin. Data-only (classes-over-interfaces): a command name and its
- * one-line summary. `CliArgs.classify` turns it into the `--help` / unknown-arg message.
+ * One optional `--flag` a command accepts. Data-only. The description is printed in `--help`, so it is
+ * written for the reader who has to DECIDE whether to pass it, not as a restatement of the name.
+ */
+class CliFlag {
+    name; // including the leading dashes, e.g. '--no-optional'
+    description;
+    constructor(name, description) {
+        this.name = name;
+        this.description = description;
+    }
+}
+exports.CliFlag = CliFlag;
+/**
+ * Usage descriptor for a `wp-*` bin. Data-only (classes-over-interfaces): a command name, its one-line
+ * summary, and the flags it accepts. `CliArgs.classify` turns it into the `--help` / unknown-arg message.
+ *
+ * `flags` defaults to [] — the no-argument case stays a two-arg construction, which is what eight of the
+ * nine `wp-*` bins are. A flag a command does not DECLARE here is still rejected with exit 2: that guard is
+ * the reason this class exists (`wp-start-upsert-pr --help` once launched a squash-merge), and making it
+ * flag-aware must not soften it.
  */
 class CliUsage {
     command;
     summary;
-    constructor(command, summary) {
+    flags;
+    constructor(command, summary, flags = []) {
         this.command = command;
         this.summary = summary;
+        this.flags = flags;
     }
 }
 exports.CliUsage = CliUsage;
+/**
+ * Which declared flags argv actually carried. Data-only (a class, per CLAUDE.md), with a `has()` accessor
+ * so every consumer asks the question the same way instead of open-coding `includes` against a raw array.
+ */
+class CliArgSet {
+    present;
+    constructor(present = []) {
+        this.present = present;
+    }
+    has(flag) {
+        return this.present.includes(flag);
+    }
+}
+exports.CliArgSet = CliArgSet;
 /**
  * Data-only outcome of checking argv against a no-argument command. `ok` true → run normally; else
  * `exitCode`/`message` are what the bin should exit with (help = 0, unknown arg = 2). Kept a pure
@@ -35,17 +69,24 @@ class CliArgsCheck {
 exports.CliArgsCheck = CliArgsCheck;
 /** Argument guard for the no-argument `wp-*` bins. */
 let CliArgs = class CliArgs {
-    // The help/usage block shown for `--help` and appended to an unknown-arg error. These commands
-    // take NO arguments, so that fact is the whole "usage".
+    // The help/usage block shown for `--help` and appended to an unknown-arg error. A command with no
+    // declared flags says so outright, because "takes no arguments" is the whole usage for eight of nine.
     usageText(usage) {
-        return (`${usage.command} — ${usage.summary}\n\n` +
-            `Usage:  pnpm ${usage.command}\n` +
-            `This command takes no arguments.`);
+        const head = `${usage.command} — ${usage.summary}\n\n`;
+        if (usage.flags.length === 0) {
+            return head + `Usage:  pnpm ${usage.command}\nThis command takes no arguments.`;
+        }
+        const width = Math.max(...usage.flags.map((f) => f.name.length));
+        const rows = usage.flags.map((f) => `  ${f.name.padEnd(width)}  ${f.description}`);
+        return head + `Usage:  pnpm ${usage.command} [flags]\n\nFlags:\n${rows.join('\n')}`;
     }
     /**
-     * Pure argv classifier for a no-argument command. No args → ok. `--help`/`-h` → not-ok, exit 0
-     * with the usage block. Anything else → not-ok, exit 2 naming the offending token(s). Split out
-     * from `assertNoArgs` so the decision is unit-testable without a thrown exception.
+     * Pure argv classifier. No args → ok. `--help`/`-h` → not-ok, exit 0 with the usage block. Any token
+     * the command did not DECLARE → not-ok, exit 2 naming the offending one(s). Split out from
+     * `assertNoArgs`/`parse` so the decision is unit-testable without a thrown exception.
+     *
+     * An undeclared token is still fatal even for a command that accepts flags — a mistyped `--no-optionl`
+     * must never be silently ignored and then run the flow WITH the reviews the caller meant to skip.
      */
     classify(args, usage) {
         if (args.length === 0)
@@ -53,7 +94,25 @@ let CliArgs = class CliArgs {
         if (args.includes('--help') || args.includes('-h')) {
             return new CliArgsCheck(false, 0, this.usageText(usage));
         }
-        return new CliArgsCheck(false, 2, `❌ Unknown argument(s): ${args.join(' ')}\n\n` + this.usageText(usage));
+        const declared = new Set(usage.flags.map((f) => f.name));
+        const unknown = args.filter((a) => !declared.has(a));
+        if (unknown.length > 0) {
+            return new CliArgsCheck(false, 2, `❌ Unknown argument(s): ${unknown.join(' ')}\n\n` + this.usageText(usage));
+        }
+        return new CliArgsCheck(true, 0, '');
+    }
+    /**
+     * The flag-accepting sibling of {@link assertNoArgs}: same guard, but it RETURNS which declared flags
+     * were passed. Call it in exactly the same place — first thing inside `runMain`, before the app touches
+     * git.
+     */
+    parse(usage) {
+        const args = process.argv.slice(2);
+        const check = this.classify(args, usage);
+        if (!check.ok)
+            throw new cli_exit_error_1.CliExitError(check.exitCode, check.message);
+        const declared = new Set(usage.flags.map((f) => f.name));
+        return new CliArgSet(args.filter((a) => declared.has(a)));
     }
     /**
      * Call it as the FIRST thing inside `runMain`, BEFORE the app touches git — a bogus flag must

package/src/cli-args.js.map

@@ -1 +1 @@
-{"version":3,"file":"cli-args.js","sourceRoot":"","sources":["../../../../../packages/tooling/rules-config/src/cli-args.ts"],"names":[],"mappings":";;;;AAAA,yCAA2D;AAC3D,qDAAgD;AAEhD;;;GAGG;AACH,MAAa,QAAQ;IACjB,OAAO,CAAS;IAChB,OAAO,CAAS;IAEhB,YAAY,OAAe,EAAE,OAAe;QACxC,IAAI,CAAC,OAAO,GAAG,OAAO,CAAC;QACvB,IAAI,CAAC,OAAO,GAAG,OAAO,CAAC;IAC3B,CAAC;CACJ;AARD,4BAQC;AAED;;;;GAIG;AACH,MAAa,YAAY;IACrB,EAAE,CAAU;IACZ,QAAQ,CAAS;IACjB,OAAO,CAAS;IAEhB,YAAY,EAAW,EAAE,QAAgB,EAAE,OAAe;QACtD,IAAI,CAAC,EAAE,GAAG,EAAE,CAAC;QACb,IAAI,CAAC,QAAQ,GAAG,QAAQ,CAAC;QACzB,IAAI,CAAC,OAAO,GAAG,OAAO,CAAC;IAC3B,CAAC;CACJ;AAVD,oCAUC;AAED,sDAAsD;AAE/C,IAAM,OAAO,GAAb,MAAM,OAAO;IAChB,+FAA+F;IAC/F,wDAAwD;IAChD,SAAS,CAAC,KAAe;QAC7B,OAAO,CACH,GAAG,KAAK,CAAC,OAAO,MAAM,KAAK,CAAC,OAAO,MAAM;YACzC,gBAAgB,KAAK,CAAC,OAAO,IAAI;YACjC,kCAAkC,CACrC,CAAC;IACN,CAAC;IAED;;;;OAIG;IACH,QAAQ,CAAC,IAAc,EAAE,KAAe;QACpC,IAAI,IAAI,CAAC,MAAM,KAAK,CAAC;YAAE,OAAO,IAAI,YAAY,CAAC,IAAI,EAAE,CAAC,EAAE,EAAE,CAAC,CAAC;QAC5D,IAAI,IAAI,CAAC,QAAQ,CAAC,QAAQ,CAAC,IAAI,IAAI,CAAC,QAAQ,CAAC,IAAI,CAAC,EAAE,CAAC;YACjD,OAAO,IAAI,YAAY,CAAC,KAAK,EAAE,CAAC,EAAE,IAAI,CAAC,SAAS,CAAC,KAAK,CAAC,CAAC,CAAC;QAC7D,CAAC;QACD,OAAO,IAAI,YAAY,CAAC,KAAK,EAAE,CAAC,EAAE,0BAA0B,IAAI,CAAC,IAAI,CAAC,GAAG,CAAC,MAAM,GAAG,IAAI,CAAC,SAAS,CAAC,KAAK,CAAC,CAAC,CAAC;IAC9G,CAAC;IAED;;;;;;;;OAQG;IACH,YAAY,CAAC,KAAe;QACxB,MAAM,KAAK,GAAG,IAAI,CAAC,QAAQ,CAAC,OAAO,CAAC,IAAI,CAAC,KAAK,CAAC,CAAC,CAAC,EAAE,KAAK,CAAC,CAAC;QAC1D,IAAI,KAAK,CAAC,EAAE;YAAE,OAAO;QACrB,MAAM,IAAI,6BAAY,CAAC,KAAK,CAAC,QAAQ,EAAE,KAAK,CAAC,OAAO,CAAC,CAAC;IAC1D,CAAC;CACJ,CAAA;AAtCY,0BAAO;kBAAP,OAAO;IADnB,IAAA,sBAAU,EAAC,8BAAkB,CAAC,SAAS,CAAC;GAC5B,OAAO,CAsCnB","sourcesContent":["import { injectable, bindingScopeValues } from 'inversify';\nimport { CliExitError } from './cli-exit-error';\n\n/**\n * Usage descriptor for a `wp-*` bin. Data-only (classes-over-interfaces): a command name and its\n * one-line summary. `CliArgs.classify` turns it into the `--help` / unknown-arg message.\n */\nexport class CliUsage {\n    command: string;\n    summary: string;\n\n    constructor(command: string, summary: string) {\n        this.command = command;\n        this.summary = summary;\n    }\n}\n\n/**\n * Data-only outcome of checking argv against a no-argument command. `ok` true → run normally; else\n * `exitCode`/`message` are what the bin should exit with (help = 0, unknown arg = 2). Kept a pure\n * value so it can be asserted directly in tests without provoking a throw.\n */\nexport class CliArgsCheck {\n    ok: boolean;\n    exitCode: number;\n    message: string;\n\n    constructor(ok: boolean, exitCode: number, message: string) {\n        this.ok = ok;\n        this.exitCode = exitCode;\n        this.message = message;\n    }\n}\n\n/** Argument guard for the no-argument `wp-*` bins. */\n@injectable(bindingScopeValues.Singleton)\nexport class CliArgs {\n    // The help/usage block shown for `--help` and appended to an unknown-arg error. These commands\n    // take NO arguments, so that fact is the whole \"usage\".\n    private usageText(usage: CliUsage): string {\n        return (\n            `${usage.command} — ${usage.summary}\\n\\n` +\n            `Usage:  pnpm ${usage.command}\\n` +\n            `This command takes no arguments.`\n        );\n    }\n\n    /**\n     * Pure argv classifier for a no-argument command. No args → ok. `--help`/`-h` → not-ok, exit 0\n     * with the usage block. Anything else → not-ok, exit 2 naming the offending token(s). Split out\n     * from `assertNoArgs` so the decision is unit-testable without a thrown exception.\n     */\n    classify(args: string[], usage: CliUsage): CliArgsCheck {\n        if (args.length === 0) return new CliArgsCheck(true, 0, '');\n        if (args.includes('--help') || args.includes('-h')) {\n            return new CliArgsCheck(false, 0, this.usageText(usage));\n        }\n        return new CliArgsCheck(false, 2, `❌ Unknown argument(s): ${args.join(' ')}\\n\\n` + this.usageText(usage));\n    }\n\n    /**\n     * Call it as the FIRST thing inside `runMain`, BEFORE the app touches git — a bogus flag must\n     * never start a mutation flow (the `wp-start-upsert-pr --help` incident: an ignored flag silently\n     * launched the squash-merge and stranded the checkout on a `…PreMerge<n>` branch).\n     *\n     * Throws `CliExitError` (never `process.exit`) so `runMain` stays the single sanctioned exit site\n     * (`no-process-exit-outside-main`): help exits 0, an unknown arg exits 2, and in both cases the\n     * flow never begins.\n     */\n    assertNoArgs(usage: CliUsage): void {\n        const check = this.classify(process.argv.slice(2), usage);\n        if (check.ok) return;\n        throw new CliExitError(check.exitCode, check.message);\n    }\n}\n"]}
+{"version":3,"file":"cli-args.js","sourceRoot":"","sources":["../../../../../packages/tooling/rules-config/src/cli-args.ts"],"names":[],"mappings":"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","sourcesContent":["import { injectable, bindingScopeValues } from 'inversify';\nimport { CliExitError } from './cli-exit-error';\n\n/**\n * One optional `--flag` a command accepts. Data-only. The description is printed in `--help`, so it is\n * written for the reader who has to DECIDE whether to pass it, not as a restatement of the name.\n */\nexport class CliFlag {\n    name: string;        // including the leading dashes, e.g. '--no-optional'\n    description: string;\n\n    constructor(name: string, description: string) {\n        this.name = name;\n        this.description = description;\n    }\n}\n\n/**\n * Usage descriptor for a `wp-*` bin. Data-only (classes-over-interfaces): a command name, its one-line\n * summary, and the flags it accepts. `CliArgs.classify` turns it into the `--help` / unknown-arg message.\n *\n * `flags` defaults to [] — the no-argument case stays a two-arg construction, which is what eight of the\n * nine `wp-*` bins are. A flag a command does not DECLARE here is still rejected with exit 2: that guard is\n * the reason this class exists (`wp-start-upsert-pr --help` once launched a squash-merge), and making it\n * flag-aware must not soften it.\n */\nexport class CliUsage {\n    command: string;\n    summary: string;\n    flags: CliFlag[];\n\n    constructor(command: string, summary: string, flags: CliFlag[] = []) {\n        this.command = command;\n        this.summary = summary;\n        this.flags = flags;\n    }\n}\n\n/**\n * Which declared flags argv actually carried. Data-only (a class, per CLAUDE.md), with a `has()` accessor\n * so every consumer asks the question the same way instead of open-coding `includes` against a raw array.\n */\nexport class CliArgSet {\n    present: string[];\n\n    constructor(present: string[] = []) {\n        this.present = present;\n    }\n\n    has(flag: string): boolean {\n        return this.present.includes(flag);\n    }\n}\n\n/**\n * Data-only outcome of checking argv against a no-argument command. `ok` true → run normally; else\n * `exitCode`/`message` are what the bin should exit with (help = 0, unknown arg = 2). Kept a pure\n * value so it can be asserted directly in tests without provoking a throw.\n */\nexport class CliArgsCheck {\n    ok: boolean;\n    exitCode: number;\n    message: string;\n\n    constructor(ok: boolean, exitCode: number, message: string) {\n        this.ok = ok;\n        this.exitCode = exitCode;\n        this.message = message;\n    }\n}\n\n/** Argument guard for the no-argument `wp-*` bins. */\n@injectable(bindingScopeValues.Singleton)\nexport class CliArgs {\n    // The help/usage block shown for `--help` and appended to an unknown-arg error. A command with no\n    // declared flags says so outright, because \"takes no arguments\" is the whole usage for eight of nine.\n    private usageText(usage: CliUsage): string {\n        const head = `${usage.command} — ${usage.summary}\\n\\n`;\n        if (usage.flags.length === 0) {\n            return head + `Usage:  pnpm ${usage.command}\\nThis command takes no arguments.`;\n        }\n        const width = Math.max(...usage.flags.map((f: CliFlag): number => f.name.length));\n        const rows = usage.flags.map((f: CliFlag): string => `  ${f.name.padEnd(width)}  ${f.description}`);\n        return head + `Usage:  pnpm ${usage.command} [flags]\\n\\nFlags:\\n${rows.join('\\n')}`;\n    }\n\n    /**\n     * Pure argv classifier. No args → ok. `--help`/`-h` → not-ok, exit 0 with the usage block. Any token\n     * the command did not DECLARE → not-ok, exit 2 naming the offending one(s). Split out from\n     * `assertNoArgs`/`parse` so the decision is unit-testable without a thrown exception.\n     *\n     * An undeclared token is still fatal even for a command that accepts flags — a mistyped `--no-optionl`\n     * must never be silently ignored and then run the flow WITH the reviews the caller meant to skip.\n     */\n    classify(args: string[], usage: CliUsage): CliArgsCheck {\n        if (args.length === 0) return new CliArgsCheck(true, 0, '');\n        if (args.includes('--help') || args.includes('-h')) {\n            return new CliArgsCheck(false, 0, this.usageText(usage));\n        }\n        const declared = new Set(usage.flags.map((f: CliFlag): string => f.name));\n        const unknown = args.filter((a: string): boolean => !declared.has(a));\n        if (unknown.length > 0) {\n            return new CliArgsCheck(false, 2, `❌ Unknown argument(s): ${unknown.join(' ')}\\n\\n` + this.usageText(usage));\n        }\n        return new CliArgsCheck(true, 0, '');\n    }\n\n    /**\n     * The flag-accepting sibling of {@link assertNoArgs}: same guard, but it RETURNS which declared flags\n     * were passed. Call it in exactly the same place — first thing inside `runMain`, before the app touches\n     * git.\n     */\n    parse(usage: CliUsage): CliArgSet {\n        const args = process.argv.slice(2);\n        const check = this.classify(args, usage);\n        if (!check.ok) throw new CliExitError(check.exitCode, check.message);\n        const declared = new Set(usage.flags.map((f: CliFlag): string => f.name));\n        return new CliArgSet(args.filter((a: string): boolean => declared.has(a)));\n    }\n\n    /**\n     * Call it as the FIRST thing inside `runMain`, BEFORE the app touches git — a bogus flag must\n     * never start a mutation flow (the `wp-start-upsert-pr --help` incident: an ignored flag silently\n     * launched the squash-merge and stranded the checkout on a `…PreMerge<n>` branch).\n     *\n     * Throws `CliExitError` (never `process.exit`) so `runMain` stays the single sanctioned exit site\n     * (`no-process-exit-outside-main`): help exits 0, an unknown arg exits 2, and in both cases the\n     * flow never begins.\n     */\n    assertNoArgs(usage: CliUsage): void {\n        const check = this.classify(process.argv.slice(2), usage);\n        if (check.ok) return;\n        throw new CliExitError(check.exitCode, check.message);\n    }\n}\n"]}

package/src/index.d.ts

@@ -2,7 +2,7 @@ export { ResolvedConfig, ResolvedRuleConfig, RuleOptions } from './types';
 export { InformAiError } from './inform-ai-error';
 export { RuleFailError } from './rule-fail-error';
 export { CliExitError } from './cli-exit-error';
-export { CliUsage, CliArgsCheck, CliArgs } from './cli-args';
+export { CliUsage, CliFlag, CliArgSet, CliArgsCheck, CliArgs } from './cli-args';
 export { runMain } from './run-main';
 export { toError } from './to-error';
 export { loadAndValidate, LoadedConfig, ConfigLoader } from './load-config';

package/src/index.js

@@ -1,12 +1,12 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.loadTemplate = exports.defaultRulesDir = exports.defaultRules = exports.matchesAnyGlob = exports.isPathExcluded = exports.ExcludePaths = exports.DESIGN_METADATA_KEYS = exports.isDocumentDesign = exports.DocumentDesign = exports.RulesConfigDesign = exports.atRoot = exports.AtomicFile = exports.CLAUDE_PROJECT_DIR_UNSET = exports.CLAUDE_PROJECT_DIR_ENV = exports.claudeEnv = exports.ClaudeEnv = exports.StateMigrationReport = exports.StateDirMigrator = exports.HOOKS_STATE_DIR = exports.LOGS_STATE_DIR = exports.WORKTREE_STATE_DIR = exports.GitDirs = exports.dotWebpieces = exports.DotWebpieces = exports.INSTRUCT_AI_LEAF = exports.INSTRUCT_AI_DIR = exports.RepoRootFinder = exports.CONFIG_PARSE_RETRY_MILLIS = exports.CONFIG_PARSE_ATTEMPTS = exports.ConfigParseAttempt = exports.ConfigFile = exports.CONFIG_FILENAME = exports.findConfigFile = exports.SECTION_PLACEMENT_MARKER = exports.RETIRED_TOP_LEVEL_MARKER = exports.RETIRED_KEY_MARKER = exports.formatConfigErrorsBanner = exports.ConfigLoader = exports.LoadedConfig = exports.loadAndValidate = exports.toError = exports.runMain = exports.CliArgs = exports.CliArgsCheck = exports.CliUsage = exports.CliExitError = exports.RuleFailError = exports.InformAiError = exports.ResolvedRuleConfig = exports.ResolvedConfig = void 0;
-exports.DiffScope = exports.isNewOrModified = exports.hasChangesInRange = exports.findNewMethodSignaturesInDiff = exports.getChangedLineNumbers = exports.getFileDiff = exports.getChangedFiles = exports.resolveBase = exports.detectBase = exports.getCurrentBranch = exports.shouldSkipRule = exports.FieldDef = exports.sectionForRule = exports.isHookGuard = exports.HOOK_GUARD_NAMES = exports.DEFAULT_MATCH_RULES = exports.renderMatchRuleMessage = exports.compileMatchRulePatterns = exports.isMatchRuleAllowedPath = exports.findMatchRuleViolations = exports.MatchRuleViolation = exports.MatchRuleConfig = exports.validateChecklistDocs = exports.retiredRuleFor = exports.retiredKeyErrorsIn = exports.retiredKeyError = exports.retiredEntry = exports.isRetiredKey = exports.RetiredConfigKey = exports.RETIRED_SCOPE_RULE = exports.RETIRED_SCOPE_KEY = exports.RETIRED_CONFIG_KEYS = exports.COMMENT_KEY_SUFFIX = exports.validateTopLevelKeys = exports.isCommentKey = exports.unknownKeyErrors = exports.validateCommandsSection = exports.seedEntryForRule = exports.recommendedSeedModeFor = exports.recommendedSeedMode = exports.allRuleNames = exports.validateMatchRulesSection = exports.validateExcludePaths = exports.validateSectionPlacement = exports.validateChecklistsSection = exports.validatePrGateSection = exports.validateWebpiecesConfig = exports.TemplateWriter = exports.writeTemplate = exports.writeTemplateIfMissing = void 0;
-exports.ValidateNoArchitectureCyclesConfig = exports.ValidateArchitectureUnchangedConfig = exports.ValidateTsInSrcConfig = exports.NoJsFilesConfig = exports.DiGraphConfig = exports.NxWiringConfig = exports.RuntimeArchitectureConfig = exports.NoFileImportCyclesConfig = exports.RedirectHowToMergeMainConfig = exports.PrMergeGuardConfig = exports.MergeInProgressGuardConfig = exports.PrCreationOrPushGuardConfig = exports.BranchCreationGuardConfig = exports.RoleTagConfig = exports.FrameworkTagConfig = exports.InjectAnnotationNotNeededForConcreteClassConfig = exports.NoFunctionOutsideClassConfig = exports.NoProcessExitOutsideMainConfig = exports.NoCustomCssConfig = exports.NoSymbolDiTokensConfig = exports.AngularNoDirectApiInResolverConfig = exports.ThrowCauseRequiredConfig = exports.CatchErrorPatternConfig = exports.NoUnmanagedExceptionsConfig = exports.NoDestructureConfig = exports.PrismaConverterConfig = exports.PrismaValidateDtosConfig = exports.NoImplicitAnyConfig = exports.NoAnyUnknownConfig = exports.NoInlineTypeLiteralsConfig = exports.RequireReturnTypeConfig = exports.MaxFileLinesConfig = exports.MaxMethodLinesConfig = exports.WP_FINISH_UPSERT_PR = exports.WP_START_UPSERT_PR = exports.WP_FINISH_UPDATE = exports.WP_START_UPDATE = exports.SyncFlowGuidance = exports.WebpiecesRulesConfig = exports.MERGE_EXPLANATION_FILE = exports.MERGE_IN_PROGRESS_FILE = exports.PR_REVIEW_DIR = exports.MERGE_INFO_DIR = exports.WEBPIECES_TMP_DIR = exports.hasDisable = exports.RULE_NAMES = exports.WEBPIECES_DISABLE = exports.AbstractRule = exports.ChangedFilesOptions = exports.DiffRange = void 0;
-exports.gateTokenMarker = exports.computeGateToken = exports.GateTokenService = exports.ALL_DIFF_ONE_READ_LINES = exports.READ_TRUNCATION_LINES = exports.ContextEntry = exports.BriefedFile = exports.ReviewerBriefing = exports.ReviewerInstructionsService = exports.ChecklistInstructionsService = exports.ChecklistValidator = exports.formatFileList = exports.normalizeChecklistDoc = exports.toChecklist = exports.ChecklistDefinition = exports.MERGE_MODES = exports.MERGE_MODE_NONE = exports.MERGE_MODE_AUTO = exports.buildLandPrConfig = exports.buildPrGateConfig = exports.defaultLandPrConfig = exports.defaultPrGateConfig = exports.defaultGates = exports.ReviewContextEntry = exports.LandPrConfig = exports.PrGateConfig = exports.GateDefinition = exports.StaleMainBashGuardConfig = exports.MergedBranchBashGuardConfig = exports.ReadStaleGuardConfig = exports.FeatureBranchGuardConfig = exports.CLIENT_CREATION_SEVERITIES = exports.NoClientCreationOutsideServerOrClientConfig = exports.VALIDATE_TS_MODES = exports.STRUCTURAL_MODES = exports.ON_OFF_MODES = exports.THROW_CAUSE_MODES = exports.DIRECT_API_RESOLVER_MODES = exports.PRISMA_CONVERTER_MODES = exports.PRISMA_DTOS_MODES = exports.PROJECT_MODES = exports.MODIFIED_CODE_MODES = exports.INLINE_TYPE_MODES = exports.RETURN_TYPE_MODES = exports.FILE_LIMIT_MODES = exports.METHOD_LIMIT_MODES = exports.BaseRuleConfig = exports.ValidateEslintSyncConfig = exports.ValidateVersionsLockedConfig = exports.ValidatePackageJsonConfig = void 0;
-exports.readMainSyncStatusFile = exports.readMainSyncStatus = exports.mainSyncLockPath = exports.mainSyncStatusPath = exports.DEFAULT_HANG_TIMEOUT_MINUTES = exports.MainSyncStatusService = exports.MainSyncLock = exports.MAIN_SYNC_STATUS_VERSION = exports.PullRequestIndex = exports.MainSyncFileStore = exports.MainSyncStatusFile = exports.MainSyncStatus = exports.reviewJsonSchemaHint = exports.reviewJsonPath = exports.prDirFor = exports.loadReviewJson = exports.ReviewJsonService = exports.ChecklistReviewContext = exports.RequiredChecklist = exports.VERDICT_STATUSES = exports.VERDICT_RED = exports.VERDICT_YELLOW = exports.VERDICT_GREEN = exports.CK_BAD_FORMAT = exports.CK_MISSING = exports.CK_FAIL = exports.CK_OVERRIDDEN = exports.CK_WARN = exports.CK_PASS = exports.ChecklistVerdict = exports.ChecklistResult = exports.PrContext = exports.ReviewJson = exports.DEFAULT_RETENTION_DAYS = exports.ProvenanceWriteRequest = exports.OfferedContext = exports.ReviewerPaths = exports.ReviewerTranscript = exports.ReviewProvenance = exports.ReviewProvenanceService = exports.PROVENANCE_SKIPPED = exports.PROVENANCE_MISSING = exports.PROVENANCE_OK = exports.ProvenanceResult = exports.TranscriptScan = exports.EvidenceRequest = exports.ReviewerEvidence = exports.SubagentProvenanceService = exports.verifyGateToken = exports.extractGateToken = void 0;
-exports.BranchMutationLog = exports.BranchMutationEvent = exports.WorktreeReaper = exports.WorktreeReapResult = exports.ReapedWorktree = exports.BranchReaper = exports.ReapResult = exports.ReapedBranch = exports.WorktreeService = exports.Worktree = exports.BRANCH_RETENTION_KEEP = exports.BRANCH_RETENTION_ARCHIVE_TAG = exports.BRANCH_RETENTION_DELETE = exports.BRANCH_RETENTIONS = exports.ARCHIVE_TAG_PREFIX = exports.ArchiveResult = exports.BranchArchiver = exports.PROMPTABLE_CLASSIFICATIONS = exports.CLASSIFICATION_DETACHED = exports.CLASSIFICATION_CURRENT = exports.CLASSIFICATION_LOCKED = exports.CLASSIFICATION_PRUNABLE = exports.CLASSIFICATION_IN_USE = exports.CLASSIFICATION_NEVER_PROPOSED = exports.CLASSIFICATION_CONTENT_IN_MAIN = exports.CLASSIFICATION_SUPERSEDED = exports.CLASSIFICATION_NO_COMMITS = exports.CLASSIFICATION_BACKUP_OF_LIVE = exports.CLASSIFICATION_BACKUP_OF_MERGED = exports.CLASSIFICATION_MERGED_PR = exports.CACHE_STALE_AFTER_MS = exports.CacheFreshness = exports.MergedBranchesService = exports.MergedBranchesCache = exports.DeletableWorktree = exports.DeletableBranch = exports.MergedBranch = exports.squashRecoverySteps = exports.stampCleanMainSyncStatus = exports.computeMainSyncStatus = exports.finishedLock = exports.inProcessLock = exports.tryAcquireMainSyncLock = exports.isRefreshInProgress = exports.isLockStale = exports.writeMainSyncLock = exports.readMainSyncLock = exports.computeAllMainSyncStatuses = exports.writeMainSyncStatusFile = exports.writeMainSyncStatus = void 0;
-exports.DEFAULT_MERGE_COMPLETE_COMMAND = exports.DEFAULT_UPSERT_PR_COMMAND = exports.buildCommandsConfig = exports.CommandsConfig = exports.logBranchMutation = exports.branchMutationLogPath = void 0;
+exports.defaultRules = exports.matchesAnyGlob = exports.isPathExcluded = exports.ExcludePaths = exports.DESIGN_METADATA_KEYS = exports.isDocumentDesign = exports.DocumentDesign = exports.RulesConfigDesign = exports.atRoot = exports.AtomicFile = exports.CLAUDE_PROJECT_DIR_UNSET = exports.CLAUDE_PROJECT_DIR_ENV = exports.claudeEnv = exports.ClaudeEnv = exports.StateMigrationReport = exports.StateDirMigrator = exports.HOOKS_STATE_DIR = exports.LOGS_STATE_DIR = exports.WORKTREE_STATE_DIR = exports.GitDirs = exports.dotWebpieces = exports.DotWebpieces = exports.INSTRUCT_AI_LEAF = exports.INSTRUCT_AI_DIR = exports.RepoRootFinder = exports.CONFIG_PARSE_RETRY_MILLIS = exports.CONFIG_PARSE_ATTEMPTS = exports.ConfigParseAttempt = exports.ConfigFile = exports.CONFIG_FILENAME = exports.findConfigFile = exports.SECTION_PLACEMENT_MARKER = exports.RETIRED_TOP_LEVEL_MARKER = exports.RETIRED_KEY_MARKER = exports.formatConfigErrorsBanner = exports.ConfigLoader = exports.LoadedConfig = exports.loadAndValidate = exports.toError = exports.runMain = exports.CliArgs = exports.CliArgsCheck = exports.CliArgSet = exports.CliFlag = exports.CliUsage = exports.CliExitError = exports.RuleFailError = exports.InformAiError = exports.ResolvedRuleConfig = exports.ResolvedConfig = void 0;
+exports.hasChangesInRange = exports.findNewMethodSignaturesInDiff = exports.getChangedLineNumbers = exports.getFileDiff = exports.getChangedFiles = exports.resolveBase = exports.detectBase = exports.getCurrentBranch = exports.shouldSkipRule = exports.FieldDef = exports.sectionForRule = exports.isHookGuard = exports.HOOK_GUARD_NAMES = exports.DEFAULT_MATCH_RULES = exports.renderMatchRuleMessage = exports.compileMatchRulePatterns = exports.isMatchRuleAllowedPath = exports.findMatchRuleViolations = exports.MatchRuleViolation = exports.MatchRuleConfig = exports.validateChecklistDocs = exports.retiredRuleFor = exports.retiredKeyErrorsIn = exports.retiredKeyError = exports.retiredEntry = exports.isRetiredKey = exports.RetiredConfigKey = exports.RETIRED_SCOPE_RULE = exports.RETIRED_SCOPE_KEY = exports.RETIRED_CONFIG_KEYS = exports.COMMENT_KEY_SUFFIX = exports.validateTopLevelKeys = exports.isCommentKey = exports.unknownKeyErrors = exports.validateCommandsSection = exports.seedEntryForRule = exports.recommendedSeedModeFor = exports.recommendedSeedMode = exports.allRuleNames = exports.validateMatchRulesSection = exports.validateExcludePaths = exports.validateSectionPlacement = exports.validateChecklistsSection = exports.validatePrGateSection = exports.validateWebpiecesConfig = exports.TemplateWriter = exports.writeTemplate = exports.writeTemplateIfMissing = exports.loadTemplate = exports.defaultRulesDir = void 0;
+exports.ValidateTsInSrcConfig = exports.NoJsFilesConfig = exports.DiGraphConfig = exports.NxWiringConfig = exports.RuntimeArchitectureConfig = exports.NoFileImportCyclesConfig = exports.RedirectHowToMergeMainConfig = exports.PrMergeGuardConfig = exports.MergeInProgressGuardConfig = exports.PrCreationOrPushGuardConfig = exports.BranchCreationGuardConfig = exports.RoleTagConfig = exports.FrameworkTagConfig = exports.InjectAnnotationNotNeededForConcreteClassConfig = exports.NoFunctionOutsideClassConfig = exports.NoProcessExitOutsideMainConfig = exports.NoCustomCssConfig = exports.NoSymbolDiTokensConfig = exports.AngularNoDirectApiInResolverConfig = exports.ThrowCauseRequiredConfig = exports.CatchErrorPatternConfig = exports.NoUnmanagedExceptionsConfig = exports.NoDestructureConfig = exports.PrismaConverterConfig = exports.PrismaValidateDtosConfig = exports.NoImplicitAnyConfig = exports.NoAnyUnknownConfig = exports.NoInlineTypeLiteralsConfig = exports.RequireReturnTypeConfig = exports.MaxFileLinesConfig = exports.MaxMethodLinesConfig = exports.WP_FINISH_UPSERT_PR = exports.WP_START_UPSERT_PR = exports.WP_FINISH_UPDATE = exports.WP_START_UPDATE = exports.SyncFlowGuidance = exports.WebpiecesRulesConfig = exports.MERGE_EXPLANATION_FILE = exports.MERGE_IN_PROGRESS_FILE = exports.PR_REVIEW_DIR = exports.MERGE_INFO_DIR = exports.WEBPIECES_TMP_DIR = exports.hasDisable = exports.RULE_NAMES = exports.WEBPIECES_DISABLE = exports.AbstractRule = exports.ChangedFilesOptions = exports.DiffRange = exports.DiffScope = exports.isNewOrModified = void 0;
+exports.GateTokenService = exports.ALL_DIFF_ONE_READ_LINES = exports.READ_TRUNCATION_LINES = exports.ContextEntry = exports.BriefedFile = exports.ReviewerBriefing = exports.ReviewerInstructionsService = exports.ChecklistInstructionsService = exports.ChecklistValidator = exports.formatFileList = exports.normalizeChecklistDoc = exports.toChecklist = exports.ChecklistDefinition = exports.MERGE_MODES = exports.MERGE_MODE_NONE = exports.MERGE_MODE_AUTO = exports.buildLandPrConfig = exports.buildPrGateConfig = exports.defaultLandPrConfig = exports.defaultPrGateConfig = exports.defaultGates = exports.ReviewContextEntry = exports.LandPrConfig = exports.PrGateConfig = exports.GateDefinition = exports.StaleMainBashGuardConfig = exports.MergedBranchBashGuardConfig = exports.ReadStaleGuardConfig = exports.FeatureBranchGuardConfig = exports.CLIENT_CREATION_SEVERITIES = exports.NoClientCreationOutsideServerOrClientConfig = exports.VALIDATE_TS_MODES = exports.STRUCTURAL_MODES = exports.ON_OFF_MODES = exports.THROW_CAUSE_MODES = exports.DIRECT_API_RESOLVER_MODES = exports.PRISMA_CONVERTER_MODES = exports.PRISMA_DTOS_MODES = exports.PROJECT_MODES = exports.MODIFIED_CODE_MODES = exports.INLINE_TYPE_MODES = exports.RETURN_TYPE_MODES = exports.FILE_LIMIT_MODES = exports.METHOD_LIMIT_MODES = exports.BaseRuleConfig = exports.ValidateEslintSyncConfig = exports.ValidateVersionsLockedConfig = exports.ValidatePackageJsonConfig = exports.ValidateNoArchitectureCyclesConfig = exports.ValidateArchitectureUnchangedConfig = void 0;
+exports.mainSyncLockPath = exports.mainSyncStatusPath = exports.DEFAULT_HANG_TIMEOUT_MINUTES = exports.MainSyncStatusService = exports.MainSyncLock = exports.MAIN_SYNC_STATUS_VERSION = exports.PullRequestIndex = exports.MainSyncFileStore = exports.MainSyncStatusFile = exports.MainSyncStatus = exports.reviewJsonSchemaHint = exports.reviewJsonPath = exports.prDirFor = exports.loadReviewJson = exports.ReviewJsonService = exports.ChecklistReviewContext = exports.RequiredChecklist = exports.VERDICT_STATUSES = exports.VERDICT_RED = exports.VERDICT_YELLOW = exports.VERDICT_GREEN = exports.CK_BAD_FORMAT = exports.CK_MISSING = exports.CK_FAIL = exports.CK_OVERRIDDEN = exports.CK_WARN = exports.CK_PASS = exports.ChecklistVerdict = exports.ChecklistResult = exports.PrContext = exports.ReviewJson = exports.DEFAULT_RETENTION_DAYS = exports.ProvenanceWriteRequest = exports.OfferedContext = exports.ReviewerPaths = exports.ReviewerTranscript = exports.ReviewProvenance = exports.ReviewProvenanceService = exports.PROVENANCE_SKIPPED = exports.PROVENANCE_MISSING = exports.PROVENANCE_OK = exports.ProvenanceResult = exports.TranscriptScan = exports.EvidenceRequest = exports.ReviewerEvidence = exports.SubagentProvenanceService = exports.verifyGateToken = exports.extractGateToken = exports.gateTokenMarker = exports.computeGateToken = void 0;
+exports.WorktreeReaper = exports.WorktreeReapResult = exports.ReapedWorktree = exports.BranchReaper = exports.ReapResult = exports.ReapedBranch = exports.WorktreeService = exports.Worktree = exports.BRANCH_RETENTION_KEEP = exports.BRANCH_RETENTION_ARCHIVE_TAG = exports.BRANCH_RETENTION_DELETE = exports.BRANCH_RETENTIONS = exports.ARCHIVE_TAG_PREFIX = exports.ArchiveResult = exports.BranchArchiver = exports.PROMPTABLE_CLASSIFICATIONS = exports.CLASSIFICATION_DETACHED = exports.CLASSIFICATION_CURRENT = exports.CLASSIFICATION_LOCKED = exports.CLASSIFICATION_PRUNABLE = exports.CLASSIFICATION_IN_USE = exports.CLASSIFICATION_NEVER_PROPOSED = exports.CLASSIFICATION_CONTENT_IN_MAIN = exports.CLASSIFICATION_SUPERSEDED = exports.CLASSIFICATION_NO_COMMITS = exports.CLASSIFICATION_BACKUP_OF_LIVE = exports.CLASSIFICATION_BACKUP_OF_MERGED = exports.CLASSIFICATION_MERGED_PR = exports.CACHE_STALE_AFTER_MS = exports.CacheFreshness = exports.MergedBranchesService = exports.MergedBranchesCache = exports.DeletableWorktree = exports.DeletableBranch = exports.MergedBranch = exports.squashRecoverySteps = exports.stampCleanMainSyncStatus = exports.computeMainSyncStatus = exports.finishedLock = exports.inProcessLock = exports.tryAcquireMainSyncLock = exports.isRefreshInProgress = exports.isLockStale = exports.writeMainSyncLock = exports.readMainSyncLock = exports.computeAllMainSyncStatuses = exports.writeMainSyncStatusFile = exports.writeMainSyncStatus = exports.readMainSyncStatusFile = exports.readMainSyncStatus = void 0;
+exports.DEFAULT_MERGE_COMPLETE_COMMAND = exports.DEFAULT_UPSERT_PR_COMMAND = exports.buildCommandsConfig = exports.CommandsConfig = exports.logBranchMutation = exports.branchMutationLogPath = exports.BranchMutationLog = exports.BranchMutationEvent = void 0;
 var types_1 = require("./types");
 Object.defineProperty(exports, "ResolvedConfig", { enumerable: true, get: function () { return types_1.ResolvedConfig; } });
 Object.defineProperty(exports, "ResolvedRuleConfig", { enumerable: true, get: function () { return types_1.ResolvedRuleConfig; } });
@@ -18,6 +18,8 @@ var cli_exit_error_1 = require("./cli-exit-error");
 Object.defineProperty(exports, "CliExitError", { enumerable: true, get: function () { return cli_exit_error_1.CliExitError; } });
 var cli_args_1 = require("./cli-args");
 Object.defineProperty(exports, "CliUsage", { enumerable: true, get: function () { return cli_args_1.CliUsage; } });
+Object.defineProperty(exports, "CliFlag", { enumerable: true, get: function () { return cli_args_1.CliFlag; } });
+Object.defineProperty(exports, "CliArgSet", { enumerable: true, get: function () { return cli_args_1.CliArgSet; } });
 Object.defineProperty(exports, "CliArgsCheck", { enumerable: true, get: function () { return cli_args_1.CliArgsCheck; } });
 Object.defineProperty(exports, "CliArgs", { enumerable: true, get: function () { return cli_args_1.CliArgs; } });
 var run_main_1 = require("./run-main");

package/src/index.js.map

@@ -1 +1 @@
-{"version":3,"file":"index.js","sourceRoot":"","sources":["../../../../../packages/tooling/rules-config/src/index.ts"],"names":[],"mappings":"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","sourcesContent":["export { ResolvedConfig, ResolvedRuleConfig, RuleOptions } from './types';\nexport { InformAiError } from './inform-ai-error';\nexport { RuleFailError } from './rule-fail-error';\nexport { CliExitError } from './cli-exit-error';\nexport { CliUsage, CliArgsCheck, CliArgs } from './cli-args';\nexport { runMain } from './run-main';\nexport { toError } from './to-error';\nexport { loadAndValidate, LoadedConfig, ConfigLoader } from './load-config';\n// The validation-failure banner: ONE cure (edit the file), plus the marker phrases the validator\n// messages embed rather than re-type.\nexport {\n    formatConfigErrorsBanner,\n    RETIRED_KEY_MARKER,\n    RETIRED_TOP_LEVEL_MARKER,\n    SECTION_PLACEMENT_MARKER,\n} from './config-error-banner';\nexport { findConfigFile, CONFIG_FILENAME, ConfigFile, ConfigParseAttempt, CONFIG_PARSE_ATTEMPTS, CONFIG_PARSE_RETRY_MILLIS } from './config-file';\nexport { RepoRootFinder, INSTRUCT_AI_DIR, INSTRUCT_AI_LEAF } from './repo-root';\n// The scoped `.webpieces` resolver. EVERY reader/writer of `.webpieces/...` goes through one of its two\n// named methods so the call site declares whether the state is repo-wide or worktree-private.\nexport { DotWebpieces, dotWebpieces, GitDirs, WORKTREE_STATE_DIR, LOGS_STATE_DIR, HOOKS_STATE_DIR } from './state-dir';\nexport { StateDirMigrator, StateMigrationReport } from './state-dir-migration';\nexport { ClaudeEnv, claudeEnv, CLAUDE_PROJECT_DIR_ENV, CLAUDE_PROJECT_DIR_UNSET } from './claude-env';\nexport { AtomicFile } from './atomic-file';\n// The ONE formatter for a remedy that must run in a named directory: `cd '<root>' && <command>`.\n// Single-quoted so a repo path containing a space is still runnable (and still un-smuggleable).\nexport { atRoot } from './at-root';\nexport { RulesConfigDesign } from './rules-config-design';\nexport { DocumentDesign, isDocumentDesign, DESIGN_METADATA_KEYS } from './di';\nexport { ExcludePaths } from './exclude-hook-paths';\nexport { isPathExcluded, matchesAnyGlob } from './exclude-paths';\nexport { defaultRules, defaultRulesDir } from './default-rules';\nexport { loadTemplate, writeTemplateIfMissing, writeTemplate, TemplateWriter } from './load-template';\nexport { validateWebpiecesConfig, validatePrGateSection, validateChecklistsSection, validateSectionPlacement, validateExcludePaths, validateMatchRulesSection, allRuleNames, recommendedSeedMode, recommendedSeedModeFor, seedEntryForRule } from './validate-config';\nexport { validateCommandsSection } from './commands-section-validators';\nexport { unknownKeyErrors, isCommentKey, validateTopLevelKeys, COMMENT_KEY_SUFFIX } from './config-key-rules';\n// The retired-key table + the no-back-compat policy it enforces. Exported so the installer can migrate\n// what the errors instruct, and so consumers can enumerate retirements.\nexport { RETIRED_CONFIG_KEYS, RETIRED_SCOPE_KEY, RETIRED_SCOPE_RULE, RetiredConfigKey, isRetiredKey, retiredEntry, retiredKeyError, retiredKeyErrorsIn, retiredRuleFor } from './retired-config-keys';\nexport { validateChecklistDocs } from './checklist-docs-validator';\nexport {\n    MatchRuleConfig,\n    MatchRuleViolation,\n    findMatchRuleViolations,\n    isMatchRuleAllowedPath,\n    compileMatchRulePatterns,\n    renderMatchRuleMessage,\n    DEFAULT_MATCH_RULES,\n} from './match-rules-config';\nexport type { ConfigSection } from './sections';\nexport { HOOK_GUARD_NAMES, isHookGuard, sectionForRule } from './sections';\nexport { FieldDef } from './field-def';\nexport type { SchemaShape } from './field-def';\nexport { shouldSkipRule, getCurrentBranch } from './skip-rule';\nexport type { SkipRuleResult } from './skip-rule';\nexport {\n    detectBase,\n    resolveBase,\n    getChangedFiles,\n    getFileDiff,\n    getChangedLineNumbers,\n    findNewMethodSignaturesInDiff,\n    hasChangesInRange,\n    isNewOrModified,\n    DiffScope,\n    DiffRange,\n    ChangedFilesOptions,\n} from './diff-scope';\nexport { AbstractRule } from './abstract-rule';\nexport {\n    WEBPIECES_DISABLE,\n    RULE_NAMES,\n    hasDisable,\n    WEBPIECES_TMP_DIR,\n    MERGE_INFO_DIR,\n    PR_REVIEW_DIR,\n    MERGE_IN_PROGRESS_FILE,\n    MERGE_EXPLANATION_FILE,\n} from './constants';\nexport { WebpiecesRulesConfig } from './WebpiecesRulesConfig';\nexport {\n    SyncFlowGuidance,\n    WP_START_UPDATE,\n    WP_FINISH_UPDATE,\n    WP_START_UPSERT_PR,\n    WP_FINISH_UPSERT_PR,\n} from './sync-flow-guidance';\nexport {\n    MaxMethodLinesConfig,\n    MaxFileLinesConfig,\n    RequireReturnTypeConfig,\n    NoInlineTypeLiteralsConfig,\n    NoAnyUnknownConfig,\n    NoImplicitAnyConfig,\n    PrismaValidateDtosConfig,\n    PrismaConverterConfig,\n    NoDestructureConfig,\n    NoUnmanagedExceptionsConfig,\n    CatchErrorPatternConfig,\n    ThrowCauseRequiredConfig,\n    AngularNoDirectApiInResolverConfig,\n    NoSymbolDiTokensConfig,\n    NoCustomCssConfig,\n    NoProcessExitOutsideMainConfig,\n    NoFunctionOutsideClassConfig,\n    InjectAnnotationNotNeededForConcreteClassConfig,\n    FrameworkTagConfig,\n    RoleTagConfig,\n    BranchCreationGuardConfig,\n    PrCreationOrPushGuardConfig,\n    MergeInProgressGuardConfig,\n    PrMergeGuardConfig,\n    RedirectHowToMergeMainConfig,\n    NoFileImportCyclesConfig,\n    RuntimeArchitectureConfig,\n    NxWiringConfig,\n    DiGraphConfig,\n    NoJsFilesConfig,\n    ValidateTsInSrcConfig,\n    ValidateArchitectureUnchangedConfig,\n    ValidateNoArchitectureCyclesConfig,\n    ValidatePackageJsonConfig,\n    ValidateVersionsLockedConfig,\n    ValidateEslintSyncConfig,\n    BaseRuleConfig,\n} from './rule-configs';\n// Mode unions + their value arrays — the single source of truth shared with code-rules.\nexport {\n    METHOD_LIMIT_MODES,\n    FILE_LIMIT_MODES,\n    RETURN_TYPE_MODES,\n    INLINE_TYPE_MODES,\n    MODIFIED_CODE_MODES,\n    PROJECT_MODES,\n    PRISMA_DTOS_MODES,\n    PRISMA_CONVERTER_MODES,\n    DIRECT_API_RESOLVER_MODES,\n    THROW_CAUSE_MODES,\n    ON_OFF_MODES,\n    STRUCTURAL_MODES,\n    VALIDATE_TS_MODES,\n} from './rule-configs';\nexport {\n    NoClientCreationOutsideServerOrClientConfig,\n    CLIENT_CREATION_SEVERITIES,\n} from './no-client-creation-config';\nexport type { ClientCreationSeverity } from './no-client-creation-config';\nexport type {\n    MethodLimitMode,\n    FileLimitMode,\n    ReturnTypeMode,\n    InlineTypeMode,\n    ModifiedCodeMode,\n    ProjectMode,\n    PrismaValidateDtosMode,\n    PrismaConverterMode,\n    DirectApiResolverMode,\n    ThrowCauseMode,\n    OnOffMode,\n    StructuralMode,\n    ValidateTsMode,\n} from './rule-configs';\nexport {\n    FeatureBranchGuardConfig,\n    ReadStaleGuardConfig,\n    MergedBranchBashGuardConfig,\n    StaleMainBashGuardConfig,\n} from './main-sync-guard-configs';\nexport {\n    GateDefinition,\n    PrGateConfig,\n    LandPrConfig,\n    ReviewContextEntry,\n    defaultGates,\n    defaultPrGateConfig,\n    defaultLandPrConfig,\n    buildPrGateConfig,\n    buildLandPrConfig,\n    MERGE_MODE_AUTO,\n    MERGE_MODE_NONE,\n    MERGE_MODES,\n} from './pr-gate-config';\nexport {\n    ChecklistDefinition,\n    toChecklist,\n    normalizeChecklistDoc,\n    formatFileList,\n} from './checklist-config';\nexport type { RawChecklistItem } from './checklist-config';\nexport { ChecklistValidator } from './checklist-validator';\nexport { ChecklistInstructionsService } from './checklist-instructions';\nexport {\n    ReviewerInstructionsService,\n    ReviewerBriefing,\n    BriefedFile,\n    ContextEntry,\n    READ_TRUNCATION_LINES,\n    ALL_DIFF_ONE_READ_LINES,\n} from './reviewer-instructions';\nexport {\n    GateTokenService,\n    computeGateToken,\n    gateTokenMarker,\n    extractGateToken,\n    verifyGateToken,\n} from './gate-token';\nexport {\n    SubagentProvenanceService,\n    ReviewerEvidence,\n    EvidenceRequest,\n    TranscriptScan,\n    ProvenanceResult,\n    PROVENANCE_OK,\n    PROVENANCE_MISSING,\n    PROVENANCE_SKIPPED,\n} from './subagent-provenance';\nexport {\n    ReviewProvenanceService,\n    ReviewProvenance,\n    ReviewerTranscript,\n    ReviewerPaths,\n    OfferedContext,\n    ProvenanceWriteRequest,\n    DEFAULT_RETENTION_DAYS,\n} from './review-provenance';\nexport {\n    ReviewJson,\n    PrContext,\n    ChecklistResult,\n    ChecklistVerdict,\n    CK_PASS,\n    CK_WARN,\n    CK_OVERRIDDEN,\n    CK_FAIL,\n    CK_MISSING,\n    CK_BAD_FORMAT,\n    VERDICT_GREEN,\n    VERDICT_YELLOW,\n    VERDICT_RED,\n    VERDICT_STATUSES,\n    RequiredChecklist,\n    ChecklistReviewContext,\n    ReviewJsonService,\n    loadReviewJson,\n    prDirFor,\n    reviewJsonPath,\n    reviewJsonSchemaHint,\n} from './review-json';\nexport {\n    MainSyncStatus,\n    MainSyncStatusFile,\n    MainSyncFileStore,\n    PullRequestIndex,\n    MAIN_SYNC_STATUS_VERSION,\n} from './main-sync-file';\nexport {\n    MainSyncLock,\n    MainSyncStatusService,\n    DEFAULT_HANG_TIMEOUT_MINUTES,\n    mainSyncStatusPath,\n    mainSyncLockPath,\n    readMainSyncStatus,\n    readMainSyncStatusFile,\n    writeMainSyncStatus,\n    writeMainSyncStatusFile,\n    computeAllMainSyncStatuses,\n    readMainSyncLock,\n    writeMainSyncLock,\n    isLockStale,\n    isRefreshInProgress,\n    tryAcquireMainSyncLock,\n    inProcessLock,\n    finishedLock,\n    computeMainSyncStatus,\n    stampCleanMainSyncStatus,\n    squashRecoverySteps,\n} from './main-sync-status';\nexport {\n    MergedBranch,\n    DeletableBranch,\n    DeletableWorktree,\n    MergedBranchesCache,\n    MergedBranchesService,\n    CacheFreshness,\n    CACHE_STALE_AFTER_MS,\n    CLASSIFICATION_MERGED_PR,\n    CLASSIFICATION_BACKUP_OF_MERGED,\n    CLASSIFICATION_BACKUP_OF_LIVE,\n    CLASSIFICATION_NO_COMMITS,\n    CLASSIFICATION_SUPERSEDED,\n    CLASSIFICATION_CONTENT_IN_MAIN,\n    CLASSIFICATION_NEVER_PROPOSED,\n    CLASSIFICATION_IN_USE,\n    CLASSIFICATION_PRUNABLE,\n    CLASSIFICATION_LOCKED,\n    CLASSIFICATION_CURRENT,\n    CLASSIFICATION_DETACHED,\n    PROMPTABLE_CLASSIFICATIONS,\n} from './merged-branches';\nexport {\n    BranchArchiver,\n    ArchiveResult,\n    ARCHIVE_TAG_PREFIX,\n    BRANCH_RETENTIONS,\n    BRANCH_RETENTION_DELETE,\n    BRANCH_RETENTION_ARCHIVE_TAG,\n    BRANCH_RETENTION_KEEP,\n} from './branch-archiver';\nexport {\n    Worktree,\n    WorktreeService,\n} from './worktrees';\nexport {\n    ReapedBranch,\n    ReapResult,\n    BranchReaper,\n} from './branch-reaper';\nexport {\n    ReapedWorktree,\n    WorktreeReapResult,\n    WorktreeReaper,\n} from './worktree-reaper';\nexport type { MutationVerb, MutationPhase } from './branch-mutation-log';\nexport {\n    BranchMutationEvent,\n    BranchMutationLog,\n    branchMutationLogPath,\n    logBranchMutation,\n} from './branch-mutation-log';\nexport {\n    CommandsConfig,\n    buildCommandsConfig,\n    DEFAULT_UPSERT_PR_COMMAND,\n    DEFAULT_MERGE_COMPLETE_COMMAND,\n} from './commands-config';\n"]}
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../../../../packages/tooling/rules-config/src/index.ts"],"names":[],"mappings":"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","sourcesContent":["export { ResolvedConfig, ResolvedRuleConfig, RuleOptions } from './types';\nexport { InformAiError } from './inform-ai-error';\nexport { RuleFailError } from './rule-fail-error';\nexport { CliExitError } from './cli-exit-error';\nexport { CliUsage, CliFlag, CliArgSet, CliArgsCheck, CliArgs } from './cli-args';\nexport { runMain } from './run-main';\nexport { toError } from './to-error';\nexport { loadAndValidate, LoadedConfig, ConfigLoader } from './load-config';\n// The validation-failure banner: ONE cure (edit the file), plus the marker phrases the validator\n// messages embed rather than re-type.\nexport {\n    formatConfigErrorsBanner,\n    RETIRED_KEY_MARKER,\n    RETIRED_TOP_LEVEL_MARKER,\n    SECTION_PLACEMENT_MARKER,\n} from './config-error-banner';\nexport { findConfigFile, CONFIG_FILENAME, ConfigFile, ConfigParseAttempt, CONFIG_PARSE_ATTEMPTS, CONFIG_PARSE_RETRY_MILLIS } from './config-file';\nexport { RepoRootFinder, INSTRUCT_AI_DIR, INSTRUCT_AI_LEAF } from './repo-root';\n// The scoped `.webpieces` resolver. EVERY reader/writer of `.webpieces/...` goes through one of its two\n// named methods so the call site declares whether the state is repo-wide or worktree-private.\nexport { DotWebpieces, dotWebpieces, GitDirs, WORKTREE_STATE_DIR, LOGS_STATE_DIR, HOOKS_STATE_DIR } from './state-dir';\nexport { StateDirMigrator, StateMigrationReport } from './state-dir-migration';\nexport { ClaudeEnv, claudeEnv, CLAUDE_PROJECT_DIR_ENV, CLAUDE_PROJECT_DIR_UNSET } from './claude-env';\nexport { AtomicFile } from './atomic-file';\n// The ONE formatter for a remedy that must run in a named directory: `cd '<root>' && <command>`.\n// Single-quoted so a repo path containing a space is still runnable (and still un-smuggleable).\nexport { atRoot } from './at-root';\nexport { RulesConfigDesign } from './rules-config-design';\nexport { DocumentDesign, isDocumentDesign, DESIGN_METADATA_KEYS } from './di';\nexport { ExcludePaths } from './exclude-hook-paths';\nexport { isPathExcluded, matchesAnyGlob } from './exclude-paths';\nexport { defaultRules, defaultRulesDir } from './default-rules';\nexport { loadTemplate, writeTemplateIfMissing, writeTemplate, TemplateWriter } from './load-template';\nexport { validateWebpiecesConfig, validatePrGateSection, validateChecklistsSection, validateSectionPlacement, validateExcludePaths, validateMatchRulesSection, allRuleNames, recommendedSeedMode, recommendedSeedModeFor, seedEntryForRule } from './validate-config';\nexport { validateCommandsSection } from './commands-section-validators';\nexport { unknownKeyErrors, isCommentKey, validateTopLevelKeys, COMMENT_KEY_SUFFIX } from './config-key-rules';\n// The retired-key table + the no-back-compat policy it enforces. Exported so the installer can migrate\n// what the errors instruct, and so consumers can enumerate retirements.\nexport { RETIRED_CONFIG_KEYS, RETIRED_SCOPE_KEY, RETIRED_SCOPE_RULE, RetiredConfigKey, isRetiredKey, retiredEntry, retiredKeyError, retiredKeyErrorsIn, retiredRuleFor } from './retired-config-keys';\nexport { validateChecklistDocs } from './checklist-docs-validator';\nexport {\n    MatchRuleConfig,\n    MatchRuleViolation,\n    findMatchRuleViolations,\n    isMatchRuleAllowedPath,\n    compileMatchRulePatterns,\n    renderMatchRuleMessage,\n    DEFAULT_MATCH_RULES,\n} from './match-rules-config';\nexport type { ConfigSection } from './sections';\nexport { HOOK_GUARD_NAMES, isHookGuard, sectionForRule } from './sections';\nexport { FieldDef } from './field-def';\nexport type { SchemaShape } from './field-def';\nexport { shouldSkipRule, getCurrentBranch } from './skip-rule';\nexport type { SkipRuleResult } from './skip-rule';\nexport {\n    detectBase,\n    resolveBase,\n    getChangedFiles,\n    getFileDiff,\n    getChangedLineNumbers,\n    findNewMethodSignaturesInDiff,\n    hasChangesInRange,\n    isNewOrModified,\n    DiffScope,\n    DiffRange,\n    ChangedFilesOptions,\n} from './diff-scope';\nexport { AbstractRule } from './abstract-rule';\nexport {\n    WEBPIECES_DISABLE,\n    RULE_NAMES,\n    hasDisable,\n    WEBPIECES_TMP_DIR,\n    MERGE_INFO_DIR,\n    PR_REVIEW_DIR,\n    MERGE_IN_PROGRESS_FILE,\n    MERGE_EXPLANATION_FILE,\n} from './constants';\nexport { WebpiecesRulesConfig } from './WebpiecesRulesConfig';\nexport {\n    SyncFlowGuidance,\n    WP_START_UPDATE,\n    WP_FINISH_UPDATE,\n    WP_START_UPSERT_PR,\n    WP_FINISH_UPSERT_PR,\n} from './sync-flow-guidance';\nexport {\n    MaxMethodLinesConfig,\n    MaxFileLinesConfig,\n    RequireReturnTypeConfig,\n    NoInlineTypeLiteralsConfig,\n    NoAnyUnknownConfig,\n    NoImplicitAnyConfig,\n    PrismaValidateDtosConfig,\n    PrismaConverterConfig,\n    NoDestructureConfig,\n    NoUnmanagedExceptionsConfig,\n    CatchErrorPatternConfig,\n    ThrowCauseRequiredConfig,\n    AngularNoDirectApiInResolverConfig,\n    NoSymbolDiTokensConfig,\n    NoCustomCssConfig,\n    NoProcessExitOutsideMainConfig,\n    NoFunctionOutsideClassConfig,\n    InjectAnnotationNotNeededForConcreteClassConfig,\n    FrameworkTagConfig,\n    RoleTagConfig,\n    BranchCreationGuardConfig,\n    PrCreationOrPushGuardConfig,\n    MergeInProgressGuardConfig,\n    PrMergeGuardConfig,\n    RedirectHowToMergeMainConfig,\n    NoFileImportCyclesConfig,\n    RuntimeArchitectureConfig,\n    NxWiringConfig,\n    DiGraphConfig,\n    NoJsFilesConfig,\n    ValidateTsInSrcConfig,\n    ValidateArchitectureUnchangedConfig,\n    ValidateNoArchitectureCyclesConfig,\n    ValidatePackageJsonConfig,\n    ValidateVersionsLockedConfig,\n    ValidateEslintSyncConfig,\n    BaseRuleConfig,\n} from './rule-configs';\n// Mode unions + their value arrays — the single source of truth shared with code-rules.\nexport {\n    METHOD_LIMIT_MODES,\n    FILE_LIMIT_MODES,\n    RETURN_TYPE_MODES,\n    INLINE_TYPE_MODES,\n    MODIFIED_CODE_MODES,\n    PROJECT_MODES,\n    PRISMA_DTOS_MODES,\n    PRISMA_CONVERTER_MODES,\n    DIRECT_API_RESOLVER_MODES,\n    THROW_CAUSE_MODES,\n    ON_OFF_MODES,\n    STRUCTURAL_MODES,\n    VALIDATE_TS_MODES,\n} from './rule-configs';\nexport {\n    NoClientCreationOutsideServerOrClientConfig,\n    CLIENT_CREATION_SEVERITIES,\n} from './no-client-creation-config';\nexport type { ClientCreationSeverity } from './no-client-creation-config';\nexport type {\n    MethodLimitMode,\n    FileLimitMode,\n    ReturnTypeMode,\n    InlineTypeMode,\n    ModifiedCodeMode,\n    ProjectMode,\n    PrismaValidateDtosMode,\n    PrismaConverterMode,\n    DirectApiResolverMode,\n    ThrowCauseMode,\n    OnOffMode,\n    StructuralMode,\n    ValidateTsMode,\n} from './rule-configs';\nexport {\n    FeatureBranchGuardConfig,\n    ReadStaleGuardConfig,\n    MergedBranchBashGuardConfig,\n    StaleMainBashGuardConfig,\n} from './main-sync-guard-configs';\nexport {\n    GateDefinition,\n    PrGateConfig,\n    LandPrConfig,\n    ReviewContextEntry,\n    defaultGates,\n    defaultPrGateConfig,\n    defaultLandPrConfig,\n    buildPrGateConfig,\n    buildLandPrConfig,\n    MERGE_MODE_AUTO,\n    MERGE_MODE_NONE,\n    MERGE_MODES,\n} from './pr-gate-config';\nexport {\n    ChecklistDefinition,\n    toChecklist,\n    normalizeChecklistDoc,\n    formatFileList,\n} from './checklist-config';\nexport type { RawChecklistItem } from './checklist-config';\nexport { ChecklistValidator } from './checklist-validator';\nexport { ChecklistInstructionsService } from './checklist-instructions';\nexport {\n    ReviewerInstructionsService,\n    ReviewerBriefing,\n    BriefedFile,\n    ContextEntry,\n    READ_TRUNCATION_LINES,\n    ALL_DIFF_ONE_READ_LINES,\n} from './reviewer-instructions';\nexport {\n    GateTokenService,\n    computeGateToken,\n    gateTokenMarker,\n    extractGateToken,\n    verifyGateToken,\n} from './gate-token';\nexport {\n    SubagentProvenanceService,\n    ReviewerEvidence,\n    EvidenceRequest,\n    TranscriptScan,\n    ProvenanceResult,\n    PROVENANCE_OK,\n    PROVENANCE_MISSING,\n    PROVENANCE_SKIPPED,\n} from './subagent-provenance';\nexport {\n    ReviewProvenanceService,\n    ReviewProvenance,\n    ReviewerTranscript,\n    ReviewerPaths,\n    OfferedContext,\n    ProvenanceWriteRequest,\n    DEFAULT_RETENTION_DAYS,\n} from './review-provenance';\nexport {\n    ReviewJson,\n    PrContext,\n    ChecklistResult,\n    ChecklistVerdict,\n    CK_PASS,\n    CK_WARN,\n    CK_OVERRIDDEN,\n    CK_FAIL,\n    CK_MISSING,\n    CK_BAD_FORMAT,\n    VERDICT_GREEN,\n    VERDICT_YELLOW,\n    VERDICT_RED,\n    VERDICT_STATUSES,\n    RequiredChecklist,\n    ChecklistReviewContext,\n    ReviewJsonService,\n    loadReviewJson,\n    prDirFor,\n    reviewJsonPath,\n    reviewJsonSchemaHint,\n} from './review-json';\nexport {\n    MainSyncStatus,\n    MainSyncStatusFile,\n    MainSyncFileStore,\n    PullRequestIndex,\n    MAIN_SYNC_STATUS_VERSION,\n} from './main-sync-file';\nexport {\n    MainSyncLock,\n    MainSyncStatusService,\n    DEFAULT_HANG_TIMEOUT_MINUTES,\n    mainSyncStatusPath,\n    mainSyncLockPath,\n    readMainSyncStatus,\n    readMainSyncStatusFile,\n    writeMainSyncStatus,\n    writeMainSyncStatusFile,\n    computeAllMainSyncStatuses,\n    readMainSyncLock,\n    writeMainSyncLock,\n    isLockStale,\n    isRefreshInProgress,\n    tryAcquireMainSyncLock,\n    inProcessLock,\n    finishedLock,\n    computeMainSyncStatus,\n    stampCleanMainSyncStatus,\n    squashRecoverySteps,\n} from './main-sync-status';\nexport {\n    MergedBranch,\n    DeletableBranch,\n    DeletableWorktree,\n    MergedBranchesCache,\n    MergedBranchesService,\n    CacheFreshness,\n    CACHE_STALE_AFTER_MS,\n    CLASSIFICATION_MERGED_PR,\n    CLASSIFICATION_BACKUP_OF_MERGED,\n    CLASSIFICATION_BACKUP_OF_LIVE,\n    CLASSIFICATION_NO_COMMITS,\n    CLASSIFICATION_SUPERSEDED,\n    CLASSIFICATION_CONTENT_IN_MAIN,\n    CLASSIFICATION_NEVER_PROPOSED,\n    CLASSIFICATION_IN_USE,\n    CLASSIFICATION_PRUNABLE,\n    CLASSIFICATION_LOCKED,\n    CLASSIFICATION_CURRENT,\n    CLASSIFICATION_DETACHED,\n    PROMPTABLE_CLASSIFICATIONS,\n} from './merged-branches';\nexport {\n    BranchArchiver,\n    ArchiveResult,\n    ARCHIVE_TAG_PREFIX,\n    BRANCH_RETENTIONS,\n    BRANCH_RETENTION_DELETE,\n    BRANCH_RETENTION_ARCHIVE_TAG,\n    BRANCH_RETENTION_KEEP,\n} from './branch-archiver';\nexport {\n    Worktree,\n    WorktreeService,\n} from './worktrees';\nexport {\n    ReapedBranch,\n    ReapResult,\n    BranchReaper,\n} from './branch-reaper';\nexport {\n    ReapedWorktree,\n    WorktreeReapResult,\n    WorktreeReaper,\n} from './worktree-reaper';\nexport type { MutationVerb, MutationPhase } from './branch-mutation-log';\nexport {\n    BranchMutationEvent,\n    BranchMutationLog,\n    branchMutationLogPath,\n    logBranchMutation,\n} from './branch-mutation-log';\nexport {\n    CommandsConfig,\n    buildCommandsConfig,\n    DEFAULT_UPSERT_PR_COMMAND,\n    DEFAULT_MERGE_COMPLETE_COMMAND,\n} from './commands-config';\n"]}

package/src/pr-gate-section-validators.js

@@ -39,10 +39,14 @@ const CHECKLIST_EXAMPLE = ('Example:\n' +
     '    "checklists": [\n' +
     '      { "subagent": "db-migration-reviewer",\n' +
     '        "doc": ".claude/review/db-migrations.md",\n' +
-    '        "patterns": ["**/migrations/**", "**/*.sql"] }\n' +
+    '        "patterns": ["**/migrations/**", "**/*.sql"],\n' +
+    '        "required": true }\n' +
     '    ]\n' +
     '  Each entry needs its OWN reviewer subagent (a .claude/agents/<subagent>.md) — that is how independent\n' +
-    '  review is enforced. "doc" is REPO-relative. Omit "patterns" (or use []) to run on every PR.');
+    '  review is enforced. "doc" is REPO-relative. Omit "patterns" (or use []) to run on every PR.\n' +
+    '  "required" is MANDATORY on every entry: true blocks the PR until the reviewer passes; false makes it\n' +
+    '  an OPTIONAL review the human is offered and may decline (but if they DO run it, a red verdict still\n' +
+    '  blocks).');
 /**
  * The `checklists` section of a pr-gate config: an ARRAY of { subagent, doc?, patterns? }, and nothing else.
  *
@@ -84,6 +88,39 @@ function legacyManifestError(value) {
         `    4. Delete the <!-- webpieces:checklists ... --> comment from "${docRel}"; keep the prose.\n` +
         `  ${CHECKLIST_EXAMPLE}`);
 }
+/**
+ * `required` is MANDATORY on every checklist entry — omitting it is an error, never a default.
+ *
+ * The error names the entry's own subagent, because that is what the consumer recognizes in a
+ * twelve-entry array; `checklists[7]` alone means counting braces. It also states BOTH edits, because the
+ * whole point of the key is that the answer differs per checklist and only the consumer knows which.
+ *
+ * Why a hard rejection instead of `?? true`: an accepted shape is never migrated. Defaulting to true
+ * silently keeps the all-blocking behavior this key exists to relieve, and every consumer that would have
+ * benefited stays on the old behavior forever without ever being told the dial exists. Defaulting to false
+ * is worse — it would silently DOWNGRADE a live review gate on upgrade. Per CLAUDE.md the reader of this
+ * message is a coding agent, so the migration is one mechanical pass.
+ */
+// webpieces-disable no-any-unknown -- one opaque checklist entry, narrowed by the typeof guards here
+// webpieces-disable no-function-outside-class -- module-level config validator, matches the rest of this file
+function requiredKeyErrors(e, i) {
+    const name = typeof e['subagent'] === 'string' && e['subagent'].trim() !== '' ? ` ("${e['subagent']}")` : '';
+    if (e['required'] === undefined) {
+        return [
+            `[pr-gate] checklists[${i}]${name} is missing "required". Every checklist must state one — there is\n` +
+                `  no default, in either direction.\n` +
+                `    "required": true   → BLOCKING. wp-finish-upsert-pr refuses the PR until this reviewer passes.\n` +
+                `                         This is what every checklist did before this key existed.\n` +
+                `    "required": false  → OPTIONAL. When it matches the diff, wp-review-upsert-pr offers it and the\n` +
+                `                         human may decline it. If they DO run it, a red verdict still blocks.\n` +
+                `  ${CHECKLIST_EXAMPLE}`,
+        ];
+    }
+    if (typeof e['required'] !== 'boolean') {
+        return [`[pr-gate] checklists[${i}]${name}.required must be a boolean (true = blocking, false = optional) — not a string or number.`];
+    }
+    return [];
+}
 // Structurally check each entry HERE — a bad `patterns` or a non-object entry is a config-file typo and
 // deserves a `checklists[i]` message — then hand the narrowed defs to ChecklistValidator for the checks only
 // the filesystem can answer (the guidance doc exists, the reviewer agent exists).
@@ -107,6 +144,7 @@ function validateChecklistArray(value, repoRoot) {
         if (e['patterns'] !== undefined && !(Array.isArray(e['patterns']) && e['patterns'].every((p) => typeof p === 'string'))) {
             errors.push(`[pr-gate] checklists[${i}].patterns must be a string[] of path globs (omit or [] to run on every PR).`);
         }
+        errors.push(...requiredKeyErrors(e, i));
         items.push(e);
     });
     if (repoRoot === undefined)