@webpieces/ai-hook-rules 0.4.609 → 0.4.611

package/src/core/rules/whole-repo-build-scan.js

@@ -0,0 +1,216 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.WholeRepoBuildScan = exports.WholeRepoBuildHit = void 0;
+/**
+ * Decides the one question whole-repo-build-guard asks of a command: would this segment build (or
+ * test) the ENTIRE monorepo rather than the part the change touches?
+ *
+ * ─── Why this is a SHAPE test and not a string match ───────────────────────────────────────────────
+ * The command that motivated the guard is `pnpm run build-all`, but matching that literal buys about a
+ * day: `npm run build-all`, `pnpm nx run-many -t ci`, `pnpm exec vitest run` and `time pnpm build-all`
+ * are the same build with a different spelling, and an agent that is blocked reaches for the next
+ * spelling rather than the smaller build. So the classifier normalizes away the package-manager
+ * wrapper first, then judges the PROGRAM and its narrowing arguments:
+ *
+ *   BLOCKED  a whole-repo script name — `build-all`, `webpieces:ci`, `wp-ci`, … — under any runner
+ *   BLOCKED  `nx run-many` of a BUILD target with no `-p`/`--projects`, or with `--all`
+ *   BLOCKED  `nx affected` of a BUILD target with no `--base` (a far wider base than the fork point)
+ *   BLOCKED  `nx <target>` with no project argument (`nx test`)
+ *   BLOCKED  `vitest`/`vitest run` with no path, `--project` or `--dir` to narrow it
+ *   BLOCKED  a bare `pnpm test` AT THE WORKSPACE ROOT — the root `test` script is the whole suite
+ *
+ *   ALLOWED  `nx affected --target=ci --base=<anything>` — the gate's own command
+ *   ALLOWED  `nx run <project>:<target>`, `nx run-many -t test -p a b`, `nx test core-util`
+ *   ALLOWED  `vitest run packages/core/core-util`, `vitest run --project core-util`
+ *   ALLOWED  anything carrying `--filter` (pnpm's own narrowing), and every non-build command
+ *   ALLOWED  a workspace-wide REGENERATION — `nx run-many --target=di-graph-generate` — which is
+ *            supposed to cover every project and which this repo's own docs prescribe
+ *
+ * Narrowing is judged POSITIVELY: a command is blocked only when the shape is whole-repo AND nothing
+ * in it narrows the scope. A flag this file has never heard of therefore fails toward ALLOW, which is
+ * the right direction for a guard whose false positive costs an agent its next legitimate command.
+ */
+// Package-manager wrappers that precede the real program (`pnpm exec vitest`, `npx nx`, `yarn build-all`).
+const RUNNERS = new Set(['pnpm', 'npm', 'yarn', 'npx', 'pnpx', 'bun', 'bunx']);
+// The runner's own verb, consumed with it: `pnpm run build-all` and `pnpm build-all` are one command.
+const RUNNER_VERBS = new Set(['run', 'run-script', 'exec', 'dlx', 'x']);
+// Any of these ANYWHERE in the segment means the human/agent already scoped the work, so nothing here
+// applies. `--filter` is pnpm's project selector; the nx selectors are checked again per-subcommand.
+const NARROWING_FLAGS = ['--filter', '-p', '--projects', '--project', '--dir', '--projectPath'];
+// Script/bin names that ARE "build the world" in every repo that defines them. `wp-ci` is webpieces'
+// own whole-repo validator and is listed as a PROGRAM as well as a script: blocking `build-all` while
+// leaving the thing it delegates to open would be a guard with a labelled side door.
+const WHOLE_REPO_SCRIPTS = new Set([
+    'build-all', 'build:all', 'buildall',
+    'test-all', 'test:all', 'lint-all', 'ci-all', 'ci:all',
+    'webpieces:ci', 'wp-ci',
+]);
+// nx verbs that are NOT "run this target across the workspace". Anything else in the first position is
+// read as a TARGET name (`nx test`, `nx build`), which is whole-repo unless a project follows.
+const NX_COMMANDS = new Set([
+    'run', 'run-many', 'affected', 'affected:graph', 'print-affected',
+    'show', 'graph', 'dep-graph', 'reset', 'daemon', 'list', 'report', 'migrate',
+    'generate', 'g', 'new', 'format', 'repair', 'connect', 'add', 'init', 'release',
+    'sync', 'watch', 'exec', 'login', 'logout', 'record', 'view-logs', 'import',
+]);
+/**
+ * The targets this guard is about. A workspace-wide `nx run-many -t di-graph-generate` or
+ * `-t architecture:generate` is a REGENERATION and is supposed to cover every project — the repo's own
+ * docs prescribe exactly that, and blocking it would make the guard wrong about a command an agent has
+ * to run. Only the compile/test/lint family is a "build of the world".
+ */
+const BUILD_TARGETS = new Set([
+    'ci', 'build', 'test', 'lint', 'e2e', 'typecheck', 'check', 'compile', 'verify',
+]);
+// vitest's leading verb, dropped before looking for a path filter.
+const VITEST_VERBS = new Set(['run', 'watch', 'dev', 'related', 'bench', 'list', 'typecheck', 'init']);
+// vitest flags whose VALUE is the next token, so the value is never mistaken for a path filter.
+const VITEST_VALUE_FLAGS = new Set([
+    '--reporter', '--config', '-c', '--mode', '-m', '--shard', '--pool', '--environment',
+    '--outputFile', '--maxWorkers', '--minWorkers', '--testNamePattern', '-t', '--retry',
+    '--testTimeout', '--hookTimeout', '--exclude', '--include', '--coverage.reporter',
+]);
+/** One whole-repo build found in a command: the segment, and the SHAPE that made it one. Data-only. */
+class WholeRepoBuildHit {
+    segment;
+    shape;
+    constructor(segment, shape) {
+        this.segment = segment;
+        this.shape = shape;
+    }
+}
+exports.WholeRepoBuildHit = WholeRepoBuildHit;
+class WholeRepoBuildScan {
+    scanner;
+    atWorkspaceRoot;
+    constructor(scanner, 
+    // True when the command runs at the workspace ROOT, where a bare `pnpm test` is the whole suite.
+    atWorkspaceRoot) {
+        this.scanner = scanner;
+        this.atWorkspaceRoot = atWorkspaceRoot;
+    }
+    /** The first segment of `command` that builds the whole repo, or null when none does. */
+    firstHit(command) {
+        for (const segment of this.scanner.commandSegments(command)) {
+            const shape = this.shapeOf(segment);
+            if (shape !== null)
+                return new WholeRepoBuildHit(segment, shape);
+        }
+        return null;
+    }
+    // The whole-repo shape this segment is, or null. One dispatch per program family.
+    shapeOf(segment) {
+        // Narrowing is judged on the RAW words, BEFORE the runner is stripped: `pnpm --filter core-util
+        // test` carries its selector on the RUNNER, and stripping first throws that fact away — which is
+        // exactly how a scoped command ends up blocked.
+        if (this.isNarrowed(this.scanner.words(segment)))
+            return null;
+        const words = this.effectiveWords(segment);
+        if (words.length === 0)
+            return null;
+        const program = this.programName(words[0]);
+        const args = words.slice(1);
+        if (WHOLE_REPO_SCRIPTS.has(program))
+            return `${program} builds every project`;
+        if (program === 'nx')
+            return this.nxShape(args);
+        if (program === 'vitest')
+            return this.vitestShape(args);
+        if (program === 'test' && args.length === 0 && this.atWorkspaceRoot) {
+            return 'the root `test` script runs every spec in the repo';
+        }
+        return null;
+    }
+    /**
+     * The segment's words with wrappers stripped: shell prefixes (`time`, `sudo`, env assignments) by
+     * CommandScanner, then the package-manager runner and its verb. `pnpm exec vitest run` and
+     * `vitest run` reduce to the same words, which is the whole point.
+     */
+    effectiveWords(segment) {
+        let words = this.scanner.words(segment);
+        while (words.length > 0 && RUNNERS.has(this.programName(words[0]))) {
+            words = words.slice(1);
+            // The runner's own flags (`--silent`, `-r`) sit between it and the program.
+            while (words.length > 0 && words[0].startsWith('-'))
+                words = words.slice(1);
+            if (words.length > 0 && RUNNER_VERBS.has(words[0]))
+                words = words.slice(1);
+        }
+        return words;
+    }
+    // `./node_modules/.bin/nx` and `/usr/local/bin/pnpm` are the same programs as `nx` and `pnpm`.
+    programName(token) {
+        const base = token.split('/').pop() ?? token;
+        return base.endsWith('.cmd') ? base.slice(0, -'.cmd'.length) : base;
+    }
+    // Did the caller already scope this command? Judged over the WHOLE segment, so a selector attached
+    // to the runner (`pnpm --filter core-util test`) counts just as much as one attached to nx.
+    isNarrowed(words) {
+        return words.some((w) => NARROWING_FLAGS.some((flag) => w === flag || w.startsWith(`${flag}=`)));
+    }
+    nxShape(args) {
+        const positional = args.filter((a) => !a.startsWith('-'));
+        const subcommand = positional[0] ?? '';
+        if (subcommand === 'run-many') {
+            if (!this.buildsAnything(args, positional))
+                return null;
+            if (this.hasFlag(args, '--all'))
+                return 'nx run-many --all builds every project';
+            return 'nx run-many with no --projects builds every project';
+        }
+        if (subcommand === 'affected') {
+            if (this.hasFlag(args, '--base'))
+                return null;
+            if (!this.buildsAnything(args, positional))
+                return null;
+            return 'nx affected with no --base compares against a far wider base than the fork point';
+        }
+        if (subcommand === '' || NX_COMMANDS.has(subcommand))
+            return null;
+        // `nx <target>` — whole-workspace unless a project name follows it.
+        if (positional.length > 1)
+            return null;
+        if (!BUILD_TARGETS.has(subcommand))
+            return null;
+        return `nx ${subcommand} with no project runs that target everywhere`;
+    }
+    vitestShape(args) {
+        let rest = args;
+        if (rest.length > 0 && VITEST_VERBS.has(rest[0]))
+            rest = rest.slice(1);
+        for (let i = 0; i < rest.length; i++) {
+            const word = rest[i];
+            if (!word.startsWith('-'))
+                return null; // a path filter — narrowed
+            if (VITEST_VALUE_FLAGS.has(word))
+                i++; // skip the flag's value
+        }
+        return 'vitest with no path filter runs every spec in the repo';
+    }
+    /**
+     * Does this nx invocation run a COMPILE/TEST target? Targets come from `-t`/`--target`/`--targets`
+     * in either spelling, comma-separated, plus (for `run-many <target>`) a second positional.
+     *
+     * An invocation naming NO target is not judged a build: nx errors on it, and guessing would block a
+     * typo with a message about build scope. An invocation naming only regeneration targets
+     * (`di-graph-generate`, `generate`) is deliberately allowed workspace-wide — see BUILD_TARGETS.
+     */
+    buildsAnything(args, positional) {
+        const targets = positional.slice(1);
+        for (let i = 0; i < args.length; i++) {
+            const word = args[i];
+            const flag = ['-t', '--target', '--targets'].find((f) => word === f || word.startsWith(`${f}=`));
+            if (flag === undefined)
+                continue;
+            const value = word === flag ? (args[i + 1] ?? '') : word.slice(flag.length + 1);
+            targets.push(...value.split(','));
+        }
+        return targets.some((t) => BUILD_TARGETS.has(t.trim()));
+    }
+    // `--base` / `--base=<x>` / `--base <x>` — the attached and detached spellings of one flag.
+    hasFlag(args, flag) {
+        return args.some((a) => a === flag || a.startsWith(`${flag}=`));
+    }
+}
+exports.WholeRepoBuildScan = WholeRepoBuildScan;
+//# sourceMappingURL=whole-repo-build-scan.js.map

