@webpieces/rules-config 0.4.705 → 0.4.707

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@webpieces/rules-config",
-  "version": "0.4.705",
+  "version": "0.4.707",
   "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-refusal.d.ts

@@ -0,0 +1,49 @@
+import { ChecklistVerdict, RequiredChecklist } from './review-json-data';
+/**
+ * THE renderer for "this reviewer said no" — one wording for every refusal, wherever it surfaces.
+ *
+ * It is its own class for the reason {@link ReviewerVerdictGate} is: this is the text an AI ACTS ON, so it
+ * is the piece most worth asserting on directly, and `review-json.ts` was already at its file-size limit.
+ * The behaviour is unchanged by the move — `ReviewJsonService.refusalError` delegates here, so there is
+ * still exactly ONE implementation and no call site has two spellings to choose between.
+ *
+ * The text was previously inlined inside review.json validation, reachable only through that path, while
+ * the command layer refused earlier with its own generic message. Two messages for one event is how the
+ * useful one became unreachable.
+ *
+ * It always quotes the reviewer's own words verbatim: the finding is the whole point, and an error that
+ * names a checklist without saying what it objected to gives the reader nothing to act on.
+ *
+ * `@injectable(bindingScopeValues.Singleton)` so it is injected by type and drawn in the DI design.
+ */
+export declare class ChecklistRefusalRenderer {
+    /**
+     * One refusal, in the terms its own verdict demands.
+     *
+     * `archivedPath` non-empty ⇒ the verdict has just been RETIRED (moved) there, which changes the message
+     * in two ways: it says where the record went, so the move does not read as data loss, and it asks for a
+     * FRESH verdict file rather than pointing at a path that no longer exists.
+     */
+    render(req: RequiredChecklist, verdict: ChecklistVerdict, archivedPath?: string): string;
+    /**
+     * The refusal for an override NOBODY AUTHORIZED — a reviewer went red and then wrote its own
+     * ship-anyway justification, with no signed human approval on the branch behind it.
+     *
+     * Worded as a completely different event from a plain refusal, because it asks for a different action.
+     * A refusal says FIX THE FINDING. This says: the decision to accept the finding is not yours to make, so
+     * STOP and ask a person — and it names the command that person runs. Telling this reader to fix the code
+     * would send them to re-do work somebody may already have decided to accept, and telling them to "get an
+     * override" is what they already, wrongly, did.
+     */
+    private unauthorizedOverride;
+    /**
+     * The ONE sentence that names the human-authorization channel, so every refusal says it identically.
+     *
+     * Deliberately addressed to the AGENT about what to ASK FOR, not about what to run: `wp-authorize` reads
+     * from `/dev/tty` and an agent has none, so an agent that tries it hangs or is denied. `wp-check-auth` is
+     * the half an agent runs, and it is named second so there is something to do once the human is done.
+     */
+    private authorizeHint;
+    /** The verdict file a checklist id maps to. Duplicated nowhere — ReviewJsonService asks this class. */
+    checklistFileName(checklistId: string): string;
+}

package/src/checklist-refusal.js

