@webpieces/rules-config 0.4.654 → 0.4.656

package/src/rule-fail-error.d.ts

@@ -1,3 +1,4 @@
+import { Option } from './fix-option';
 /**
  * Thrown by ANY rule — in `ai-hook-rules` (edit-time) OR `code-rules` (build/CI-time) — to report a
  * failure from anywhere in its logic. Each engine wraps every rule in a per-rule try/catch, so a
@@ -14,12 +15,19 @@
  *  - `aiMessage`    — what the AI sees in the ai-hook path (also `Error.message`).
  *  - `humanMessage` — what a developer/CI sees in the code-rules console (defaults to `aiMessage`).
  *
- * `line`/`snippet`/`fixHints` are optional context the ai-hook engine folds into its `Violation`.
+ * `line`/`snippet`/`fixOptions` are optional context the ai-hook engine folds into its `Violation`.
+ *
+ * `fixOptions` is `readonly Option[]` — the SAME `Option` that `FixHint.fixOptions` carries, so there is
+ * exactly ONE representation of "the list of cures" across both engines, and a build-time rule can mark
+ * one cure `preferred` exactly like an edit-time rule can. It was `readonly string[]`; that spelling is
+ * deleted and does not compile. NEVER hand-number the cures inside `aiMessage` — the framework
+ * (`formatFixOptions`) owns the "Fix Option N:" numbering and the "(preferred)" tag.
  *
  * Constructor is positional to match this package's other data classes (`Violation`, `ResolvedConfig`)
  * and the project's classes-over-interfaces convention. Common throws:
  *   throw new RuleFailError('no-any-unknown', 'Avoid `any` here — use `unknown`.', 42, 'const x: any');
- *   throw new RuleFailError('max-file-lines', 'File exceeds the limit.', undefined, undefined, ['Split it up']);
+ *   throw new RuleFailError('max-file-lines', 'File exceeds the limit.', undefined, undefined,
+ *       [new Option('Split it into two modules', true), new Option('Move the helpers to a sibling file')]);
  */
 export declare class RuleFailError extends Error {
     cause?: Error;
@@ -28,6 +36,18 @@ export declare class RuleFailError extends Error {
     readonly humanMessage: string;
     readonly line: number | undefined;
     readonly snippet: string | undefined;
-    readonly fixHints: readonly string[];
-    constructor(ruleName: string, aiMessage: string, line?: number, snippet?: string, fixHints?: readonly string[], humanMessage?: string, cause?: Error);
+    readonly fixOptions: readonly Option[];
+    constructor(ruleName: string, aiMessage: string, line?: number, snippet?: string, fixOptions?: readonly Option[], humanMessage?: string, cause?: Error);
 }
+/**
+ * The AI-audience rendering of a thrown `RuleFailError`: its `aiMessage` plus its cures, numbered and
+ * tagged by the framework. Used by the top-level handlers in `ai-hook-rules`.
+ *
+ * WHY it exists: every handler used to print `aiMessage`/`humanMessage` alone, so a `RuleFailError`
+ * that escaped a per-rule catch reached the AI or the CI console with its `fixOptions` SILENTLY
+ * DROPPED — the rule had said how to fix the problem and the renderer threw that away. One renderer per
+ * audience means a cure cannot go missing depending on which catch caught the throw.
+ */
+export declare function renderRuleFailForAi(error: RuleFailError): string;
+/** The developer/CI rendering: `humanMessage` (which defaults to `aiMessage`) plus the same cures. */
+export declare function renderRuleFailForHuman(error: RuleFailError): string;

package/src/rule-fail-error.js

@@ -1,6 +1,9 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.RuleFailError = void 0;
+exports.renderRuleFailForAi = renderRuleFailForAi;
+exports.renderRuleFailForHuman = renderRuleFailForHuman;
+const fix_option_1 = require("./fix-option");
 /**
  * Thrown by ANY rule — in `ai-hook-rules` (edit-time) OR `code-rules` (build/CI-time) — to report a
  * failure from anywhere in its logic. Each engine wraps every rule in a per-rule try/catch, so a
@@ -17,12 +20,19 @@ exports.RuleFailError = void 0;
  *  - `aiMessage`    — what the AI sees in the ai-hook path (also `Error.message`).
  *  - `humanMessage` — what a developer/CI sees in the code-rules console (defaults to `aiMessage`).
  *
- * `line`/`snippet`/`fixHints` are optional context the ai-hook engine folds into its `Violation`.
+ * `line`/`snippet`/`fixOptions` are optional context the ai-hook engine folds into its `Violation`.
+ *
+ * `fixOptions` is `readonly Option[]` — the SAME `Option` that `FixHint.fixOptions` carries, so there is
+ * exactly ONE representation of "the list of cures" across both engines, and a build-time rule can mark
+ * one cure `preferred` exactly like an edit-time rule can. It was `readonly string[]`; that spelling is
+ * deleted and does not compile. NEVER hand-number the cures inside `aiMessage` — the framework
+ * (`formatFixOptions`) owns the "Fix Option N:" numbering and the "(preferred)" tag.
  *
  * Constructor is positional to match this package's other data classes (`Violation`, `ResolvedConfig`)
  * and the project's classes-over-interfaces convention. Common throws:
  *   throw new RuleFailError('no-any-unknown', 'Avoid `any` here — use `unknown`.', 42, 'const x: any');
- *   throw new RuleFailError('max-file-lines', 'File exceeds the limit.', undefined, undefined, ['Split it up']);
+ *   throw new RuleFailError('max-file-lines', 'File exceeds the limit.', undefined, undefined,
+ *       [new Option('Split it into two modules', true), new Option('Move the helpers to a sibling file')]);
  */
 class RuleFailError extends Error {
     cause;
@@ -31,8 +41,8 @@ class RuleFailError extends Error {
     humanMessage;
     line;
     snippet;
-    fixHints;
-    constructor(ruleName, aiMessage, line, snippet, fixHints = [], humanMessage, cause) {
+    fixOptions;
+    constructor(ruleName, aiMessage, line, snippet, fixOptions = [], humanMessage, cause) {
         super(aiMessage);
         this.name = 'RuleFailError';
         this.ruleName = ruleName;
@@ -40,9 +50,32 @@ class RuleFailError extends Error {
         this.humanMessage = humanMessage ?? aiMessage;
         this.line = line;
         this.snippet = snippet;
-        this.fixHints = fixHints;
+        this.fixOptions = fixOptions;
         this.cause = cause;
     }
 }
 exports.RuleFailError = RuleFailError;
+/**
+ * The AI-audience rendering of a thrown `RuleFailError`: its `aiMessage` plus its cures, numbered and
+ * tagged by the framework. Used by the top-level handlers in `ai-hook-rules`.
+ *
+ * WHY it exists: every handler used to print `aiMessage`/`humanMessage` alone, so a `RuleFailError`
+ * that escaped a per-rule catch reached the AI or the CI console with its `fixOptions` SILENTLY
+ * DROPPED — the rule had said how to fix the problem and the renderer threw that away. One renderer per
+ * audience means a cure cannot go missing depending on which catch caught the throw.
+ */
+// webpieces-disable no-function-outside-class -- string formatter, sibling of formatFixOptions
+function renderRuleFailForAi(error) {
+    return joinCures(error.aiMessage, error.fixOptions);
+}
+/** The developer/CI rendering: `humanMessage` (which defaults to `aiMessage`) plus the same cures. */
+// webpieces-disable no-function-outside-class -- string formatter, sibling of formatFixOptions
+function renderRuleFailForHuman(error) {
+    return joinCures(error.humanMessage, error.fixOptions);
+}
+// webpieces-disable no-function-outside-class -- private helper of the two renderers above
+function joinCures(message, fixOptions) {
+    const rendered = (0, fix_option_1.formatFixOptions)(fixOptions);
+    return rendered.length === 0 ? message : `${message}\n${rendered.join('\n')}`;
+}
 //# sourceMappingURL=rule-fail-error.js.map

package/src/rule-fail-error.js.map

@@ -1 +1 @@
-{"version":3,"file":"rule-fail-error.js","sourceRoot":"","sources":["../../../../../packages/tooling/rules-config/src/rule-fail-error.ts"],"names":[],"mappings":";;;AAAA;;;;;;;;;;;;;;;;;;;;;;GAsBG;AACH,MAAa,aAAc,SAAQ,KAAK;IAC3B,KAAK,CAAS;IACd,QAAQ,CAAS;IACjB,SAAS,CAAS;IAClB,YAAY,CAAS;IACrB,IAAI,CAAqB;IACzB,OAAO,CAAqB;IAC5B,QAAQ,CAAoB;IAErC,YACI,QAAgB,EAChB,SAAiB,EACjB,IAAa,EACb,OAAgB,EAChB,WAA8B,EAAE,EAChC,YAAqB,EACrB,KAAa;QAEb,KAAK,CAAC,SAAS,CAAC,CAAC;QACjB,IAAI,CAAC,IAAI,GAAG,eAAe,CAAC;QAC5B,IAAI,CAAC,QAAQ,GAAG,QAAQ,CAAC;QACzB,IAAI,CAAC,SAAS,GAAG,SAAS,CAAC;QAC3B,IAAI,CAAC,YAAY,GAAG,YAAY,IAAI,SAAS,CAAC;QAC9C,IAAI,CAAC,IAAI,GAAG,IAAI,CAAC;QACjB,IAAI,CAAC,OAAO,GAAG,OAAO,CAAC;QACvB,IAAI,CAAC,QAAQ,GAAG,QAAQ,CAAC;QACzB,IAAI,CAAC,KAAK,GAAG,KAAK,CAAC;IACvB,CAAC;CACJ;AA5BD,sCA4BC","sourcesContent":["/**\n * Thrown by ANY rule — in `ai-hook-rules` (edit-time) OR `code-rules` (build/CI-time) — to report a\n * failure from anywhere in its logic. Each engine wraps every rule in a per-rule try/catch, so a\n * thrown `RuleFailError` becomes one visible failure entry and the loop keeps going to the next rule;\n * a plain `Error` (a real bug) is caught the same way and surfaced too — one rule can never abort the\n * others.\n *\n * It is a STANDALONE `Error` — deliberately NOT an `InformAiError`. `InformAiError` is an AI-only\n * concept (it informs Claude Code); `code-rules` has no notion of \"AI\", so a shared rule-failure type\n * must not depend on it. Rules report failures with `RuleFailError`; `InformAiError` stays for\n * config/stdin/plumbing errors and the AI-facing guards path.\n *\n * Two audiences, one throw:\n *  - `aiMessage`    — what the AI sees in the ai-hook path (also `Error.message`).\n *  - `humanMessage` — what a developer/CI sees in the code-rules console (defaults to `aiMessage`).\n *\n * `line`/`snippet`/`fixHints` are optional context the ai-hook engine folds into its `Violation`.\n *\n * Constructor is positional to match this package's other data classes (`Violation`, `ResolvedConfig`)\n * and the project's classes-over-interfaces convention. Common throws:\n *   throw new RuleFailError('no-any-unknown', 'Avoid `any` here — use `unknown`.', 42, 'const x: any');\n *   throw new RuleFailError('max-file-lines', 'File exceeds the limit.', undefined, undefined, ['Split it up']);\n */\nexport class RuleFailError extends Error {\n    override cause?: Error;\n    readonly ruleName: string;\n    readonly aiMessage: string;\n    readonly humanMessage: string;\n    readonly line: number | undefined;\n    readonly snippet: string | undefined;\n    readonly fixHints: readonly string[];\n\n    constructor(\n        ruleName: string,\n        aiMessage: string,\n        line?: number,\n        snippet?: string,\n        fixHints: readonly string[] = [],\n        humanMessage?: string,\n        cause?: Error,\n    ) {\n        super(aiMessage);\n        this.name = 'RuleFailError';\n        this.ruleName = ruleName;\n        this.aiMessage = aiMessage;\n        this.humanMessage = humanMessage ?? aiMessage;\n        this.line = line;\n        this.snippet = snippet;\n        this.fixHints = fixHints;\n        this.cause = cause;\n    }\n}\n"]}
+{"version":3,"file":"rule-fail-error.js","sourceRoot":"","sources":["../../../../../packages/tooling/rules-config/src/rule-fail-error.ts"],"names":[],"mappings":";;;AAwEA,kDAEC;AAID,wDAEC;AAhFD,6CAAwD;AAExD;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA6BG;AACH,MAAa,aAAc,SAAQ,KAAK;IAC3B,KAAK,CAAS;IACd,QAAQ,CAAS;IACjB,SAAS,CAAS;IAClB,YAAY,CAAS;IACrB,IAAI,CAAqB;IACzB,OAAO,CAAqB;IAC5B,UAAU,CAAoB;IAEvC,YACI,QAAgB,EAChB,SAAiB,EACjB,IAAa,EACb,OAAgB,EAChB,aAAgC,EAAE,EAClC,YAAqB,EACrB,KAAa;QAEb,KAAK,CAAC,SAAS,CAAC,CAAC;QACjB,IAAI,CAAC,IAAI,GAAG,eAAe,CAAC;QAC5B,IAAI,CAAC,QAAQ,GAAG,QAAQ,CAAC;QACzB,IAAI,CAAC,SAAS,GAAG,SAAS,CAAC;QAC3B,IAAI,CAAC,YAAY,GAAG,YAAY,IAAI,SAAS,CAAC;QAC9C,IAAI,CAAC,IAAI,GAAG,IAAI,CAAC;QACjB,IAAI,CAAC,OAAO,GAAG,OAAO,CAAC;QACvB,IAAI,CAAC,UAAU,GAAG,UAAU,CAAC;QAC7B,IAAI,CAAC,KAAK,GAAG,KAAK,CAAC;IACvB,CAAC;CACJ;AA5BD,sCA4BC;AAED;;;;;;;;GAQG;AACH,+FAA+F;AAC/F,SAAgB,mBAAmB,CAAC,KAAoB;IACpD,OAAO,SAAS,CAAC,KAAK,CAAC,SAAS,EAAE,KAAK,CAAC,UAAU,CAAC,CAAC;AACxD,CAAC;AAED,sGAAsG;AACtG,+FAA+F;AAC/F,SAAgB,sBAAsB,CAAC,KAAoB;IACvD,OAAO,SAAS,CAAC,KAAK,CAAC,YAAY,EAAE,KAAK,CAAC,UAAU,CAAC,CAAC;AAC3D,CAAC;AAED,2FAA2F;AAC3F,SAAS,SAAS,CAAC,OAAe,EAAE,UAA6B;IAC7D,MAAM,QAAQ,GAAG,IAAA,6BAAgB,EAAC,UAAU,CAAC,CAAC;IAC9C,OAAO,QAAQ,CAAC,MAAM,KAAK,CAAC,CAAC,CAAC,CAAC,OAAO,CAAC,CAAC,CAAC,GAAG,OAAO,KAAK,QAAQ,CAAC,IAAI,CAAC,IAAI,CAAC,EAAE,CAAC;AAClF,CAAC","sourcesContent":["import { Option, formatFixOptions } from './fix-option';\n\n/**\n * Thrown by ANY rule — in `ai-hook-rules` (edit-time) OR `code-rules` (build/CI-time) — to report a\n * failure from anywhere in its logic. Each engine wraps every rule in a per-rule try/catch, so a\n * thrown `RuleFailError` becomes one visible failure entry and the loop keeps going to the next rule;\n * a plain `Error` (a real bug) is caught the same way and surfaced too — one rule can never abort the\n * others.\n *\n * It is a STANDALONE `Error` — deliberately NOT an `InformAiError`. `InformAiError` is an AI-only\n * concept (it informs Claude Code); `code-rules` has no notion of \"AI\", so a shared rule-failure type\n * must not depend on it. Rules report failures with `RuleFailError`; `InformAiError` stays for\n * config/stdin/plumbing errors and the AI-facing guards path.\n *\n * Two audiences, one throw:\n *  - `aiMessage`    — what the AI sees in the ai-hook path (also `Error.message`).\n *  - `humanMessage` — what a developer/CI sees in the code-rules console (defaults to `aiMessage`).\n *\n * `line`/`snippet`/`fixOptions` are optional context the ai-hook engine folds into its `Violation`.\n *\n * `fixOptions` is `readonly Option[]` — the SAME `Option` that `FixHint.fixOptions` carries, so there is\n * exactly ONE representation of \"the list of cures\" across both engines, and a build-time rule can mark\n * one cure `preferred` exactly like an edit-time rule can. It was `readonly string[]`; that spelling is\n * deleted and does not compile. NEVER hand-number the cures inside `aiMessage` — the framework\n * (`formatFixOptions`) owns the \"Fix Option N:\" numbering and the \"(preferred)\" tag.\n *\n * Constructor is positional to match this package's other data classes (`Violation`, `ResolvedConfig`)\n * and the project's classes-over-interfaces convention. Common throws:\n *   throw new RuleFailError('no-any-unknown', 'Avoid `any` here — use `unknown`.', 42, 'const x: any');\n *   throw new RuleFailError('max-file-lines', 'File exceeds the limit.', undefined, undefined,\n *       [new Option('Split it into two modules', true), new Option('Move the helpers to a sibling file')]);\n */\nexport class RuleFailError extends Error {\n    override cause?: Error;\n    readonly ruleName: string;\n    readonly aiMessage: string;\n    readonly humanMessage: string;\n    readonly line: number | undefined;\n    readonly snippet: string | undefined;\n    readonly fixOptions: readonly Option[];\n\n    constructor(\n        ruleName: string,\n        aiMessage: string,\n        line?: number,\n        snippet?: string,\n        fixOptions: readonly Option[] = [],\n        humanMessage?: string,\n        cause?: Error,\n    ) {\n        super(aiMessage);\n        this.name = 'RuleFailError';\n        this.ruleName = ruleName;\n        this.aiMessage = aiMessage;\n        this.humanMessage = humanMessage ?? aiMessage;\n        this.line = line;\n        this.snippet = snippet;\n        this.fixOptions = fixOptions;\n        this.cause = cause;\n    }\n}\n\n/**\n * The AI-audience rendering of a thrown `RuleFailError`: its `aiMessage` plus its cures, numbered and\n * tagged by the framework. Used by the top-level handlers in `ai-hook-rules`.\n *\n * WHY it exists: every handler used to print `aiMessage`/`humanMessage` alone, so a `RuleFailError`\n * that escaped a per-rule catch reached the AI or the CI console with its `fixOptions` SILENTLY\n * DROPPED — the rule had said how to fix the problem and the renderer threw that away. One renderer per\n * audience means a cure cannot go missing depending on which catch caught the throw.\n */\n// webpieces-disable no-function-outside-class -- string formatter, sibling of formatFixOptions\nexport function renderRuleFailForAi(error: RuleFailError): string {\n    return joinCures(error.aiMessage, error.fixOptions);\n}\n\n/** The developer/CI rendering: `humanMessage` (which defaults to `aiMessage`) plus the same cures. */\n// webpieces-disable no-function-outside-class -- string formatter, sibling of formatFixOptions\nexport function renderRuleFailForHuman(error: RuleFailError): string {\n    return joinCures(error.humanMessage, error.fixOptions);\n}\n\n// webpieces-disable no-function-outside-class -- private helper of the two renderers above\nfunction joinCures(message: string, fixOptions: readonly Option[]): string {\n    const rendered = formatFixOptions(fixOptions);\n    return rendered.length === 0 ? message : `${message}\\n${rendered.join('\\n')}`;\n}\n"]}

package/src/skip-rule.d.ts

@@ -1,6 +1,22 @@
-export interface SkipRuleResult {
+/**
+ * The skip decision. A CLASS, not an interface (CLAUDE.md rule 1), because it carries a THIRD fact
+ * beyond yes/no that a caller has to be able to read rather than read about in a log line.
+ *
+ * `hatchNotApplied` is that fact: a branch hatch WAS configured, and it could NOT apply — today only
+ * because HEAD is detached (a tag checkout, a `git bisect` step, a CI checkout of a merge ref). The rule
+ * is ENFORCED in that case, so there is nothing to report unless the rule then FAILS; when it does, its
+ * own RuleFailError is where this belongs, as context on why the hatch the config shows did not save it.
+ *
+ * It is deliberately NOT printed here. Everything in this framework throws to ONE place that renders per
+ * audience; a console write from a library function cannot be caught, re-rendered or asserted on.
+ */
+export declare class SkipRuleResult {
     skip: boolean;
-    reason?: string;
+    /** Why the rule IS being skipped. '' whenever `skip` is false. */
+    reason: string;
+    /** Why a CONFIGURED branch hatch did not apply, or '' when there is nothing to say. */
+    hatchNotApplied: string;
+    constructor(skip: boolean, reason?: string, hatchNotApplied?: string);
 }
 export declare function getCurrentBranch(): string;
-export declare function shouldSkipRule(epoch: number | undefined, branchPattern: string | undefined | null): SkipRuleResult;
+export declare function shouldSkipRule(epoch: number | undefined, branchName: string | undefined | null): SkipRuleResult;

package/src/skip-rule.js

@@ -1,10 +1,44 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
+exports.SkipRuleResult = void 0;
 exports.getCurrentBranch = getCurrentBranch;
 exports.shouldSkipRule = shouldSkipRule;
+const tslib_1 = require("tslib");
 const child_process_1 = require("child_process");
+const fs = tslib_1.__importStar(require("fs"));
 const inform_ai_error_1 = require("./inform-ai-error");
+const rule_fail_error_1 = require("./rule-fail-error");
+const fix_option_1 = require("./fix-option");
 const to_error_1 = require("./to-error");
+// Universal "should this rule be skipped right now?" logic, shared by code-rules,
+// ai-hook-rules and the Nx executors so every rule honors the same two escape
+// hatches: turnOffRuleWhileOnBranch (skip while on a named branch) and
+// turnOffRuleUntilEpoch (skip until an epoch passes).
+/**
+ * The skip decision. A CLASS, not an interface (CLAUDE.md rule 1), because it carries a THIRD fact
+ * beyond yes/no that a caller has to be able to read rather than read about in a log line.
+ *
+ * `hatchNotApplied` is that fact: a branch hatch WAS configured, and it could NOT apply — today only
+ * because HEAD is detached (a tag checkout, a `git bisect` step, a CI checkout of a merge ref). The rule
+ * is ENFORCED in that case, so there is nothing to report unless the rule then FAILS; when it does, its
+ * own RuleFailError is where this belongs, as context on why the hatch the config shows did not save it.
+ *
+ * It is deliberately NOT printed here. Everything in this framework throws to ONE place that renders per
+ * audience; a console write from a library function cannot be caught, re-rendered or asserted on.
+ */
+class SkipRuleResult {
+    skip;
+    /** Why the rule IS being skipped. '' whenever `skip` is false. */
+    reason;
+    /** Why a CONFIGURED branch hatch did not apply, or '' when there is nothing to say. */
+    hatchNotApplied;
+    constructor(skip, reason = '', hatchNotApplied = '') {
+        this.skip = skip;
+        this.reason = reason;
+        this.hatchNotApplied = hatchNotApplied;
+    }
+}
+exports.SkipRuleResult = SkipRuleResult;
 // The actual checked-out branch. The grab bag of ambient env vars (BRANCH_NAME, GIT_BRANCH,
 // CI_COMMIT_BRANCH, …) was intentionally REMOVED and must stay removed: a stray GIT_BRANCH=main
 // locally made this return "main" on a feature branch, which (a) mislabeled the main-sync cache and
@@ -19,6 +53,12 @@ const to_error_1 = require("./to-error");
 //                      GITHUB_REF_NAME: on pull_request that is "<N>/merge", not a branch.)
 //   WEBPIECES_BRANCH — one documented opt-in override for CI systems not special-cased here
 //                      (GitLab, CircleCI, Buildkite). Nobody sets it by accident.
+//
+// This getter answers "what branch am I on?" and NOTHING about whether that answer may be TRUSTED to
+// unlock an escape hatch. That second question is asked by shouldSkipRule alone (see
+// assertBranchIsTrustworthy) because this getter has callers — the main-sync cache label, merged-PR
+// detection, code-rules' re-export of it — for which a fork's own branch name is a perfectly good
+// answer, and making the getter itself throw would redden all of them.
 function getCurrentBranch() {
     const prBranch = process.env['GITHUB_HEAD_REF'];
     if (prBranch)
@@ -36,40 +76,136 @@ function getCurrentBranch() {
         throw new inform_ai_error_1.InformAiError(`Failed to determine current git branch: ${error.message}`, { cause: error });
     }
 }
+/**
+ * Refuse the branch hatch on a pull request whose head branch this repo does not own.
+ *
+ * The hole it closes: hatch names live in `webpieces.config.json`, which is COMMITTED and public. On a
+ * `pull_request` from a FORK the runner sets GITHUB_HEAD_REF to the FORK AUTHOR's branch name, so an
+ * outside contributor who names their branch after one of your hatches silently disables that rule on
+ * their PR — the one place you least want a rule off.
+ *
+ * It is answered with no network and no token, from `$GITHUB_EVENT_PATH` — a JSON file the runner writes
+ * before the job starts:
+ *   - `pull_request_target` runs with the BASE repo's secrets against contributor-authored code, so it is
+ *     untrusted unconditionally; there is nothing to compare.
+ *   - `pull_request` is trusted only when the head repo's `full_name` EQUALS `GITHUB_REPOSITORY`.
+ *
+ * "Cannot tell" counts as untrusted — a `pull_request` run with no readable event file cannot make the
+ * comparison, and a hatch that cannot be proven to be yours must not fire.
+ *
+ * This is the ONE hard failure left in this module, and it is not the "no branch here" case (see
+ * shouldSkipRule, which enforces quietly when HEAD is detached). It is a hatch name that DOES resolve but
+ * is attacker-chosen — a security property, not a checkout that happens not to be editing.
+ *
+ * Called ONLY from inside `if (branchName)`. With turnOffRuleWhileOnBranch null — the overwhelmingly
+ * common value — nothing here runs and no fork PR is affected in any way.
+ */
+// webpieces-disable no-function-outside-class -- module-scope helper of the module-scope shouldSkipRule it serves; this whole module is functional by design (imported as free functions by code-rules, ai-hook-rules and the nx executors)
+function assertBranchIsTrustworthy(branchName) {
+    const eventName = process.env['GITHUB_EVENT_NAME'];
+    if (eventName !== 'pull_request' && eventName !== 'pull_request_target')
+        return;
+    if (eventName === 'pull_request_target')
+        throw forkRefusal(branchName, 'pull_request_target run');
+    const headRepo = readHeadRepoFullName(branchName);
+    const thisRepo = process.env['GITHUB_REPOSITORY'] ?? '';
+    if (headRepo !== null && thisRepo !== '' && headRepo === thisRepo)
+        return;
+    throw forkRefusal(branchName, headRepo === null
+        ? 'pull_request run with no readable $GITHUB_EVENT_PATH, so the head branch cannot be proven to belong to this repo'
+        : `pull_request run whose head branch lives in "${headRepo}", not in "${thisRepo}"`);
+}
+/**
+ * The head repo's `owner/name` from the runner's event file, or null when there is no such file.
+ *
+ * A file that exists but cannot be parsed is a different thing from one that is absent, and it throws:
+ * it means the runner wrote something this code does not understand, and silently downgrading that to
+ * "untrusted" would hide a real incompatibility behind a message about forks.
+ */
+// webpieces-disable no-function-outside-class -- module-scope helper, see assertBranchIsTrustworthy
+function readHeadRepoFullName(branchName) {
+    const eventPath = process.env['GITHUB_EVENT_PATH'];
+    if (!eventPath || !fs.existsSync(eventPath))
+        return null;
+    // webpieces-disable no-unmanaged-exceptions -- chokepoint: a raw SyntaxError from the runner's event file would say nothing about hatches; this names the hatch, the file and the rule that stayed ON
+    // eslint-disable-next-line @webpieces/no-unmanaged-exceptions -- see above
+    try {
+        const parsed = JSON.parse(fs.readFileSync(eventPath, 'utf8'));
+        return parsed.pull_request?.head?.repo?.full_name ?? null;
+    }
+    catch (err) {
+        const error = (0, to_error_1.toError)(err);
+        throw new rule_fail_error_1.RuleFailError('turnOffRuleWhileOnBranch', `turnOffRuleWhileOnBranch: "${branchName}" is configured and this is a pull_request run, so the ` +
+            `head repository must be checked before the hatch may fire — but the runner's event file ` +
+            `${eventPath} could not be read: ${error.message}`, undefined, undefined, [new fix_option_1.Option('Use turnOffRuleUntilEpoch instead — it is TIME based and needs no event file.', true),
+            new fix_option_1.Option('Or clear turnOffRuleWhileOnBranch (set it to null) so no trust check is needed at all.')], undefined, error);
+    }
+}
+/**
+ * The fork refusal, as a `RuleFailError`.
+ *
+ * The cures are `fixOptions` — a LIST of `Option` — because the framework owns how they are labelled
+ * and numbered (`formatFixOptions` renders "Fix Option N:" and the "(preferred)" tag for BOTH engines).
+ * A hand-numbered "WORKAROUNDS: 1. … 2. …" string literal, which is what this used to be, is exactly
+ * the shape `Option` exists to prevent. `Option` lives HERE in `rules-config`, so the same class serves
+ * this build-time throw and `FixHint` in `ai-hook-rules` — one cure shape, one definition.
+ *
+ * `ruleName` is the HATCH, not the rule being evaluated: `shouldSkipRule` is handed only the two hatch
+ * values and does not know whose rule it is deciding for — and the thing that failed genuinely is the
+ * hatch, which cannot be honored here.
+ */
+// webpieces-disable no-function-outside-class -- module-scope helper, see assertBranchIsTrustworthy
+function forkRefusal(branchName, what) {
+    return new rule_fail_error_1.RuleFailError('turnOffRuleWhileOnBranch', `turnOffRuleWhileOnBranch: "${branchName}" is configured, but this is a ${what}. The branch name ` +
+        `there is chosen by the PULL REQUEST AUTHOR, and hatch names are public (webpieces.config.json ` +
+        `is committed), so honoring the hatch would let anyone turn this rule off on their own PR just ` +
+        `by naming their branch after it. The rule is NOT skipped, and this fails loudly rather than ` +
+        `quietly enforcing a rule the config says is off.`, undefined, undefined, [
+        new fix_option_1.Option('If the rule must be off for outside contributions too, use turnOffRuleUntilEpoch — it is TIME ' +
+            'based, so it cannot be self-granted by naming a branch. Keep the date short: it is repo-wide ' +
+            'while it lasts, so it also shelters unrelated work landing in the same window.', true),
+        new fix_option_1.Option('Otherwise clear turnOffRuleWhileOnBranch (set it to null) and fix the findings on the ' +
+            'contributed branch like any other.'),
+    ]);
+}
 function shouldSkipRule(epoch, 
+// The branch hatch is an EXACT branch name — compared with `===`, never a glob, regex or prefix.
+// That is deliberate and is not to be "improved": the hatch turns a rule OFF, and a pattern lets one
+// config line switch rules off on branches nobody enumerated when it was written. If two branches
+// need the same rule off, that is two branches renamed to one hatch name, not one wildcard.
+//
 // null (the "no branch / always on" value of turnOffRuleWhileOnBranch) is treated exactly like
 // undefined — no branch scoping. Only a non-empty branch name activates the branch hatch.
-branchPattern) {
-    if (branchPattern) {
+branchName) {
+    if (branchName) {
+        // The fork gate fires ONLY inside `if (branchName)`. With turnOffRuleWhileOnBranch=null — the
+        // overwhelmingly common value — nothing below runs, so an outside contribution to a repo that
+        // configured no hatch is an ordinary run.
+        //
+        // A DETACHED HEAD is NOT an error here. The branch hatch exists to relax a rule while you EDIT on
+        // a branch; a tag checkout or a `git bisect` step is not editing (you cannot commit to a tag, and
+        // to edit you branch off it first). So when no branch can be resolved the hatch simply does not
+        // apply and THE RULE IS ENFORCED — whoever hits a violation then gets that rule's own message and
+        // cure, which is the useful output. WHY the hatch did not fire rides back on the result
+        // (SkipRuleResult.hatchNotApplied) rather than being printed, so a caller that does fail can fold
+        // it into its own error instead of a library writing to a console nobody can catch.
+        assertBranchIsTrustworthy(branchName);
         const current = getCurrentBranch();
-        // ONLY inside `if (branchPattern)`. A detached HEAD with turnOffRuleWhileOnBranch=null (the
-        // overwhelmingly common value) is a non-event and must stay silent, or every tag build,
-        // bisect and `gh pr checkout --detach` starts failing for no reason. The fault reported here
-        // is "you asked for branch scoping where no branch exists", never "HEAD is detached".
         if (current === 'HEAD' || current === '') {
-            throw new inform_ai_error_1.InformAiError(`turnOffRuleWhileOnBranch: "${branchPattern}" is configured, but the current branch ` +
-                `cannot be determined — HEAD is detached, which is what a CI checkout of a merge ref ` +
-                `looks like. The hatch would silently NOT apply, so this fails now rather than passing ` +
-                `on your machine and failing in CI with an unrelated-looking error.\n\n` +
-                `WORKAROUNDS, in order of preference:\n` +
-                `  1. Upgrade to a webpieces that reads GITHUB_HEAD_REF (no workflow change needed).\n` +
-                `  2. Set WEBPIECES_BRANCH in the workflow so the branch can be resolved.\n` +
-                `  3. Use turnOffRuleUntilEpoch instead — it is TIME based, so it survives any checkout ` +
-                `including a detached one, and it is the only hatch that works in CI today. Set it to a ` +
-                `SHORT date (a few days): unlike branch scoping it is repo-wide while it lasts, so it ` +
-                `also shelters unrelated work that lands in the same window.`);
+            return new SkipRuleResult(false, '', `turnOffRuleWhileOnBranch: "${branchName}" did not apply — HEAD is detached, so there is no ` +
+                `branch to match (a tag checkout, a git bisect step, or a CI checkout of a merge ref).`);
         }
-        if (current === branchPattern) {
-            return { skip: true, reason: `on branch "${branchPattern}"` };
+        if (current === branchName) {
+            return new SkipRuleResult(true, `on branch "${branchName}"`);
         }
     }
     if (epoch !== undefined) {
         const nowSeconds = Date.now() / 1000;
         if (nowSeconds < epoch) {
             const expiresDate = new Date(epoch * 1000).toISOString().split('T')[0];
-            return { skip: true, reason: `turnOffRuleUntilEpoch active, expires: ${expiresDate}` };
+            return new SkipRuleResult(true, `turnOffRuleUntilEpoch active, expires: ${expiresDate}`);
         }
     }
-    return { skip: false };
+    return new SkipRuleResult(false);
 }
 //# sourceMappingURL=skip-rule.js.map

package/src/skip-rule.js.map

@@ -1 +1 @@
-{"version":3,"file":"skip-rule.js","sourceRoot":"","sources":["../../../../../packages/tooling/rules-config/src/skip-rule.ts"],"names":[],"mappings":";;AA6BA,4CAeC;AAED,wCAuCC;AArFD,iDAAyC;AAEzC,uDAAkD;AAClD,yCAAqC;AAYrC,4FAA4F;AAC5F,gGAAgG;AAChG,oGAAoG;AACpG,2EAA2E;AAC3E,EAAE;AACF,qGAAqG;AACrG,qGAAqG;AACrG,qGAAqG;AACrG,+CAA+C;AAC/C,oGAAoG;AACpG,mGAAmG;AACnG,4FAA4F;AAC5F,4FAA4F;AAC5F,kFAAkF;AAClF,SAAgB,gBAAgB;IAC5B,MAAM,QAAQ,GAAG,OAAO,CAAC,GAAG,CAAC,iBAAiB,CAAC,CAAC;IAChD,IAAI,QAAQ;QAAE,OAAO,QAAQ,CAAC;IAE9B,MAAM,QAAQ,GAAG,OAAO,CAAC,GAAG,CAAC,kBAAkB,CAAC,CAAC;IACjD,IAAI,QAAQ;QAAE,OAAO,QAAQ,CAAC;IAE9B,wHAAwH;IACxH,0IAA0I;IAC1I,IAAI,CAAC;QACD,OAAO,IAAA,wBAAQ,EAAC,iCAAiC,EAAE,EAAE,QAAQ,EAAE,MAAM,EAAE,CAAC,CAAC,IAAI,EAAE,CAAC;IACpF,CAAC;IAAC,OAAO,GAAY,EAAE,CAAC;QACpB,MAAM,KAAK,GAAG,IAAA,kBAAO,EAAC,GAAG,CAAC,CAAC;QAC3B,MAAM,IAAI,+BAAa,CAAC,2CAA2C,KAAK,CAAC,OAAO,EAAE,EAAE,EAAE,KAAK,EAAE,KAAK,EAAE,CAAC,CAAC;IAC1G,CAAC;AACL,CAAC;AAED,SAAgB,cAAc,CAC1B,KAAyB;AACzB,+FAA+F;AAC/F,0FAA0F;AAC1F,aAAwC;IAExC,IAAI,aAAa,EAAE,CAAC;QAChB,MAAM,OAAO,GAAG,gBAAgB,EAAE,CAAC;QACnC,4FAA4F;QAC5F,wFAAwF;QACxF,6FAA6F;QAC7F,sFAAsF;QACtF,IAAI,OAAO,KAAK,MAAM,IAAI,OAAO,KAAK,EAAE,EAAE,CAAC;YACvC,MAAM,IAAI,+BAAa,CACnB,8BAA8B,aAAa,0CAA0C;gBACjF,sFAAsF;gBACtF,wFAAwF;gBACxF,wEAAwE;gBACxE,wCAAwC;gBACxC,uFAAuF;gBACvF,4EAA4E;gBAC5E,yFAAyF;gBACzF,yFAAyF;gBACzF,uFAAuF;gBACvF,6DAA6D,CACpE,CAAC;QACN,CAAC;QACD,IAAI,OAAO,KAAK,aAAa,EAAE,CAAC;YAC5B,OAAO,EAAE,IAAI,EAAE,IAAI,EAAE,MAAM,EAAE,cAAc,aAAa,GAAG,EAAE,CAAC;QAClE,CAAC;IACL,CAAC;IACD,IAAI,KAAK,KAAK,SAAS,EAAE,CAAC;QACtB,MAAM,UAAU,GAAG,IAAI,CAAC,GAAG,EAAE,GAAG,IAAI,CAAC;QACrC,IAAI,UAAU,GAAG,KAAK,EAAE,CAAC;YACrB,MAAM,WAAW,GAAG,IAAI,IAAI,CAAC,KAAK,GAAG,IAAI,CAAC,CAAC,WAAW,EAAE,CAAC,KAAK,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC,CAAC;YACvE,OAAO,EAAE,IAAI,EAAE,IAAI,EAAE,MAAM,EAAE,0CAA0C,WAAW,EAAE,EAAE,CAAC;QAC3F,CAAC;IACL,CAAC;IACD,OAAO,EAAE,IAAI,EAAE,KAAK,EAAE,CAAC;AAC3B,CAAC","sourcesContent":["import { execSync } from 'child_process';\n\nimport { InformAiError } from './inform-ai-error';\nimport { toError } from './to-error';\n\n// Universal \"should this rule be skipped right now?\" logic, shared by code-rules,\n// ai-hook-rules and the Nx executors so every rule honors the same two escape\n// hatches: turnOffRuleWhileOnBranch (skip while on a named branch) and\n// turnOffRuleUntilEpoch (skip until an epoch passes).\n\nexport interface SkipRuleResult {\n    skip: boolean;\n    reason?: string;\n}\n\n// The actual checked-out branch. The grab bag of ambient env vars (BRANCH_NAME, GIT_BRANCH,\n// CI_COMMIT_BRANCH, …) was intentionally REMOVED and must stay removed: a stray GIT_BRANCH=main\n// locally made this return \"main\" on a feature branch, which (a) mislabeled the main-sync cache and\n// (b) silently disabled merged-PR detection (detectMergedPr skips \"main\").\n//\n// The two vars below are NOT that. They are consulted BEFORE git because git cannot answer at all in\n// the case they cover — a `pull_request` checkout leaves HEAD detached on refs/pull/<N>/merge, where\n// `git rev-parse --abbrev-ref HEAD` returns the literal string \"HEAD\" and no branch hatch can match.\n// Neither can go stale the way GIT_BRANCH did:\n//   GITHUB_HEAD_REF  — set by the GitHub runner ONLY on pull_request/pull_request_target, and it IS\n//                      the source branch name. Absent on push, so the fallthrough stays safe. (Not\n//                      GITHUB_REF_NAME: on pull_request that is \"<N>/merge\", not a branch.)\n//   WEBPIECES_BRANCH — one documented opt-in override for CI systems not special-cased here\n//                      (GitLab, CircleCI, Buildkite). Nobody sets it by accident.\nexport function getCurrentBranch(): string {\n    const prBranch = process.env['GITHUB_HEAD_REF'];\n    if (prBranch) return prBranch;\n\n    const override = process.env['WEBPIECES_BRANCH'];\n    if (override) return override;\n\n    // webpieces-disable no-unmanaged-exceptions -- rethrow as InformAiError so global catch surfaces readable message to AI\n    // eslint-disable-next-line @webpieces/no-unmanaged-exceptions -- rethrow as InformAiError so global catch surfaces readable message to AI\n    try {\n        return execSync('git rev-parse --abbrev-ref HEAD', { encoding: 'utf8' }).trim();\n    } catch (err: unknown) {\n        const error = toError(err);\n        throw new InformAiError(`Failed to determine current git branch: ${error.message}`, { cause: error });\n    }\n}\n\nexport function shouldSkipRule(\n    epoch: number | undefined,\n    // null (the \"no branch / always on\" value of turnOffRuleWhileOnBranch) is treated exactly like\n    // undefined — no branch scoping. Only a non-empty branch name activates the branch hatch.\n    branchPattern: string | undefined | null\n): SkipRuleResult {\n    if (branchPattern) {\n        const current = getCurrentBranch();\n        // ONLY inside `if (branchPattern)`. A detached HEAD with turnOffRuleWhileOnBranch=null (the\n        // overwhelmingly common value) is a non-event and must stay silent, or every tag build,\n        // bisect and `gh pr checkout --detach` starts failing for no reason. The fault reported here\n        // is \"you asked for branch scoping where no branch exists\", never \"HEAD is detached\".\n        if (current === 'HEAD' || current === '') {\n            throw new InformAiError(\n                `turnOffRuleWhileOnBranch: \"${branchPattern}\" is configured, but the current branch ` +\n                    `cannot be determined — HEAD is detached, which is what a CI checkout of a merge ref ` +\n                    `looks like. The hatch would silently NOT apply, so this fails now rather than passing ` +\n                    `on your machine and failing in CI with an unrelated-looking error.\\n\\n` +\n                    `WORKAROUNDS, in order of preference:\\n` +\n                    `  1. Upgrade to a webpieces that reads GITHUB_HEAD_REF (no workflow change needed).\\n` +\n                    `  2. Set WEBPIECES_BRANCH in the workflow so the branch can be resolved.\\n` +\n                    `  3. Use turnOffRuleUntilEpoch instead — it is TIME based, so it survives any checkout ` +\n                    `including a detached one, and it is the only hatch that works in CI today. Set it to a ` +\n                    `SHORT date (a few days): unlike branch scoping it is repo-wide while it lasts, so it ` +\n                    `also shelters unrelated work that lands in the same window.`\n            );\n        }\n        if (current === branchPattern) {\n            return { skip: true, reason: `on branch \"${branchPattern}\"` };\n        }\n    }\n    if (epoch !== undefined) {\n        const nowSeconds = Date.now() / 1000;\n        if (nowSeconds < epoch) {\n            const expiresDate = new Date(epoch * 1000).toISOString().split('T')[0];\n            return { skip: true, reason: `turnOffRuleUntilEpoch active, expires: ${expiresDate}` };\n        }\n    }\n    return { skip: false };\n}\n"]}
+{"version":3,"file":"skip-rule.js","sourceRoot":"","sources":["../../../../../packages/tooling/rules-config/src/skip-rule.ts"],"names":[],"mappings":"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","sourcesContent":["import { execSync } from 'child_process';\nimport * as fs from 'fs';\n\nimport { InformAiError } from './inform-ai-error';\nimport { RuleFailError } from './rule-fail-error';\nimport { Option } from './fix-option';\nimport { toError } from './to-error';\n\n// Universal \"should this rule be skipped right now?\" logic, shared by code-rules,\n// ai-hook-rules and the Nx executors so every rule honors the same two escape\n// hatches: turnOffRuleWhileOnBranch (skip while on a named branch) and\n// turnOffRuleUntilEpoch (skip until an epoch passes).\n\n/**\n * The skip decision. A CLASS, not an interface (CLAUDE.md rule 1), because it carries a THIRD fact\n * beyond yes/no that a caller has to be able to read rather than read about in a log line.\n *\n * `hatchNotApplied` is that fact: a branch hatch WAS configured, and it could NOT apply — today only\n * because HEAD is detached (a tag checkout, a `git bisect` step, a CI checkout of a merge ref). The rule\n * is ENFORCED in that case, so there is nothing to report unless the rule then FAILS; when it does, its\n * own RuleFailError is where this belongs, as context on why the hatch the config shows did not save it.\n *\n * It is deliberately NOT printed here. Everything in this framework throws to ONE place that renders per\n * audience; a console write from a library function cannot be caught, re-rendered or asserted on.\n */\nexport class SkipRuleResult {\n    skip: boolean;\n    /** Why the rule IS being skipped. '' whenever `skip` is false. */\n    reason: string;\n    /** Why a CONFIGURED branch hatch did not apply, or '' when there is nothing to say. */\n    hatchNotApplied: string;\n\n    constructor(skip: boolean, reason: string = '', hatchNotApplied: string = '') {\n        this.skip = skip;\n        this.reason = reason;\n        this.hatchNotApplied = hatchNotApplied;\n    }\n}\n\n// The actual checked-out branch. The grab bag of ambient env vars (BRANCH_NAME, GIT_BRANCH,\n// CI_COMMIT_BRANCH, …) was intentionally REMOVED and must stay removed: a stray GIT_BRANCH=main\n// locally made this return \"main\" on a feature branch, which (a) mislabeled the main-sync cache and\n// (b) silently disabled merged-PR detection (detectMergedPr skips \"main\").\n//\n// The two vars below are NOT that. They are consulted BEFORE git because git cannot answer at all in\n// the case they cover — a `pull_request` checkout leaves HEAD detached on refs/pull/<N>/merge, where\n// `git rev-parse --abbrev-ref HEAD` returns the literal string \"HEAD\" and no branch hatch can match.\n// Neither can go stale the way GIT_BRANCH did:\n//   GITHUB_HEAD_REF  — set by the GitHub runner ONLY on pull_request/pull_request_target, and it IS\n//                      the source branch name. Absent on push, so the fallthrough stays safe. (Not\n//                      GITHUB_REF_NAME: on pull_request that is \"<N>/merge\", not a branch.)\n//   WEBPIECES_BRANCH — one documented opt-in override for CI systems not special-cased here\n//                      (GitLab, CircleCI, Buildkite). Nobody sets it by accident.\n//\n// This getter answers \"what branch am I on?\" and NOTHING about whether that answer may be TRUSTED to\n// unlock an escape hatch. That second question is asked by shouldSkipRule alone (see\n// assertBranchIsTrustworthy) because this getter has callers — the main-sync cache label, merged-PR\n// detection, code-rules' re-export of it — for which a fork's own branch name is a perfectly good\n// answer, and making the getter itself throw would redden all of them.\nexport function getCurrentBranch(): string {\n    const prBranch = process.env['GITHUB_HEAD_REF'];\n    if (prBranch) return prBranch;\n\n    const override = process.env['WEBPIECES_BRANCH'];\n    if (override) return override;\n\n    // webpieces-disable no-unmanaged-exceptions -- rethrow as InformAiError so global catch surfaces readable message to AI\n    // eslint-disable-next-line @webpieces/no-unmanaged-exceptions -- rethrow as InformAiError so global catch surfaces readable message to AI\n    try {\n        return execSync('git rev-parse --abbrev-ref HEAD', { encoding: 'utf8' }).trim();\n    } catch (err: unknown) {\n        const error = toError(err);\n        throw new InformAiError(`Failed to determine current git branch: ${error.message}`, { cause: error });\n    }\n}\n\n// The slice of the GitHub `pull_request` event payload that says WHO OWNS the head branch. Only the\n// one field below is read; everything else in that file is ignored.\ninterface RawPullRequestEvent {\n    pull_request?: {\n        head?: {\n            repo?: {\n                full_name?: string;\n            };\n        };\n    };\n}\n\n/**\n * Refuse the branch hatch on a pull request whose head branch this repo does not own.\n *\n * The hole it closes: hatch names live in `webpieces.config.json`, which is COMMITTED and public. On a\n * `pull_request` from a FORK the runner sets GITHUB_HEAD_REF to the FORK AUTHOR's branch name, so an\n * outside contributor who names their branch after one of your hatches silently disables that rule on\n * their PR — the one place you least want a rule off.\n *\n * It is answered with no network and no token, from `$GITHUB_EVENT_PATH` — a JSON file the runner writes\n * before the job starts:\n *   - `pull_request_target` runs with the BASE repo's secrets against contributor-authored code, so it is\n *     untrusted unconditionally; there is nothing to compare.\n *   - `pull_request` is trusted only when the head repo's `full_name` EQUALS `GITHUB_REPOSITORY`.\n *\n * \"Cannot tell\" counts as untrusted — a `pull_request` run with no readable event file cannot make the\n * comparison, and a hatch that cannot be proven to be yours must not fire.\n *\n * This is the ONE hard failure left in this module, and it is not the \"no branch here\" case (see\n * shouldSkipRule, which enforces quietly when HEAD is detached). It is a hatch name that DOES resolve but\n * is attacker-chosen — a security property, not a checkout that happens not to be editing.\n *\n * Called ONLY from inside `if (branchName)`. With turnOffRuleWhileOnBranch null — the overwhelmingly\n * common value — nothing here runs and no fork PR is affected in any way.\n */\n// webpieces-disable no-function-outside-class -- module-scope helper of the module-scope shouldSkipRule it serves; this whole module is functional by design (imported as free functions by code-rules, ai-hook-rules and the nx executors)\nfunction assertBranchIsTrustworthy(branchName: string): void {\n    const eventName = process.env['GITHUB_EVENT_NAME'];\n    if (eventName !== 'pull_request' && eventName !== 'pull_request_target') return;\n    if (eventName === 'pull_request_target') throw forkRefusal(branchName, 'pull_request_target run');\n\n    const headRepo = readHeadRepoFullName(branchName);\n    const thisRepo = process.env['GITHUB_REPOSITORY'] ?? '';\n    if (headRepo !== null && thisRepo !== '' && headRepo === thisRepo) return;\n    throw forkRefusal(branchName, headRepo === null\n        ? 'pull_request run with no readable $GITHUB_EVENT_PATH, so the head branch cannot be proven to belong to this repo'\n        : `pull_request run whose head branch lives in \"${headRepo}\", not in \"${thisRepo}\"`);\n}\n\n/**\n * The head repo's `owner/name` from the runner's event file, or null when there is no such file.\n *\n * A file that exists but cannot be parsed is a different thing from one that is absent, and it throws:\n * it means the runner wrote something this code does not understand, and silently downgrading that to\n * \"untrusted\" would hide a real incompatibility behind a message about forks.\n */\n// webpieces-disable no-function-outside-class -- module-scope helper, see assertBranchIsTrustworthy\nfunction readHeadRepoFullName(branchName: string): string | null {\n    const eventPath = process.env['GITHUB_EVENT_PATH'];\n    if (!eventPath || !fs.existsSync(eventPath)) return null;\n    // webpieces-disable no-unmanaged-exceptions -- chokepoint: a raw SyntaxError from the runner's event file would say nothing about hatches; this names the hatch, the file and the rule that stayed ON\n    // eslint-disable-next-line @webpieces/no-unmanaged-exceptions -- see above\n    try {\n        const parsed = JSON.parse(fs.readFileSync(eventPath, 'utf8')) as RawPullRequestEvent;\n        return parsed.pull_request?.head?.repo?.full_name ?? null;\n    } catch (err: unknown) {\n        const error = toError(err);\n        throw new RuleFailError(\n            'turnOffRuleWhileOnBranch',\n            `turnOffRuleWhileOnBranch: \"${branchName}\" is configured and this is a pull_request run, so the ` +\n                `head repository must be checked before the hatch may fire — but the runner's event file ` +\n                `${eventPath} could not be read: ${error.message}`,\n            undefined,\n            undefined,\n            [new Option('Use turnOffRuleUntilEpoch instead — it is TIME based and needs no event file.', true),\n             new Option('Or clear turnOffRuleWhileOnBranch (set it to null) so no trust check is needed at all.')],\n            undefined,\n            error);\n    }\n}\n\n/**\n * The fork refusal, as a `RuleFailError`.\n *\n * The cures are `fixOptions` — a LIST of `Option` — because the framework owns how they are labelled\n * and numbered (`formatFixOptions` renders \"Fix Option N:\" and the \"(preferred)\" tag for BOTH engines).\n * A hand-numbered \"WORKAROUNDS: 1. … 2. …\" string literal, which is what this used to be, is exactly\n * the shape `Option` exists to prevent. `Option` lives HERE in `rules-config`, so the same class serves\n * this build-time throw and `FixHint` in `ai-hook-rules` — one cure shape, one definition.\n *\n * `ruleName` is the HATCH, not the rule being evaluated: `shouldSkipRule` is handed only the two hatch\n * values and does not know whose rule it is deciding for — and the thing that failed genuinely is the\n * hatch, which cannot be honored here.\n */\n// webpieces-disable no-function-outside-class -- module-scope helper, see assertBranchIsTrustworthy\nfunction forkRefusal(branchName: string, what: string): RuleFailError {\n    return new RuleFailError(\n        'turnOffRuleWhileOnBranch',\n        `turnOffRuleWhileOnBranch: \"${branchName}\" is configured, but this is a ${what}. The branch name ` +\n            `there is chosen by the PULL REQUEST AUTHOR, and hatch names are public (webpieces.config.json ` +\n            `is committed), so honoring the hatch would let anyone turn this rule off on their own PR just ` +\n            `by naming their branch after it. The rule is NOT skipped, and this fails loudly rather than ` +\n            `quietly enforcing a rule the config says is off.`,\n        undefined,\n        undefined,\n        [\n            new Option(\n                'If the rule must be off for outside contributions too, use turnOffRuleUntilEpoch — it is TIME ' +\n                    'based, so it cannot be self-granted by naming a branch. Keep the date short: it is repo-wide ' +\n                    'while it lasts, so it also shelters unrelated work landing in the same window.',\n                true,\n            ),\n            new Option(\n                'Otherwise clear turnOffRuleWhileOnBranch (set it to null) and fix the findings on the ' +\n                    'contributed branch like any other.',\n            ),\n        ],\n    );\n}\n\nexport function shouldSkipRule(\n    epoch: number | undefined,\n    // The branch hatch is an EXACT branch name — compared with `===`, never a glob, regex or prefix.\n    // That is deliberate and is not to be \"improved\": the hatch turns a rule OFF, and a pattern lets one\n    // config line switch rules off on branches nobody enumerated when it was written. If two branches\n    // need the same rule off, that is two branches renamed to one hatch name, not one wildcard.\n    //\n    // null (the \"no branch / always on\" value of turnOffRuleWhileOnBranch) is treated exactly like\n    // undefined — no branch scoping. Only a non-empty branch name activates the branch hatch.\n    branchName: string | undefined | null\n): SkipRuleResult {\n    if (branchName) {\n        // The fork gate fires ONLY inside `if (branchName)`. With turnOffRuleWhileOnBranch=null — the\n        // overwhelmingly common value — nothing below runs, so an outside contribution to a repo that\n        // configured no hatch is an ordinary run.\n        //\n        // A DETACHED HEAD is NOT an error here. The branch hatch exists to relax a rule while you EDIT on\n        // a branch; a tag checkout or a `git bisect` step is not editing (you cannot commit to a tag, and\n        // to edit you branch off it first). So when no branch can be resolved the hatch simply does not\n        // apply and THE RULE IS ENFORCED — whoever hits a violation then gets that rule's own message and\n        // cure, which is the useful output. WHY the hatch did not fire rides back on the result\n        // (SkipRuleResult.hatchNotApplied) rather than being printed, so a caller that does fail can fold\n        // it into its own error instead of a library writing to a console nobody can catch.\n        assertBranchIsTrustworthy(branchName);\n        const current = getCurrentBranch();\n        if (current === 'HEAD' || current === '') {\n            return new SkipRuleResult(false, '',\n                `turnOffRuleWhileOnBranch: \"${branchName}\" did not apply — HEAD is detached, so there is no ` +\n                `branch to match (a tag checkout, a git bisect step, or a CI checkout of a merge ref).`);\n        }\n        if (current === branchName) {\n            return new SkipRuleResult(true, `on branch \"${branchName}\"`);\n        }\n    }\n    if (epoch !== undefined) {\n        const nowSeconds = Date.now() / 1000;\n        if (nowSeconds < epoch) {\n            const expiresDate = new Date(epoch * 1000).toISOString().split('T')[0];\n            return new SkipRuleResult(true, `turnOffRuleUntilEpoch active, expires: ${expiresDate}`);\n        }\n    }\n    return new SkipRuleResult(false);\n}\n"]}

package/src/validate-config.d.ts

@@ -2,6 +2,18 @@ import { validateChecklistsSection } from './pr-gate-section-validators';
 export { validateChecklistsSection };
 export { allRuleNames } from './rule-schemas';
 export { recommendedSeedMode, recommendedSeedModeFor, seedEntryForRule } from './seed-entry';
+/**
+ * The longest a `turnOffRuleUntilEpoch` may reach into the future: ONE WEEK. Poke it again next week to
+ * extend — that weekly re-set IS the intended workflow, not a workaround: it is what makes a rule that is
+ * off on purpose stay a decision somebody keeps making, instead of one nobody remembers.
+ *
+ * DELIBERATELY ASYMMETRIC with turnOffRuleWhileOnBranch, which has NO cap and must not get one. The epoch
+ * hatch is REPO-WIDE while it lasts, so a long window shelters every unrelated change that lands inside it
+ * (a fleet repo was found with max-file-lines/max-method-lines switched off until 2026-10-01 — 43 days
+ * out, six times this cap). The branch hatch fires only on ONE exact branch name — a big refactor
+ * legitimately runs 35+ days, and capping that would only interrupt the one branch that opted in.
+ */
+export declare const MAX_TURN_OFF_EPOCH_DAYS = 7;
 export declare function validateWebpiecesConfig(rawRules: Record<string, Record<string, unknown>>, hasCustomRulesDir?: boolean): string[];
 /**
  * Validate the top-level `pr-gate` section. It is REQUIRED (a client that opts out sets mode "OFF").