package/src/core/rules/whole-repo-build-scan.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"whole-repo-build-scan.js","sourceRoot":"","sources":["../../../../../../../packages/tooling/ai-hook-rules/src/core/rules/whole-repo-build-scan.ts"],"names":[],"mappings":"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","sourcesContent":["import { CommandScanner } from '../command-scan';\n\n/**\n * Decides the one question whole-repo-build-guard asks of a command: would this segment build (or\n * test) the ENTIRE monorepo rather than the part the change touches?\n *\n * ─── Why this is a SHAPE test and not a string match ───────────────────────────────────────────────\n * The command that motivated the guard is `pnpm run build-all`, but matching that literal buys about a\n * day: `npm run build-all`, `pnpm nx run-many -t ci`, `pnpm exec vitest run` and `time pnpm build-all`\n * are the same build with a different spelling, and an agent that is blocked reaches for the next\n * spelling rather than the smaller build. So the classifier normalizes away the package-manager\n * wrapper first, then judges the PROGRAM and its narrowing arguments:\n *\n *   BLOCKED  a whole-repo script name — `build-all`, `webpieces:ci`, `wp-ci`, … — under any runner\n *   BLOCKED  `nx run-many` of a BUILD target with no `-p`/`--projects`, or with `--all`\n *   BLOCKED  `nx affected` of a BUILD target with no `--base` (a far wider base than the fork point)\n *   BLOCKED  `nx <target>` with no project argument (`nx test`)\n *   BLOCKED  `vitest`/`vitest run` with no path, `--project` or `--dir` to narrow it\n *   BLOCKED  a bare `pnpm test` AT THE WORKSPACE ROOT — the root `test` script is the whole suite\n *\n *   ALLOWED  `nx affected --target=ci --base=<anything>` — the gate's own command\n *   ALLOWED  `nx run <project>:<target>`, `nx run-many -t test -p a b`, `nx test core-util`\n *   ALLOWED  `vitest run packages/core/core-util`, `vitest run --project core-util`\n *   ALLOWED  anything carrying `--filter` (pnpm's own narrowing), and every non-build command\n *   ALLOWED  a workspace-wide REGENERATION — `nx run-many --target=di-graph-generate` — which is\n *            supposed to cover every project and which this repo's own docs prescribe\n *\n * Narrowing is judged POSITIVELY: a command is blocked only when the shape is whole-repo AND nothing\n * in it narrows the scope. A flag this file has never heard of therefore fails toward ALLOW, which is\n * the right direction for a guard whose false positive costs an agent its next legitimate command.\n */\n\n// Package-manager wrappers that precede the real program (`pnpm exec vitest`, `npx nx`, `yarn build-all`).\nconst RUNNERS: ReadonlySet<string> = new Set(['pnpm', 'npm', 'yarn', 'npx', 'pnpx', 'bun', 'bunx']);\n\n// The runner's own verb, consumed with it: `pnpm run build-all` and `pnpm build-all` are one command.\nconst RUNNER_VERBS: ReadonlySet<string> = new Set(['run', 'run-script', 'exec', 'dlx', 'x']);\n\n// Any of these ANYWHERE in the segment means the human/agent already scoped the work, so nothing here\n// applies. `--filter` is pnpm's project selector; the nx selectors are checked again per-subcommand.\nconst NARROWING_FLAGS: readonly string[] = ['--filter', '-p', '--projects', '--project', '--dir', '--projectPath'];\n\n// Script/bin names that ARE \"build the world\" in every repo that defines them. `wp-ci` is webpieces'\n// own whole-repo validator and is listed as a PROGRAM as well as a script: blocking `build-all` while\n// leaving the thing it delegates to open would be a guard with a labelled side door.\nconst WHOLE_REPO_SCRIPTS: ReadonlySet<string> = new Set([\n    'build-all', 'build:all', 'buildall',\n    'test-all', 'test:all', 'lint-all', 'ci-all', 'ci:all',\n    'webpieces:ci', 'wp-ci',\n]);\n\n// nx verbs that are NOT \"run this target across the workspace\". Anything else in the first position is\n// read as a TARGET name (`nx test`, `nx build`), which is whole-repo unless a project follows.\nconst NX_COMMANDS: ReadonlySet<string> = new Set([\n    'run', 'run-many', 'affected', 'affected:graph', 'print-affected',\n    'show', 'graph', 'dep-graph', 'reset', 'daemon', 'list', 'report', 'migrate',\n    'generate', 'g', 'new', 'format', 'repair', 'connect', 'add', 'init', 'release',\n    'sync', 'watch', 'exec', 'login', 'logout', 'record', 'view-logs', 'import',\n]);\n\n/**\n * The targets this guard is about. A workspace-wide `nx run-many -t di-graph-generate` or\n * `-t architecture:generate` is a REGENERATION and is supposed to cover every project — the repo's own\n * docs prescribe exactly that, and blocking it would make the guard wrong about a command an agent has\n * to run. Only the compile/test/lint family is a \"build of the world\".\n */\nconst BUILD_TARGETS: ReadonlySet<string> = new Set([\n    'ci', 'build', 'test', 'lint', 'e2e', 'typecheck', 'check', 'compile', 'verify',\n]);\n\n// vitest's leading verb, dropped before looking for a path filter.\nconst VITEST_VERBS: ReadonlySet<string> = new Set(['run', 'watch', 'dev', 'related', 'bench', 'list', 'typecheck', 'init']);\n\n// vitest flags whose VALUE is the next token, so the value is never mistaken for a path filter.\nconst VITEST_VALUE_FLAGS: ReadonlySet<string> = new Set([\n    '--reporter', '--config', '-c', '--mode', '-m', '--shard', '--pool', '--environment',\n    '--outputFile', '--maxWorkers', '--minWorkers', '--testNamePattern', '-t', '--retry',\n    '--testTimeout', '--hookTimeout', '--exclude', '--include', '--coverage.reporter',\n]);\n\n/** One whole-repo build found in a command: the segment, and the SHAPE that made it one. Data-only. */\nexport class WholeRepoBuildHit {\n    segment: string;\n    shape: string;\n\n    constructor(segment: string, shape: string) {\n        this.segment = segment;\n        this.shape = shape;\n    }\n}\n\nexport class WholeRepoBuildScan {\n    constructor(\n        private readonly scanner: CommandScanner,\n        // True when the command runs at the workspace ROOT, where a bare `pnpm test` is the whole suite.\n        private readonly atWorkspaceRoot: boolean,\n    ) {}\n\n    /** The first segment of `command` that builds the whole repo, or null when none does. */\n    firstHit(command: string): WholeRepoBuildHit | null {\n        for (const segment of this.scanner.commandSegments(command)) {\n            const shape = this.shapeOf(segment);\n            if (shape !== null) return new WholeRepoBuildHit(segment, shape);\n        }\n        return null;\n    }\n\n    // The whole-repo shape this segment is, or null. One dispatch per program family.\n    private shapeOf(segment: string): string | null {\n        // Narrowing is judged on the RAW words, BEFORE the runner is stripped: `pnpm --filter core-util\n        // test` carries its selector on the RUNNER, and stripping first throws that fact away — which is\n        // exactly how a scoped command ends up blocked.\n        if (this.isNarrowed(this.scanner.words(segment))) return null;\n\n        const words = this.effectiveWords(segment);\n        if (words.length === 0) return null;\n\n        const program = this.programName(words[0]);\n        const args = words.slice(1);\n\n        if (WHOLE_REPO_SCRIPTS.has(program)) return `${program} builds every project`;\n        if (program === 'nx') return this.nxShape(args);\n        if (program === 'vitest') return this.vitestShape(args);\n        if (program === 'test' && args.length === 0 && this.atWorkspaceRoot) {\n            return 'the root `test` script runs every spec in the repo';\n        }\n        return null;\n    }\n\n    /**\n     * The segment's words with wrappers stripped: shell prefixes (`time`, `sudo`, env assignments) by\n     * CommandScanner, then the package-manager runner and its verb. `pnpm exec vitest run` and\n     * `vitest run` reduce to the same words, which is the whole point.\n     */\n    private effectiveWords(segment: string): readonly string[] {\n        let words = this.scanner.words(segment);\n        while (words.length > 0 && RUNNERS.has(this.programName(words[0]))) {\n            words = words.slice(1);\n            // The runner's own flags (`--silent`, `-r`) sit between it and the program.\n            while (words.length > 0 && words[0].startsWith('-')) words = words.slice(1);\n            if (words.length > 0 && RUNNER_VERBS.has(words[0])) words = words.slice(1);\n        }\n        return words;\n    }\n\n    // `./node_modules/.bin/nx` and `/usr/local/bin/pnpm` are the same programs as `nx` and `pnpm`.\n    private programName(token: string): string {\n        const base = token.split('/').pop() ?? token;\n        return base.endsWith('.cmd') ? base.slice(0, -'.cmd'.length) : base;\n    }\n\n    // Did the caller already scope this command? Judged over the WHOLE segment, so a selector attached\n    // to the runner (`pnpm --filter core-util test`) counts just as much as one attached to nx.\n    private isNarrowed(words: readonly string[]): boolean {\n        return words.some((w: string): boolean =>\n            NARROWING_FLAGS.some((flag: string): boolean => w === flag || w.startsWith(`${flag}=`)));\n    }\n\n    private nxShape(args: readonly string[]): string | null {\n        const positional = args.filter((a: string): boolean => !a.startsWith('-'));\n        const subcommand = positional[0] ?? '';\n\n        if (subcommand === 'run-many') {\n            if (!this.buildsAnything(args, positional)) return null;\n            if (this.hasFlag(args, '--all')) return 'nx run-many --all builds every project';\n            return 'nx run-many with no --projects builds every project';\n        }\n        if (subcommand === 'affected') {\n            if (this.hasFlag(args, '--base')) return null;\n            if (!this.buildsAnything(args, positional)) return null;\n            return 'nx affected with no --base compares against a far wider base than the fork point';\n        }\n        if (subcommand === '' || NX_COMMANDS.has(subcommand)) return null;\n        // `nx <target>` — whole-workspace unless a project name follows it.\n        if (positional.length > 1) return null;\n        if (!BUILD_TARGETS.has(subcommand)) return null;\n        return `nx ${subcommand} with no project runs that target everywhere`;\n    }\n\n    private vitestShape(args: readonly string[]): string | null {\n        let rest = args;\n        if (rest.length > 0 && VITEST_VERBS.has(rest[0])) rest = rest.slice(1);\n        for (let i = 0; i < rest.length; i++) {\n            const word = rest[i];\n            if (!word.startsWith('-')) return null;                 // a path filter — narrowed\n            if (VITEST_VALUE_FLAGS.has(word)) i++;                  // skip the flag's value\n        }\n        return 'vitest with no path filter runs every spec in the repo';\n    }\n\n    /**\n     * Does this nx invocation run a COMPILE/TEST target? Targets come from `-t`/`--target`/`--targets`\n     * in either spelling, comma-separated, plus (for `run-many <target>`) a second positional.\n     *\n     * An invocation naming NO target is not judged a build: nx errors on it, and guessing would block a\n     * typo with a message about build scope. An invocation naming only regeneration targets\n     * (`di-graph-generate`, `generate`) is deliberately allowed workspace-wide — see BUILD_TARGETS.\n     */\n    private buildsAnything(args: readonly string[], positional: readonly string[]): boolean {\n        const targets: string[] = positional.slice(1);\n        for (let i = 0; i < args.length; i++) {\n            const word = args[i];\n            const flag = ['-t', '--target', '--targets'].find(\n                (f: string): boolean => word === f || word.startsWith(`${f}=`));\n            if (flag === undefined) continue;\n            const value = word === flag ? (args[i + 1] ?? '') : word.slice(flag.length + 1);\n            targets.push(...value.split(','));\n        }\n        return targets.some((t: string): boolean => BUILD_TARGETS.has(t.trim()));\n    }\n\n    // `--base` / `--base=<x>` / `--base <x>` — the attached and detached spellings of one flag.\n    private hasFlag(args: readonly string[], flag: string): boolean {\n        return args.some((a: string): boolean => a === flag || a.startsWith(`${flag}=`));\n    }\n}\n"]}