@@ -0,0 +1,92 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.ChecklistRefusalRenderer = void 0;
+const tslib_1 = require("tslib");
+const inversify_1 = require("inversify");
+const review_json_data_1 = require("./review-json-data");
+/**
+ * THE renderer for "this reviewer said no" — one wording for every refusal, wherever it surfaces.
+ *
+ * It is its own class for the reason {@link ReviewerVerdictGate} is: this is the text an AI ACTS ON, so it
+ * is the piece most worth asserting on directly, and `review-json.ts` was already at its file-size limit.
+ * The behaviour is unchanged by the move — `ReviewJsonService.refusalError` delegates here, so there is
+ * still exactly ONE implementation and no call site has two spellings to choose between.
+ *
+ * The text was previously inlined inside review.json validation, reachable only through that path, while
+ * the command layer refused earlier with its own generic message. Two messages for one event is how the
+ * useful one became unreachable.
+ *
+ * It always quotes the reviewer's own words verbatim: the finding is the whole point, and an error that
+ * names a checklist without saying what it objected to gives the reader nothing to act on.
+ *
+ * `@injectable(bindingScopeValues.Singleton)` so it is injected by type and drawn in the DI design.
+ */
+let ChecklistRefusalRenderer = class ChecklistRefusalRenderer {
+    /**
+     * One refusal, in the terms its own verdict demands.
+     *
+     * `archivedPath` non-empty ⇒ the verdict has just been RETIRED (moved) there, which changes the message
+     * in two ways: it says where the record went, so the move does not read as data loss, and it asks for a
+     * FRESH verdict file rather than pointing at a path that no longer exists.
+     */
+    render(req, verdict, archivedPath = '') {
+        if (verdict.status === review_json_data_1.CK_UNAUTHORIZED)
+            return this.unauthorizedOverride(req, verdict, archivedPath);
+        const finding = `${verdict.detail.split('\n').join('\n      ')}\n`;
+        const head = `Checklist "${req.id}" FAILED review (status:"${review_json_data_1.VERDICT_RED}"). The reviewer (${req.subagent}) wrote:\n      ` + finding;
+        if (archivedPath === '') {
+            return head +
+                `      Fix it, then re-run. To ship it UNFIXED instead, a HUMAN must authorize it — see ` +
+                `${this.authorizeHint(req.id)}`;
+        }
+        // Re-spawning is the LAST thing said, and only after the finding, because an instruction to spawn a
+        // subagent is the one line an AI acts on first — see refusedChecklists for what that cost.
+        return head +
+            `      That verdict has been RETIRED to ${archivedPath} (audit only — it is not a live verdict).\n` +
+            `      A FRESH ${this.checklistFileName(req.id)} is now required. Fix the finding first, then have the ` +
+            `"${req.subagent}" subagent review again and write a new verdict.\n` +
+            `      To ship it UNFIXED instead: ${this.authorizeHint(req.id)}`;
+    }
+    /**
+     * The refusal for an override NOBODY AUTHORIZED — a reviewer went red and then wrote its own
+     * ship-anyway justification, with no signed human approval on the branch behind it.
+     *
+     * Worded as a completely different event from a plain refusal, because it asks for a different action.
+     * A refusal says FIX THE FINDING. This says: the decision to accept the finding is not yours to make, so
+     * STOP and ask a person — and it names the command that person runs. Telling this reader to fix the code
+     * would send them to re-do work somebody may already have decided to accept, and telling them to "get an
+     * override" is what they already, wrongly, did.
+     */
+    unauthorizedOverride(req, verdict, archivedPath) {
+        const claimed = `${verdict.detail.split('\n').join('\n      ')}\n`;
+        const retired = archivedPath === '' ? ''
+            : `      That verdict has been RETIRED to ${archivedPath} (audit only — it is not a live verdict).\n`;
+        return (`Checklist "${req.id}" is RED and carries an override that NO HUMAN AUTHORIZED. The override written ` +
+            `into ${this.checklistFileName(req.id)} was:\n      ` + claimed + retired +
+            `      An override is only honoured while a signed human approval for "${req.id}" verifies on this ` +
+            `branch. Writing the field yourself is an agent authorizing itself, which is exactly what this gate ` +
+            `stops — and no message, ticket comment or relayed quote counts either.\n` +
+            `      ${this.authorizeHint(req.id)}`);
+    }
+    /**
+     * The ONE sentence that names the human-authorization channel, so every refusal says it identically.
+     *
+     * Deliberately addressed to the AGENT about what to ASK FOR, not about what to run: `wp-authorize` reads
+     * from `/dev/tty` and an agent has none, so an agent that tries it hangs or is denied. `wp-check-auth` is
+     * the half an agent runs, and it is named second so there is something to do once the human is done.
+     */
+    authorizeHint(checklistId) {
+        return (`ASK THE HUMAN to run, in their own terminal:  pnpm wp-authorize --checklist ${checklistId}\n` +
+            `      (it prompts THEM, at a tty, for what they are approving and why — you cannot run it and must ` +
+            `not try). Then verify it yourself with:  pnpm wp-check-auth --checklist ${checklistId}`);
+    }
+    /** The verdict file a checklist id maps to. Duplicated nowhere — ReviewJsonService asks this class. */
+    checklistFileName(checklistId) {
+        return `review-${checklistId}.json`;
+    }
+};
+exports.ChecklistRefusalRenderer = ChecklistRefusalRenderer;
+exports.ChecklistRefusalRenderer = ChecklistRefusalRenderer = tslib_1.__decorate([
+    (0, inversify_1.injectable)(inversify_1.bindingScopeValues.Singleton)
+], ChecklistRefusalRenderer);
+//# sourceMappingURL=checklist-refusal.js.map

