@webpieces/ai-hook-rules 0.4.494 → 0.4.496

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@webpieces/ai-hook-rules",
-  "version": "0.4.494",
+  "version": "0.4.496",
   "description": "Pluggable write-time validation framework for AI coding agents (@webpieces/ai-hook-rules). Claude Code PreToolUse + openclaw before_tool_call adapters share one rule engine.",
   "type": "commonjs",
   "main": "./src/index.js",
@@ -32,7 +32,7 @@
     "directory": "packages/tooling/ai-hook-rules"
   },
   "dependencies": {
-    "@webpieces/rules-config": "0.4.494"
+    "@webpieces/rules-config": "0.4.496"
   },
   "publishConfig": {
     "access": "public"

package/src/core/command-scan.d.ts

@@ -61,6 +61,12 @@ export declare class CommandScanner {
      * Returns the subcommand as an EXACT token: `git merge-base …` yields `'merge-base'`, never `'merge'`.
      */
     gitSubcommand(segment: string): string | null;
+    /**
+     * gitSubcommand, for a caller that already holds the segment's effective words (ShellSegmentScan
+     * strips leading shell keywords, so `do git status` must be resolved from ITS words, not from the
+     * raw segment text where `do` is the command).
+     */
+    gitSubcommandOf(words: readonly string[]): string | null;
     /** True when this segment actually invokes `git <subcommand>`. */
     invokesGit(segment: string, subcommand: string): boolean;
     /** True when ANY segment of the command invokes one of `subcommands`. */

package/src/core/command-scan.js

@@ -82,6 +82,15 @@ class CommandScanner {
                 current += ch;
                 continue;
             }
+            // The `&` of a REDIRECTION (`2>&1`, `1>&2`, `&>log`) is not a separator. Splitting on it
+            // tore `git fetch origin main 2>&1 | tail -5` into THREE segments — `git fetch … 2>`, `1`
+            // and `tail -5` — and the bare `1` is not an allowlisted command, so every guard that
+            // requires all segments to pass denied the command. That is `2>&1`, the single most common
+            // decoration an agent appends.
+            if (ch === '&' && command[i + 1] !== '&' && (current.trimEnd().endsWith('>') || command[i + 1] === '>')) {
+                current += ch;
+                continue;
+            }
             if (ch === '\n' || ch === ';' || ch === '|' || ch === '&' || ch === '(' || ch === ')') {
                 // Consume the second char of `&&` / `||` so it does not start an empty segment.
                 const doubled = (ch === '|' || ch === '&') && command[i + 1] === ch;
@@ -116,7 +125,15 @@ class CommandScanner {
      * Returns the subcommand as an EXACT token: `git merge-base …` yields `'merge-base'`, never `'merge'`.
      */
     gitSubcommand(segment) {
-        const tokens = this.stripPrefixes(this.tokenize(segment));
+        return this.gitSubcommandOf(this.stripPrefixes(this.tokenize(segment)));
+    }
+    /**
+     * gitSubcommand, for a caller that already holds the segment's effective words (ShellSegmentScan
+     * strips leading shell keywords, so `do git status` must be resolved from ITS words, not from the
+     * raw segment text where `do` is the command).
+     */
+    gitSubcommandOf(words) {
+        const tokens = this.stripPrefixes(words);
         if (tokens.length === 0 || tokens[0] !== 'git')
             return null;
         let i = 1;

package/src/core/command-scan.js.map

@@ -1 +1 @@
-{"version":3,"file":"command-scan.js","sourceRoot":"","sources":["../../../../../../packages/tooling/ai-hook-rules/src/core/command-scan.ts"],"names":[],"mappings":"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","sourcesContent":["/**\n * Shared shell-command scanning for the bash guards.\n *\n * A guard that bans a command family (`git merge`, `git push`, …) must answer one question\n * precisely: *does this command actually invoke `git <subcommand>`?* A bare\n * `/\\bgit\\s+merge\\b/.test(command)` gets that wrong in both directions:\n *\n *  - False positive: `grep 'git merge main' notes.md` or `echo \"git rebase main\"` merely MENTION\n *    the phrase. A diagnostic grep was blocked this way while triaging the incident that motivated\n *    the merge/rebase ban.\n *  - False positive: `\\b` sits between `e` and `-`, so `/\\bgit\\s+merge\\b/` matches the read-only\n *    `git merge-base origin/main HEAD` — which appears in this repo's own documented build command.\n *\n * Both classes vanish if you tokenize instead of substring-match: a command invokes git only when a\n * segment's first word IS `git`, and the subcommand is then an exact token (`merge-base` is simply\n * not the token `merge`). No lookahead regex needed.\n */\n\n// Wrappers/prefixes that may precede the real command word (`sudo git merge`, `GIT_DIR=x git merge`).\nconst COMMAND_PREFIXES: ReadonlySet<string> = new Set(['sudo', 'command', 'nohup', 'time', 'env', 'exec']);\n\n// git's own global flags that consume the FOLLOWING token as their value, so\n// `git -C /some/path merge main` still resolves to the `merge` subcommand.\nconst GIT_FLAGS_WITH_VALUE: ReadonlySet<string> = new Set([\n    '-C', '-c', '--git-dir', '--work-tree', '--namespace', '--exec-path',\n]);\n\nconst ENV_ASSIGNMENT = /^[A-Za-z_][A-Za-z0-9_]*=/;\n\n/**\n * One invoked segment of a command, plus whether a PIPE fed it.\n *\n * `pipedInto` is what separates `git log | grep foo` (grep consumes the pipe — reads no file) from\n * `grep foo src/` (grep reads the working tree). A guard that cares about which FILES a command\n * reads cannot tell those apart from the segment text alone, because splitting on `|` throws exactly\n * that fact away. Data-only, so a class (per CLAUDE.md).\n */\nexport class CommandSegment {\n    text: string;\n    pipedInto: boolean;\n\n    constructor(text: string, pipedInto: boolean) {\n        this.text = text;\n        this.pipedInto = pipedInto;\n    }\n}\n\nexport class CommandScanner {\n    /**\n     * Split a raw command into individually-invoked segments.\n     *\n     * Splits on `&&`, `||`, `;`, `|`, `&`, newline, and the `(`/`)` of subshells and `$(…)` command\n     * substitution — the last of these matters, since it means `--base=$(git rebase main)` is scanned\n     * as its own `git rebase main` segment rather than hiding inside a `pnpm …` segment.\n     *\n     * Quoted spans are opaque: a separator inside quotes is literal text, so\n     * `git commit -m \"fix; ship it\"` stays one segment. (Corollary: a `$(…)` nested inside double\n     * quotes is not split out. Bash would expand it; we do not scan it. Contrived enough to accept.)\n     */\n    commandSegments(command: string): readonly string[] {\n        return this.segmentsWithPipes(command).map((s: CommandSegment): string => s.text);\n    }\n\n    /**\n     * commandSegments, but each segment also carries whether the separator BEFORE it was a pipe.\n     * Only a guard reasoning about which files a segment reads needs that; everything else uses\n     * commandSegments, which is this method with the flag dropped.\n     */\n    segmentsWithPipes(command: string): readonly CommandSegment[] {\n        const segments: CommandSegment[] = [];\n        let current = '';\n        let quote: string | null = null;\n        let piped = false;      // was the separator that ENDED the previous segment a pipe?\n\n        for (let i = 0; i < command.length; i++) {\n            const ch = command[i];\n\n            if (quote !== null) {\n                current += ch;\n                // A backslash-escaped quote does not close the span (only meaningful inside \"…\").\n                if (ch === quote && command[i - 1] !== '\\\\') quote = null;\n                continue;\n            }\n\n            if (ch === '\"' || ch === \"'\") {\n                quote = ch;\n                current += ch;\n                continue;\n            }\n\n            if (ch === '\\n' || ch === ';' || ch === '|' || ch === '&' || ch === '(' || ch === ')') {\n                // Consume the second char of `&&` / `||` so it does not start an empty segment.\n                const doubled = (ch === '|' || ch === '&') && command[i + 1] === ch;\n                if (doubled) i++;\n                segments.push(new CommandSegment(current, piped));\n                // `|` pipes into the next segment; `||` is a separator, not a pipe.\n                piped = ch === '|' && !doubled;\n                current = '';\n                continue;\n            }\n\n            current += ch;\n        }\n        segments.push(new CommandSegment(current, piped));\n\n        return segments\n            .map((s: CommandSegment): CommandSegment => new CommandSegment(s.text.trim(), s.pipedInto))\n            .filter((s: CommandSegment): boolean => s.text.length > 0);\n    }\n\n    /**\n     * One segment's shell words, with wrappers/env-assignments stripped, so `words('sudo cat a b')`\n     * is `['cat', 'a', 'b']`. The public view of the same tokenizer gitSubcommand uses — a guard that\n     * must inspect a NON-git command's arguments (which paths does this `grep` actually read?) needs\n     * the tokens, and re-splitting on whitespace in the guard would get quoting wrong.\n     */\n    words(segment: string): readonly string[] {\n        return this.stripPrefixes(this.tokenize(segment));\n    }\n\n    /**\n     * The git subcommand a segment invokes, or null when the segment does not invoke git at all\n     * (a different program, a mere mention inside quotes, an empty segment).\n     *\n     * Returns the subcommand as an EXACT token: `git merge-base …` yields `'merge-base'`, never `'merge'`.\n     */\n    gitSubcommand(segment: string): string | null {\n        const tokens = this.stripPrefixes(this.tokenize(segment));\n        if (tokens.length === 0 || tokens[0] !== 'git') return null;\n\n        let i = 1;\n        while (i < tokens.length) {\n            const token = tokens[i];\n            if (GIT_FLAGS_WITH_VALUE.has(token)) { i += 2; continue; }\n            // `--git-dir=/x` style (value attached) and any other global flag.\n            if (token.startsWith('-')) { i++; continue; }\n            return token;\n        }\n        return null;\n    }\n\n    /** True when this segment actually invokes `git <subcommand>`. */\n    invokesGit(segment: string, subcommand: string): boolean {\n        return this.gitSubcommand(segment) === subcommand;\n    }\n\n    /** True when ANY segment of the command invokes one of `subcommands`. */\n    commandInvokesAnyGit(command: string, subcommands: readonly string[]): boolean {\n        return this.commandSegments(command).some((seg: string) =>\n            subcommands.some((sub: string) => this.invokesGit(seg, sub)));\n    }\n\n    /**\n     * Split one segment into shell words, dropping quote characters (so the ARGUMENT of\n     * `echo \"git merge main\"` is the single word `git merge main`, never the word `git`).\n     */\n    private tokenize(segment: string): readonly string[] {\n        const tokens: string[] = [];\n        let current = '';\n        let started = false;\n        let quote: string | null = null;\n\n        for (let i = 0; i < segment.length; i++) {\n            const ch = segment[i];\n\n            if (quote !== null) {\n                if (ch === quote) quote = null;\n                else current += ch;\n                started = true;\n                continue;\n            }\n\n            if (ch === '\"' || ch === \"'\") {\n                quote = ch;\n                started = true;\n                continue;\n            }\n\n            if (/\\s/.test(ch)) {\n                if (started) {\n                    tokens.push(current);\n                    current = '';\n                    started = false;\n                }\n                continue;\n            }\n\n            current += ch;\n            started = true;\n        }\n        if (started) tokens.push(current);\n\n        return tokens;\n    }\n\n    private stripPrefixes(tokens: readonly string[]): readonly string[] {\n        let i = 0;\n        while (i < tokens.length) {\n            const token = tokens[i];\n            if (COMMAND_PREFIXES.has(token)) { i++; continue; }\n            if (ENV_ASSIGNMENT.test(token)) { i++; continue; }\n            break;\n        }\n        return tokens.slice(i);\n    }\n}\n"]}
+{"version":3,"file":"command-scan.js","sourceRoot":"","sources":["../../../../../../packages/tooling/ai-hook-rules/src/core/command-scan.ts"],"names":[],"mappings":"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","sourcesContent":["/**\n * Shared shell-command scanning for the bash guards.\n *\n * A guard that bans a command family (`git merge`, `git push`, …) must answer one question\n * precisely: *does this command actually invoke `git <subcommand>`?* A bare\n * `/\\bgit\\s+merge\\b/.test(command)` gets that wrong in both directions:\n *\n *  - False positive: `grep 'git merge main' notes.md` or `echo \"git rebase main\"` merely MENTION\n *    the phrase. A diagnostic grep was blocked this way while triaging the incident that motivated\n *    the merge/rebase ban.\n *  - False positive: `\\b` sits between `e` and `-`, so `/\\bgit\\s+merge\\b/` matches the read-only\n *    `git merge-base origin/main HEAD` — which appears in this repo's own documented build command.\n *\n * Both classes vanish if you tokenize instead of substring-match: a command invokes git only when a\n * segment's first word IS `git`, and the subcommand is then an exact token (`merge-base` is simply\n * not the token `merge`). No lookahead regex needed.\n */\n\n// Wrappers/prefixes that may precede the real command word (`sudo git merge`, `GIT_DIR=x git merge`).\nconst COMMAND_PREFIXES: ReadonlySet<string> = new Set(['sudo', 'command', 'nohup', 'time', 'env', 'exec']);\n\n// git's own global flags that consume the FOLLOWING token as their value, so\n// `git -C /some/path merge main` still resolves to the `merge` subcommand.\nconst GIT_FLAGS_WITH_VALUE: ReadonlySet<string> = new Set([\n    '-C', '-c', '--git-dir', '--work-tree', '--namespace', '--exec-path',\n]);\n\nconst ENV_ASSIGNMENT = /^[A-Za-z_][A-Za-z0-9_]*=/;\n\n/**\n * One invoked segment of a command, plus whether a PIPE fed it.\n *\n * `pipedInto` is what separates `git log | grep foo` (grep consumes the pipe — reads no file) from\n * `grep foo src/` (grep reads the working tree). A guard that cares about which FILES a command\n * reads cannot tell those apart from the segment text alone, because splitting on `|` throws exactly\n * that fact away. Data-only, so a class (per CLAUDE.md).\n */\nexport class CommandSegment {\n    text: string;\n    pipedInto: boolean;\n\n    constructor(text: string, pipedInto: boolean) {\n        this.text = text;\n        this.pipedInto = pipedInto;\n    }\n}\n\nexport class CommandScanner {\n    /**\n     * Split a raw command into individually-invoked segments.\n     *\n     * Splits on `&&`, `||`, `;`, `|`, `&`, newline, and the `(`/`)` of subshells and `$(…)` command\n     * substitution — the last of these matters, since it means `--base=$(git rebase main)` is scanned\n     * as its own `git rebase main` segment rather than hiding inside a `pnpm …` segment.\n     *\n     * Quoted spans are opaque: a separator inside quotes is literal text, so\n     * `git commit -m \"fix; ship it\"` stays one segment. (Corollary: a `$(…)` nested inside double\n     * quotes is not split out. Bash would expand it; we do not scan it. Contrived enough to accept.)\n     */\n    commandSegments(command: string): readonly string[] {\n        return this.segmentsWithPipes(command).map((s: CommandSegment): string => s.text);\n    }\n\n    /**\n     * commandSegments, but each segment also carries whether the separator BEFORE it was a pipe.\n     * Only a guard reasoning about which files a segment reads needs that; everything else uses\n     * commandSegments, which is this method with the flag dropped.\n     */\n    segmentsWithPipes(command: string): readonly CommandSegment[] {\n        const segments: CommandSegment[] = [];\n        let current = '';\n        let quote: string | null = null;\n        let piped = false;      // was the separator that ENDED the previous segment a pipe?\n\n        for (let i = 0; i < command.length; i++) {\n            const ch = command[i];\n\n            if (quote !== null) {\n                current += ch;\n                // A backslash-escaped quote does not close the span (only meaningful inside \"…\").\n                if (ch === quote && command[i - 1] !== '\\\\') quote = null;\n                continue;\n            }\n\n            if (ch === '\"' || ch === \"'\") {\n                quote = ch;\n                current += ch;\n                continue;\n            }\n\n            // The `&` of a REDIRECTION (`2>&1`, `1>&2`, `&>log`) is not a separator. Splitting on it\n            // tore `git fetch origin main 2>&1 | tail -5` into THREE segments — `git fetch … 2>`, `1`\n            // and `tail -5` — and the bare `1` is not an allowlisted command, so every guard that\n            // requires all segments to pass denied the command. That is `2>&1`, the single most common\n            // decoration an agent appends.\n            if (ch === '&' && command[i + 1] !== '&' && (current.trimEnd().endsWith('>') || command[i + 1] === '>')) {\n                current += ch;\n                continue;\n            }\n\n            if (ch === '\\n' || ch === ';' || ch === '|' || ch === '&' || ch === '(' || ch === ')') {\n                // Consume the second char of `&&` / `||` so it does not start an empty segment.\n                const doubled = (ch === '|' || ch === '&') && command[i + 1] === ch;\n                if (doubled) i++;\n                segments.push(new CommandSegment(current, piped));\n                // `|` pipes into the next segment; `||` is a separator, not a pipe.\n                piped = ch === '|' && !doubled;\n                current = '';\n                continue;\n            }\n\n            current += ch;\n        }\n        segments.push(new CommandSegment(current, piped));\n\n        return segments\n            .map((s: CommandSegment): CommandSegment => new CommandSegment(s.text.trim(), s.pipedInto))\n            .filter((s: CommandSegment): boolean => s.text.length > 0);\n    }\n\n    /**\n     * One segment's shell words, with wrappers/env-assignments stripped, so `words('sudo cat a b')`\n     * is `['cat', 'a', 'b']`. The public view of the same tokenizer gitSubcommand uses — a guard that\n     * must inspect a NON-git command's arguments (which paths does this `grep` actually read?) needs\n     * the tokens, and re-splitting on whitespace in the guard would get quoting wrong.\n     */\n    words(segment: string): readonly string[] {\n        return this.stripPrefixes(this.tokenize(segment));\n    }\n\n    /**\n     * The git subcommand a segment invokes, or null when the segment does not invoke git at all\n     * (a different program, a mere mention inside quotes, an empty segment).\n     *\n     * Returns the subcommand as an EXACT token: `git merge-base …` yields `'merge-base'`, never `'merge'`.\n     */\n    gitSubcommand(segment: string): string | null {\n        return this.gitSubcommandOf(this.stripPrefixes(this.tokenize(segment)));\n    }\n\n    /**\n     * gitSubcommand, for a caller that already holds the segment's effective words (ShellSegmentScan\n     * strips leading shell keywords, so `do git status` must be resolved from ITS words, not from the\n     * raw segment text where `do` is the command).\n     */\n    gitSubcommandOf(words: readonly string[]): string | null {\n        const tokens = this.stripPrefixes(words);\n        if (tokens.length === 0 || tokens[0] !== 'git') return null;\n\n        let i = 1;\n        while (i < tokens.length) {\n            const token = tokens[i];\n            if (GIT_FLAGS_WITH_VALUE.has(token)) { i += 2; continue; }\n            // `--git-dir=/x` style (value attached) and any other global flag.\n            if (token.startsWith('-')) { i++; continue; }\n            return token;\n        }\n        return null;\n    }\n\n    /** True when this segment actually invokes `git <subcommand>`. */\n    invokesGit(segment: string, subcommand: string): boolean {\n        return this.gitSubcommand(segment) === subcommand;\n    }\n\n    /** True when ANY segment of the command invokes one of `subcommands`. */\n    commandInvokesAnyGit(command: string, subcommands: readonly string[]): boolean {\n        return this.commandSegments(command).some((seg: string) =>\n            subcommands.some((sub: string) => this.invokesGit(seg, sub)));\n    }\n\n    /**\n     * Split one segment into shell words, dropping quote characters (so the ARGUMENT of\n     * `echo \"git merge main\"` is the single word `git merge main`, never the word `git`).\n     */\n    private tokenize(segment: string): readonly string[] {\n        const tokens: string[] = [];\n        let current = '';\n        let started = false;\n        let quote: string | null = null;\n\n        for (let i = 0; i < segment.length; i++) {\n            const ch = segment[i];\n\n            if (quote !== null) {\n                if (ch === quote) quote = null;\n                else current += ch;\n                started = true;\n                continue;\n            }\n\n            if (ch === '\"' || ch === \"'\") {\n                quote = ch;\n                started = true;\n                continue;\n            }\n\n            if (/\\s/.test(ch)) {\n                if (started) {\n                    tokens.push(current);\n                    current = '';\n                    started = false;\n                }\n                continue;\n            }\n\n            current += ch;\n            started = true;\n        }\n        if (started) tokens.push(current);\n\n        return tokens;\n    }\n\n    private stripPrefixes(tokens: readonly string[]): readonly string[] {\n        let i = 0;\n        while (i < tokens.length) {\n            const token = tokens[i];\n            if (COMMAND_PREFIXES.has(token)) { i++; continue; }\n            if (ENV_ASSIGNMENT.test(token)) { i++; continue; }\n            break;\n        }\n        return tokens.slice(i);\n    }\n}\n"]}

package/src/core/report.d.ts

@@ -1,2 +1,21 @@
 import type { RuleGroup } from './types';
-export declare function formatReport(relativePath: string, ruleGroups: readonly RuleGroup[]): string;
+/**
+ * How the report names the tool it just blocked. Data-only, so a class (per CLAUDE.md).
+ *
+ * WHY it is a parameter: the header and footer used to be hard-coded to "write". A blocked READ
+ * therefore printed "\u274c webpieces ai-hooks blocked this write:" and closed with "This is a pre-write
+ * check. Fix and retry the Write/Edit." \u2014 observed live, and actively misleading, because the agent is
+ * told to fix and retry the one tool it did not use. A blocked Bash command printed the same thing
+ * against the path `<bash>`.
+ */
+export declare class ReportSubject {
+    /** Fills "blocked this ___". */
+    noun: string;
+    /** The closing line: what kind of check this was and which tool to retry. */
+    footer: string;
+    constructor(noun: string, footer: string);
+}
+export declare const WRITE_SUBJECT: ReportSubject;
+export declare const READ_SUBJECT: ReportSubject;
+export declare const BASH_SUBJECT: ReportSubject;
+export declare function formatReport(relativePath: string, ruleGroups: readonly RuleGroup[], subject?: ReportSubject): string;

package/src/core/report.js

@@ -1,9 +1,34 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
+exports.BASH_SUBJECT = exports.READ_SUBJECT = exports.WRITE_SUBJECT = exports.ReportSubject = void 0;
 exports.formatReport = formatReport;
-function formatReport(relativePath, ruleGroups) {
+/**
+ * How the report names the tool it just blocked. Data-only, so a class (per CLAUDE.md).
+ *
+ * WHY it is a parameter: the header and footer used to be hard-coded to "write". A blocked READ
+ * therefore printed "\u274c webpieces ai-hooks blocked this write:" and closed with "This is a pre-write
+ * check. Fix and retry the Write/Edit." \u2014 observed live, and actively misleading, because the agent is
+ * told to fix and retry the one tool it did not use. A blocked Bash command printed the same thing
+ * against the path `<bash>`.
+ */
+class ReportSubject {
+    /** Fills "blocked this ___". */
+    noun;
+    /** The closing line: what kind of check this was and which tool to retry. */
+    footer;
+    constructor(noun, footer) {
+        this.noun = noun;
+        this.footer = footer;
+    }
+}
+exports.ReportSubject = ReportSubject;
+exports.WRITE_SUBJECT = new ReportSubject('write', 'This is a pre-write check. Fix and retry the Write/Edit.');
+exports.READ_SUBJECT = new ReportSubject('read', 'This is a pre-read check. Follow the fix above, then retry the Read.');
+exports.BASH_SUBJECT = new ReportSubject('command', 'This is a pre-run check. Follow the fix above, then retry the command.');
+// webpieces-disable no-function-outside-class -- pre-existing shape: this whole module is the report formatter as module-scope functions, and a lone class here would break it
+function formatReport(relativePath, ruleGroups, subject = exports.WRITE_SUBJECT) {
     const lines = [];
-    lines.push(`\u274c webpieces ai-hooks blocked this write: ${relativePath}`);
+    lines.push(`\u274c webpieces ai-hooks blocked this ${subject.noun}: ${relativePath}`);
     lines.push('');
     for (const group of ruleGroups) {
         const count = group.violations.length;
@@ -37,7 +62,7 @@ function formatReport(relativePath, ruleGroups) {
         }
         lines.push('');
     }
-    lines.push('This is a pre-write check. Fix and retry the Write/Edit.');
+    lines.push(subject.footer);
     lines.push('');
     return lines.join('\n');
 }

package/src/core/report.js.map

@@ -1 +1 @@
-{"version":3,"file":"report.js","sourceRoot":"","sources":["../../../../../../packages/tooling/ai-hook-rules/src/core/report.ts"],"names":[],"mappings":"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","sourcesContent":["import type { RuleGroup, Violation } from './types';\nimport type { Option } from './fix-hint';\n\nexport function formatReport(relativePath: string, ruleGroups: readonly RuleGroup[]): string {\n    const lines: string[] = [];\n    lines.push(`\\u274c webpieces ai-hooks blocked this write: ${relativePath}`);\n    lines.push('');\n\n    for (const group of ruleGroups) {\n        const count = group.violations.length;\n        const label = count === 1 ? '1 violation' : `${count} violations`;\n        lines.push(`[${group.ruleName}] (${label})`);\n        const fh = group.fixHint;\n        for (const v of group.violations) {\n            const editPrefix = formatEditPrefix(v);\n            lines.push(`  ${editPrefix}L${String(v.line)}:  ${v.snippet}`);\n            // Per-occurrence override (dynamic rules), else the rule-level FixHint.violation.\n            lines.push(`    \\u2192 ${v.message ?? fh.violation}`);\n        }\n        // mainMessage may be '' (guidance already on the violation line) \\u2014 skip when empty.\n        if (fh.mainMessage) for (const l of fh.mainMessage.split('\\n')) lines.push(`  ${l}`);\n        // \"Fix Option N:\" numbering + \"(preferred)\" are framework-owned so a multi-line message\n        // can never become fake options and authors never hand-write those labels.\n        fh.fixOptions.forEach((opt: Option, i: number) => {\n            const optLines = opt.text.split('\\n');\n            const tag = opt.preferred ? '(preferred) ' : '';\n            lines.push(`  Fix Option ${String(i + 1)}: ${tag}${optLines[0]}`);\n            for (const l of optLines.slice(1)) lines.push(`    ${l}`);\n        });\n        // Framework-owned disable escape (only the 9 disable-able code-style rules set this).\n        if (fh.escape) {\n            lines.push(fh.escape.allowed\n                ? `  Escape (if truly needed): ${fh.escape.comment}`\n                : '  \\u{1F512} The team disabled escaping via webpieces-disable for this rule (disableAllowed:false) — it must be followed.');\n        }\n        lines.push('');\n    }\n\n    lines.push('This is a pre-write check. Fix and retry the Write/Edit.');\n    lines.push('');\n    return lines.join('\\n');\n}\n\nfunction formatEditPrefix(v: Violation): string {\n    if (v.editIndex !== undefined && v.editCount !== undefined && v.editCount > 1) {\n        return `edit ${String(v.editIndex + 1)}/${String(v.editCount)} `;\n    }\n    return '';\n}\n"]}
+{"version":3,"file":"report.js","sourceRoot":"","sources":["../../../../../../packages/tooling/ai-hook-rules/src/core/report.ts"],"names":[],"mappings":"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","sourcesContent":["import type { RuleGroup, Violation } from './types';\nimport type { Option } from './fix-hint';\n\n/**\n * How the report names the tool it just blocked. Data-only, so a class (per CLAUDE.md).\n *\n * WHY it is a parameter: the header and footer used to be hard-coded to \"write\". A blocked READ\n * therefore printed \"\\u274c webpieces ai-hooks blocked this write:\" and closed with \"This is a pre-write\n * check. Fix and retry the Write/Edit.\" \\u2014 observed live, and actively misleading, because the agent is\n * told to fix and retry the one tool it did not use. A blocked Bash command printed the same thing\n * against the path `<bash>`.\n */\nexport class ReportSubject {\n    /** Fills \"blocked this ___\". */\n    noun: string;\n    /** The closing line: what kind of check this was and which tool to retry. */\n    footer: string;\n\n    constructor(noun: string, footer: string) {\n        this.noun = noun;\n        this.footer = footer;\n    }\n}\n\nexport const WRITE_SUBJECT = new ReportSubject(\n    'write', 'This is a pre-write check. Fix and retry the Write/Edit.');\nexport const READ_SUBJECT = new ReportSubject(\n    'read', 'This is a pre-read check. Follow the fix above, then retry the Read.');\nexport const BASH_SUBJECT = new ReportSubject(\n    'command', 'This is a pre-run check. Follow the fix above, then retry the command.');\n\n// webpieces-disable no-function-outside-class -- pre-existing shape: this whole module is the report formatter as module-scope functions, and a lone class here would break it\nexport function formatReport(\n    relativePath: string,\n    ruleGroups: readonly RuleGroup[],\n    subject: ReportSubject = WRITE_SUBJECT,\n): string {\n    const lines: string[] = [];\n    lines.push(`\\u274c webpieces ai-hooks blocked this ${subject.noun}: ${relativePath}`);\n    lines.push('');\n\n    for (const group of ruleGroups) {\n        const count = group.violations.length;\n        const label = count === 1 ? '1 violation' : `${count} violations`;\n        lines.push(`[${group.ruleName}] (${label})`);\n        const fh = group.fixHint;\n        for (const v of group.violations) {\n            const editPrefix = formatEditPrefix(v);\n            lines.push(`  ${editPrefix}L${String(v.line)}:  ${v.snippet}`);\n            // Per-occurrence override (dynamic rules), else the rule-level FixHint.violation.\n            lines.push(`    \\u2192 ${v.message ?? fh.violation}`);\n        }\n        // mainMessage may be '' (guidance already on the violation line) \\u2014 skip when empty.\n        if (fh.mainMessage) for (const l of fh.mainMessage.split('\\n')) lines.push(`  ${l}`);\n        // \"Fix Option N:\" numbering + \"(preferred)\" are framework-owned so a multi-line message\n        // can never become fake options and authors never hand-write those labels.\n        fh.fixOptions.forEach((opt: Option, i: number) => {\n            const optLines = opt.text.split('\\n');\n            const tag = opt.preferred ? '(preferred) ' : '';\n            lines.push(`  Fix Option ${String(i + 1)}: ${tag}${optLines[0]}`);\n            for (const l of optLines.slice(1)) lines.push(`    ${l}`);\n        });\n        // Framework-owned disable escape (only the 9 disable-able code-style rules set this).\n        if (fh.escape) {\n            lines.push(fh.escape.allowed\n                ? `  Escape (if truly needed): ${fh.escape.comment}`\n                : '  \\u{1F512} The team disabled escaping via webpieces-disable for this rule (disableAllowed:false) — it must be followed.');\n        }\n        lines.push('');\n    }\n\n    lines.push(subject.footer);\n    lines.push('');\n    return lines.join('\\n');\n}\n\nfunction formatEditPrefix(v: Violation): string {\n    if (v.editIndex !== undefined && v.editCount !== undefined && v.editCount > 1) {\n        return `edit ${String(v.editIndex + 1)}/${String(v.editCount)} `;\n    }\n    return '';\n}\n"]}

package/src/core/rules/branch-creation-guard.d.ts

@@ -72,6 +72,22 @@ export declare class BranchCreationGuardRule extends BashRuleBase<BranchCreation
      * so the cap starts enforcing on its own.
      */
     private checkBranchCap;
+    /**
+     * The branch cap, yielding by ONE when the agent is standing on an already-merged branch.
+     *
+     * Two individually-correct guards were composing into a trap: merged-branch-bash-guard blocks
+     * almost all Bash until you get off a merged branch, and the ONLY way off it that guard advertises
+     * is creating a fresh branch — which this cap then refused. Every printed exit led to editing
+     * webpieces.config.json, and that is what an unsupervised agent did.
+     *
+     * One over cap, and only while a merged branch is what is pushing you: the branch about to be
+     * created replaces a branch that is already dead, so the steady-state count does not grow. The cap
+     * still fires on the NEXT creation, so this defers the cleanup by exactly one branch, never skips it.
+     *
+     * Fails toward the strict cap: no cache, a cache for another branch, or a clean branch → no yield.
+     */
+    private effectiveBranchCap;
+    private currentBranchOrNull;
     /**
      * The worktree cap — the second budget. Same gate, same fail-open rule as the branch cap: a
      * worktree list we cannot classify (no cache on disk) blocks nothing.
@@ -95,6 +111,20 @@ export declare class BranchCreationGuardRule extends BashRuleBase<BranchCreation
      * a message that tells an agent to delete has to be exactly true about why that's safe.
      */
     private capFixHint;
+    /**
+     * The remedy that actually deletes something without loosening anything: SHOW the spared branches
+     * and ASK the human which may go.
+     *
+     * `keep` is the list the tooling refuses to touch on its own — no merged PR, so no proof the work
+     * is safe. That is exactly the list a human can adjudicate in five seconds and the tooling never
+     * can, and it was never printed: the cap said "N branches were SPARED, do not delete those" and
+     * then offered only config edits. So the agent edited the config.
+     *
+     * Every column is read straight off `.webpieces/merged-branches.json` (written by the detached
+     * refresher) — nothing is recomputed on this blocking path. The SHA is there so the human can see
+     * the delete is reversible; the commit count is there so "0 commits" branches are obvious yeses.
+     */
+    private askHumanOption;
     /**
      * The worktree reap instructions.
      *

package/src/core/rules/branch-creation-guard.js

@@ -321,7 +321,8 @@ class BranchCreationGuardRule extends rule_base_1.BashRuleBase {
         const parked = this.mergedBranches.localBranches(ctx.workspaceRoot)
             .filter((branch) => !held.has(branch));
         const count = parked.length;
-        if (count < this.maxLocalBranches)
+        const cap = this.effectiveBranchCap(ctx);
+        if (count < cap)
             return null;
         const cache = this.mergedBranches.readMergedBranches(ctx.workspaceRoot);
         if (!cache)
@@ -335,6 +336,42 @@ class BranchCreationGuardRule extends rule_base_1.BashRuleBase {
             `the cap (branch-creation-guard.maxLocalBranches) is ${String(this.maxLocalBranches)}. ` +
             `${detail} Clean up before creating another.`);
     }
+    /**
+     * The branch cap, yielding by ONE when the agent is standing on an already-merged branch.
+     *
+     * Two individually-correct guards were composing into a trap: merged-branch-bash-guard blocks
+     * almost all Bash until you get off a merged branch, and the ONLY way off it that guard advertises
+     * is creating a fresh branch — which this cap then refused. Every printed exit led to editing
+     * webpieces.config.json, and that is what an unsupervised agent did.
+     *
+     * One over cap, and only while a merged branch is what is pushing you: the branch about to be
+     * created replaces a branch that is already dead, so the steady-state count does not grow. The cap
+     * still fires on the NEXT creation, so this defers the cleanup by exactly one branch, never skips it.
+     *
+     * Fails toward the strict cap: no cache, a cache for another branch, or a clean branch → no yield.
+     */
+    effectiveBranchCap(ctx) {
+        const status = (0, rules_config_1.readMainSyncStatus)(ctx.workspaceRoot);
+        if (status === null || !status.branchAlreadyMerged)
+            return this.maxLocalBranches;
+        const current = this.currentBranchOrNull(ctx.workspaceRoot);
+        if (current === null || status.branch !== current)
+            return this.maxLocalBranches;
+        return this.maxLocalBranches + 1;
+    }
+    currentBranchOrNull(workspaceRoot) {
+        // eslint-disable-next-line @webpieces/no-unmanaged-exceptions
+        try {
+            return (0, child_process_1.execSync)('git rev-parse --abbrev-ref HEAD', {
+                cwd: workspaceRoot, encoding: 'utf8', stdio: ['pipe', 'pipe', 'pipe'],
+            }).trim();
+        }
+        catch (err) {
+            const error = (0, to_error_1.toError)(err);
+            void error;
+            return null;
+        }
+    }
     /**
      * The worktree cap — the second budget. Same gate, same fail-open rule as the branch cap: a
      * worktree list we cannot classify (no cache on disk) blocks nothing.
@@ -374,6 +411,11 @@ class BranchCreationGuardRule extends rule_base_1.BashRuleBase {
      */
     capFixHint(cache) {
         const options = [];
+        // Nothing auto-reapable → the ASK is the preferred move, and it comes FIRST. This is the whole
+        // point of the option: with an empty `deletable` list the only advice left used to be "raise
+        // maxLocalBranches" / "set turnOffRuleUntilEpoch", and an agent with no human in the loop
+        // edited webpieces.config.json to escape — loosening the very rule that was working correctly.
+        const askFirst = cache.deletable.length === 0;
         if (cache.deletable.length > 0) {
             const names = cache.deletable.map((entry) => entry.branch);
             options.push(new fix_hint_1.Option(`Run: pnpm wp-cleanup — it deletes these ${String(names.length)} dead branches. Each is either ` +
@@ -381,10 +423,14 @@ class BranchCreationGuardRule extends rule_base_1.BashRuleBase {
                 `is logged with a recover-by-SHA command (see merged-branches.json for the per-branch reason): ` +
                 names.join(' '), true));
         }
-        options.push(new fix_hint_1.Option('If you genuinely need more branches in flight, raise branch-creation-guard.maxLocalBranches ' +
-            'in webpieces.config.json.'));
-        options.push(new fix_hint_1.Option('To bypass this once, set branch-creation-guard.turnOffRuleUntilEpoch (a future epoch) ' +
-            'in webpieces.config.json.'));
+        const ask = this.askHumanOption(cache, askFirst);
+        if (ask)
+            options.push(ask);
+        options.push(new fix_hint_1.Option('ONLY IF A HUMAN SAYS SO: raise branch-creation-guard.maxLocalBranches in ' +
+            'webpieces.config.json. Editing this config to get past a guard is not a fix you may make on ' +
+            'your own — ask first (use the option above).'));
+        options.push(new fix_hint_1.Option('ONLY IF A HUMAN SAYS SO: set branch-creation-guard.turnOffRuleUntilEpoch (a future epoch) ' +
+            'in webpieces.config.json to bypass this once. Same rule — ask, do not self-approve.'));
         const kept = cache.keep.length > 0
             ? ` ${String(cache.keep.length)} unmerged branch(es) with real commits were deliberately SPARED — ` +
                 'do not delete those; a human decides.'
@@ -392,6 +438,38 @@ class BranchCreationGuardRule extends rule_base_1.BashRuleBase {
         return new fix_hint_1.FixHint('Too many local branches — reap the dead ones before creating another.', 'Full detail (deletable + spared, with per-branch reasons) is in .webpieces/merged-branches.json, ' +
             `refreshed ${cache.timestamp || 'never'}.${kept} Pick one:`, options);
     }
+    /**
+     * The remedy that actually deletes something without loosening anything: SHOW the spared branches
+     * and ASK the human which may go.
+     *
+     * `keep` is the list the tooling refuses to touch on its own — no merged PR, so no proof the work
+     * is safe. That is exactly the list a human can adjudicate in five seconds and the tooling never
+     * can, and it was never printed: the cap said "N branches were SPARED, do not delete those" and
+     * then offered only config edits. So the agent edited the config.
+     *
+     * Every column is read straight off `.webpieces/merged-branches.json` (written by the detached
+     * refresher) — nothing is recomputed on this blocking path. The SHA is there so the human can see
+     * the delete is reversible; the commit count is there so "0 commits" branches are obvious yeses.
+     */
+    askHumanOption(cache, preferred) {
+        if (cache.keep.length === 0)
+            return null;
+        const rows = cache.keep.map((entry) => {
+            const sha = entry.sha !== '' ? entry.sha : '???????';
+            const pr = entry.pr > 0
+                ? `PR #${String(entry.pr)} ${entry.prState || 'MERGED'}`
+                : (entry.prState !== '' ? `PR ${entry.prState}` : 'no PR');
+            const commits = entry.commits >= 0 ? `${String(entry.commits)} commit(s) of its own` : 'commit count unknown';
+            return `    ${entry.branch}  [${sha}]  ${pr}  ${commits}  — ${entry.reason}`;
+        });
+        return new fix_hint_1.Option(`ASK THE HUMAN which of these ${String(cache.keep.length)} branches may be deleted. They are ` +
+            'not provably dead, so the tooling will not reap them — but a human can decide in seconds, ' +
+            'and deleting one is the correct fix for "too many branches". Paste this list and ask:\n' +
+            rows.join('\n') + '\n' +
+            'Then delete ONLY the ones approved: git branch -D <approved-branch>\n' +
+            '(each is recoverable — `git branch <name> <sha>` restores it at the SHA shown above).\n' +
+            'Do NOT delete any of these without an explicit yes, and do NOT edit webpieces.config.json instead.', preferred);
+    }
     /**
      * The worktree reap instructions.
      *