package/src/core/runner.js

@@ -241,7 +241,6 @@ function gitFromSubdirBlock(command, tree) {
         `     ${(0, effective_tree_1.atRoot)(tree.root, command)}\n` +
         `   A leading \`cd <path> &&\` is ACCEPTED by the guards — it cannot change what the command\n` +
         `   does to the repo. (The webpieces guards evaluate the repo's git state at its root.)`;
-    (0, decision_log_1.logGuardDecision)(tree.root, new decision_log_1.GuardDecision('force-to-root', 'Bash', command, (0, decision_log_1.branchForLog)(tree.root), 'BLOCK', 'git/gh from subdir'));
     return new types_1.BlockedResult(report);
 }
 // The L0 cure bypass's audit line. Anchored at the repo root that owns `.webpieces` — RepoRootFinder
@@ -251,7 +250,7 @@ function gitFromSubdirBlock(command, tree) {
 // webpieces-disable no-function-outside-class -- sibling of the module-scope runner helpers; the whole file is functions and a lone class here would break its shape
 function logL0CureBypass(command, cwd) {
     const root = new rules_config_1.RepoRootFinder().resolveRepoRoot(cwd);
-    (0, decision_log_1.logGuardDecision)(root, new decision_log_1.GuardDecision('-', 'Bash', command, (0, decision_log_1.branchForLog)(root), 'ALLOW', 'L0 cure bypass (always allowed)'));
+    (0, decision_log_1.logGuardDecision)(root, new decision_log_1.GuardDecision('-', 'Bash', command, (0, decision_log_1.branchForLog)(root), 'ALLOW', 'L0 cure bypass (always allowed)', '-', l0_fault_codes_1.L0_FAULT_NONE, decision_log_1.MATRIX_L0));
 }
 /**
  * Load the config for the bash path — but do NOT let an unloadable config trap the tools needed to
@@ -293,7 +292,6 @@ function coordinatorInWorktreeBlock(command, tree, agent) {
     const report = new coordinator_worktree_1.CoordinatorWorktreeGuard().block(command, tree, agent);
     if (report === null)
         return null;
-    (0, decision_log_1.logGuardDecision)(tree.root, new decision_log_1.GuardDecision('coordinator-in-worktree', 'Bash', command, (0, decision_log_1.branchForLog)(tree.root), 'BLOCK', 'coordinator working inside a linked worktree'));
     return new types_1.BlockedResult(report);
 }
 // Where the command lands in L1's five dimensions (K/A/R/G/P). The ONE place the runner's view of the
@@ -320,23 +318,45 @@ function l1Classify(command, tree, agent) {
 // reason FROM the resolved tree. Classifying it would mean asking L1_ROWS a question whose answer the
 // classification itself depends on. It is the same shape as L2's `bareCheckoutOfMain` pre-stage.
 //
-// KNOWN GAP, stated rather than discovered later: that makes it an L1 block with NO row in L1_ROWS, so
-// guards/L1-location.md does not describe it — the exact drift this table exists to prevent, arriving
-// while the table was being built. It needs a row (its "state" would be a command shape, the way L2
-// row 2 carries one), which changes the rendered doc and so belongs in its own change, not in a merge
-// resolution.
+// It is therefore ROW 0 — "pre-stage, decided from command text" — rather than a row among 1-6. That
+// keeps it IN the table (the drift this table exists to prevent) without pretending it is classified
+// over the same five dimensions, which is the thing that cannot be true. `L1_PRESTAGE_ROW` is the
+// number the doc prints and the number `row=` logs, so the two still join.
+//
+// THIS FUNCTION IS THE ONE PLACE L1 REPORTS. It is the only scope holding the classification, the
+// matched row, the resolved tree and the agent at once — so logging here, BEFORE the early return,
+// is what finally records the outcomes that were previously invisible: the exempt row and the three
+// hand-downs wrote nothing at all, which is why "L1 had no objection" could not be observed and
+// "show me every L1 decision" had no answer. The three block helpers no longer log for themselves.
 // webpieces-disable no-function-outside-class -- sibling of gitFromSubdirBlock() and the other module-scope runner helpers; the whole file is functions and a lone class here would break its shape
 function l1LocationBlock(command, tree, agent) {
     const misplacedCd = misplacedCdBlock(command, tree);
-    if (misplacedCd !== null)
+    if (misplacedCd !== null) {
+        logL1(tree, command, 'BLOCK_AI_CURE', l1_rows_1.L1_PRESTAGE_ROW, 'cd-must-be-first', 'cd not leading/literal');
         return misplacedCd;
+    }
     const row = (0, l1_rows_1.firstMatchingL1Row)(l1Classify(command, tree, agent));
-    if (row.blockId === null)
-        return null; // exempt (row 1) or hand down to L2 (rows 2, 4, 6)
+    const rowNum = String(row.num);
+    if (row.blockId === null) {
+        // ALLOW_EXEMPT stops here; ALLOW means "no objection, handed down to L2". Recording the
+        // difference is the point — see Verdict. Neither is a claim that the call actually ran: the
+        // parallel L-1 hook may still have denied it.
+        logL1(tree, command, row.action.kind === 'exempt' ? 'ALLOW_EXEMPT' : 'ALLOW', rowNum, '-', row.why);
+        return null;
+    }
+    logL1(tree, command, 'BLOCK_AI_CURE', rowNum, row.blockId, row.why);
     if (row.blockId === 'coordinator-in-worktree')
         return coordinatorInWorktreeBlock(command, tree, agent);
     return gitFromSubdirBlock(command, tree);
 }
+// One L1 line, into L1's OWN stream. `row` is the number the generated doc prints, so a reader who
+// sees `row=5` can open guards/L1-location.md at row 5 and read the state, the cure and the use cases
+// that row is supposed to cover.
+// eslint-disable-next-line @typescript-eslint/max-params -- the six fields of one log line, and a class here would break this file's shape
+// webpieces-disable no-function-outside-class -- sibling of the module-scope runner helpers; the whole file is functions
+function logL1(tree, command, verdict, row, rule, why) {
+    (0, decision_log_1.logL1Decision)(tree.root, new decision_log_1.GuardDecision(rule, 'Bash', command, (0, decision_log_1.branchForLog)(tree.root), verdict, why, '-', l0_fault_codes_1.L0_FAULT_NONE, new decision_log_1.MatrixRef('L1', row)));
+}
 /**
  * ONE legal shape for relocating a command: `cd <literal path> && <work>`. Anything else — a `cd` after
  * another command or after a `VAR=…` assignment, or a `cd "$DIR"` the guard cannot expand — is refused
@@ -365,7 +385,6 @@ function misplacedCdBlock(command, tree) {
         `   Fix Option 2: drop the \`cd\` — ${tree.root} is where the command is judged anyway.\n` +
         `   Fix Option 3: split it — run the work in one call, the \`cd\` in another (a \`cd\` alone still\n` +
         `                 moves nothing the guards judge; see EffectiveTree on why cwd cannot be assumed).`;
-    (0, decision_log_1.logGuardDecision)(tree.root, new decision_log_1.GuardDecision('cd-must-be-first', 'Bash', command, (0, decision_log_1.branchForLog)(tree.root), 'BLOCK', 'cd not leading/literal'));
     return new types_1.BlockedResult(report);
 }
 // webpieces-disable no-function-outside-class -- sibling of run()/runBash() in this module; the whole runner is module-scope functions and a lone class for this one entry point would break the file's shape
@@ -391,7 +410,7 @@ function runBashInternal(command, cwd, mode, agent) {
     // Intentional, not a silent hole. A LINKED WORKTREE of this repo is deliberately NOT foreign — it
     // is the same project, so the guards run against THAT tree's branch and cache.
     if (tree.kind === 'foreign') {
-        (0, decision_log_1.logGuardDecision)(workspaceRoot, new decision_log_1.GuardDecision('-', 'Bash', command, (0, decision_log_1.branchForLog)(workspaceRoot), 'ALLOW', 'foreign git repo (out of scope)'));
+        (0, decision_log_1.logGuardDecision)(workspaceRoot, new decision_log_1.GuardDecision('-', 'Bash', command, (0, decision_log_1.branchForLog)(workspaceRoot), 'ALLOW_EXEMPT', 'foreign git repo (out of scope)', '-', l0_fault_codes_1.L0_FAULT_NONE, new decision_log_1.MatrixRef('L1', '1')));
         return null;
     }
     // Honour excludePaths on the bash path too (not just Read/Edit): a command whose effective
@@ -421,12 +440,12 @@ function runBashInternal(command, cwd, mode, agent) {
         // focused (the whole point of the log is "why did/didn't a guard fire?"). Blocks are always
         // logged below.
         if (/\b(?:git|gh)\b/.test(command)) {
-            (0, decision_log_1.logGuardDecision)(tree.root, new decision_log_1.GuardDecision('-', 'Bash', command, (0, decision_log_1.branchForLog)(tree.root), 'ALLOW', 'no bash-guard block'));
+            (0, decision_log_1.logGuardDecision)(tree.root, new decision_log_1.GuardDecision('-', 'Bash', command, (0, decision_log_1.branchForLog)(tree.root), 'ALLOW', 'no bash-guard block', '-', l0_fault_codes_1.L0_FAULT_NONE, decision_log_1.MATRIX_L2));
         }
         return null;
     }
     const ruleNames = groups.map((g) => g.ruleName).join(',');
-    (0, decision_log_1.logGuardDecision)(tree.root, new decision_log_1.GuardDecision(ruleNames, 'Bash', command, (0, decision_log_1.branchForLog)(tree.root), 'BLOCK', 'bash-guard block'));
+    (0, decision_log_1.logGuardDecision)(tree.root, new decision_log_1.GuardDecision(ruleNames, 'Bash', command, (0, decision_log_1.branchForLog)(tree.root), 'BLOCK_AI_CURE', 'bash-guard block', '-', l0_fault_codes_1.L0_FAULT_NONE, decision_log_1.MATRIX_L2));
     const report = (0, report_1.formatReport)(commandLabel(command), groups, report_1.BASH_SUBJECT) + exemptTreesHint(groups, loaded.excludePaths.paths);
     return new types_1.BlockedResult(report);
 }