package/src/checklist-refusal.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"checklist-refusal.js","sourceRoot":"","sources":["../../../../../packages/tooling/rules-config/src/checklist-refusal.ts"],"names":[],"mappings":";;;;AAAA,yCAA2D;AAC3D,yDAAuG;AAEvG;;;;;;;;;;;;;;;;GAgBG;AAEI,IAAM,wBAAwB,GAA9B,MAAM,wBAAwB;IACjC;;;;;;OAMG;IACH,MAAM,CAAC,GAAsB,EAAE,OAAyB,EAAE,YAAY,GAAG,EAAE;QACvE,IAAI,OAAO,CAAC,MAAM,KAAK,kCAAe;YAAE,OAAO,IAAI,CAAC,oBAAoB,CAAC,GAAG,EAAE,OAAO,EAAE,YAAY,CAAC,CAAC;QACrG,MAAM,OAAO,GAAG,GAAG,OAAO,CAAC,MAAM,CAAC,KAAK,CAAC,IAAI,CAAC,CAAC,IAAI,CAAC,UAAU,CAAC,IAAI,CAAC;QACnE,MAAM,IAAI,GAAG,cAAc,GAAG,CAAC,EAAE,4BAA4B,8BAAW,qBAAqB,GAAG,CAAC,QAAQ,kBAAkB,GAAG,OAAO,CAAC;QACtI,IAAI,YAAY,KAAK,EAAE,EAAE,CAAC;YACtB,OAAO,IAAI;gBACP,yFAAyF;gBACzF,GAAG,IAAI,CAAC,aAAa,CAAC,GAAG,CAAC,EAAE,CAAC,EAAE,CAAC;QACxC,CAAC;QACD,oGAAoG;QACpG,2FAA2F;QAC3F,OAAO,IAAI;YACP,0CAA0C,YAAY,6CAA6C;YACnG,iBAAiB,IAAI,CAAC,iBAAiB,CAAC,GAAG,CAAC,EAAE,CAAC,yDAAyD;YACxG,IAAI,GAAG,CAAC,QAAQ,oDAAoD;YACpE,qCAAqC,IAAI,CAAC,aAAa,CAAC,GAAG,CAAC,EAAE,CAAC,EAAE,CAAC;IAC1E,CAAC;IAED;;;;;;;;;OASG;IACK,oBAAoB,CAAC,GAAsB,EAAE,OAAyB,EAAE,YAAoB;QAChG,MAAM,OAAO,GAAG,GAAG,OAAO,CAAC,MAAM,CAAC,KAAK,CAAC,IAAI,CAAC,CAAC,IAAI,CAAC,UAAU,CAAC,IAAI,CAAC;QACnE,MAAM,OAAO,GAAG,YAAY,KAAK,EAAE,CAAC,CAAC,CAAC,EAAE;YACpC,CAAC,CAAC,0CAA0C,YAAY,6CAA6C,CAAC;QAC1G,OAAO,CACH,cAAc,GAAG,CAAC,EAAE,kFAAkF;YACtG,QAAQ,IAAI,CAAC,iBAAiB,CAAC,GAAG,CAAC,EAAE,CAAC,eAAe,GAAG,OAAO,GAAG,OAAO;YACzE,yEAAyE,GAAG,CAAC,EAAE,qBAAqB;YACpG,qGAAqG;YACrG,0EAA0E;YAC1E,SAAS,IAAI,CAAC,aAAa,CAAC,GAAG,CAAC,EAAE,CAAC,EAAE,CACxC,CAAC;IACN,CAAC;IAED;;;;;;OAMG;IACK,aAAa,CAAC,WAAmB;QACrC,OAAO,CACH,+EAA+E,WAAW,IAAI;YAC9F,qGAAqG;YACrG,2EAA2E,WAAW,EAAE,CAC3F,CAAC;IACN,CAAC;IAED,uGAAuG;IACvG,iBAAiB,CAAC,WAAmB;QACjC,OAAO,UAAU,WAAW,OAAO,CAAC;IACxC,CAAC;CACJ,CAAA;AArEY,4DAAwB;mCAAxB,wBAAwB;IADpC,IAAA,sBAAU,EAAC,8BAAkB,CAAC,SAAS,CAAC;GAC5B,wBAAwB,CAqEpC","sourcesContent":["import { injectable, bindingScopeValues } from 'inversify';\nimport { CK_UNAUTHORIZED, ChecklistVerdict, RequiredChecklist, VERDICT_RED } from './review-json-data';\n\n/**\n * THE renderer for \"this reviewer said no\" — one wording for every refusal, wherever it surfaces.\n *\n * It is its own class for the reason {@link ReviewerVerdictGate} is: this is the text an AI ACTS ON, so it\n * is the piece most worth asserting on directly, and `review-json.ts` was already at its file-size limit.\n * The behaviour is unchanged by the move — `ReviewJsonService.refusalError` delegates here, so there is\n * still exactly ONE implementation and no call site has two spellings to choose between.\n *\n * The text was previously inlined inside review.json validation, reachable only through that path, while\n * the command layer refused earlier with its own generic message. Two messages for one event is how the\n * useful one became unreachable.\n *\n * It always quotes the reviewer's own words verbatim: the finding is the whole point, and an error that\n * names a checklist without saying what it objected to gives the reader nothing to act on.\n *\n * `@injectable(bindingScopeValues.Singleton)` so it is injected by type and drawn in the DI design.\n */\n@injectable(bindingScopeValues.Singleton)\nexport class ChecklistRefusalRenderer {\n    /**\n     * One refusal, in the terms its own verdict demands.\n     *\n     * `archivedPath` non-empty ⇒ the verdict has just been RETIRED (moved) there, which changes the message\n     * in two ways: it says where the record went, so the move does not read as data loss, and it asks for a\n     * FRESH verdict file rather than pointing at a path that no longer exists.\n     */\n    render(req: RequiredChecklist, verdict: ChecklistVerdict, archivedPath = ''): string {\n        if (verdict.status === CK_UNAUTHORIZED) return this.unauthorizedOverride(req, verdict, archivedPath);\n        const finding = `${verdict.detail.split('\\n').join('\\n      ')}\\n`;\n        const head = `Checklist \"${req.id}\" FAILED review (status:\"${VERDICT_RED}\"). The reviewer (${req.subagent}) wrote:\\n      ` + finding;\n        if (archivedPath === '') {\n            return head +\n                `      Fix it, then re-run. To ship it UNFIXED instead, a HUMAN must authorize it — see ` +\n                `${this.authorizeHint(req.id)}`;\n        }\n        // Re-spawning is the LAST thing said, and only after the finding, because an instruction to spawn a\n        // subagent is the one line an AI acts on first — see refusedChecklists for what that cost.\n        return head +\n            `      That verdict has been RETIRED to ${archivedPath} (audit only — it is not a live verdict).\\n` +\n            `      A FRESH ${this.checklistFileName(req.id)} is now required. Fix the finding first, then have the ` +\n            `\"${req.subagent}\" subagent review again and write a new verdict.\\n` +\n            `      To ship it UNFIXED instead: ${this.authorizeHint(req.id)}`;\n    }\n\n    /**\n     * The refusal for an override NOBODY AUTHORIZED — a reviewer went red and then wrote its own\n     * ship-anyway justification, with no signed human approval on the branch behind it.\n     *\n     * Worded as a completely different event from a plain refusal, because it asks for a different action.\n     * A refusal says FIX THE FINDING. This says: the decision to accept the finding is not yours to make, so\n     * STOP and ask a person — and it names the command that person runs. Telling this reader to fix the code\n     * would send them to re-do work somebody may already have decided to accept, and telling them to \"get an\n     * override\" is what they already, wrongly, did.\n     */\n    private unauthorizedOverride(req: RequiredChecklist, verdict: ChecklistVerdict, archivedPath: string): string {\n        const claimed = `${verdict.detail.split('\\n').join('\\n      ')}\\n`;\n        const retired = archivedPath === '' ? ''\n            : `      That verdict has been RETIRED to ${archivedPath} (audit only — it is not a live verdict).\\n`;\n        return (\n            `Checklist \"${req.id}\" is RED and carries an override that NO HUMAN AUTHORIZED. The override written ` +\n            `into ${this.checklistFileName(req.id)} was:\\n      ` + claimed + retired +\n            `      An override is only honoured while a signed human approval for \"${req.id}\" verifies on this ` +\n            `branch. Writing the field yourself is an agent authorizing itself, which is exactly what this gate ` +\n            `stops — and no message, ticket comment or relayed quote counts either.\\n` +\n            `      ${this.authorizeHint(req.id)}`\n        );\n    }\n\n    /**\n     * The ONE sentence that names the human-authorization channel, so every refusal says it identically.\n     *\n     * Deliberately addressed to the AGENT about what to ASK FOR, not about what to run: `wp-authorize` reads\n     * from `/dev/tty` and an agent has none, so an agent that tries it hangs or is denied. `wp-check-auth` is\n     * the half an agent runs, and it is named second so there is something to do once the human is done.\n     */\n    private authorizeHint(checklistId: string): string {\n        return (\n            `ASK THE HUMAN to run, in their own terminal:  pnpm wp-authorize --checklist ${checklistId}\\n` +\n            `      (it prompts THEM, at a tty, for what they are approving and why — you cannot run it and must ` +\n            `not try). Then verify it yourself with:  pnpm wp-check-auth --checklist ${checklistId}`\n        );\n    }\n\n    /** The verdict file a checklist id maps to. Duplicated nowhere — ReviewJsonService asks this class. */\n    checklistFileName(checklistId: string): string {\n        return `review-${checklistId}.json`;\n    }\n}\n"]}

