@webpieces/ai-hook-rules 0.4.557 → 0.4.559

package/src/bin/shim-testkit.js

@@ -83,6 +83,26 @@ class ShimTestkit {
         const r = (0, child_process_1.spawnSync)('/bin/sh', [shimAbs, bin], { cwd: subdir, input: stdin, encoding: 'utf8' });
         return new ShimRun(r.status, r.stdout, r.stderr);
     }
+    /**
+     * A repo root staged so the shim's VERSION-DRIFT check (fault D) fires: an installed guard bin, a
+     * declared @webpieces/pr-gate pin in package.json, and a different installed version in
+     * node_modules. The fake bin prints EXECED, so "the guards actually ran" is observable in stdout —
+     * pass matching versions to stage the no-drift case instead.
+     *
+     * Lives here rather than in one spec because two spec files now need the identical staging, and a
+     * second copy is a second definition of what "drift" means.
+     */
+    stageDriftRoot(declared, installed) {
+        const root = this.mktmp();
+        const binDir = path.join(root, 'node_modules', '.bin');
+        fs.mkdirSync(binDir, { recursive: true });
+        fs.writeFileSync(path.join(binDir, 'wp-ai-guards-hook'), '#!/bin/sh\nprintf EXECED\n', { mode: 0o755 });
+        fs.writeFileSync(path.join(root, 'package.json'), JSON.stringify({ dependencies: { '@webpieces/pr-gate': declared } }, null, 2) + '\n');
+        const manifestDir = path.join(root, 'node_modules', '@webpieces', 'pr-gate');
+        fs.mkdirSync(manifestDir, { recursive: true });
+        fs.writeFileSync(path.join(manifestDir, 'package.json'), JSON.stringify({ name: '@webpieces/pr-gate', version: installed }, null, 2) + '\n');
+        return root;
+    }
     /** A Bash tool payload, as Claude Code sends it on stdin. */
     bashPayload(command) {
         return JSON.stringify({ tool_name: 'Bash', tool_input: { command } });

package/src/bin/shim-testkit.js.map

@@ -1 +1 @@
-{"version":3,"file":"shim-testkit.js","sourceRoot":"","sources":["../../../../../../packages/tooling/ai-hook-rules/src/bin/shim-testkit.ts"],"names":[],"mappings":"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","sourcesContent":["import * as fs from 'fs';\nimport * as os from 'os';\nimport * as path from 'path';\nimport { spawnSync } from 'child_process';\nimport { renderShim } from './shim';\n\n/**\n * The shim's PreToolUse deny payload, as it prints it on stdout. Named (not an inline literal on the\n * JSON.parse cast) so the wire shape this testkit depends on is stated once, in one place.\n */\nexport class HookSpecificOutput {\n    constructor(public readonly permissionDecisionReason: string) {}\n}\n\n/** The decision envelope wrapping {@link HookSpecificOutput}. */\nexport class PreToolUseDecision {\n    constructor(public readonly hookSpecificOutput: HookSpecificOutput) {}\n}\n\n/** The outcome of one shim invocation. Data-only → a class, per CLAUDE.md. */\nexport class ShimRun {\n    constructor(\n        public readonly status: number | null,\n        public readonly stdout: string,\n        public readonly stderr: string,\n    ) {}\n\n    /** True when the shim emitted a PreToolUse deny. */\n    isDenied(): boolean {\n        return this.stdout.includes('\"permissionDecision\":\"deny\"');\n    }\n\n    /**\n     * The deny REASON, parsed out of the PreToolUse JSON.\n     * @throws if this run was not a deny (there is no reason to read).\n     */\n    denyReason(): string {\n        // eslint-disable-next-line @webpieces/no-unmanaged-exceptions\n        const decision = JSON.parse(this.stdout) as PreToolUseDecision;\n        return decision.hookSpecificOutput.permissionDecisionReason;\n    }\n}\n\n/**\n * ShimTestkit — the shared harness for driving the rendered shim through a REAL /bin/sh.\n *\n * Extracted so setup.spec.ts and shim-drift.spec.ts drive the shim the SAME way instead of each\n * keeping its own copy: the shim's entire contract is \"what /bin/sh actually does with it\", so two\n * drifting harnesses would silently become two different contracts.\n *\n * An instance class (not module-scope functions) because this is normal source to the linter — only\n * *.spec.ts is exempt from no-function-outside-class, and a testkit should not need a disable comment\n * to exist.\n */\nexport class ShimTestkit {\n    /** A throwaway repo root under the OS temp dir. */\n    mktmp(): string {\n        return fs.mkdtempSync(path.join(os.tmpdir(), 'wp-setup-'));\n    }\n\n    /**\n     * Run the rendered shim exactly as Claude Code would: `sh <shim> <bin> ...`, from a repo cwd,\n     * piping tool-payload JSON on stdin. spawnSync never throws on non-zero exit.\n     */\n    runShim(root: string, bin: string, stdin: string): ShimRun {\n        // Place the shim at its REAL relative location (<root>/.claude/webpieces/ai-hook.sh) so its\n        // self-location (`dirname $0/../..` → <root>) resolves the bin correctly. Run it from a SUBDIR\n        // to prove it does not depend on the caller's cwd.\n        const shimAbs = path.join(root, '.claude', 'webpieces', 'ai-hook.sh');\n        fs.mkdirSync(path.dirname(shimAbs), { recursive: true });\n        fs.writeFileSync(shimAbs, renderShim(), { mode: 0o755 });\n        const subdir = path.join(root, 'packages', 'deep', 'sub');\n        fs.mkdirSync(subdir, { recursive: true });\n        const r = spawnSync('/bin/sh', [shimAbs, bin], { cwd: subdir, input: stdin, encoding: 'utf8' });\n        return new ShimRun(r.status, r.stdout, r.stderr);\n    }\n\n    /** A Bash tool payload, as Claude Code sends it on stdin. */\n    bashPayload(command: string): string {\n        return JSON.stringify({ tool_name: 'Bash', tool_input: { command } });\n    }\n\n    /** A Read payload — the L0 allowlist entry that keeps a broken tree inspectable. */\n    readPayload(filePath: string): string {\n        return JSON.stringify({ tool_name: 'Read', tool_input: { file_path: filePath } });\n    }\n\n    /** A file-tool payload, for the always-allowed webpieces.config.json recovery target. */\n    filePayload(toolName: string, filePath: string): string {\n        return JSON.stringify({ tool_name: toolName, tool_input: { file_path: filePath } });\n    }\n\n    /** True when `cmd` matches a POSIX ERE, judged by the SAME `grep -E` the shim itself runs. */\n    ereMatches(ere: string, cmd: string): boolean {\n        return this.ereMatchSet(ere, [cmd]).matched(cmd);\n    }\n\n    /**\n     * Which of `cmds` that same `grep -E` matches — answered in ONE grep process for the whole batch.\n     *\n     * grep is a line matcher, so feeding N commands as N lines asks exactly the question `-Eq` answers\n     * per command; the engine, the ERE and the anchors are unchanged. What changes is cost: a process\n     * spawn is ~5ms on an idle machine but ~100ms when the suite runs projects in parallel, so a\n     * 16-command twin check used to be 16 spawns (~2s of pure spawn latency) for one grep pass. That\n     * is what made these files miss the per-test timeout under load.\n     */\n    ereMatchSet(ere: string, cmds: readonly string[]): EreMatchSet {\n        for (const cmd of cmds) {\n            // A command carrying a newline would arrive at grep as TWO lines and be judged as two\n            // different commands — a silently wrong answer. Nothing in the allowlists does this.\n            if (cmd.includes('\\n')) throw new Error(`ereMatchSet cannot batch a multi-line command: ${JSON.stringify(cmd)}`);\n        }\n        const result = spawnSync('grep', ['-E', ere], { input: cmds.join('\\n'), encoding: 'utf8' });\n        const hits = new Set((result.stdout ?? '').split('\\n').filter((line: string): boolean => line !== ''));\n        return new EreMatchSet(hits);\n    }\n}\n\n/** The lines `grep -E` matched in one batched run — ask it per command with {@link matched}. */\nexport class EreMatchSet {\n    private readonly hits: ReadonlySet<string>;\n\n    constructor(hits: ReadonlySet<string>) {\n        this.hits = hits;\n    }\n\n    matched(cmd: string): boolean {\n        return this.hits.has(cmd);\n    }\n}\n"]}
+{"version":3,"file":"shim-testkit.js","sourceRoot":"","sources":["../../../../../../packages/tooling/ai-hook-rules/src/bin/shim-testkit.ts"],"names":[],"mappings":"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","sourcesContent":["import * as fs from 'fs';\nimport * as os from 'os';\nimport * as path from 'path';\nimport { spawnSync } from 'child_process';\nimport { renderShim } from './shim';\n\n/**\n * The shim's PreToolUse deny payload, as it prints it on stdout. Named (not an inline literal on the\n * JSON.parse cast) so the wire shape this testkit depends on is stated once, in one place.\n */\nexport class HookSpecificOutput {\n    constructor(public readonly permissionDecisionReason: string) {}\n}\n\n/** The decision envelope wrapping {@link HookSpecificOutput}. */\nexport class PreToolUseDecision {\n    constructor(public readonly hookSpecificOutput: HookSpecificOutput) {}\n}\n\n/** The outcome of one shim invocation. Data-only → a class, per CLAUDE.md. */\nexport class ShimRun {\n    constructor(\n        public readonly status: number | null,\n        public readonly stdout: string,\n        public readonly stderr: string,\n    ) {}\n\n    /** True when the shim emitted a PreToolUse deny. */\n    isDenied(): boolean {\n        return this.stdout.includes('\"permissionDecision\":\"deny\"');\n    }\n\n    /**\n     * The deny REASON, parsed out of the PreToolUse JSON.\n     * @throws if this run was not a deny (there is no reason to read).\n     */\n    denyReason(): string {\n        // eslint-disable-next-line @webpieces/no-unmanaged-exceptions\n        const decision = JSON.parse(this.stdout) as PreToolUseDecision;\n        return decision.hookSpecificOutput.permissionDecisionReason;\n    }\n}\n\n/**\n * ShimTestkit — the shared harness for driving the rendered shim through a REAL /bin/sh.\n *\n * Extracted so setup.spec.ts and shim-drift.spec.ts drive the shim the SAME way instead of each\n * keeping its own copy: the shim's entire contract is \"what /bin/sh actually does with it\", so two\n * drifting harnesses would silently become two different contracts.\n *\n * An instance class (not module-scope functions) because this is normal source to the linter — only\n * *.spec.ts is exempt from no-function-outside-class, and a testkit should not need a disable comment\n * to exist.\n */\nexport class ShimTestkit {\n    /** A throwaway repo root under the OS temp dir. */\n    mktmp(): string {\n        return fs.mkdtempSync(path.join(os.tmpdir(), 'wp-setup-'));\n    }\n\n    /**\n     * Run the rendered shim exactly as Claude Code would: `sh <shim> <bin> ...`, from a repo cwd,\n     * piping tool-payload JSON on stdin. spawnSync never throws on non-zero exit.\n     */\n    runShim(root: string, bin: string, stdin: string): ShimRun {\n        // Place the shim at its REAL relative location (<root>/.claude/webpieces/ai-hook.sh) so its\n        // self-location (`dirname $0/../..` → <root>) resolves the bin correctly. Run it from a SUBDIR\n        // to prove it does not depend on the caller's cwd.\n        const shimAbs = path.join(root, '.claude', 'webpieces', 'ai-hook.sh');\n        fs.mkdirSync(path.dirname(shimAbs), { recursive: true });\n        fs.writeFileSync(shimAbs, renderShim(), { mode: 0o755 });\n        const subdir = path.join(root, 'packages', 'deep', 'sub');\n        fs.mkdirSync(subdir, { recursive: true });\n        const r = spawnSync('/bin/sh', [shimAbs, bin], { cwd: subdir, input: stdin, encoding: 'utf8' });\n        return new ShimRun(r.status, r.stdout, r.stderr);\n    }\n\n    /**\n     * A repo root staged so the shim's VERSION-DRIFT check (fault D) fires: an installed guard bin, a\n     * declared @webpieces/pr-gate pin in package.json, and a different installed version in\n     * node_modules. The fake bin prints EXECED, so \"the guards actually ran\" is observable in stdout —\n     * pass matching versions to stage the no-drift case instead.\n     *\n     * Lives here rather than in one spec because two spec files now need the identical staging, and a\n     * second copy is a second definition of what \"drift\" means.\n     */\n    stageDriftRoot(declared: string, installed: string): string {\n        const root = this.mktmp();\n        const binDir = path.join(root, 'node_modules', '.bin');\n        fs.mkdirSync(binDir, { recursive: true });\n        fs.writeFileSync(path.join(binDir, 'wp-ai-guards-hook'), '#!/bin/sh\\nprintf EXECED\\n', { mode: 0o755 });\n        fs.writeFileSync(path.join(root, 'package.json'),\n            JSON.stringify({ dependencies: { '@webpieces/pr-gate': declared } }, null, 2) + '\\n');\n        const manifestDir = path.join(root, 'node_modules', '@webpieces', 'pr-gate');\n        fs.mkdirSync(manifestDir, { recursive: true });\n        fs.writeFileSync(path.join(manifestDir, 'package.json'),\n            JSON.stringify({ name: '@webpieces/pr-gate', version: installed }, null, 2) + '\\n');\n        return root;\n    }\n\n    /** A Bash tool payload, as Claude Code sends it on stdin. */\n    bashPayload(command: string): string {\n        return JSON.stringify({ tool_name: 'Bash', tool_input: { command } });\n    }\n\n    /** A Read payload — the L0 allowlist entry that keeps a broken tree inspectable. */\n    readPayload(filePath: string): string {\n        return JSON.stringify({ tool_name: 'Read', tool_input: { file_path: filePath } });\n    }\n\n    /** A file-tool payload, for the always-allowed webpieces.config.json recovery target. */\n    filePayload(toolName: string, filePath: string): string {\n        return JSON.stringify({ tool_name: toolName, tool_input: { file_path: filePath } });\n    }\n\n    /** True when `cmd` matches a POSIX ERE, judged by the SAME `grep -E` the shim itself runs. */\n    ereMatches(ere: string, cmd: string): boolean {\n        return this.ereMatchSet(ere, [cmd]).matched(cmd);\n    }\n\n    /**\n     * Which of `cmds` that same `grep -E` matches — answered in ONE grep process for the whole batch.\n     *\n     * grep is a line matcher, so feeding N commands as N lines asks exactly the question `-Eq` answers\n     * per command; the engine, the ERE and the anchors are unchanged. What changes is cost: a process\n     * spawn is ~5ms on an idle machine but ~100ms when the suite runs projects in parallel, so a\n     * 16-command twin check used to be 16 spawns (~2s of pure spawn latency) for one grep pass. That\n     * is what made these files miss the per-test timeout under load.\n     */\n    ereMatchSet(ere: string, cmds: readonly string[]): EreMatchSet {\n        for (const cmd of cmds) {\n            // A command carrying a newline would arrive at grep as TWO lines and be judged as two\n            // different commands — a silently wrong answer. Nothing in the allowlists does this.\n            if (cmd.includes('\\n')) throw new Error(`ereMatchSet cannot batch a multi-line command: ${JSON.stringify(cmd)}`);\n        }\n        const result = spawnSync('grep', ['-E', ere], { input: cmds.join('\\n'), encoding: 'utf8' });\n        const hits = new Set((result.stdout ?? '').split('\\n').filter((line: string): boolean => line !== ''));\n        return new EreMatchSet(hits);\n    }\n}\n\n/** The lines `grep -E` matched in one batched run — ask it per command with {@link matched}. */\nexport class EreMatchSet {\n    private readonly hits: ReadonlySet<string>;\n\n    constructor(hits: ReadonlySet<string>) {\n        this.hits = hits;\n    }\n\n    matched(cmd: string): boolean {\n        return this.hits.has(cmd);\n    }\n}\n"]}

package/src/core/coordinator-worktree.d.ts

@@ -0,0 +1,61 @@
+import { EffectiveTree } from './effective-tree';
+/**
+ * WHO is making this tool call — the coordinator (the main agent loop) or a subagent?
+ *
+ * The PreToolUse payload carries `agent_id` / `agent_type` ONLY when the hook fires inside a SUBAGENT.
+ * Absent means the coordinator. That is the whole signal; there is no positive "I am the coordinator"
+ * field to read, so this class exists to make the absence explicit rather than an inline `?? ''`.
+ *
+ * Data-only (per CLAUDE.md, classes for data) — `coordinator` is derived once in the constructor, the
+ * same way EffectiveTree derives `redirected`.
+ */
+export declare class AgentIdentity {
+    /** Empty when the hook fired in the coordinator. */
+    readonly agentId: string;
+    /** Empty when the hook fired in the coordinator. */
+    readonly agentType: string;
+    readonly coordinator: boolean;
+    constructor(agentId: string, agentType: string);
+}
+/**
+ * The default for every caller that cannot tell — library consumers, the openclaw adapter, and every
+ * existing runBash() call site. It reads as NOT the coordinator on purpose: only the Claude Code
+ * adapter parses the payload that carries the answer, and a caller who does not know must never be
+ * GUESSED into a block. Fail open; the one caller that knows passes the real identity.
+ */
+export declare const UNKNOWN_AGENT: AgentIdentity;
+/**
+ * L1: the COORDINATOR must not work inside a linked worktree — it must delegate that work to a
+ * subagent bound to the worktree.
+ *
+ * THE INCIDENT (reproduced from a transcript). The coordinator ran `git worktree add ../l2-matrix-doc`,
+ * `cd`'d in, and worked there for the rest of the session. Its governance stayed anchored to the
+ * PRIMARY clone — `$CLAUDE_PROJECT_DIR` is fixed at session start and does not follow a `cd` — while
+ * its filesystem was in the worktree. An L0 version-drift fault then fired against the PRIMARY
+ * (pin 0.4.545 vs node_modules 0.4.526) and prescribed `pnpm install`; that install ran in the
+ * WORKTREE, which was internally consistent at 0.4.526/0.4.526, so it succeeded, changed nothing in
+ * the measured tree, and the guard re-denied. Five identical installs later the agent had invented a
+ * false theory ("the harness is stripping my cd prefix") and handed the problem to the human.
+ *
+ * The cure is not a better message on that fault — it is upstream of it: a split between the tree the
+ * agent stands in and the tree that governs it must not be reachable at all. A subagent bound to the
+ * worktree has both in one place, so the project stays governed consistently.
+ *
+ * SCOPE, deliberately narrow:
+ *   - `kind === 'worktree'` only. `'primary'` is home; `'foreign'` and `'outside'` are other
+ *     jurisdictions and this guard leaves their classification exactly as it was.
+ *   - subagents are never blocked — one pinned to a worktree is the CORRECT pattern.
+ *   - reading is never blocked. The Read tool never reaches here, and a provably-inert inspection
+ *     command is allowed through so the coordinator can still look around before it delegates.
+ *
+ * NOT in scope, and not a hole: the L0 cure allowlist runs BEFORE this in runBashInternal, so
+ * `cd <worktree> && pnpm install` — the literal command from the incident — still passes. That is the
+ * invariant L0 exists to hold (a cure must stay reachable), and it is fine: what this guard removes is
+ * the session shape in which running that install in the wrong tree was ever plausible.
+ */
+export declare class CoordinatorWorktreeGuard {
+    private readonly inspection;
+    /** The deny report, or null to allow. */
+    block(command: string, tree: EffectiveTree, agent: AgentIdentity): string | null;
+    private report;
+}

package/src/core/coordinator-worktree.js

@@ -0,0 +1,94 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.CoordinatorWorktreeGuard = exports.UNKNOWN_AGENT = exports.AgentIdentity = void 0;
+const read_only_inspection_1 = require("./read-only-inspection");
+/**
+ * WHO is making this tool call — the coordinator (the main agent loop) or a subagent?
+ *
+ * The PreToolUse payload carries `agent_id` / `agent_type` ONLY when the hook fires inside a SUBAGENT.
+ * Absent means the coordinator. That is the whole signal; there is no positive "I am the coordinator"
+ * field to read, so this class exists to make the absence explicit rather than an inline `?? ''`.
+ *
+ * Data-only (per CLAUDE.md, classes for data) — `coordinator` is derived once in the constructor, the
+ * same way EffectiveTree derives `redirected`.
+ */
+class AgentIdentity {
+    /** Empty when the hook fired in the coordinator. */
+    agentId;
+    /** Empty when the hook fired in the coordinator. */
+    agentType;
+    coordinator;
+    constructor(agentId, agentType) {
+        this.agentId = agentId;
+        this.agentType = agentType;
+        this.coordinator = agentId === '' && agentType === '';
+    }
+}
+exports.AgentIdentity = AgentIdentity;
+/**
+ * The default for every caller that cannot tell — library consumers, the openclaw adapter, and every
+ * existing runBash() call site. It reads as NOT the coordinator on purpose: only the Claude Code
+ * adapter parses the payload that carries the answer, and a caller who does not know must never be
+ * GUESSED into a block. Fail open; the one caller that knows passes the real identity.
+ */
+exports.UNKNOWN_AGENT = new AgentIdentity('unknown', 'unknown');
+/**
+ * L1: the COORDINATOR must not work inside a linked worktree — it must delegate that work to a
+ * subagent bound to the worktree.
+ *
+ * THE INCIDENT (reproduced from a transcript). The coordinator ran `git worktree add ../l2-matrix-doc`,
+ * `cd`'d in, and worked there for the rest of the session. Its governance stayed anchored to the
+ * PRIMARY clone — `$CLAUDE_PROJECT_DIR` is fixed at session start and does not follow a `cd` — while
+ * its filesystem was in the worktree. An L0 version-drift fault then fired against the PRIMARY
+ * (pin 0.4.545 vs node_modules 0.4.526) and prescribed `pnpm install`; that install ran in the
+ * WORKTREE, which was internally consistent at 0.4.526/0.4.526, so it succeeded, changed nothing in
+ * the measured tree, and the guard re-denied. Five identical installs later the agent had invented a
+ * false theory ("the harness is stripping my cd prefix") and handed the problem to the human.
+ *
+ * The cure is not a better message on that fault — it is upstream of it: a split between the tree the
+ * agent stands in and the tree that governs it must not be reachable at all. A subagent bound to the
+ * worktree has both in one place, so the project stays governed consistently.
+ *
+ * SCOPE, deliberately narrow:
+ *   - `kind === 'worktree'` only. `'primary'` is home; `'foreign'` and `'outside'` are other
+ *     jurisdictions and this guard leaves their classification exactly as it was.
+ *   - subagents are never blocked — one pinned to a worktree is the CORRECT pattern.
+ *   - reading is never blocked. The Read tool never reaches here, and a provably-inert inspection
+ *     command is allowed through so the coordinator can still look around before it delegates.
+ *
+ * NOT in scope, and not a hole: the L0 cure allowlist runs BEFORE this in runBashInternal, so
+ * `cd <worktree> && pnpm install` — the literal command from the incident — still passes. That is the
+ * invariant L0 exists to hold (a cure must stay reachable), and it is fine: what this guard removes is
+ * the session shape in which running that install in the wrong tree was ever plausible.
+ */
+class CoordinatorWorktreeGuard {
+    inspection = new read_only_inspection_1.ReadOnlyInspectionScan();
+    /** The deny report, or null to allow. */
+    block(command, tree, agent) {
+        if (!agent.coordinator)
+            return null;
+        if (tree.kind !== 'worktree')
+            return null;
+        if (this.inspection.isReadOnlyInspection(command))
+            return null;
+        return this.report(tree);
+    }
+    // Short on purpose — main landed a deliberate L0 message diet (384cdae) and these blocks regress
+    // straight back to a wall of text if each new one argues its case. State the block, name the
+    // worktree, prescribe the subagent, list the read-only escapes. Nothing else.
+    report(tree) {
+        return [
+            `❌ You are the COORDINATOR and this command works inside linked worktree ${tree.root}.`,
+            `   Your governance is anchored to ${tree.governedRoot} and does NOT follow a \`cd\`, so working`,
+            `   here splits your filesystem from your guards — the failure that burned five no-op installs.`,
+            '',
+            '   Spawn a subagent bound to that worktree and work through it: the Agent tool with worktree',
+            `   isolation, or have the subagent call EnterWorktree with path: ${tree.root}`,
+            '',
+            `   You can still READ from here without moving: the Read tool, \`git -C ${tree.root} <cmd>\`,`,
+            '   or `git show <branch>:<file>`.',
+        ].join('\n');
+    }
+}
+exports.CoordinatorWorktreeGuard = CoordinatorWorktreeGuard;
+//# sourceMappingURL=coordinator-worktree.js.map

package/src/core/coordinator-worktree.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"coordinator-worktree.js","sourceRoot":"","sources":["../../../../../../packages/tooling/ai-hook-rules/src/core/coordinator-worktree.ts"],"names":[],"mappings":";;;AACA,iEAAgE;AAEhE;;;;;;;;;GASG;AACH,MAAa,aAAa;IACtB,oDAAoD;IAC3C,OAAO,CAAS;IACzB,oDAAoD;IAC3C,SAAS,CAAS;IAClB,WAAW,CAAU;IAE9B,YAAY,OAAe,EAAE,SAAiB;QAC1C,IAAI,CAAC,OAAO,GAAG,OAAO,CAAC;QACvB,IAAI,CAAC,SAAS,GAAG,SAAS,CAAC;QAC3B,IAAI,CAAC,WAAW,GAAG,OAAO,KAAK,EAAE,IAAI,SAAS,KAAK,EAAE,CAAC;IAC1D,CAAC;CACJ;AAZD,sCAYC;AAED;;;;;GAKG;AACU,QAAA,aAAa,GAAG,IAAI,aAAa,CAAC,SAAS,EAAE,SAAS,CAAC,CAAC;AAErE;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA4BG;AACH,MAAa,wBAAwB;IAChB,UAAU,GAAG,IAAI,6CAAsB,EAAE,CAAC;IAE3D,yCAAyC;IACzC,KAAK,CAAC,OAAe,EAAE,IAAmB,EAAE,KAAoB;QAC5D,IAAI,CAAC,KAAK,CAAC,WAAW;YAAE,OAAO,IAAI,CAAC;QACpC,IAAI,IAAI,CAAC,IAAI,KAAK,UAAU;YAAE,OAAO,IAAI,CAAC;QAC1C,IAAI,IAAI,CAAC,UAAU,CAAC,oBAAoB,CAAC,OAAO,CAAC;YAAE,OAAO,IAAI,CAAC;QAC/D,OAAO,IAAI,CAAC,MAAM,CAAC,IAAI,CAAC,CAAC;IAC7B,CAAC;IAED,iGAAiG;IACjG,6FAA6F;IAC7F,8EAA8E;IACtE,MAAM,CAAC,IAAmB;QAC9B,OAAO;YACH,2EAA2E,IAAI,CAAC,IAAI,GAAG;YACvF,qCAAqC,IAAI,CAAC,YAAY,2CAA2C;YACjG,gGAAgG;YAChG,EAAE;YACF,8FAA8F;YAC9F,oEAAoE,IAAI,CAAC,IAAI,EAAE;YAC/E,EAAE;YACF,2EAA2E,IAAI,CAAC,IAAI,WAAW;YAC/F,mCAAmC;SACtC,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC;IACjB,CAAC;CACJ;AA3BD,4DA2BC","sourcesContent":["import { EffectiveTree } from './effective-tree';\nimport { ReadOnlyInspectionScan } from './read-only-inspection';\n\n/**\n * WHO is making this tool call — the coordinator (the main agent loop) or a subagent?\n *\n * The PreToolUse payload carries `agent_id` / `agent_type` ONLY when the hook fires inside a SUBAGENT.\n * Absent means the coordinator. That is the whole signal; there is no positive \"I am the coordinator\"\n * field to read, so this class exists to make the absence explicit rather than an inline `?? ''`.\n *\n * Data-only (per CLAUDE.md, classes for data) — `coordinator` is derived once in the constructor, the\n * same way EffectiveTree derives `redirected`.\n */\nexport class AgentIdentity {\n    /** Empty when the hook fired in the coordinator. */\n    readonly agentId: string;\n    /** Empty when the hook fired in the coordinator. */\n    readonly agentType: string;\n    readonly coordinator: boolean;\n\n    constructor(agentId: string, agentType: string) {\n        this.agentId = agentId;\n        this.agentType = agentType;\n        this.coordinator = agentId === '' && agentType === '';\n    }\n}\n\n/**\n * The default for every caller that cannot tell — library consumers, the openclaw adapter, and every\n * existing runBash() call site. It reads as NOT the coordinator on purpose: only the Claude Code\n * adapter parses the payload that carries the answer, and a caller who does not know must never be\n * GUESSED into a block. Fail open; the one caller that knows passes the real identity.\n */\nexport const UNKNOWN_AGENT = new AgentIdentity('unknown', 'unknown');\n\n/**\n * L1: the COORDINATOR must not work inside a linked worktree — it must delegate that work to a\n * subagent bound to the worktree.\n *\n * THE INCIDENT (reproduced from a transcript). The coordinator ran `git worktree add ../l2-matrix-doc`,\n * `cd`'d in, and worked there for the rest of the session. Its governance stayed anchored to the\n * PRIMARY clone — `$CLAUDE_PROJECT_DIR` is fixed at session start and does not follow a `cd` — while\n * its filesystem was in the worktree. An L0 version-drift fault then fired against the PRIMARY\n * (pin 0.4.545 vs node_modules 0.4.526) and prescribed `pnpm install`; that install ran in the\n * WORKTREE, which was internally consistent at 0.4.526/0.4.526, so it succeeded, changed nothing in\n * the measured tree, and the guard re-denied. Five identical installs later the agent had invented a\n * false theory (\"the harness is stripping my cd prefix\") and handed the problem to the human.\n *\n * The cure is not a better message on that fault — it is upstream of it: a split between the tree the\n * agent stands in and the tree that governs it must not be reachable at all. A subagent bound to the\n * worktree has both in one place, so the project stays governed consistently.\n *\n * SCOPE, deliberately narrow:\n *   - `kind === 'worktree'` only. `'primary'` is home; `'foreign'` and `'outside'` are other\n *     jurisdictions and this guard leaves their classification exactly as it was.\n *   - subagents are never blocked — one pinned to a worktree is the CORRECT pattern.\n *   - reading is never blocked. The Read tool never reaches here, and a provably-inert inspection\n *     command is allowed through so the coordinator can still look around before it delegates.\n *\n * NOT in scope, and not a hole: the L0 cure allowlist runs BEFORE this in runBashInternal, so\n * `cd <worktree> && pnpm install` — the literal command from the incident — still passes. That is the\n * invariant L0 exists to hold (a cure must stay reachable), and it is fine: what this guard removes is\n * the session shape in which running that install in the wrong tree was ever plausible.\n */\nexport class CoordinatorWorktreeGuard {\n    private readonly inspection = new ReadOnlyInspectionScan();\n\n    /** The deny report, or null to allow. */\n    block(command: string, tree: EffectiveTree, agent: AgentIdentity): string | null {\n        if (!agent.coordinator) return null;\n        if (tree.kind !== 'worktree') return null;\n        if (this.inspection.isReadOnlyInspection(command)) return null;\n        return this.report(tree);\n    }\n\n    // Short on purpose — main landed a deliberate L0 message diet (384cdae) and these blocks regress\n    // straight back to a wall of text if each new one argues its case. State the block, name the\n    // worktree, prescribe the subagent, list the read-only escapes. Nothing else.\n    private report(tree: EffectiveTree): string {\n        return [\n            `❌ You are the COORDINATOR and this command works inside linked worktree ${tree.root}.`,\n            `   Your governance is anchored to ${tree.governedRoot} and does NOT follow a \\`cd\\`, so working`,\n            `   here splits your filesystem from your guards — the failure that burned five no-op installs.`,\n            '',\n            '   Spawn a subagent bound to that worktree and work through it: the Agent tool with worktree',\n            `   isolation, or have the subagent call EnterWorktree with path: ${tree.root}`,\n            '',\n            `   You can still READ from here without moving: the Read tool, \\`git -C ${tree.root} <cmd>\\`,`,\n            '   or `git show <branch>:<file>`.',\n        ].join('\\n');\n    }\n}\n"]}

package/src/core/effective-tree.js.map

@@ -1 +1 @@
-{"version":3,"file":"effective-tree.js","sourceRoot":"","sources":["../../../../../../packages/tooling/ai-hook-rules/src/core/effective-tree.ts"],"names":[],"mappings":"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","sourcesContent":["import * as path from 'path';\nimport { spawnSync } from 'child_process';\n\nimport { WorktreeService, Worktree } from '@webpieces/rules-config';\n\nimport { CommandScanner } from './command-scan';\nimport { ShellSegmentScan } from './rules/shell-segment-scan';\n\n/**\n * WHICH TREE does a Bash command actually act on? The ONE resolver every bash guard and the\n * force-to-root check share.\n *\n * WHY it has to exist at all: the shell cwd a PreToolUse hook is handed does not tell you which tree\n * the command acts on. `cd` behaves TWO different ways, and both break a cwd-based guard:\n *\n *   - A `cd` that stays INSIDE the session's working directory PERSISTS to later calls. So the cwd\n *     can be a subdirectory of the governed root, left there by an unrelated command several turns\n *     earlier — a relative path then resolves somewhere other than the root while still being in the\n *     governed tree.\n *   - A `cd` that LEAVES it is reset by the harness, which says so (`Shell cwd was reset to <root>`).\n *     So an agent working in a linked worktree is back in the primary clone by the next call and must\n *     write self-contained `cd <worktree> && …` commands — and the cwd the hook sees is the primary\n *     clone, not the worktree the command targets.\n *\n * (Measured on 2026-08-02: `cd backlog && pwd` → `…/backlog`, then a bare `pwd` in a FRESH call →\n * still `…/backlog`. But `cd ../<linked-worktree> && pwd` → the worktree, then a bare `pwd` → back at\n * the primary clone. An earlier version of this comment asserted `cd` never persists; that was the\n * worktree case generalized. The conclusion below is unchanged — only the reason was wrong.)\n *\n * Either way a guard that reasons from the raw cwd judges the wrong tree. Three field sightings in\n * one session:\n * an `ls` of a path outside every repo blocked as \"this branch is merged\"; a version-drift cure\n * (`pnpm install`) that could not be typed from the directory that needed it; and a command aimed at\n * `/private/tmp` blocked because the PRIMARY clone's main was behind — with a remedy (`git pull` in\n * the primary clone) the agent had been explicitly forbidden to run.\n *\n * Two separate copies of the cwd logic used to exist (the runner's foreign-repo/excludePaths check\n * and force-to-root). They are both this class now: two resolvers WILL disagree about which tree you\n * are in, and a guard that disagrees with the guard beside it is worse than either being wrong.\n *\n * Resolution, in order:\n *   1. `effectiveCwd` — the leading run of `cd`/`pushd` in the command itself, resolved left to right.\n *   2. If that sits under the governed root, the tree is the governed root unless git says the\n *      directory belongs to a DIFFERENT repo (a nested clone under `repositories/**`) → foreign.\n *   3. Otherwise ask git for the worktree list. A LINKED WORKTREE of the governed repo is MANAGED —\n *      it is the same project, just another checkout — so guards run, keyed on THAT tree's branch and\n *      its own `.webpieces/` cache. Before this, a linked worktree read as a different git toplevel\n *      and so as FOREIGN, which silently disabled every guard for `cd <worktree> && …` commands.\n *   4. Anything else that is a git repo → foreign (out of scope, hands-off, as before).\n *   5. Not a git repo at all (`cd /tmp && …`) → OUTSIDE. The guards still run — an absolute path back\n *      into the repo must still be judged — but nothing the command names relative to `/tmp` is\n *      workspace content, which is what ContentReadScan uses `effectiveCwd` for.\n */\n// L1's K dimension. 'primary' and 'worktree' are never distinguished by a guard (a linked worktree is\n// the same project) — guards/L1-location.md writes them as one value, `pw`.\n//\n// 'outside' is produced below (gitRoot === null) and consumed NOWHERE, so a command in no git repo is\n// judged against governedRoot — a repo it is not in. guards/L1-location.md's \"Not done\" section explains why\n// exempting it must ship together with target-based jurisdiction, never alone.\nexport type TreeKind = 'primary' | 'worktree' | 'foreign' | 'outside';\n\n/** Data-only (per CLAUDE.md, classes for data). */\nexport class EffectiveTree {\n    /** The pre-`cd` cwd the hook was handed. For an agent in a worktree this is the primary clone. */\n    readonly shellCwd: string;\n    /** The directory the command really runs in, after its own leading `cd`/`pushd` run. */\n    readonly effectiveCwd: string;\n    /** The tree root to JUDGE: the owning worktree root, the foreign repo root, or the governed root. */\n    readonly root: string;\n    /** The root that owns webpieces.config.json — where config and excludePaths come from. */\n    readonly governedRoot: string;\n    readonly kind: TreeKind;\n    /** The command acts on a tree other than the shell's own — messages must steer with `cd <root> &&`. */\n    readonly redirected: boolean;\n\n    constructor(shellCwd: string, effectiveCwd: string, root: string, governedRoot: string, kind: TreeKind) {\n        this.shellCwd = shellCwd;\n        this.effectiveCwd = effectiveCwd;\n        this.root = root;\n        this.governedRoot = governedRoot;\n        this.kind = kind;\n        this.redirected = path.resolve(root) !== path.resolve(shellCwd);\n    }\n}\n\nexport class EffectiveTreeResolver {\n    private readonly worktrees = new WorktreeService();\n    private readonly shell: ShellSegmentScan;\n\n    constructor(private readonly scanner: CommandScanner = new CommandScanner()) {\n        this.shell = new ShellSegmentScan(scanner);\n    }\n\n    resolve(command: string, shellCwd: string, governedRoot: string): EffectiveTree {\n        const effectiveCwd = this.effectiveCwd(command, shellCwd);\n        const kindAndRoot = this.classify(effectiveCwd, governedRoot);\n        return new EffectiveTree(shellCwd, effectiveCwd, kindAndRoot.root, governedRoot, kindAndRoot.kind);\n    }\n\n    /**\n     * The cwd a command actually runs from, resolving a LEADING run of `cd`/`pushd` in the command.\n     *\n     * ONLY a leading run counts. Once a non-cd command appears it has ALREADY run in the current dir,\n     * so a later `cd` must not retroactively pull it out of scope — otherwise a trailing\n     * `… && cd <exempt-tree>` would exempt the WHOLE line, smuggling a root-level `git push` past the\n     * guards. `cd a && cd b && git …` resolves left to right, matching the shell.\n     *\n     * Segmentation is ShellSegmentScan's (over CommandScanner), so quoting is handled exactly as the\n     * guards handle it: `echo \"cd sub && git push\"` is ONE opaque segment whose first word is `echo`,\n     * so the quoted `cd` is never picked up and cannot be weaponised into a scope escape.\n     */\n    effectiveCwd(command: string, shellCwd: string): string {\n        let effective = shellCwd;\n        for (const segment of this.scanner.commandSegments(command)) {\n            const words = this.shell.effectiveWords(segment);\n            if (words[0] !== 'cd' && words[0] !== 'pushd') break;\n            if (words[1] !== undefined) effective = path.resolve(effective, words[1]);\n        }\n        return effective;\n    }\n\n    private classify(effectiveCwd: string, governedRoot: string): TreeClassification {\n        // Fast path — no `cd`, or a `cd` within the governed tree. No worktree enumeration needed, and\n        // the nested-clone check keeps its exact previous behaviour.\n        if (this.isInside(effectiveCwd, governedRoot)) {\n            const gitRoot = gitToplevel(effectiveCwd);\n            if (gitRoot === null) return new TreeClassification('primary', governedRoot);\n            if (path.resolve(gitRoot) === path.resolve(governedRoot)) return new TreeClassification('primary', governedRoot);\n            return new TreeClassification('foreign', gitRoot);\n        }\n\n        // Outside the governed tree: is it a linked worktree of the SAME repo? Longest match wins, so a\n        // worktree nested under another resolves to the innermost one.\n        const owner = this.owningWorktree(effectiveCwd, governedRoot);\n        if (owner !== null) {\n            return new TreeClassification(owner.isMain ? 'primary' : 'worktree', owner.path);\n        }\n\n        const gitRoot = gitToplevel(effectiveCwd);\n        if (gitRoot === null) return new TreeClassification('outside', governedRoot);\n        if (path.resolve(gitRoot) === path.resolve(governedRoot)) return new TreeClassification('primary', governedRoot);\n        return new TreeClassification('foreign', gitRoot);\n    }\n\n    private owningWorktree(dir: string, governedRoot: string): Worktree | null {\n        let best: Worktree | null = null;\n        for (const tree of this.worktrees.listWorktrees(governedRoot)) {\n            if (!this.isInside(dir, tree.path)) continue;\n            if (best === null || tree.path.length > best.path.length) best = tree;\n        }\n        return best;\n    }\n\n    /** Is `dir` the directory `root` itself, or somewhere beneath it? Pure path math, no filesystem. */\n    private isInside(dir: string, root: string): boolean {\n        const relative = path.relative(path.resolve(root), path.resolve(dir));\n        return relative === '' || (!relative.startsWith('..') && !path.isAbsolute(relative));\n    }\n}\n\n/** Data-only carrier for the two values classify() decides together. */\nclass TreeClassification {\n    readonly kind: TreeKind;\n    readonly root: string;\n\n    constructor(kind: TreeKind, root: string) {\n        this.kind = kind;\n        this.root = root;\n    }\n}\n\n/**\n * The steering prefix every remedy needs, re-exported from @webpieces/rules-config so the guards, the\n * message builders and pr-gate's worktree notices all emit the IDENTICAL string — including the single\n * quotes that keep it runnable when the repo path contains a space. See atRoot's own header for why the\n * quotes are single and never double.\n */\nexport { atRoot } from '@webpieces/rules-config';\n\n// The git repo root of `dir`, or null when it is not in a git repo / git is unavailable. `status !== 0`\n// IS the expected \"not a repo\" answer (spawnSync does not throw on a non-zero exit), so no try/catch.\n// webpieces-disable no-function-outside-class -- sibling of atRoot(); this module is the resolver plus its two pure helpers\nfunction gitToplevel(dir: string): string | null {\n    const r = spawnSync('git', ['-C', dir, 'rev-parse', '--show-toplevel'], { encoding: 'utf8' });\n    if (r.status !== 0) return null;\n    const root = (r.stdout ?? '').trim();\n    return root !== '' ? root : null;\n}\n"]}
+{"version":3,"file":"effective-tree.js","sourceRoot":"","sources":["../../../../../../packages/tooling/ai-hook-rules/src/core/effective-tree.ts"],"names":[],"mappings":"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","sourcesContent":["import * as path from 'path';\nimport { spawnSync } from 'child_process';\n\nimport { WorktreeService, Worktree } from '@webpieces/rules-config';\n\nimport { CommandScanner } from './command-scan';\nimport { ShellSegmentScan } from './rules/shell-segment-scan';\n\n/**\n * WHICH TREE does a Bash command actually act on? The ONE resolver every bash guard and the\n * force-to-root check share.\n *\n * WHY it has to exist at all: the shell cwd a PreToolUse hook is handed does not tell you which tree\n * the command acts on. `cd` behaves TWO different ways, and both break a cwd-based guard:\n *\n *   - A `cd` that stays INSIDE the session's working directory PERSISTS to later calls. So the cwd\n *     can be a subdirectory of the governed root, left there by an unrelated command several turns\n *     earlier — a relative path then resolves somewhere other than the root while still being in the\n *     governed tree.\n *   - A `cd` that LEAVES it is reset by the harness, which says so (`Shell cwd was reset to <root>`).\n *     So an agent working in a linked worktree is back in the primary clone by the next call and must\n *     write self-contained `cd <worktree> && …` commands — and the cwd the hook sees is the primary\n *     clone, not the worktree the command targets.\n *\n * (Measured on 2026-08-02: `cd backlog && pwd` → `…/backlog`, then a bare `pwd` in a FRESH call →\n * still `…/backlog`. But `cd ../<linked-worktree> && pwd` → the worktree, then a bare `pwd` → back at\n * the primary clone. An earlier version of this comment asserted `cd` never persists; that was the\n * worktree case generalized. The conclusion below is unchanged — only the reason was wrong.)\n *\n * Either way a guard that reasons from the raw cwd judges the wrong tree. Three field sightings in\n * one session:\n * an `ls` of a path outside every repo blocked as \"this branch is merged\"; a version-drift cure\n * (`pnpm install`) that could not be typed from the directory that needed it; and a command aimed at\n * `/private/tmp` blocked because the PRIMARY clone's main was behind — with a remedy (`git pull` in\n * the primary clone) the agent had been explicitly forbidden to run.\n *\n * Two separate copies of the cwd logic used to exist (the runner's foreign-repo/excludePaths check\n * and force-to-root). They are both this class now: two resolvers WILL disagree about which tree you\n * are in, and a guard that disagrees with the guard beside it is worse than either being wrong.\n *\n * Resolution, in order:\n *   1. `effectiveCwd` — the leading run of `cd`/`pushd` in the command itself, resolved left to right.\n *   2. If that sits under the governed root, the tree is the governed root unless git says the\n *      directory belongs to a DIFFERENT repo (a nested clone under `repositories/**`) → foreign.\n *   3. Otherwise ask git for the worktree list. A LINKED WORKTREE of the governed repo is MANAGED —\n *      it is the same project, just another checkout — so guards run, keyed on THAT tree's branch and\n *      its own `.webpieces/` cache. Before this, a linked worktree read as a different git toplevel\n *      and so as FOREIGN, which silently disabled every guard for `cd <worktree> && …` commands.\n *   4. Anything else that is a git repo → foreign (out of scope, hands-off, as before).\n *   5. Not a git repo at all (`cd /tmp && …`) → OUTSIDE. The guards still run — an absolute path back\n *      into the repo must still be judged — but nothing the command names relative to `/tmp` is\n *      workspace content, which is what ContentReadScan uses `effectiveCwd` for.\n */\n// L1's K dimension. 'primary' and 'worktree' are the same PROJECT, so every rule-scoped guard treats\n// them alike — guards/L1-location.md writes them as one value, `pw`. Exactly ONE guard separates them,\n// and on a dimension that is not the tree at all: CoordinatorWorktreeGuard blocks the COORDINATOR\n// (never a subagent) from working inside a linked worktree, because the coordinator's governance is\n// anchored at session start and does not follow a `cd`.\n//\n// 'outside' is produced below (gitRoot === null) and consumed NOWHERE, so a command in no git repo is\n// judged against governedRoot — a repo it is not in. guards/L1-location.md's \"Not done\" section explains why\n// exempting it must ship together with target-based jurisdiction, never alone.\nexport type TreeKind = 'primary' | 'worktree' | 'foreign' | 'outside';\n\n/** Data-only (per CLAUDE.md, classes for data). */\nexport class EffectiveTree {\n    /** The pre-`cd` cwd the hook was handed. For an agent in a worktree this is the primary clone. */\n    readonly shellCwd: string;\n    /** The directory the command really runs in, after its own leading `cd`/`pushd` run. */\n    readonly effectiveCwd: string;\n    /** The tree root to JUDGE: the owning worktree root, the foreign repo root, or the governed root. */\n    readonly root: string;\n    /** The root that owns webpieces.config.json — where config and excludePaths come from. */\n    readonly governedRoot: string;\n    readonly kind: TreeKind;\n    /** The command acts on a tree other than the shell's own — messages must steer with `cd <root> &&`. */\n    readonly redirected: boolean;\n\n    constructor(shellCwd: string, effectiveCwd: string, root: string, governedRoot: string, kind: TreeKind) {\n        this.shellCwd = shellCwd;\n        this.effectiveCwd = effectiveCwd;\n        this.root = root;\n        this.governedRoot = governedRoot;\n        this.kind = kind;\n        this.redirected = path.resolve(root) !== path.resolve(shellCwd);\n    }\n}\n\nexport class EffectiveTreeResolver {\n    private readonly worktrees = new WorktreeService();\n    private readonly shell: ShellSegmentScan;\n\n    constructor(private readonly scanner: CommandScanner = new CommandScanner()) {\n        this.shell = new ShellSegmentScan(scanner);\n    }\n\n    resolve(command: string, shellCwd: string, governedRoot: string): EffectiveTree {\n        const effectiveCwd = this.effectiveCwd(command, shellCwd);\n        const kindAndRoot = this.classify(effectiveCwd, governedRoot);\n        return new EffectiveTree(shellCwd, effectiveCwd, kindAndRoot.root, governedRoot, kindAndRoot.kind);\n    }\n\n    /**\n     * The cwd a command actually runs from, resolving a LEADING run of `cd`/`pushd` in the command.\n     *\n     * ONLY a leading run counts. Once a non-cd command appears it has ALREADY run in the current dir,\n     * so a later `cd` must not retroactively pull it out of scope — otherwise a trailing\n     * `… && cd <exempt-tree>` would exempt the WHOLE line, smuggling a root-level `git push` past the\n     * guards. `cd a && cd b && git …` resolves left to right, matching the shell.\n     *\n     * Segmentation is ShellSegmentScan's (over CommandScanner), so quoting is handled exactly as the\n     * guards handle it: `echo \"cd sub && git push\"` is ONE opaque segment whose first word is `echo`,\n     * so the quoted `cd` is never picked up and cannot be weaponised into a scope escape.\n     */\n    effectiveCwd(command: string, shellCwd: string): string {\n        let effective = shellCwd;\n        for (const segment of this.scanner.commandSegments(command)) {\n            const words = this.shell.effectiveWords(segment);\n            if (words[0] !== 'cd' && words[0] !== 'pushd') break;\n            if (words[1] !== undefined) effective = path.resolve(effective, words[1]);\n        }\n        return effective;\n    }\n\n    private classify(effectiveCwd: string, governedRoot: string): TreeClassification {\n        // Fast path — no `cd`, or a `cd` within the governed tree. No worktree enumeration needed, and\n        // the nested-clone check keeps its exact previous behaviour.\n        if (this.isInside(effectiveCwd, governedRoot)) {\n            const gitRoot = gitToplevel(effectiveCwd);\n            if (gitRoot === null) return new TreeClassification('primary', governedRoot);\n            if (path.resolve(gitRoot) === path.resolve(governedRoot)) return new TreeClassification('primary', governedRoot);\n            return new TreeClassification('foreign', gitRoot);\n        }\n\n        // Outside the governed tree: is it a linked worktree of the SAME repo? Longest match wins, so a\n        // worktree nested under another resolves to the innermost one.\n        const owner = this.owningWorktree(effectiveCwd, governedRoot);\n        if (owner !== null) {\n            return new TreeClassification(owner.isMain ? 'primary' : 'worktree', owner.path);\n        }\n\n        const gitRoot = gitToplevel(effectiveCwd);\n        if (gitRoot === null) return new TreeClassification('outside', governedRoot);\n        if (path.resolve(gitRoot) === path.resolve(governedRoot)) return new TreeClassification('primary', governedRoot);\n        return new TreeClassification('foreign', gitRoot);\n    }\n\n    private owningWorktree(dir: string, governedRoot: string): Worktree | null {\n        let best: Worktree | null = null;\n        for (const tree of this.worktrees.listWorktrees(governedRoot)) {\n            if (!this.isInside(dir, tree.path)) continue;\n            if (best === null || tree.path.length > best.path.length) best = tree;\n        }\n        return best;\n    }\n\n    /** Is `dir` the directory `root` itself, or somewhere beneath it? Pure path math, no filesystem. */\n    private isInside(dir: string, root: string): boolean {\n        const relative = path.relative(path.resolve(root), path.resolve(dir));\n        return relative === '' || (!relative.startsWith('..') && !path.isAbsolute(relative));\n    }\n}\n\n/** Data-only carrier for the two values classify() decides together. */\nclass TreeClassification {\n    readonly kind: TreeKind;\n    readonly root: string;\n\n    constructor(kind: TreeKind, root: string) {\n        this.kind = kind;\n        this.root = root;\n    }\n}\n\n/**\n * The steering prefix every remedy needs, re-exported from @webpieces/rules-config so the guards, the\n * message builders and pr-gate's worktree notices all emit the IDENTICAL string — including the single\n * quotes that keep it runnable when the repo path contains a space. See atRoot's own header for why the\n * quotes are single and never double.\n */\nexport { atRoot } from '@webpieces/rules-config';\n\n// The git repo root of `dir`, or null when it is not in a git repo / git is unavailable. `status !== 0`\n// IS the expected \"not a repo\" answer (spawnSync does not throw on a non-zero exit), so no try/catch.\n// webpieces-disable no-function-outside-class -- sibling of atRoot(); this module is the resolver plus its two pure helpers\nfunction gitToplevel(dir: string): string | null {\n    const r = spawnSync('git', ['-C', dir, 'rev-parse', '--show-toplevel'], { encoding: 'utf8' });\n    if (r.status !== 0) return null;\n    const root = (r.stdout ?? '').trim();\n    return root !== '' ? root : null;\n}\n"]}