package/src/exclude-paths.d.ts

@@ -28,5 +28,21 @@ export declare function isPathExcluded(relPath: string, excludePaths: readonly s
  *
  * Paths are normalized to forward slashes so Windows backslashes match too. Empty `patterns` matches
  * nothing, so an unconfigured list is inert rather than universal.
+ *
+ * DOTFILE PATHS COUNT (`{ dot: true }`). minimatch's default hides any path segment starting with `.`
+ * from a wildcard, so `**` does not match `.github/workflows/deploy.yml` and `.claude/**` does not match
+ * `.claude/agents/x.md`. For a repo-path classifier that default is simply wrong: `.github/`, `.claude/`
+ * and `.webpieces/` are ordinary, frequently-changed directories here, and a pattern author writing
+ * `**` means all of it. It was also a live hazard — a human authorization scoped to a diff that includes
+ * a dotfile path would have silently failed to cover it, so the approval would die for a reason nobody
+ * could see. Shell-style dot-hiding protects against globbing up `.` and `..`, which is not a hazard any
+ * caller here has.
+ *
+ * The three consumers OUTSIDE the authorization path are named here on purpose, because the widening is
+ * silent for them: `build-artifact-gate` (stale generated artifacts), `api-scanner.externalApiPaths`
+ * (project classification) and `no-custom-css-scope.allowGlobs` (an EXEMPTION list, so wider = more
+ * exempt). None configures a dot-path today, and for all three "the pattern author meant the whole
+ * subtree" is the reading they already assume — but a future dot-path entry now matches where it
+ * silently did not, and that is a deliberate decision recorded here rather than an accident.
  */
 export declare function matchesAnyGlob(relPath: string, patterns: readonly string[]): boolean;

package/src/exclude-paths.js

@@ -45,14 +45,30 @@ function isPathExcluded(relPath, excludePaths) {
  *
  * Paths are normalized to forward slashes so Windows backslashes match too. Empty `patterns` matches
  * nothing, so an unconfigured list is inert rather than universal.
+ *
+ * DOTFILE PATHS COUNT (`{ dot: true }`). minimatch's default hides any path segment starting with `.`
+ * from a wildcard, so `**` does not match `.github/workflows/deploy.yml` and `.claude/**` does not match
+ * `.claude/agents/x.md`. For a repo-path classifier that default is simply wrong: `.github/`, `.claude/`
+ * and `.webpieces/` are ordinary, frequently-changed directories here, and a pattern author writing
+ * `**` means all of it. It was also a live hazard — a human authorization scoped to a diff that includes
+ * a dotfile path would have silently failed to cover it, so the approval would die for a reason nobody
+ * could see. Shell-style dot-hiding protects against globbing up `.` and `..`, which is not a hazard any
+ * caller here has.
+ *
+ * The three consumers OUTSIDE the authorization path are named here on purpose, because the widening is
+ * silent for them: `build-artifact-gate` (stale generated artifacts), `api-scanner.externalApiPaths`
+ * (project classification) and `no-custom-css-scope.allowGlobs` (an EXEMPTION list, so wider = more
+ * exempt). None configures a dot-path today, and for all three "the pattern author meant the whole
+ * subtree" is the reading they already assume — but a future dot-path entry now matches where it
+ * silently did not, and that is a deliberate decision recorded here rather than an accident.
  */
 // webpieces-disable no-function-outside-class -- pure path predicate, sibling of isPathExcluded above
 function matchesAnyGlob(relPath, patterns) {
     const norm = relPath.replace(/\\/g, '/');
     for (const pattern of patterns) {
-        if ((0, minimatch_1.minimatch)(norm, pattern))
+        if ((0, minimatch_1.minimatch)(norm, pattern, { dot: true }))
             return true;
-        if ((0, minimatch_1.minimatch)(norm, `${pattern}/**`))
+        if ((0, minimatch_1.minimatch)(norm, `${pattern}/**`, { dot: true }))
             return true;
     }
     return false;

package/src/exclude-paths.js.map

@@ -1 +1 @@
-{"version":3,"file":"exclude-paths.js","sourceRoot":"","sources":["../../../../../packages/tooling/rules-config/src/exclude-paths.ts"],"names":[],"mappings":";;AAoBA,wCASC;AAeD,wCAOC;AAnDD,yCAAsC;AAEtC;;;;;;;;;;;;;;;;;GAiBG;AACH,SAAgB,cAAc,CAAC,OAAe,EAAE,YAA+B;IAC3E,MAAM,IAAI,GAAG,OAAO,CAAC,OAAO,CAAC,KAAK,EAAE,GAAG,CAAC,CAAC;IACzC,MAAM,QAAQ,GAAG,IAAI,CAAC,KAAK,CAAC,GAAG,CAAC,CAAC;IACjC,KAAK,MAAM,OAAO,IAAI,YAAY,EAAE,CAAC;QACjC,IAAI,QAAQ,CAAC,QAAQ,CAAC,OAAO,CAAC;YAAE,OAAO,IAAI,CAAC;QAC5C,IAAI,IAAA,qBAAS,EAAC,IAAI,EAAE,OAAO,CAAC;YAAE,OAAO,IAAI,CAAC;QAC1C,IAAI,IAAA,qBAAS,EAAC,IAAI,EAAE,GAAG,OAAO,KAAK,CAAC;YAAE,OAAO,IAAI,CAAC;IACtD,CAAC;IACD,OAAO,KAAK,CAAC;AACjB,CAAC;AAED;;;;;;;;;;;GAWG;AACH,sGAAsG;AACtG,SAAgB,cAAc,CAAC,OAAe,EAAE,QAA2B;IACvE,MAAM,IAAI,GAAG,OAAO,CAAC,OAAO,CAAC,KAAK,EAAE,GAAG,CAAC,CAAC;IACzC,KAAK,MAAM,OAAO,IAAI,QAAQ,EAAE,CAAC;QAC7B,IAAI,IAAA,qBAAS,EAAC,IAAI,EAAE,OAAO,CAAC;YAAE,OAAO,IAAI,CAAC;QAC1C,IAAI,IAAA,qBAAS,EAAC,IAAI,EAAE,GAAG,OAAO,KAAK,CAAC;YAAE,OAAO,IAAI,CAAC;IACtD,CAAC;IACD,OAAO,KAAK,CAAC;AACjB,CAAC","sourcesContent":["import { minimatch } from 'minimatch';\n\n/**\n * Holistic exclusion check shared by validate-ts-in-src (Layer 1 + Layer 2)\n * and the file-location AI-hook rule, so the two implementations can never\n * drift apart again.\n *\n * `relPath` is a workspace-relative path (e.g.\n * \"libraries/foo/codegen.ts\"). An entry in `excludePaths` matches when ANY\n * of the following hold:\n *\n *   1. Bare directory/segment name appearing anywhere in the path. This is\n *      the historical behavior and keeps entries like \"node_modules\",\n *      \"dist\", \"scripts\", \"architecture\" working at any depth.\n *   2. A glob matched against the full relative path, e.g. \"**\\/*.d.ts\" or\n *      \"**\\/codegen.ts\".\n *   3. A directory-prefix glob, e.g. \"libraries/apis\" -> \"libraries/apis/**\".\n *\n * Paths are normalized to forward slashes so Windows backslashes match too.\n */\nexport function isPathExcluded(relPath: string, excludePaths: readonly string[]): boolean {\n    const norm = relPath.replace(/\\\\/g, '/');\n    const segments = norm.split('/');\n    for (const pattern of excludePaths) {\n        if (segments.includes(pattern)) return true;\n        if (minimatch(norm, pattern)) return true;\n        if (minimatch(norm, `${pattern}/**`)) return true;\n    }\n    return false;\n}\n\n/**\n * Does `relPath` match any of `patterns`, as a glob or as a directory prefix?\n *\n * The strict sibling of {@link isPathExcluded}: it drops rule 1 (bare segment name matching anywhere\n * in the path), which is right for an opt-out exclusion list but wrong for anything that CLASSIFIES\n * a path — a pattern like \"external\" would otherwise claim every path containing that segment at any\n * depth. Used for config lists that positively identify a set of projects (e.g.\n * `runtime-architecture.externalApiPaths`).\n *\n * Paths are normalized to forward slashes so Windows backslashes match too. Empty `patterns` matches\n * nothing, so an unconfigured list is inert rather than universal.\n */\n// webpieces-disable no-function-outside-class -- pure path predicate, sibling of isPathExcluded above\nexport function matchesAnyGlob(relPath: string, patterns: readonly string[]): boolean {\n    const norm = relPath.replace(/\\\\/g, '/');\n    for (const pattern of patterns) {\n        if (minimatch(norm, pattern)) return true;\n        if (minimatch(norm, `${pattern}/**`)) return true;\n    }\n    return false;\n}\n"]}
+{"version":3,"file":"exclude-paths.js","sourceRoot":"","sources":["../../../../../packages/tooling/rules-config/src/exclude-paths.ts"],"names":[],"mappings":";;AAoBA,wCASC;AA+BD,wCAOC;AAnED,yCAAsC;AAEtC;;;;;;;;;;;;;;;;;GAiBG;AACH,SAAgB,cAAc,CAAC,OAAe,EAAE,YAA+B;IAC3E,MAAM,IAAI,GAAG,OAAO,CAAC,OAAO,CAAC,KAAK,EAAE,GAAG,CAAC,CAAC;IACzC,MAAM,QAAQ,GAAG,IAAI,CAAC,KAAK,CAAC,GAAG,CAAC,CAAC;IACjC,KAAK,MAAM,OAAO,IAAI,YAAY,EAAE,CAAC;QACjC,IAAI,QAAQ,CAAC,QAAQ,CAAC,OAAO,CAAC;YAAE,OAAO,IAAI,CAAC;QAC5C,IAAI,IAAA,qBAAS,EAAC,IAAI,EAAE,OAAO,CAAC;YAAE,OAAO,IAAI,CAAC;QAC1C,IAAI,IAAA,qBAAS,EAAC,IAAI,EAAE,GAAG,OAAO,KAAK,CAAC;YAAE,OAAO,IAAI,CAAC;IACtD,CAAC;IACD,OAAO,KAAK,CAAC;AACjB,CAAC;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;;GA2BG;AACH,sGAAsG;AACtG,SAAgB,cAAc,CAAC,OAAe,EAAE,QAA2B;IACvE,MAAM,IAAI,GAAG,OAAO,CAAC,OAAO,CAAC,KAAK,EAAE,GAAG,CAAC,CAAC;IACzC,KAAK,MAAM,OAAO,IAAI,QAAQ,EAAE,CAAC;QAC7B,IAAI,IAAA,qBAAS,EAAC,IAAI,EAAE,OAAO,EAAE,EAAE,GAAG,EAAE,IAAI,EAAE,CAAC;YAAE,OAAO,IAAI,CAAC;QACzD,IAAI,IAAA,qBAAS,EAAC,IAAI,EAAE,GAAG,OAAO,KAAK,EAAE,EAAE,GAAG,EAAE,IAAI,EAAE,CAAC;YAAE,OAAO,IAAI,CAAC;IACrE,CAAC;IACD,OAAO,KAAK,CAAC;AACjB,CAAC","sourcesContent":["import { minimatch } from 'minimatch';\n\n/**\n * Holistic exclusion check shared by validate-ts-in-src (Layer 1 + Layer 2)\n * and the file-location AI-hook rule, so the two implementations can never\n * drift apart again.\n *\n * `relPath` is a workspace-relative path (e.g.\n * \"libraries/foo/codegen.ts\"). An entry in `excludePaths` matches when ANY\n * of the following hold:\n *\n *   1. Bare directory/segment name appearing anywhere in the path. This is\n *      the historical behavior and keeps entries like \"node_modules\",\n *      \"dist\", \"scripts\", \"architecture\" working at any depth.\n *   2. A glob matched against the full relative path, e.g. \"**\\/*.d.ts\" or\n *      \"**\\/codegen.ts\".\n *   3. A directory-prefix glob, e.g. \"libraries/apis\" -> \"libraries/apis/**\".\n *\n * Paths are normalized to forward slashes so Windows backslashes match too.\n */\nexport function isPathExcluded(relPath: string, excludePaths: readonly string[]): boolean {\n    const norm = relPath.replace(/\\\\/g, '/');\n    const segments = norm.split('/');\n    for (const pattern of excludePaths) {\n        if (segments.includes(pattern)) return true;\n        if (minimatch(norm, pattern)) return true;\n        if (minimatch(norm, `${pattern}/**`)) return true;\n    }\n    return false;\n}\n\n/**\n * Does `relPath` match any of `patterns`, as a glob or as a directory prefix?\n *\n * The strict sibling of {@link isPathExcluded}: it drops rule 1 (bare segment name matching anywhere\n * in the path), which is right for an opt-out exclusion list but wrong for anything that CLASSIFIES\n * a path — a pattern like \"external\" would otherwise claim every path containing that segment at any\n * depth. Used for config lists that positively identify a set of projects (e.g.\n * `runtime-architecture.externalApiPaths`).\n *\n * Paths are normalized to forward slashes so Windows backslashes match too. Empty `patterns` matches\n * nothing, so an unconfigured list is inert rather than universal.\n *\n * DOTFILE PATHS COUNT (`{ dot: true }`). minimatch's default hides any path segment starting with `.`\n * from a wildcard, so `**` does not match `.github/workflows/deploy.yml` and `.claude/**` does not match\n * `.claude/agents/x.md`. For a repo-path classifier that default is simply wrong: `.github/`, `.claude/`\n * and `.webpieces/` are ordinary, frequently-changed directories here, and a pattern author writing\n * `**` means all of it. It was also a live hazard — a human authorization scoped to a diff that includes\n * a dotfile path would have silently failed to cover it, so the approval would die for a reason nobody\n * could see. Shell-style dot-hiding protects against globbing up `.` and `..`, which is not a hazard any\n * caller here has.\n *\n * The three consumers OUTSIDE the authorization path are named here on purpose, because the widening is\n * silent for them: `build-artifact-gate` (stale generated artifacts), `api-scanner.externalApiPaths`\n * (project classification) and `no-custom-css-scope.allowGlobs` (an EXEMPTION list, so wider = more\n * exempt). None configures a dot-path today, and for all three \"the pattern author meant the whole\n * subtree\" is the reading they already assume — but a future dot-path entry now matches where it\n * silently did not, and that is a deliberate decision recorded here rather than an accident.\n */\n// webpieces-disable no-function-outside-class -- pure path predicate, sibling of isPathExcluded above\nexport function matchesAnyGlob(relPath: string, patterns: readonly string[]): boolean {\n    const norm = relPath.replace(/\\\\/g, '/');\n    for (const pattern of patterns) {\n        if (minimatch(norm, pattern, { dot: true })) return true;\n        if (minimatch(norm, `${pattern}/**`, { dot: true })) return true;\n    }\n    return false;\n}\n"]}

package/src/human-authorization.d.ts

@@ -0,0 +1,203 @@
+import { DotWebpieces } from './state-dir';
+export declare const AUTHORIZATIONS_DIR = "authorizations";
+export declare const DEFAULT_APPROVAL_HOURS = 4;
+/**
+ * ONE human approval of ONE checklist's override, on ONE branch. Data-only (per CLAUDE.md).
+ *
+ * `approves` is prose the human typed at the tty in their own words, and it is the POINT of the record:
+ * `wp-check-auth` prints it, so a reviewer can judge whether the approval actually covers the thing it is
+ * being applied to — not merely that *an* approval exists on this branch.
+ *
+ * `hmac` is `HMAC-SHA256(prGate.gateSalt, canonical payload)` over every other field plus the branch. It
+ * is what makes the approval VERIFIABLE by an agent that cannot MINT one: the agent runs `wp-check-auth`,
+ * which recomputes the HMAC, rather than believing a claim relayed to it in a message.
+ */
+export declare class HumanApproval {
+    checklist: string;
+    gate: string;
+    approves: string;
+    scopePaths: string[];
+    forkPoint: string;
+    issuedAt: string;
+    expiresAt: string;
+    hmac: string;
+    constructor(checklist: string, gate: string, approves: string, scopePaths: string[], forkPoint: string, issuedAt: string, expiresAt: string, hmac?: string);
+}
+/**
+ * The append-only authorization file for ONE branch: N approvals, each naming what it approves. Data-only.
+ *
+ * The unit is the BRANCH, not the gate, because one run of work routinely needs more than one override and
+ * they arrive at different times. One file per gate would mean the human re-answering the same "where does
+ * this go?" question on every approval.
+ */
+export declare class AuthorizationFile {
+    branch: string;
+    approvals: HumanApproval[];
+    /**
+     * '' when the file was absent or read cleanly. Non-empty = it EXISTS but could not be parsed, and the
+     * reason.
+     *
+     * Carried rather than swallowed because "no approvals" and "approvals I could not read" are different
+     * facts and the second one is actionable: a corrupt file means the human's approval is sitting on disk
+     * unreadable, and the fix is to re-authorize rather than to wonder why nothing was found. `verifiedFor`
+     * turns this into a `rejected` line, which `wp-check-auth` already prints.
+     */
+    unreadable: string;
+    constructor(branch?: string, approvals?: HumanApproval[], unreadable?: string);
+}
+/**
+ * The git facts an approval is verified AGAINST, gathered once by the caller. Data-only.
+ *
+ * A data class rather than four parameters because the four must describe ONE branch state: a `forkPoint`
+ * resolved from one tree checked against a `changedFiles` gathered from another is a verification that
+ * means nothing, and separate parameters are how that happens.
+ */
+export declare class AuthorizationContext {
+    branch: string;
+    forkPoint: string;
+    changedFiles: string[];
+    now: Date;
+    constructor(branch: string, forkPoint: string, changedFiles?: string[], now?: Date);
+}
+/**
+ * The verdict on ONE approval. `ok` false ⇒ `reason` says WHICH of the four bindings failed, in the
+ * human's terms, because that is the sentence the agent has to relay back to them. Data-only.
+ */
+export declare class AuthorizationCheck {
+    ok: boolean;
+    reason: string;
+    approval: HumanApproval | null;
+    constructor(ok: boolean, reason: string, approval: HumanApproval | null);
+}
+/**
+ * What a branch is actually authorized to override RIGHT NOW: checklist id → the human's `approves` prose.
+ * Data-only, with accessors so every consumer asks the question one way.
+ *
+ * `rejected` carries the approvals that were found but did NOT verify, one rendered line each. They are
+ * kept rather than dropped because "there is an approval on this branch, and here is why it no longer
+ * counts" is a completely different message from "nobody has authorized anything" — the first needs a
+ * re-authorization, the second needs a human at all — and an empty map cannot tell them apart.
+ */
+export declare class AuthorizedOverrides {
+    proseById: Map<string, string>;
+    rejected: string[];
+    constructor(proseById?: Map<string, string>, rejected?: string[]);
+    has(checklistId: string): boolean;
+    /** The human's own words for `checklistId`, or '' when it is not authorized. */
+    proseFor(checklistId: string): string;
+}
+/**
+ * Mints (for a HUMAN at a tty) and verifies (for ANYONE, agents included) the human-authorization records
+ * that are the ONLY channel by which a review checklist's override may be granted.
+ *
+ * ─── The problem ───────────────────────────────────────────────────────────────────────────────────────
+ * A required checklist goes red, the human authorizes the partial scope, and there is NO channel by which
+ * the subagent doing the work can know that. Every channel available before this carried a CLAIM of
+ * authorization and never EVIDENCE of it: a coordinator relaying the human's words is unverifiable by
+ * construction (and correctly refused — that refusal is the shape a prompt injection exploits); a ticket
+ * comment can be written by an agent holding the same MCP; and the `override` field in review-<id>.json is
+ * the agent authorizing itself.
+ *
+ * So the property this class buys is exactly one sentence: **an agent can VERIFY an authorization it
+ * cannot MINT.** `wp-authorize` reads the approval from `/dev/tty`, which an agent's Bash tool has no way
+ * to answer; `wp-check-auth` recomputes the HMAC and is read-only, so agents run it freely.
+ *
+ * ─── Bound to SCOPE, never to a diff sha ───────────────────────────────────────────────────────────────
+ * An approval bound to the head-commit diff would be void on the next commit, so the human would
+ * re-authorize on every push and nobody would use it. Each approval binds to WHAT WAS APPROVED instead:
+ *   • `scopePaths` — the globs the diff touched when approved. A "terraform only" approval is void the
+ *     moment app files appear, which is the abuse actually worth stopping.
+ *   • `forkPoint`  — the merge-base when approved. Survives new commits; dies if the branch is restarted.
+ *   • `expiresAt`  — hours, not days.
+ * Edits inside the approved scope keep working; widening it does not. That is what the human means when
+ * they say "yes, ship the terraform half".
+ *
+ * ─── Where the file lives, and why it is SHARED rather than per-worktree ───────────────────────────────
+ * `dotWebpieces.shared()/authorizations/<branch-slug>.json`, keyed by BRANCH. Not `local()`: the human
+ * routinely types `wp-authorize` in the primary clone while the agent works in a linked worktree, and
+ * under `local()` those are two different files — the approval would be minted somewhere the agent never
+ * looks, which is the same stall this feature exists to end. The branch key is what makes sharing safe:
+ * an approval names its branch inside the SIGNED payload, so a file copied to another branch does not
+ * verify there.
+ *
+ * It is never committed (`.webpieces/` is gitignored in full). A committed authorization would travel to
+ * branches nobody approved.
+ *
+ * ─── Honest limits — do not oversell this ─────────────────────────────────────────────────────────────
+ * The agent runs as the SAME OS USER as the human, and the HMAC key is `prGate.gateSalt`, which lives in a
+ * committed file agents read routinely. Nothing here is cryptographically airtight against a determined
+ * model; the real enforcement is the tty affordance plus the harness deny rule. That is fine, because the
+ * problem being solved is agents drifting, guessing, or being confused by relays — not an adversarial
+ * model. Moving the key to `~/.webpieces/authorize.key` is a one-line change to `sign()` if the threat
+ * model ever changes; nothing else in the design moves.
+ *
+ * `@injectable(bindingScopeValues.Singleton)` so it is injected by type and drawn in the DI design.
+ */
+export declare class HumanAuthorizationService {
+    private readonly dotDir;
+    constructor(dotDir?: DotWebpieces);
+    /** The repo-wide authorizations directory. See the class docstring for why `shared()` and not `local()`. */
+    dirFor(repoRoot: string): string;
+    /**
+     * A filesystem-safe leaf for a branch name. Slashes and anything exotic collapse to `-`, so
+     * `dean/one-2779-grants` becomes `dean-one-2779-grants`.
+     *
+     * A collision between two slugs is harmless: the branch is inside the SIGNED payload, so an approval
+     * that landed in a colliding file fails `verify` on the branch check rather than leaking across.
+     */
+    slugFor(branch: string): string;
+    pathFor(repoRoot: string, branch: string): string;
+    /**
+     * The exact bytes that get signed: a version tag, the branch, and every field of the approval EXCEPT
+     * the hmac, in a fixed order with `scopePaths` sorted.
+     *
+     * Fixed order and sorting are load-bearing — `JSON.stringify` over a re-parsed object preserves
+     * insertion order, so a round-tripped approval whose keys arrived in a different order would compute a
+     * different payload and fail to verify a signature that is perfectly good.
+     */
+    canonicalPayload(branch: string, approval: HumanApproval): string;
+    /** `HMAC-SHA256(salt, canonical payload)`. '' for an empty salt — the caller treats '' as "not configured". */
+    sign(branch: string, approval: HumanApproval, salt: string): string;
+    /** The same approval, carrying its signature. Never mutates the input. */
+    signed(branch: string, approval: HumanApproval, salt: string): HumanApproval;
+    /**
+     * Every approval recorded for `branch`, signature UNCHECKED. An absent or unreadable file is an EMPTY
+     * file, never a throw: a corrupt authorization must degrade to "nothing is authorized", which is the
+     * safe direction, and a branch that cannot open its own authorization file must still be able to run
+     * the gate and be told to go get one.
+     */
+    load(repoRoot: string, branch: string): AuthorizationFile;
+    private toApproval;
+    private str;
+    private strList;
+    /**
+     * APPEND one signed approval to the branch's file and return the path written. Append, never replace:
+     * a run of work needs several overrides at different times, and each one is its own record of intent.
+     */
+    append(repoRoot: string, branch: string, approval: HumanApproval, salt: string): string;
+    /**
+     * Verify ONE approval against the branch state, in the order a reader wants to hear it: signature,
+     * expiry, fork point, scope. Signature first — an unsigned entry's other fields are not evidence of
+     * anything, and reporting "expired" for a forged record would be answering the wrong question.
+     */
+    verify(ctx: AuthorizationContext, approval: HumanApproval, salt: string): AuthorizationCheck;
+    private fail;
+    private expired;
+    /**
+     * The changed files NOT covered by `scopePaths`. An approval with an EMPTY `scopePaths` covers nothing
+     * and is therefore always out of scope when anything changed — `wp-authorize` never mints one, and the
+     * alternative reading ("empty means everything") is precisely the widening-by-absence that makes the
+     * permissive path the shortest thing to type.
+     */
+    private outsideScope;
+    /**
+     * THE question every consumer asks: what is this branch authorized to override right now? Verifies every
+     * recorded approval and returns the ones that hold, plus a rendered line per one that does not.
+     *
+     * Later approvals win for the same checklist — the human appended it because they meant to say something
+     * newer, and the file is append-only precisely so the earlier one stays readable as history.
+     */
+    verifiedFor(repoRoot: string, ctx: AuthorizationContext, salt: string): AuthorizedOverrides;
+    /** An expiry `hours` from `issuedAt`, as ISO — the one place the TTL arithmetic lives. */
+    expiryFrom(issuedAt: Date, hours: number): string;
+}