package/src/core/l0-matrix.js

@@ -103,7 +103,7 @@ exports.L0Fault = L0Fault;
 // ORDERING (2026-08-02): writing the file yourself now LEADS. The bare installer used to be OPTION 1,
 // but it seeds the config and then PROMPTS twice for a hook target, which hangs a non-interactive
 // agent. Writing the file is the one cure that always works, and it is the same cure every other config
-// problem has (see the config-validation invariant in GUARD_MATRIX.md): the validator reports every
+// problem has (see the config-validation invariant in guards/L0-tooling.md): the validator reports every
 // error at once, so the write/validate loop converges in a couple of passes.
 exports.CONFIG_MISSING_REPORT = `${rules_config_1.CONFIG_FILENAME} not found — the webpieces guards cannot run without it, so every other tool call is blocked.\n` +
     'THIS IS NOT A DEADLOCK: both options below are explicitly allowed through while this guard is up.\n' +
@@ -119,7 +119,7 @@ exports.CONFIG_MISSING_REPORT = `${rules_config_1.CONFIG_FILENAME} not found —
 // detail). Kept here so the fault table quotes the same text the runner emits.
 exports.CONFIG_OUT_OF_SYNC_HEADER = `${rules_config_1.CONFIG_FILENAME} is out of sync — new built-in rules are present that have no entry in ${rules_config_1.CONFIG_FILENAME}.`;
 // Writing/repairing the file yourself. PREFERRED for both config faults, per the config-validation
-// invariant in GUARD_MATRIX.md: every config problem cures to "make the file right", the validator
+// invariant in guards/L0-tooling.md: every config problem cures to "make the file right", the validator
 // reports all errors at once so the loop converges in a couple of passes, and allowlist entry 2 permits
 // this edit unconditionally. (That section is the authority — do not restate its reasoning here.)
 const CONFIG_WRITE_CURE = new L0Cure(rules_config_1.CONFIG_FILENAME, new shim_1.L0Call('Edit', '', `/repo/${rules_config_1.CONFIG_FILENAME}`), true, 'this fault fires at all — it is the only cure that needs no other tool, and it is never denied');

package/src/core/l0-matrix.js.map

@@ -1 +1 @@
-{"version":3,"file":"l0-matrix.js","sourceRoot":"","sources":["../../../../../../packages/tooling/ai-hook-rules/src/core/l0-matrix.ts"],"names":[],"mappings":"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","sourcesContent":["import { CONFIG_FILENAME, writeTemplate } from '@webpieces/rules-config';\n\nimport {\n    INSTALL_HOOKS_CMD, L0AllowEntry, L0Call, L0_ALLOWLIST, RECOVERY_CMD,\n    RESTORE_SHIM_CMD, UPGRADE_SHIM_CMD, renderShim, shimStaleDenyReason,\n} from '../bin/shim';\nimport { toError } from './to-error';\n\n// ---------------------------------------------------------------------------\n// L0 — the TOOLING-INTEGRITY layer, as data.\n//\n// L0 is the outermost guard: it blocks work while node_modules, the committed shim, or\n// webpieces.config.json are in a state that makes every OTHER guard untrustworthy. It has SIX faults\n// and — drawn as a decision matrix — NO genuine second dimension:\n//\n//     fault present AND call not on the allowlist  ->  BLOCK(messageFor(fault))\n//\n// so the only thing that varies per fault is the MESSAGE. This module holds the fault table and\n// renders it, together with L0_ALLOWLIST (../bin/shim), into webpieces.guard-matrix.md — the doc the\n// deny messages point the AI at. Doc and code come from the SAME arrays, so they cannot drift.\n// ---------------------------------------------------------------------------\n\n/**\n * The doc L0's deny messages point at. Lives in @webpieces/rules-config/templates alongside the others,\n * and is written to <root>/.webpieces/instruct-ai/ lazily, only on an L0 BLOCK.\n *\n * That generated doc is the AUTHORITY for the fault table and the allowlist (same arrays, cannot\n * drift). guards/L0-tooling.md is the hand-written companion: it adds L0's evaluation\n * ORDER, the use cases and the known gaps, and it documents L1, none of which are rendered from code.\n * Change L0_FAULTS or L0_ALLOWLIST and the generated doc follows automatically — guards/L0-tooling.md does\n * not, so update it in the same PR.\n */\nexport const GUARD_MATRIX_DOC = 'webpieces.guard-matrix.md';\n\n/**\n * One CURE for a fault: the exact call, plus the `mention` that must appear in that fault's deny text.\n *\n * Both halves are asserted (l0-matrix.spec.ts): the call must be accepted by isAllowed(), and the deny\n * message must actually name it. That pairing is the anti-deadlock invariant — a message that\n * prescribes a command the allowlist rejects is exactly the shape of the three deadlocks CLAUDE.md\n * records, and it is how the dead `wp-setup-ai-hooks` bin in the config-missing text was caught.\n */\nexport class L0Cure {\n    // eslint-disable-next-line @typescript-eslint/max-params\n    constructor(\n        readonly mention: string,\n        readonly call: L0Call,\n        /**\n         * The one to reach for first when a fault has several. Exactly one cure per fault carries it,\n         * so the rendered Fix section never asks the reader to choose between equals.\n         */\n        readonly preferred: boolean,\n        /**\n         * WHEN to pick this cure over its siblings — the sentence that makes a list of commands\n         * actionable instead of a menu (\"when the PIN is the stale side\", not \"an alternative\").\n         */\n        readonly discriminator: string,\n    ) {}\n\n    /** A Bash cure renders as a literal command; a tool-shaped one renders as the edit it stands for. */\n    isCommand(): boolean {\n        return this.call.toolName === 'Bash';\n    }\n}\n\n/** One L0 fault. Data-only → a class, per CLAUDE.md. */\nexport class L0Fault {\n    constructor(\n        readonly code: string,\n        readonly name: string,\n        readonly detectedBy: string,\n        readonly enforcedIn: string,\n        readonly cures: readonly L0Cure[],\n        /**\n         * The artifact carrying this fault's deny text. For S/C/Y that is the deny string itself; for\n         * D/X/K the text is built in POSIX sh inside the rendered shim, so it is the rendered shim —\n         * the same bytes the consumer runs, which is what the mention assertion needs to search.\n         */\n        readonly denyText: string,\n    ) {}\n}\n\n// The deny for fault C, and the ONLY message L0 has for a repo with no webpieces.config.json at all.\n// Moved here from runner.ts so the fault table and the runner cannot state different cures.\n//\n// It used to name `./node_modules/.bin/wp-setup-ai-hooks` — a bin that HAS NOT EXISTED since it was\n// renamed to wp-install-ai-hooks. So the one command this deny prescribed was (a) not installable and\n// (b) not on the L0 allowlist in that spelling, i.e. the AI was handed a cure it could neither run nor\n// get past the guard. Now it names the installer that actually seeds the config AND is entry 8 of the\n// allowlist, and it says out loud that writing the config yourself is allowed through.\n//\n// ORDERING (2026-08-02): writing the file yourself now LEADS. The bare installer used to be OPTION 1,\n// but it seeds the config and then PROMPTS twice for a hook target, which hangs a non-interactive\n// agent. Writing the file is the one cure that always works, and it is the same cure every other config\n// problem has (see the config-validation invariant in GUARD_MATRIX.md): the validator reports every\n// error at once, so the write/validate loop converges in a couple of passes.\nexport const CONFIG_MISSING_REPORT =\n    `${CONFIG_FILENAME} not found — the webpieces guards cannot run without it, so every other tool call is blocked.\\n` +\n    'THIS IS NOT A DEADLOCK: both options below are explicitly allowed through while this guard is up.\\n' +\n    `OPTION 1 (preferred — it needs no other tool and it never prompts) - create ${CONFIG_FILENAME}\\n` +\n    'yourself: any Read, and any Write/Edit whose target is that file, is always allowed through, so\\n' +\n    'you can inspect the repo and write it. The validator reports EVERY missing/invalid entry at once\\n' +\n    '(each with the snippet to paste), so a minimal first draft converges in about two passes.\\n' +\n    'OPTION 2 (pick this ONLY at an interactive terminal where you can answer its two prompts) - run\\n' +\n    'EXACTLY this command to seed the config: `pnpm exec wp-install-ai-hooks`. It goes on to wire the\\n' +\n    'Claude Code hooks and asks for a target twice, which hangs a non-interactive session.\\n' +\n    'Do not append anything to the option you pick — the allowlist is anchored to the whole command.';\n\n// The first line of the fault-Y deny (built out in runner.checkConfigSync, which appends the per-rule\n// detail). Kept here so the fault table quotes the same text the runner emits.\nexport const CONFIG_OUT_OF_SYNC_HEADER =\n    `${CONFIG_FILENAME} is out of sync — new built-in rules are present that have no entry in ${CONFIG_FILENAME}.`;\n\n// Writing/repairing the file yourself. PREFERRED for both config faults, per the config-validation\n// invariant in GUARD_MATRIX.md: every config problem cures to \"make the file right\", the validator\n// reports all errors at once so the loop converges in a couple of passes, and allowlist entry 2 permits\n// this edit unconditionally. (That section is the authority — do not restate its reasoning here.)\nconst CONFIG_WRITE_CURE = new L0Cure(\n    CONFIG_FILENAME, new L0Call('Edit', '', `/repo/${CONFIG_FILENAME}`), true,\n    'this fault fires at all — it is the only cure that needs no other tool, and it is never denied',\n);\n\n// Cure calls are spelled exactly as the deny messages spell them, so the mention assertion is a real\n// string search rather than a paraphrase.\n// webpieces-disable no-function-outside-class -- pure constructor helper for the L0_FAULTS literal below, in this data module\nfunction bashCure(command: string, preferred: boolean, discriminator: string): L0Cure {\n    return new L0Cure(command, new L0Call('Bash', command, ''), preferred, discriminator);\n}\n\n/**\n * THE six L0 faults, in first-match-wins order. D/X/K are decided in POSIX sh BEFORE the bin runs (a\n * stale, missing or broken validator cannot be trusted to validate itself); S/C/Y are decided inside\n * the bin, in JS. One model, two enforcement points.\n */\nexport const L0_FAULTS: readonly L0Fault[] = [\n    new L0Fault('D', 'version drift — root package.json pin != installed version',\n        'sh, before the bin runs', 'sh',\n        [\n            // `pnpm install` clears D in BOTH directions — it makes installed == pin by definition — so\n            // it is always the preferred cure. The direction only decides whether the PIN is the version\n            // you WANT, which is what the second cure is for.\n            bashCure('pnpm install', true,\n                'node_modules is OLDER than the pin, OR you are on a feature branch and want YOUR '\n                + 'branch pin (usually the case) — it always clears the drift'),\n            bashCure('git pull', false,\n                'node_modules is NEWER than the pin AND you are on main — the PIN is the stale side, so '\n                + 'pull first and install second; a bare install would downgrade you'),\n        ], renderShim()),\n    new L0Fault('X', 'guard bin missing (fresh clone / new worktree / package removed)',\n        'sh, before the bin runs', 'sh',\n        [bashCure('pnpm install', true,\n            'this fault fires at all — nothing is installed in THIS tree, and a new git worktree '\n            + 'copies no node_modules')],\n        renderShim()),\n    new L0Fault('K', 'guard bin present but CRASHED (exit code not 0 or 2 — corrupt node_modules)',\n        'sh, before the bin runs', 'sh',\n        [bashCure(RECOVERY_CMD, true,\n            'this fault fires at all — a BARE pnpm install SKIPS the corrupt package, because pnpm sees '\n            + 'the right version on disk and considers it installed; only the delete forces a rewrite')],\n        renderShim()),\n    new L0Fault('S', 'committed .claude/webpieces/ai-hook.sh != renderShim()',\n        'the guard bin', 'JS',\n        [\n            // wp-upgrade-shim is the SURGICAL tool and therefore leads: upgrade-shim.ts writes\n            // renderShim() to .claude/webpieces/ai-hook.sh and touches nothing else — no config, no\n            // settings.json — and it imports only fs/path, so it runs on a tree too broken to load the\n            // rule engine. The INSTALLER is deliberately NOT a cure here: it also migrates the config\n            // and wires BOTH hooks, prompting for a target twice, which hangs a non-interactive agent.\n            bashCure(UPGRADE_SHIM_CMD, true,\n                'this fault fires at all — it regenerates the shim and NOTHING else (no config, no '\n                + 'settings.json); needs installed @webpieces/ai-hook-rules 0.4.408 or newer'),\n            // 2026-07-21: the version gap below caused a real \"command not found\" deadlock.\n            bashCure(RESTORE_SHIM_CMD, false,\n                'the installed @webpieces/ai-hook-rules is OLDER than 0.4.408, so wp-upgrade-shim does '\n                + 'not exist yet — this works on every release, though Claude Code may ask you to '\n                + 'confirm the overwrite, and that prompt is NOT this guard'),\n        ],\n        shimStaleDenyReason('')),\n    new L0Fault('C', `${CONFIG_FILENAME} missing`,\n        'the guard bin', 'JS',\n        [\n            CONFIG_WRITE_CURE,\n            // Kept, but demoted: it seeds the file and then PROMPTS twice for a hook target.\n            bashCure(INSTALL_HOOKS_CMD, false,\n                'you are at an INTERACTIVE terminal and can answer its two hook-target prompts'),\n        ], CONFIG_MISSING_REPORT),\n    new L0Fault('Y', `a loaded rule has no ${CONFIG_FILENAME} key`,\n        'the guard bin', 'JS',\n        [CONFIG_WRITE_CURE], CONFIG_OUT_OF_SYNC_HEADER),\n];\n\n/**\n * One fault's FIX section, rendered from its `cures` array — literal commands only, never prose.\n *\n * This is the half that used to live in hand-written docs and drift. The three fields of L0Cure map\n * onto the three things a blocked reader needs and nothing else: WHAT to type (the call), WHETHER it is\n * the default (preferred), and WHEN to pick a sibling instead (discriminator). A cure with no\n * discriminator would render as a menu of equals, which is how an agent picks the wrong one.\n */\n// webpieces-disable no-function-outside-class -- pure string builder for renderGuardMatrixDoc below, beside the arrays it reads\nfunction renderFixSection(fault: L0Fault): string[] {\n    const options = fault.cures.map((cure: L0Cure, i: number): string => {\n        // A Bash cure is the command verbatim; a tool-shaped one is the file it edits (allowlist entry 2).\n        const literal = cure.isCommand() ? `\\`${cure.call.command}\\`` : `edit \\`${cure.mention}\\` yourself`;\n        const label = cure.preferred ? `Option ${i + 1} (preferred)` : `Option ${i + 1}`;\n        return `- **${label}**: ${literal}  ← pick this when ${cure.discriminator}`;\n    });\n    return [`### \\`${fault.code}\\` — ${fault.name}`, '', ...options, ''];\n}\n\n/**\n * Render webpieces.guard-matrix.md from L0_FAULTS + L0_ALLOWLIST.\n *\n * A unit test locks the committed template byte-identical to this output, the same way\n * templates/ai-hook.sh is locked to renderShim(). That is what makes the doc assertable instead of\n * aspirational: the table in the doc IS the array the guard consults.\n */\n// webpieces-disable no-function-outside-class -- pure string builder over the two exported arrays, beside them in this module\nexport function renderGuardMatrixDoc(): string {\n    return [\n        '# webpieces guard matrix — L0 (tooling integrity)',\n        '',\n        'GENERATED from `L0_FAULTS` + `L0_ALLOWLIST` in `@webpieces/ai-hook-rules`. Do not hand-edit —',\n        'a unit test locks this file byte-identical to `renderGuardMatrixDoc()`, so the table below is',\n        'the array the guard actually consults, not a description of it.',\n        '',\n        'L0 is the OUTERMOST guard layer. It blocks work while `node_modules`, the committed shim, or',\n        '`webpieces.config.json` are in a state that makes every other guard untrustworthy. If you are',\n        'reading this, one of the six faults below fired and named this file.',\n        '',\n        '## The faults',\n        '',\n        '| code | fault | detected by | enforced in |',\n        '|---|---|---|---|',\n        ...L0_FAULTS.map((f: L0Fault): string => `| \\`${f.code}\\` | ${f.name} | ${f.detectedBy} | ${f.enforcedIn} |`),\n        '',\n        'First match wins. `D`/`X`/`K` are decided in POSIX `sh` inside the committed shim, BEFORE the',\n        'guard bin runs — a stale, missing or broken validator cannot be trusted to validate itself.',\n        '',\n        '## The fix, per fault',\n        '',\n        'Every command below is rendered from that fault\\'s `cures` array and is asserted, by unit test,',\n        'to be accepted by `isAllowed()` — so nothing here can be a command the guard then rejects. Type',\n        'the option you pick EXACTLY as written and run nothing else on that line.',\n        '',\n        ...L0_FAULTS.flatMap(renderFixSection),\n        ...renderMatrixAndAllowlist(),\n    ].join('\\n');\n}\n\n/**\n * The second half of the doc: the three-row matrix and the ONE allowlist. Split out of\n * renderGuardMatrixDoc solely to keep it inside the method-line budget — the join order is what makes\n * the two halves one file, so keep them adjacent and keep the byte-lock test as the arbiter.\n */\n// webpieces-disable no-function-outside-class -- second half of renderGuardMatrixDoc's string, beside it in this module\nfunction renderMatrixAndAllowlist(): string[] {\n    return [\n        '## The matrix',\n        '',\n        'L0 has NO genuine second dimension. Every branch reduces to one question:',\n        '',\n        '| # | fault | on the allowlist? | outcome |',\n        '|---|---|---|---|',\n        '| 1 | none | — | hand down to the next guard layer |',\n        '| 2 | any | yes | PASS or ALLOW (see the entry) |',\n        '| 3 | any | no | BLOCK — **only the message varies by fault** |',\n        '',\n        'The tool is not a dimension either: \"any Read\" is an allowlist ENTRY, not a tool check.',\n        '',\n        '## The allowlist',\n        '',\n        'ONE list, consulted identically by all six faults. A cure that cannot help a given fault also',\n        'cannot hurt it, and gating each entry on a fault is what produced four real defects (a stale',\n        'shim that denied `pnpm install` and `git pull`; faults that denied every Read; a config fault',\n        'that denied `rm -rf node_modules && pnpm install` while allowing a bare `pnpm install`).',\n        '',\n        '| # | allowed | outcome |',\n        '|---|---|---|',\n        ...L0_ALLOWLIST.map((e: L0AllowEntry, i: number): string => `| ${i + 1} | ${e.label} | ${e.kind.toUpperCase()} |`),\n        '',\n        '- **PASS** — L0 has no objection; the call falls THROUGH so the downstream guards still judge it.',\n        '- **ALLOW** — terminal; bypasses everything, because a cure must stay reachable even when a',\n        '  downstream guard would block it.',\n        '',\n        'Every Bash entry is anchored to the WHOLE command. A leading `cd <dir> &&`, a trailing `2>&1`',\n        'and a pipe into `tail`/`head` are tolerated; nothing else is. Appending `&& git status` makes it',\n        'a DIFFERENT command and it is rejected again — that is not the guard refusing its own cure.',\n        '',\n        '`git merge` is deliberately NOT on this list. Main is merged ONLY through the 3-point fork merge',\n        '(`pnpm wp-start-update`, or `pnpm wp-start-upsert-pr` when a PR is already open).',\n        '',\n        '## Known asymmetry',\n        '',\n        'Under `S`/`C`/`Y` the guard bin IS running, so a PASS really does fall through to the downstream',\n        'guards. Under `D`/`X`/`K` the bin is never executed, so there is nothing to fall through to and a',\n        'PASS degenerates into a terminal allow — reads are unguarded during those three faults.',\n        '',\n        '## Widening L0',\n        '',\n        'Add an entry to `L0_ALLOWLIST` in `packages/tooling/ai-hook-rules/src/bin/shim.ts`. That array is',\n        'the single source for the JS allowlist, the `grep -E` inside the rendered shim, and this file.',\n        '',\n    ];\n}\n\n/**\n * Drop the matrix doc where the AI can read it, and return its absolute path ('' if it could not be\n * written). Called from the L0 BLOCK path so the deny can say `READ <path>`.\n *\n * Best-effort by design: this runs while the tree is already known-broken, and a missing template (an\n * @webpieces/rules-config older than this package) must degrade the deny message, never replace it\n * with a crash.\n */\n// webpieces-disable no-function-outside-class -- sibling of renderGuardMatrixDoc in this module\nexport function writeGuardMatrixDoc(workspaceRoot: string): string {\n    // eslint-disable-next-line @webpieces/no-unmanaged-exceptions\n    try {\n        return writeTemplate(workspaceRoot, GUARD_MATRIX_DOC);\n    } catch (err: unknown) {\n        const error = toError(err);\n        void error; // best-effort: no doc → the deny simply omits the pointer\n        return '';\n    }\n}\n\n/** The `READ <path>` pointer appended to an L0 deny, or '' when the doc could not be written. */\n// webpieces-disable no-function-outside-class -- sibling of writeGuardMatrixDoc in this module\nexport function guardMatrixPointer(docPath: string): string {\n    if (docPath === '') return '';\n    return ` The full L0 guard matrix - all six faults and everything that is allowed through - is at ${docPath}; READ it if you are unsure why this call was blocked.`;\n}\n"]}
+{"version":3,"file":"l0-matrix.js","sourceRoot":"","sources":["../../../../../../packages/tooling/ai-hook-rules/src/core/l0-matrix.ts"],"names":[],"mappings":"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","sourcesContent":["import { CONFIG_FILENAME, writeTemplate } from '@webpieces/rules-config';\n\nimport {\n    INSTALL_HOOKS_CMD, L0AllowEntry, L0Call, L0_ALLOWLIST, RECOVERY_CMD,\n    RESTORE_SHIM_CMD, UPGRADE_SHIM_CMD, renderShim, shimStaleDenyReason,\n} from '../bin/shim';\nimport { toError } from './to-error';\n\n// ---------------------------------------------------------------------------\n// L0 — the TOOLING-INTEGRITY layer, as data.\n//\n// L0 is the outermost guard: it blocks work while node_modules, the committed shim, or\n// webpieces.config.json are in a state that makes every OTHER guard untrustworthy. It has SIX faults\n// and — drawn as a decision matrix — NO genuine second dimension:\n//\n//     fault present AND call not on the allowlist  ->  BLOCK(messageFor(fault))\n//\n// so the only thing that varies per fault is the MESSAGE. This module holds the fault table and\n// renders it, together with L0_ALLOWLIST (../bin/shim), into webpieces.guard-matrix.md — the doc the\n// deny messages point the AI at. Doc and code come from the SAME arrays, so they cannot drift.\n// ---------------------------------------------------------------------------\n\n/**\n * The doc L0's deny messages point at. Lives in @webpieces/rules-config/templates alongside the others,\n * and is written to <root>/.webpieces/instruct-ai/ lazily, only on an L0 BLOCK.\n *\n * That generated doc is the AUTHORITY for the fault table and the allowlist (same arrays, cannot\n * drift). guards/L0-tooling.md is the hand-written companion: it adds L0's evaluation\n * ORDER, the use cases and the known gaps, and it documents L1, none of which are rendered from code.\n * Change L0_FAULTS or L0_ALLOWLIST and the generated doc follows automatically — guards/L0-tooling.md does\n * not, so update it in the same PR.\n */\nexport const GUARD_MATRIX_DOC = 'webpieces.guard-matrix.md';\n\n/**\n * One CURE for a fault: the exact call, plus the `mention` that must appear in that fault's deny text.\n *\n * Both halves are asserted (l0-matrix.spec.ts): the call must be accepted by isAllowed(), and the deny\n * message must actually name it. That pairing is the anti-deadlock invariant — a message that\n * prescribes a command the allowlist rejects is exactly the shape of the three deadlocks CLAUDE.md\n * records, and it is how the dead `wp-setup-ai-hooks` bin in the config-missing text was caught.\n */\nexport class L0Cure {\n    // eslint-disable-next-line @typescript-eslint/max-params\n    constructor(\n        readonly mention: string,\n        readonly call: L0Call,\n        /**\n         * The one to reach for first when a fault has several. Exactly one cure per fault carries it,\n         * so the rendered Fix section never asks the reader to choose between equals.\n         */\n        readonly preferred: boolean,\n        /**\n         * WHEN to pick this cure over its siblings — the sentence that makes a list of commands\n         * actionable instead of a menu (\"when the PIN is the stale side\", not \"an alternative\").\n         */\n        readonly discriminator: string,\n    ) {}\n\n    /** A Bash cure renders as a literal command; a tool-shaped one renders as the edit it stands for. */\n    isCommand(): boolean {\n        return this.call.toolName === 'Bash';\n    }\n}\n\n/** One L0 fault. Data-only → a class, per CLAUDE.md. */\nexport class L0Fault {\n    constructor(\n        readonly code: string,\n        readonly name: string,\n        readonly detectedBy: string,\n        readonly enforcedIn: string,\n        readonly cures: readonly L0Cure[],\n        /**\n         * The artifact carrying this fault's deny text. For S/C/Y that is the deny string itself; for\n         * D/X/K the text is built in POSIX sh inside the rendered shim, so it is the rendered shim —\n         * the same bytes the consumer runs, which is what the mention assertion needs to search.\n         */\n        readonly denyText: string,\n    ) {}\n}\n\n// The deny for fault C, and the ONLY message L0 has for a repo with no webpieces.config.json at all.\n// Moved here from runner.ts so the fault table and the runner cannot state different cures.\n//\n// It used to name `./node_modules/.bin/wp-setup-ai-hooks` — a bin that HAS NOT EXISTED since it was\n// renamed to wp-install-ai-hooks. So the one command this deny prescribed was (a) not installable and\n// (b) not on the L0 allowlist in that spelling, i.e. the AI was handed a cure it could neither run nor\n// get past the guard. Now it names the installer that actually seeds the config AND is entry 8 of the\n// allowlist, and it says out loud that writing the config yourself is allowed through.\n//\n// ORDERING (2026-08-02): writing the file yourself now LEADS. The bare installer used to be OPTION 1,\n// but it seeds the config and then PROMPTS twice for a hook target, which hangs a non-interactive\n// agent. Writing the file is the one cure that always works, and it is the same cure every other config\n// problem has (see the config-validation invariant in guards/L0-tooling.md): the validator reports every\n// error at once, so the write/validate loop converges in a couple of passes.\nexport const CONFIG_MISSING_REPORT =\n    `${CONFIG_FILENAME} not found — the webpieces guards cannot run without it, so every other tool call is blocked.\\n` +\n    'THIS IS NOT A DEADLOCK: both options below are explicitly allowed through while this guard is up.\\n' +\n    `OPTION 1 (preferred — it needs no other tool and it never prompts) - create ${CONFIG_FILENAME}\\n` +\n    'yourself: any Read, and any Write/Edit whose target is that file, is always allowed through, so\\n' +\n    'you can inspect the repo and write it. The validator reports EVERY missing/invalid entry at once\\n' +\n    '(each with the snippet to paste), so a minimal first draft converges in about two passes.\\n' +\n    'OPTION 2 (pick this ONLY at an interactive terminal where you can answer its two prompts) - run\\n' +\n    'EXACTLY this command to seed the config: `pnpm exec wp-install-ai-hooks`. It goes on to wire the\\n' +\n    'Claude Code hooks and asks for a target twice, which hangs a non-interactive session.\\n' +\n    'Do not append anything to the option you pick — the allowlist is anchored to the whole command.';\n\n// The first line of the fault-Y deny (built out in runner.checkConfigSync, which appends the per-rule\n// detail). Kept here so the fault table quotes the same text the runner emits.\nexport const CONFIG_OUT_OF_SYNC_HEADER =\n    `${CONFIG_FILENAME} is out of sync — new built-in rules are present that have no entry in ${CONFIG_FILENAME}.`;\n\n// Writing/repairing the file yourself. PREFERRED for both config faults, per the config-validation\n// invariant in guards/L0-tooling.md: every config problem cures to \"make the file right\", the validator\n// reports all errors at once so the loop converges in a couple of passes, and allowlist entry 2 permits\n// this edit unconditionally. (That section is the authority — do not restate its reasoning here.)\nconst CONFIG_WRITE_CURE = new L0Cure(\n    CONFIG_FILENAME, new L0Call('Edit', '', `/repo/${CONFIG_FILENAME}`), true,\n    'this fault fires at all — it is the only cure that needs no other tool, and it is never denied',\n);\n\n// Cure calls are spelled exactly as the deny messages spell them, so the mention assertion is a real\n// string search rather than a paraphrase.\n// webpieces-disable no-function-outside-class -- pure constructor helper for the L0_FAULTS literal below, in this data module\nfunction bashCure(command: string, preferred: boolean, discriminator: string): L0Cure {\n    return new L0Cure(command, new L0Call('Bash', command, ''), preferred, discriminator);\n}\n\n/**\n * THE six L0 faults, in first-match-wins order. D/X/K are decided in POSIX sh BEFORE the bin runs (a\n * stale, missing or broken validator cannot be trusted to validate itself); S/C/Y are decided inside\n * the bin, in JS. One model, two enforcement points.\n */\nexport const L0_FAULTS: readonly L0Fault[] = [\n    new L0Fault('D', 'version drift — root package.json pin != installed version',\n        'sh, before the bin runs', 'sh',\n        [\n            // `pnpm install` clears D in BOTH directions — it makes installed == pin by definition — so\n            // it is always the preferred cure. The direction only decides whether the PIN is the version\n            // you WANT, which is what the second cure is for.\n            bashCure('pnpm install', true,\n                'node_modules is OLDER than the pin, OR you are on a feature branch and want YOUR '\n                + 'branch pin (usually the case) — it always clears the drift'),\n            bashCure('git pull', false,\n                'node_modules is NEWER than the pin AND you are on main — the PIN is the stale side, so '\n                + 'pull first and install second; a bare install would downgrade you'),\n        ], renderShim()),\n    new L0Fault('X', 'guard bin missing (fresh clone / new worktree / package removed)',\n        'sh, before the bin runs', 'sh',\n        [bashCure('pnpm install', true,\n            'this fault fires at all — nothing is installed in THIS tree, and a new git worktree '\n            + 'copies no node_modules')],\n        renderShim()),\n    new L0Fault('K', 'guard bin present but CRASHED (exit code not 0 or 2 — corrupt node_modules)',\n        'sh, before the bin runs', 'sh',\n        [bashCure(RECOVERY_CMD, true,\n            'this fault fires at all — a BARE pnpm install SKIPS the corrupt package, because pnpm sees '\n            + 'the right version on disk and considers it installed; only the delete forces a rewrite')],\n        renderShim()),\n    new L0Fault('S', 'committed .claude/webpieces/ai-hook.sh != renderShim()',\n        'the guard bin', 'JS',\n        [\n            // wp-upgrade-shim is the SURGICAL tool and therefore leads: upgrade-shim.ts writes\n            // renderShim() to .claude/webpieces/ai-hook.sh and touches nothing else — no config, no\n            // settings.json — and it imports only fs/path, so it runs on a tree too broken to load the\n            // rule engine. The INSTALLER is deliberately NOT a cure here: it also migrates the config\n            // and wires BOTH hooks, prompting for a target twice, which hangs a non-interactive agent.\n            bashCure(UPGRADE_SHIM_CMD, true,\n                'this fault fires at all — it regenerates the shim and NOTHING else (no config, no '\n                + 'settings.json); needs installed @webpieces/ai-hook-rules 0.4.408 or newer'),\n            // 2026-07-21: the version gap below caused a real \"command not found\" deadlock.\n            bashCure(RESTORE_SHIM_CMD, false,\n                'the installed @webpieces/ai-hook-rules is OLDER than 0.4.408, so wp-upgrade-shim does '\n                + 'not exist yet — this works on every release, though Claude Code may ask you to '\n                + 'confirm the overwrite, and that prompt is NOT this guard'),\n        ],\n        shimStaleDenyReason('')),\n    new L0Fault('C', `${CONFIG_FILENAME} missing`,\n        'the guard bin', 'JS',\n        [\n            CONFIG_WRITE_CURE,\n            // Kept, but demoted: it seeds the file and then PROMPTS twice for a hook target.\n            bashCure(INSTALL_HOOKS_CMD, false,\n                'you are at an INTERACTIVE terminal and can answer its two hook-target prompts'),\n        ], CONFIG_MISSING_REPORT),\n    new L0Fault('Y', `a loaded rule has no ${CONFIG_FILENAME} key`,\n        'the guard bin', 'JS',\n        [CONFIG_WRITE_CURE], CONFIG_OUT_OF_SYNC_HEADER),\n];\n\n/**\n * One fault's FIX section, rendered from its `cures` array — literal commands only, never prose.\n *\n * This is the half that used to live in hand-written docs and drift. The three fields of L0Cure map\n * onto the three things a blocked reader needs and nothing else: WHAT to type (the call), WHETHER it is\n * the default (preferred), and WHEN to pick a sibling instead (discriminator). A cure with no\n * discriminator would render as a menu of equals, which is how an agent picks the wrong one.\n */\n// webpieces-disable no-function-outside-class -- pure string builder for renderGuardMatrixDoc below, beside the arrays it reads\nfunction renderFixSection(fault: L0Fault): string[] {\n    const options = fault.cures.map((cure: L0Cure, i: number): string => {\n        // A Bash cure is the command verbatim; a tool-shaped one is the file it edits (allowlist entry 2).\n        const literal = cure.isCommand() ? `\\`${cure.call.command}\\`` : `edit \\`${cure.mention}\\` yourself`;\n        const label = cure.preferred ? `Option ${i + 1} (preferred)` : `Option ${i + 1}`;\n        return `- **${label}**: ${literal}  ← pick this when ${cure.discriminator}`;\n    });\n    return [`### \\`${fault.code}\\` — ${fault.name}`, '', ...options, ''];\n}\n\n/**\n * Render webpieces.guard-matrix.md from L0_FAULTS + L0_ALLOWLIST.\n *\n * A unit test locks the committed template byte-identical to this output, the same way\n * templates/ai-hook.sh is locked to renderShim(). That is what makes the doc assertable instead of\n * aspirational: the table in the doc IS the array the guard consults.\n */\n// webpieces-disable no-function-outside-class -- pure string builder over the two exported arrays, beside them in this module\nexport function renderGuardMatrixDoc(): string {\n    return [\n        '# webpieces guard matrix — L0 (tooling integrity)',\n        '',\n        'GENERATED from `L0_FAULTS` + `L0_ALLOWLIST` in `@webpieces/ai-hook-rules`. Do not hand-edit —',\n        'a unit test locks this file byte-identical to `renderGuardMatrixDoc()`, so the table below is',\n        'the array the guard actually consults, not a description of it.',\n        '',\n        'L0 is the OUTERMOST guard layer. It blocks work while `node_modules`, the committed shim, or',\n        '`webpieces.config.json` are in a state that makes every other guard untrustworthy. If you are',\n        'reading this, one of the six faults below fired and named this file.',\n        '',\n        '## The faults',\n        '',\n        '| code | fault | detected by | enforced in |',\n        '|---|---|---|---|',\n        ...L0_FAULTS.map((f: L0Fault): string => `| \\`${f.code}\\` | ${f.name} | ${f.detectedBy} | ${f.enforcedIn} |`),\n        '',\n        'First match wins. `D`/`X`/`K` are decided in POSIX `sh` inside the committed shim, BEFORE the',\n        'guard bin runs — a stale, missing or broken validator cannot be trusted to validate itself.',\n        '',\n        '## The fix, per fault',\n        '',\n        'Every command below is rendered from that fault\\'s `cures` array and is asserted, by unit test,',\n        'to be accepted by `isAllowed()` — so nothing here can be a command the guard then rejects. Type',\n        'the option you pick EXACTLY as written and run nothing else on that line.',\n        '',\n        ...L0_FAULTS.flatMap(renderFixSection),\n        ...renderMatrixAndAllowlist(),\n    ].join('\\n');\n}\n\n/**\n * The second half of the doc: the three-row matrix and the ONE allowlist. Split out of\n * renderGuardMatrixDoc solely to keep it inside the method-line budget — the join order is what makes\n * the two halves one file, so keep them adjacent and keep the byte-lock test as the arbiter.\n */\n// webpieces-disable no-function-outside-class -- second half of renderGuardMatrixDoc's string, beside it in this module\nfunction renderMatrixAndAllowlist(): string[] {\n    return [\n        '## The matrix',\n        '',\n        'L0 has NO genuine second dimension. Every branch reduces to one question:',\n        '',\n        '| # | fault | on the allowlist? | outcome |',\n        '|---|---|---|---|',\n        '| 1 | none | — | hand down to the next guard layer |',\n        '| 2 | any | yes | PASS or ALLOW (see the entry) |',\n        '| 3 | any | no | BLOCK — **only the message varies by fault** |',\n        '',\n        'The tool is not a dimension either: \"any Read\" is an allowlist ENTRY, not a tool check.',\n        '',\n        '## The allowlist',\n        '',\n        'ONE list, consulted identically by all six faults. A cure that cannot help a given fault also',\n        'cannot hurt it, and gating each entry on a fault is what produced four real defects (a stale',\n        'shim that denied `pnpm install` and `git pull`; faults that denied every Read; a config fault',\n        'that denied `rm -rf node_modules && pnpm install` while allowing a bare `pnpm install`).',\n        '',\n        '| # | allowed | outcome |',\n        '|---|---|---|',\n        ...L0_ALLOWLIST.map((e: L0AllowEntry, i: number): string => `| ${i + 1} | ${e.label} | ${e.kind.toUpperCase()} |`),\n        '',\n        '- **PASS** — L0 has no objection; the call falls THROUGH so the downstream guards still judge it.',\n        '- **ALLOW** — terminal; bypasses everything, because a cure must stay reachable even when a',\n        '  downstream guard would block it.',\n        '',\n        'Every Bash entry is anchored to the WHOLE command. A leading `cd <dir> &&`, a trailing `2>&1`',\n        'and a pipe into `tail`/`head` are tolerated; nothing else is. Appending `&& git status` makes it',\n        'a DIFFERENT command and it is rejected again — that is not the guard refusing its own cure.',\n        '',\n        '`git merge` is deliberately NOT on this list. Main is merged ONLY through the 3-point fork merge',\n        '(`pnpm wp-start-update`, or `pnpm wp-start-upsert-pr` when a PR is already open).',\n        '',\n        '## Known asymmetry',\n        '',\n        'Under `S`/`C`/`Y` the guard bin IS running, so a PASS really does fall through to the downstream',\n        'guards. Under `D`/`X`/`K` the bin is never executed, so there is nothing to fall through to and a',\n        'PASS degenerates into a terminal allow — reads are unguarded during those three faults.',\n        '',\n        '## Widening L0',\n        '',\n        'Add an entry to `L0_ALLOWLIST` in `packages/tooling/ai-hook-rules/src/bin/shim.ts`. That array is',\n        'the single source for the JS allowlist, the `grep -E` inside the rendered shim, and this file.',\n        '',\n    ];\n}\n\n/**\n * Drop the matrix doc where the AI can read it, and return its absolute path ('' if it could not be\n * written). Called from the L0 BLOCK path so the deny can say `READ <path>`.\n *\n * Best-effort by design: this runs while the tree is already known-broken, and a missing template (an\n * @webpieces/rules-config older than this package) must degrade the deny message, never replace it\n * with a crash.\n */\n// webpieces-disable no-function-outside-class -- sibling of renderGuardMatrixDoc in this module\nexport function writeGuardMatrixDoc(workspaceRoot: string): string {\n    // eslint-disable-next-line @webpieces/no-unmanaged-exceptions\n    try {\n        return writeTemplate(workspaceRoot, GUARD_MATRIX_DOC);\n    } catch (err: unknown) {\n        const error = toError(err);\n        void error; // best-effort: no doc → the deny simply omits the pointer\n        return '';\n    }\n}\n\n/** The `READ <path>` pointer appended to an L0 deny, or '' when the doc could not be written. */\n// webpieces-disable no-function-outside-class -- sibling of writeGuardMatrixDoc in this module\nexport function guardMatrixPointer(docPath: string): string {\n    if (docPath === '') return '';\n    return ` The full L0 guard matrix - all six faults and everything that is allowed through - is at ${docPath}; READ it if you are unsure why this call was blocked.`;\n}\n"]}

package/src/core/runner.d.ts

@@ -1,10 +1,11 @@
 import { ExcludePaths } from '@webpieces/rules-config';
+import { AgentIdentity } from './coordinator-worktree';
 import { ToolKind, NormalizedToolInput, BlockedResult, HookMode, Rule, Violation, EditContext, FileContext, BashContext } from './types';
 export declare function filterByExcludedPaths(rules: readonly Rule[], relativePath: string, ex: ExcludePaths): readonly Rule[];
 export declare function effectiveBashCwd(command: string, cwd: string): string;
 export declare function isGitOrGhCommand(command: string): boolean;
 export declare function run(toolKind: ToolKind, input: NormalizedToolInput, cwd: string, mode?: HookMode): BlockedResult | null;
-export declare function runBash(command: string, cwd: string, mode?: HookMode): BlockedResult | null;
+export declare function runBash(command: string, cwd: string, mode?: HookMode, agent?: AgentIdentity): BlockedResult | null;
 /**
  * The Read path. Deliberately NOT `run()`:
  *