@webpieces/ai-hook-rules 0.4.623 → 0.4.625

package/src/core/version-sync.js

@@ -0,0 +1,148 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.VersionSyncGuard = void 0;
+const read_only_inspection_1 = require("./read-only-inspection");
+const webpieces_versions_1 = require("./webpieces-versions");
+/**
+ * L1 row 8 — a tree may not be worked in while its `@webpieces` version disagrees with the MAIN tree's.
+ *
+ * ─── WHY THIS EXISTS, and what it replaces ─────────────────────────────────────────────────────────
+ * The guard hooks are registered ABSOLUTE (`$CLAUDE_PROJECT_DIR/...`), so the MAIN tree governs every
+ * tree. That is not a new imposition — it is what was always happening, because a linked worktree has no
+ * `node_modules` and ai-hook.sh's upward walk already executed the main tree's binary. The design now
+ * says so out loud, which makes ONE case newly important: a worktree whose branch pins a DIFFERENT
+ * release is being linted, validated and built by a release it never asked for.
+ *
+ * This guard makes that case LOUD instead of silent. It replaces `CoordinatorWorktreeGuard`, and the
+ * replacement is strictly better on the axis that matters: the old guard keyed off WHO was asking
+ * (coordinator vs subagent), and agent identity was measured untrustworthy — a worktree-isolated agent
+ * whose tree is auto-reaped at a turn boundary silently resumes with its cwd on the primary clone
+ * (reproduced twice, 2026-08-10). This guard keys off the PATH the command acts on, which cannot lie.
+ *
+ * ─── IT EXISTS TO STOP A LOOP, not to enforce tidiness ─────────────────────────────────────────────
+ * A main/worktree manifest mismatch is exactly the shape that produced the founding incident: an agent
+ * is shown a fault measured against one tree, runs the prescribed cure in another, the cure succeeds,
+ * nothing the guard measures changes, and the guard re-denies. Five identical no-op `pnpm install`s and
+ * a fabricated theory about the harness later, a human had to untangle it. Firing EARLY, with a message
+ * that names all the versions and all their files, is the whole point. Any future proposal to soften
+ * this to a warning must answer: what stops the five-install loop instead?
+ *
+ * ─── Never a deadlock ──────────────────────────────────────────────────────────────────────────────
+ * Two structurally independent escapes, and neither depends on an allowlist regex staying in step:
+ *   1. WORK IN THE MAIN TREE — a main-tree-targeted command cannot classify as `worktree`, so it never
+ *      reaches this guard at all. No allowlist entry can break it because none is involved.
+ *   2. EDIT THE MANIFESTS — `pnpm-workspace.yaml` / `package.json` edits are carved out in the runner
+ *      the same way `webpieces.config.json` already is, so the cure is typable from inside the block.
+ * Reads and read-only inspection are never blocked either, so an agent can always look before it fixes.
+ */
+class VersionSyncGuard {
+    inspection = new read_only_inspection_1.ReadOnlyInspectionScan();
+    versions = new webpieces_versions_1.WebpiecesVersions();
+    /**
+     * True when this tree is a linked worktree whose webpieces version disagrees with the main tree's.
+     * This is the `V` dimension of the L1 matrix; the runner asks it for EVERY Bash call so the answer
+     * lands in the audit log even when nothing blocks.
+     */
+    skewed(tree) {
+        if (tree.kind !== 'worktree')
+            return false;
+        return !this.quartetFor(tree).inSync;
+    }
+    /** The deny report, or null to allow. */
+    block(command, tree) {
+        if (tree.kind !== 'worktree')
+            return null;
+        if (this.inspection.isReadOnlyInspection(command))
+            return null;
+        if (this.isCureOrLook(command))
+            return null;
+        const quartet = this.quartetFor(tree);
+        if (quartet.inSync)
+            return null;
+        return this.report(tree, quartet);
+    }
+    /**
+     * Commands that must pass EVEN WHILE THIS GUARD IS BLOCKING, because they are how you get unblocked
+     * — or how you look at the tree first.
+     *
+     * `ReadOnlyInspectionScan` deliberately excludes git and gh OUTRIGHT ("the guards exist to police
+     * git, and read-only git is not a line worth drawing while flying blind"), which is right for the
+     * guards that police git but WRONG here: this guard's own prescribed cure is `git pull` in both
+     * trees. Without this carve-out the guard would deny the exact command it tells the reader to run —
+     * the single failure shape this repo has been burned by most often, and the reason the deny text is
+     * allowed to promise "STILL ALLOWED HERE: ... pnpm install, git pull/fetch".
+     *
+     * Deliberately NARROW: fetching, pulling and installing cannot make a skew worse, and every one of
+     * them moves the tree toward agreement. Anything that BUILDS, TESTS or COMMITS is still blocked,
+     * because those are the operations that would be judged by the wrong release.
+     */
+    isCureOrLook(command) {
+        const words = command.trim().split(/\s+/);
+        const head = words[0] ?? '';
+        const sub = words[1] ?? '';
+        if (head === 'git' || head === 'gh') {
+            // `git -C <dir> <sub>` names its own directory; take the first non-flag word after it.
+            const subcommand = sub === '-C' ? (words[3] ?? '') : sub;
+            return ['pull', 'fetch', 'status', 'log', 'diff', 'show', 'branch', 'rev-parse', 'worktree'].includes(subcommand);
+        }
+        return (head === 'pnpm' || head === 'npm') && (sub === 'install' || sub === 'i');
+    }
+    /** Public so the runner can log all four versions on ALLOW as well as on BLOCK (audit, not just deny). */
+    quartetFor(tree) {
+        return this.versions.quartet(tree.governedRoot, tree.root);
+    }
+    // Short on purpose — L0 ran a deliberate message diet and these blocks regress into a wall of text
+    // if each one argues its case. State the skew, show every version WITH its file, give the git cure
+    // first, then the two structural escapes, then what is still allowed.
+    report(tree, quartet) {
+        return [
+            `❌ @webpieces version SKEW — this worktree and the main tree disagree, so work here is blocked.`,
+            '',
+            ...this.versionLines(tree, quartet),
+            '',
+            `   The guard hooks are ABSOLUTE, so the MAIN tree governs every tree. This worktree would be`,
+            `   linted, validated and built by a release its own manifest does not ask for.`,
+            '',
+            `   FIX (usually just git — the pin is TRACKED, so the same commit gives the same version):`,
+            `     1. \`git -C ${tree.governedRoot} pull\` and \`git -C ${tree.root} pull\` onto the same main,`,
+            `        then ONE \`cd '${tree.governedRoot}' && pnpm install\`. A worktree needs no install of its own.`,
+            `     2. Or work in the MAIN tree instead — it is never blocked by this guard.`,
+            `     3. Or, if this tree genuinely needs a different version, use a separate CLONE, not a`,
+            `        worktree: a clone gets its own node_modules and its own governance; a worktree cannot.`,
+            '',
+            `   STILL ALLOWED HERE: every Read, read-only inspection, \`pnpm install\`, \`git pull\`/\`fetch\`,`,
+            `   and edits to pnpm-workspace.yaml / package.json / webpieces.config.json.`,
+            `   Do NOT lower the MAIN tree's pin to match — that downgrades every tree, including this`,
+            `   session's own governor. If you are a SUBAGENT, you cannot fix the main tree: report to your`,
+            `   coordinator that one of you must move to the other's version.`,
+        ].join('\n');
+    }
+    // Every version WITH the file it came from. An agent that is told "they disagree" without being told
+    // WHICH FILE to edit re-derives it by grepping, which is exactly the turn-burning this guard exists
+    // to prevent. Unreadable legs are printed as `-` rather than omitted, so the reader can tell
+    // "this one is absent" from "I forgot to look".
+    versionLines(tree, quartet) {
+        const lines = [
+            `   main pin       ${this.show(quartet.main.pinned)}   ${tree.governedRoot}/pnpm-workspace.yaml`,
+            `   main installed ${this.show(quartet.main.installed)}   ${tree.governedRoot}/node_modules/${webpieces_versions_1.UMBRELLA_PACKAGE}`,
+            `                  ^ the binary judging this very call`,
+            `   this worktree  ${this.show(quartet.worktree.pinned)}   ${tree.root}/pnpm-workspace.yaml`,
+        ];
+        if (quartet.worktree.installed !== null) {
+            lines.push(`   its installed  ${this.show(quartet.worktree.installed)}   ${tree.root}/node_modules/${webpieces_versions_1.UMBRELLA_PACKAGE}`);
+            lines.push('                  ^ what nx, vitest and eslint load IN this tree');
+        }
+        const others = this.versions.otherWorktrees(tree.governedRoot, tree.root);
+        if (others.length > 0) {
+            lines.push(`   NOTE ${others.length} other worktree(s) exist and are governed the same way — if they are`);
+            lines.push('        skewed too, their agents are already mis-governed. Consider clones, or');
+            lines.push('        serializing the work in the main tree.');
+        }
+        return lines;
+    }
+    show(version) {
+        return (version ?? '-').padEnd(10);
+    }
+}
+exports.VersionSyncGuard = VersionSyncGuard;
+//# sourceMappingURL=version-sync.js.map

package/src/core/version-sync.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"version-sync.js","sourceRoot":"","sources":["../../../../../../packages/tooling/ai-hook-rules/src/core/version-sync.ts"],"names":[],"mappings":"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","sourcesContent":["import { EffectiveTree } from './effective-tree';\nimport { ReadOnlyInspectionScan } from './read-only-inspection';\nimport { UMBRELLA_PACKAGE, VersionQuartet, WebpiecesVersions } from './webpieces-versions';\n\n/**\n * L1 row 8 — a tree may not be worked in while its `@webpieces` version disagrees with the MAIN tree's.\n *\n * ─── WHY THIS EXISTS, and what it replaces ─────────────────────────────────────────────────────────\n * The guard hooks are registered ABSOLUTE (`$CLAUDE_PROJECT_DIR/...`), so the MAIN tree governs every\n * tree. That is not a new imposition — it is what was always happening, because a linked worktree has no\n * `node_modules` and ai-hook.sh's upward walk already executed the main tree's binary. The design now\n * says so out loud, which makes ONE case newly important: a worktree whose branch pins a DIFFERENT\n * release is being linted, validated and built by a release it never asked for.\n *\n * This guard makes that case LOUD instead of silent. It replaces `CoordinatorWorktreeGuard`, and the\n * replacement is strictly better on the axis that matters: the old guard keyed off WHO was asking\n * (coordinator vs subagent), and agent identity was measured untrustworthy — a worktree-isolated agent\n * whose tree is auto-reaped at a turn boundary silently resumes with its cwd on the primary clone\n * (reproduced twice, 2026-08-10). This guard keys off the PATH the command acts on, which cannot lie.\n *\n * ─── IT EXISTS TO STOP A LOOP, not to enforce tidiness ─────────────────────────────────────────────\n * A main/worktree manifest mismatch is exactly the shape that produced the founding incident: an agent\n * is shown a fault measured against one tree, runs the prescribed cure in another, the cure succeeds,\n * nothing the guard measures changes, and the guard re-denies. Five identical no-op `pnpm install`s and\n * a fabricated theory about the harness later, a human had to untangle it. Firing EARLY, with a message\n * that names all the versions and all their files, is the whole point. Any future proposal to soften\n * this to a warning must answer: what stops the five-install loop instead?\n *\n * ─── Never a deadlock ──────────────────────────────────────────────────────────────────────────────\n * Two structurally independent escapes, and neither depends on an allowlist regex staying in step:\n *   1. WORK IN THE MAIN TREE — a main-tree-targeted command cannot classify as `worktree`, so it never\n *      reaches this guard at all. No allowlist entry can break it because none is involved.\n *   2. EDIT THE MANIFESTS — `pnpm-workspace.yaml` / `package.json` edits are carved out in the runner\n *      the same way `webpieces.config.json` already is, so the cure is typable from inside the block.\n * Reads and read-only inspection are never blocked either, so an agent can always look before it fixes.\n */\nexport class VersionSyncGuard {\n    private readonly inspection = new ReadOnlyInspectionScan();\n    private readonly versions = new WebpiecesVersions();\n\n    /**\n     * True when this tree is a linked worktree whose webpieces version disagrees with the main tree's.\n     * This is the `V` dimension of the L1 matrix; the runner asks it for EVERY Bash call so the answer\n     * lands in the audit log even when nothing blocks.\n     */\n    skewed(tree: EffectiveTree): boolean {\n        if (tree.kind !== 'worktree') return false;\n        return !this.quartetFor(tree).inSync;\n    }\n\n    /** The deny report, or null to allow. */\n    block(command: string, tree: EffectiveTree): string | null {\n        if (tree.kind !== 'worktree') return null;\n        if (this.inspection.isReadOnlyInspection(command)) return null;\n        if (this.isCureOrLook(command)) return null;\n        const quartet = this.quartetFor(tree);\n        if (quartet.inSync) return null;\n        return this.report(tree, quartet);\n    }\n\n    /**\n     * Commands that must pass EVEN WHILE THIS GUARD IS BLOCKING, because they are how you get unblocked\n     * — or how you look at the tree first.\n     *\n     * `ReadOnlyInspectionScan` deliberately excludes git and gh OUTRIGHT (\"the guards exist to police\n     * git, and read-only git is not a line worth drawing while flying blind\"), which is right for the\n     * guards that police git but WRONG here: this guard's own prescribed cure is `git pull` in both\n     * trees. Without this carve-out the guard would deny the exact command it tells the reader to run —\n     * the single failure shape this repo has been burned by most often, and the reason the deny text is\n     * allowed to promise \"STILL ALLOWED HERE: ... pnpm install, git pull/fetch\".\n     *\n     * Deliberately NARROW: fetching, pulling and installing cannot make a skew worse, and every one of\n     * them moves the tree toward agreement. Anything that BUILDS, TESTS or COMMITS is still blocked,\n     * because those are the operations that would be judged by the wrong release.\n     */\n    private isCureOrLook(command: string): boolean {\n        const words = command.trim().split(/\\s+/);\n        const head = words[0] ?? '';\n        const sub = words[1] ?? '';\n        if (head === 'git' || head === 'gh') {\n            // `git -C <dir> <sub>` names its own directory; take the first non-flag word after it.\n            const subcommand = sub === '-C' ? (words[3] ?? '') : sub;\n            return ['pull', 'fetch', 'status', 'log', 'diff', 'show', 'branch', 'rev-parse', 'worktree'].includes(subcommand);\n        }\n        return (head === 'pnpm' || head === 'npm') && (sub === 'install' || sub === 'i');\n    }\n\n    /** Public so the runner can log all four versions on ALLOW as well as on BLOCK (audit, not just deny). */\n    quartetFor(tree: EffectiveTree): VersionQuartet {\n        return this.versions.quartet(tree.governedRoot, tree.root);\n    }\n\n    // Short on purpose — L0 ran a deliberate message diet and these blocks regress into a wall of text\n    // if each one argues its case. State the skew, show every version WITH its file, give the git cure\n    // first, then the two structural escapes, then what is still allowed.\n    private report(tree: EffectiveTree, quartet: VersionQuartet): string {\n        return [\n            `❌ @webpieces version SKEW — this worktree and the main tree disagree, so work here is blocked.`,\n            '',\n            ...this.versionLines(tree, quartet),\n            '',\n            `   The guard hooks are ABSOLUTE, so the MAIN tree governs every tree. This worktree would be`,\n            `   linted, validated and built by a release its own manifest does not ask for.`,\n            '',\n            `   FIX (usually just git — the pin is TRACKED, so the same commit gives the same version):`,\n            `     1. \\`git -C ${tree.governedRoot} pull\\` and \\`git -C ${tree.root} pull\\` onto the same main,`,\n            `        then ONE \\`cd '${tree.governedRoot}' && pnpm install\\`. A worktree needs no install of its own.`,\n            `     2. Or work in the MAIN tree instead — it is never blocked by this guard.`,\n            `     3. Or, if this tree genuinely needs a different version, use a separate CLONE, not a`,\n            `        worktree: a clone gets its own node_modules and its own governance; a worktree cannot.`,\n            '',\n            `   STILL ALLOWED HERE: every Read, read-only inspection, \\`pnpm install\\`, \\`git pull\\`/\\`fetch\\`,`,\n            `   and edits to pnpm-workspace.yaml / package.json / webpieces.config.json.`,\n            `   Do NOT lower the MAIN tree's pin to match — that downgrades every tree, including this`,\n            `   session's own governor. If you are a SUBAGENT, you cannot fix the main tree: report to your`,\n            `   coordinator that one of you must move to the other's version.`,\n        ].join('\\n');\n    }\n\n    // Every version WITH the file it came from. An agent that is told \"they disagree\" without being told\n    // WHICH FILE to edit re-derives it by grepping, which is exactly the turn-burning this guard exists\n    // to prevent. Unreadable legs are printed as `-` rather than omitted, so the reader can tell\n    // \"this one is absent\" from \"I forgot to look\".\n    private versionLines(tree: EffectiveTree, quartet: VersionQuartet): readonly string[] {\n        const lines = [\n            `   main pin       ${this.show(quartet.main.pinned)}   ${tree.governedRoot}/pnpm-workspace.yaml`,\n            `   main installed ${this.show(quartet.main.installed)}   ${tree.governedRoot}/node_modules/${UMBRELLA_PACKAGE}`,\n            `                  ^ the binary judging this very call`,\n            `   this worktree  ${this.show(quartet.worktree.pinned)}   ${tree.root}/pnpm-workspace.yaml`,\n        ];\n        if (quartet.worktree.installed !== null) {\n            lines.push(`   its installed  ${this.show(quartet.worktree.installed)}   ${tree.root}/node_modules/${UMBRELLA_PACKAGE}`);\n            lines.push('                  ^ what nx, vitest and eslint load IN this tree');\n        }\n        const others = this.versions.otherWorktrees(tree.governedRoot, tree.root);\n        if (others.length > 0) {\n            lines.push(`   NOTE ${others.length} other worktree(s) exist and are governed the same way — if they are`);\n            lines.push('        skewed too, their agents are already mis-governed. Consider clones, or');\n            lines.push('        serializing the work in the main tree.');\n        }\n        return lines;\n    }\n\n    private show(version: string | null): string {\n        return (version ?? '-').padEnd(10);\n    }\n}\n"]}

package/src/core/webpieces-versions.d.ts

@@ -0,0 +1,83 @@
+/** The umbrella package every consumer pins. One `catalog:` entry pins its children in lockstep. */
+export declare const UMBRELLA_PACKAGE = "@webpieces/nx-webpieces-rules";
+/**
+ * ONE tree's answer to "which @webpieces does this tree declare, and which does it have installed".
+ * Data-only (per CLAUDE.md, classes for data). `null` means "could not be determined" — which is NOT
+ * the same as disagreeing, and every caller must treat it as "no opinion", never as skew.
+ */
+export declare class TreeVersions {
+    readonly root: string;
+    /** The catalog pin in this tree's `pnpm-workspace.yaml`. Tracked in git, so it is per-branch. */
+    readonly pinned: string | null;
+    /** The version actually installed under this tree's own `node_modules`, when it has one. */
+    readonly installed: string | null;
+    constructor(root: string, 
+    /** The catalog pin in this tree's `pnpm-workspace.yaml`. Tracked in git, so it is per-branch. */
+    pinned: string | null, 
+    /** The version actually installed under this tree's own `node_modules`, when it has one. */
+    installed: string | null);
+}
+/**
+ * The 3-or-4 webpieces versions in play when a worktree is involved, and whether they agree.
+ *
+ * THREE always — main pin, worktree pin, main install — and a FOURTH when the worktree has its own
+ * `node_modules`, which happens the moment anyone runs `pnpm add <anything>` in it. That fourth is the
+ * uncommon one, and it is NOT optional to check: nx, vitest and the eslint plugin all run IN that tree
+ * and load THAT copy. (It does not decide who *judges* the tree — with the guard hooks registered
+ * absolutely, the judging binary is always the main tree's — but it decides who *builds, lints and
+ * tests* it, and nothing else looks at it.)
+ */
+export declare class VersionQuartet {
+    readonly main: TreeVersions;
+    readonly worktree: TreeVersions;
+    constructor(main: TreeVersions, worktree: TreeVersions);
+    /** Every version that was actually readable, deduped — the set that must have exactly one member. */
+    get distinct(): readonly string[];
+    /**
+     * True when every version we could read agrees.
+     *
+     * FAILS OPEN on purpose: if nothing could be read (`distinct` is empty) this is `true`. A guard that
+     * cannot measure must not block — the repo's worst incidents are guards that fired on a state they
+     * could not diagnose, leaving an agent with no reachable cure.
+     */
+    get inSync(): boolean;
+}
+/**
+ * Reads the webpieces versions a tree declares and installs.
+ *
+ * WHY A DEDICATED READER rather than reusing the sh drift guard's scraping: that one compares a pin to
+ * an install WITHIN ONE TREE, which is a different question. This is the CROSS-TREE generalisation, and
+ * it is the only thing that can catch the case the absolute-registration design deliberately accepts —
+ * a worktree being judged by the main tree's release while its own manifest asks for another.
+ *
+ * Every read is best-effort and returns `null` rather than throwing: this runs on the hook's BLOCKING
+ * path, so an unreadable file must degrade to "no opinion", never to a fault.
+ */
+export declare class WebpiecesVersions {
+    private readonly byRoot;
+    /** Both trees' versions, ready to compare. */
+    quartet(mainRoot: string, worktreeRoot: string): VersionQuartet;
+    /** One tree's declared + installed versions, memoized. */
+    forTree(root: string): TreeVersions;
+    /**
+     * The catalog pin, scraped from `pnpm-workspace.yaml`.
+     *
+     * Deliberately a narrow regex rather than a YAML parser: this module must stay dependency-free (it
+     * loads on the hook path, where a broken tree is exactly the case that matters), and the catalog
+     * entry has one shape — `'@webpieces/nx-webpieces-rules': 0.4.616`, optionally unquoted. A RANGE
+     * (`^`, `~`, `workspace:*`) is returned as null, not as a version: a range cannot be compared for
+     * equality, and treating it as skew would block every consumer who pins loosely.
+     */
+    private readPin;
+    /** The version under this tree's OWN node_modules, or null when it has none (the normal worktree). */
+    private readInstalled;
+    private readText;
+    /**
+     * Every OTHER linked worktree of this repo, so a block can name the ones that are ALSO skewed.
+     *
+     * A skew is never a two-tree problem: if worktree A is aligned and B is not, the agents working in B
+     * are already mis-governed and nothing has told them. Best-effort — an empty answer means "could not
+     * enumerate", and callers must never read that as "there are no other worktrees".
+     */
+    otherWorktrees(mainRoot: string, exclude: string): readonly string[];
+}

package/src/core/webpieces-versions.js

@@ -0,0 +1,169 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.WebpiecesVersions = exports.VersionQuartet = exports.TreeVersions = exports.UMBRELLA_PACKAGE = void 0;
+const tslib_1 = require("tslib");
+const child_process_1 = require("child_process");
+const fs = tslib_1.__importStar(require("fs"));
+const path = tslib_1.__importStar(require("path"));
+const to_error_1 = require("./to-error");
+/** The umbrella package every consumer pins. One `catalog:` entry pins its children in lockstep. */
+exports.UMBRELLA_PACKAGE = '@webpieces/nx-webpieces-rules';
+/** `pnpm-workspace.yaml`'s catalog is the ONE place a webpieces version is declared. */
+const WORKSPACE_FILE = 'pnpm-workspace.yaml';
+/**
+ * ONE tree's answer to "which @webpieces does this tree declare, and which does it have installed".
+ * Data-only (per CLAUDE.md, classes for data). `null` means "could not be determined" — which is NOT
+ * the same as disagreeing, and every caller must treat it as "no opinion", never as skew.
+ */
+class TreeVersions {
+    root;
+    pinned;
+    installed;
+    constructor(root, 
+    /** The catalog pin in this tree's `pnpm-workspace.yaml`. Tracked in git, so it is per-branch. */
+    pinned, 
+    /** The version actually installed under this tree's own `node_modules`, when it has one. */
+    installed) {
+        this.root = root;
+        this.pinned = pinned;
+        this.installed = installed;
+    }
+}
+exports.TreeVersions = TreeVersions;
+/**
+ * The 3-or-4 webpieces versions in play when a worktree is involved, and whether they agree.
+ *
+ * THREE always — main pin, worktree pin, main install — and a FOURTH when the worktree has its own
+ * `node_modules`, which happens the moment anyone runs `pnpm add <anything>` in it. That fourth is the
+ * uncommon one, and it is NOT optional to check: nx, vitest and the eslint plugin all run IN that tree
+ * and load THAT copy. (It does not decide who *judges* the tree — with the guard hooks registered
+ * absolutely, the judging binary is always the main tree's — but it decides who *builds, lints and
+ * tests* it, and nothing else looks at it.)
+ */
+class VersionQuartet {
+    main;
+    worktree;
+    constructor(main, worktree) {
+        this.main = main;
+        this.worktree = worktree;
+    }
+    /** Every version that was actually readable, deduped — the set that must have exactly one member. */
+    get distinct() {
+        const all = [this.main.pinned, this.main.installed, this.worktree.pinned, this.worktree.installed];
+        const seen = [];
+        for (const v of all) {
+            if (v !== null && !seen.includes(v))
+                seen.push(v);
+        }
+        return seen;
+    }
+    /**
+     * True when every version we could read agrees.
+     *
+     * FAILS OPEN on purpose: if nothing could be read (`distinct` is empty) this is `true`. A guard that
+     * cannot measure must not block — the repo's worst incidents are guards that fired on a state they
+     * could not diagnose, leaving an agent with no reachable cure.
+     */
+    get inSync() {
+        return this.distinct.length <= 1;
+    }
+}
+exports.VersionQuartet = VersionQuartet;
+/**
+ * Reads the webpieces versions a tree declares and installs.
+ *
+ * WHY A DEDICATED READER rather than reusing the sh drift guard's scraping: that one compares a pin to
+ * an install WITHIN ONE TREE, which is a different question. This is the CROSS-TREE generalisation, and
+ * it is the only thing that can catch the case the absolute-registration design deliberately accepts —
+ * a worktree being judged by the main tree's release while its own manifest asks for another.
+ *
+ * Every read is best-effort and returns `null` rather than throwing: this runs on the hook's BLOCKING
+ * path, so an unreadable file must degrade to "no opinion", never to a fault.
+ */
+class WebpiecesVersions {
+    // root -> answer. The hook resolves the same two roots many times per invocation; git and fs are
+    // both far too expensive to repeat on a blocking path.
+    byRoot = new Map();
+    /** Both trees' versions, ready to compare. */
+    quartet(mainRoot, worktreeRoot) {
+        return new VersionQuartet(this.forTree(mainRoot), this.forTree(worktreeRoot));
+    }
+    /** One tree's declared + installed versions, memoized. */
+    forTree(root) {
+        const cached = this.byRoot.get(root);
+        if (cached !== undefined)
+            return cached;
+        const answer = new TreeVersions(root, this.readPin(root), this.readInstalled(root));
+        this.byRoot.set(root, answer);
+        return answer;
+    }
+    /**
+     * The catalog pin, scraped from `pnpm-workspace.yaml`.
+     *
+     * Deliberately a narrow regex rather than a YAML parser: this module must stay dependency-free (it
+     * loads on the hook path, where a broken tree is exactly the case that matters), and the catalog
+     * entry has one shape — `'@webpieces/nx-webpieces-rules': 0.4.616`, optionally unquoted. A RANGE
+     * (`^`, `~`, `workspace:*`) is returned as null, not as a version: a range cannot be compared for
+     * equality, and treating it as skew would block every consumer who pins loosely.
+     */
+    readPin(root) {
+        const file = path.join(root, WORKSPACE_FILE);
+        const text = this.readText(file);
+        if (text === null)
+            return null;
+        const escaped = exports.UMBRELLA_PACKAGE.replace('/', '\\/');
+        const match = new RegExp(`['"]?${escaped}['"]?\\s*:\\s*['"]?([^'"\\s#]+)`).exec(text);
+        if (match === null)
+            return null;
+        const value = match[1];
+        return /^[0-9]/.test(value) ? value : null;
+    }
+    /** The version under this tree's OWN node_modules, or null when it has none (the normal worktree). */
+    readInstalled(root) {
+        const manifest = path.join(root, 'node_modules', exports.UMBRELLA_PACKAGE, 'package.json');
+        const text = this.readText(manifest);
+        if (text === null)
+            return null;
+        const match = /"version"\s*:\s*"([^"]+)"/.exec(text);
+        return match === null ? null : match[1];
+    }
+    // Best-effort by design: this runs on the hook's BLOCKING path, so an unreadable or half-written
+    // manifest must degrade to "no opinion" rather than fault. A null here can only ever make the guard
+    // quieter, never noisier — VersionQuartet.inSync fails open on an empty read.
+    readText(file) {
+        // webpieces-disable no-unmanaged-exceptions -- a manifest read on a PreToolUse blocking path has no chokepoint above it; letting it throw would fail every tool call over an unrelated fs error
+        // eslint-disable-next-line @webpieces/no-unmanaged-exceptions
+        try {
+            return fs.existsSync(file) ? fs.readFileSync(file, 'utf8') : null;
+        }
+        catch (err) {
+            const error = (0, to_error_1.toError)(err);
+            void error;
+            return null;
+        }
+    }
+    /**
+     * Every OTHER linked worktree of this repo, so a block can name the ones that are ALSO skewed.
+     *
+     * A skew is never a two-tree problem: if worktree A is aligned and B is not, the agents working in B
+     * are already mis-governed and nothing has told them. Best-effort — an empty answer means "could not
+     * enumerate", and callers must never read that as "there are no other worktrees".
+     */
+    otherWorktrees(mainRoot, exclude) {
+        const result = (0, child_process_1.spawnSync)('git', ['-C', mainRoot, 'worktree', 'list', '--porcelain'], { encoding: 'utf8' });
+        if (result.status !== 0)
+            return [];
+        const roots = [];
+        for (const line of (result.stdout ?? '').split('\n')) {
+            if (!line.startsWith('worktree '))
+                continue;
+            const dir = line.slice('worktree '.length).trim();
+            if (dir !== '' && path.resolve(dir) !== path.resolve(mainRoot) && path.resolve(dir) !== path.resolve(exclude)) {
+                roots.push(dir);
+            }
+        }
+        return roots;
+    }
+}
+exports.WebpiecesVersions = WebpiecesVersions;
+//# sourceMappingURL=webpieces-versions.js.map

package/src/core/webpieces-versions.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"webpieces-versions.js","sourceRoot":"","sources":["../../../../../../packages/tooling/ai-hook-rules/src/core/webpieces-versions.ts"],"names":[],"mappings":"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","sourcesContent":["import { spawnSync } from 'child_process';\nimport * as fs from 'fs';\nimport * as path from 'path';\n\nimport { toError } from './to-error';\n\n/** The umbrella package every consumer pins. One `catalog:` entry pins its children in lockstep. */\nexport const UMBRELLA_PACKAGE = '@webpieces/nx-webpieces-rules';\n\n/** `pnpm-workspace.yaml`'s catalog is the ONE place a webpieces version is declared. */\nconst WORKSPACE_FILE = 'pnpm-workspace.yaml';\n\n/**\n * ONE tree's answer to \"which @webpieces does this tree declare, and which does it have installed\".\n * Data-only (per CLAUDE.md, classes for data). `null` means \"could not be determined\" — which is NOT\n * the same as disagreeing, and every caller must treat it as \"no opinion\", never as skew.\n */\nexport class TreeVersions {\n    constructor(\n        readonly root: string,\n        /** The catalog pin in this tree's `pnpm-workspace.yaml`. Tracked in git, so it is per-branch. */\n        readonly pinned: string | null,\n        /** The version actually installed under this tree's own `node_modules`, when it has one. */\n        readonly installed: string | null,\n    ) {}\n}\n\n/**\n * The 3-or-4 webpieces versions in play when a worktree is involved, and whether they agree.\n *\n * THREE always — main pin, worktree pin, main install — and a FOURTH when the worktree has its own\n * `node_modules`, which happens the moment anyone runs `pnpm add <anything>` in it. That fourth is the\n * uncommon one, and it is NOT optional to check: nx, vitest and the eslint plugin all run IN that tree\n * and load THAT copy. (It does not decide who *judges* the tree — with the guard hooks registered\n * absolutely, the judging binary is always the main tree's — but it decides who *builds, lints and\n * tests* it, and nothing else looks at it.)\n */\nexport class VersionQuartet {\n    constructor(\n        readonly main: TreeVersions,\n        readonly worktree: TreeVersions,\n    ) {}\n\n    /** Every version that was actually readable, deduped — the set that must have exactly one member. */\n    get distinct(): readonly string[] {\n        const all = [this.main.pinned, this.main.installed, this.worktree.pinned, this.worktree.installed];\n        const seen: string[] = [];\n        for (const v of all) {\n            if (v !== null && !seen.includes(v)) seen.push(v);\n        }\n        return seen;\n    }\n\n    /**\n     * True when every version we could read agrees.\n     *\n     * FAILS OPEN on purpose: if nothing could be read (`distinct` is empty) this is `true`. A guard that\n     * cannot measure must not block — the repo's worst incidents are guards that fired on a state they\n     * could not diagnose, leaving an agent with no reachable cure.\n     */\n    get inSync(): boolean {\n        return this.distinct.length <= 1;\n    }\n}\n\n/**\n * Reads the webpieces versions a tree declares and installs.\n *\n * WHY A DEDICATED READER rather than reusing the sh drift guard's scraping: that one compares a pin to\n * an install WITHIN ONE TREE, which is a different question. This is the CROSS-TREE generalisation, and\n * it is the only thing that can catch the case the absolute-registration design deliberately accepts —\n * a worktree being judged by the main tree's release while its own manifest asks for another.\n *\n * Every read is best-effort and returns `null` rather than throwing: this runs on the hook's BLOCKING\n * path, so an unreadable file must degrade to \"no opinion\", never to a fault.\n */\nexport class WebpiecesVersions {\n    // root -> answer. The hook resolves the same two roots many times per invocation; git and fs are\n    // both far too expensive to repeat on a blocking path.\n    private readonly byRoot = new Map<string, TreeVersions>();\n\n    /** Both trees' versions, ready to compare. */\n    quartet(mainRoot: string, worktreeRoot: string): VersionQuartet {\n        return new VersionQuartet(this.forTree(mainRoot), this.forTree(worktreeRoot));\n    }\n\n    /** One tree's declared + installed versions, memoized. */\n    forTree(root: string): TreeVersions {\n        const cached = this.byRoot.get(root);\n        if (cached !== undefined) return cached;\n        const answer = new TreeVersions(root, this.readPin(root), this.readInstalled(root));\n        this.byRoot.set(root, answer);\n        return answer;\n    }\n\n    /**\n     * The catalog pin, scraped from `pnpm-workspace.yaml`.\n     *\n     * Deliberately a narrow regex rather than a YAML parser: this module must stay dependency-free (it\n     * loads on the hook path, where a broken tree is exactly the case that matters), and the catalog\n     * entry has one shape — `'@webpieces/nx-webpieces-rules': 0.4.616`, optionally unquoted. A RANGE\n     * (`^`, `~`, `workspace:*`) is returned as null, not as a version: a range cannot be compared for\n     * equality, and treating it as skew would block every consumer who pins loosely.\n     */\n    private readPin(root: string): string | null {\n        const file = path.join(root, WORKSPACE_FILE);\n        const text = this.readText(file);\n        if (text === null) return null;\n        const escaped = UMBRELLA_PACKAGE.replace('/', '\\\\/');\n        const match = new RegExp(`['\"]?${escaped}['\"]?\\\\s*:\\\\s*['\"]?([^'\"\\\\s#]+)`).exec(text);\n        if (match === null) return null;\n        const value = match[1];\n        return /^[0-9]/.test(value) ? value : null;\n    }\n\n    /** The version under this tree's OWN node_modules, or null when it has none (the normal worktree). */\n    private readInstalled(root: string): string | null {\n        const manifest = path.join(root, 'node_modules', UMBRELLA_PACKAGE, 'package.json');\n        const text = this.readText(manifest);\n        if (text === null) return null;\n        const match = /\"version\"\\s*:\\s*\"([^\"]+)\"/.exec(text);\n        return match === null ? null : match[1];\n    }\n\n    // Best-effort by design: this runs on the hook's BLOCKING path, so an unreadable or half-written\n    // manifest must degrade to \"no opinion\" rather than fault. A null here can only ever make the guard\n    // quieter, never noisier — VersionQuartet.inSync fails open on an empty read.\n    private readText(file: string): string | null {\n        // webpieces-disable no-unmanaged-exceptions -- a manifest read on a PreToolUse blocking path has no chokepoint above it; letting it throw would fail every tool call over an unrelated fs error\n        // eslint-disable-next-line @webpieces/no-unmanaged-exceptions\n        try {\n            return fs.existsSync(file) ? fs.readFileSync(file, 'utf8') : null;\n        } catch (err: unknown) {\n            const error = toError(err);\n            void error;\n            return null;\n        }\n    }\n\n    /**\n     * Every OTHER linked worktree of this repo, so a block can name the ones that are ALSO skewed.\n     *\n     * A skew is never a two-tree problem: if worktree A is aligned and B is not, the agents working in B\n     * are already mis-governed and nothing has told them. Best-effort — an empty answer means \"could not\n     * enumerate\", and callers must never read that as \"there are no other worktrees\".\n     */\n    otherWorktrees(mainRoot: string, exclude: string): readonly string[] {\n        const result = spawnSync('git', ['-C', mainRoot, 'worktree', 'list', '--porcelain'], { encoding: 'utf8' });\n        if (result.status !== 0) return [];\n        const roots: string[] = [];\n        for (const line of (result.stdout ?? '').split('\\n')) {\n            if (!line.startsWith('worktree ')) continue;\n            const dir = line.slice('worktree '.length).trim();\n            if (dir !== '' && path.resolve(dir) !== path.resolve(mainRoot) && path.resolve(dir) !== path.resolve(exclude)) {\n                roots.push(dir);\n            }\n        }\n        return roots;\n    }\n}\n"]}

package/templates/ai-hook.sh

@@ -7,8 +7,8 @@
 # the hook has a stable entry point even when node_modules is absent. Safe to delete along with the
 # matching .claude/settings.json entries if you remove @webpieces/ai-hook-rules.
 #
-# Usage (wired into .claude/settings.json, RELATIVE so each git tree runs its own copy):
-#   sh ".claude/webpieces/ai-hook.sh" <bin-name>
+# Usage (wired into .claude/settings.json, ABSOLUTE so the MAIN tree governs every tree):
+#   sh "$CLAUDE_PROJECT_DIR/.claude/webpieces/ai-hook.sh" <bin-name>
 BIN_NAME="$1"
 shift
 # Resolve the tree relative to THIS script (…/<root>/.claude/webpieces/ai-hook.sh → <root>), not the
@@ -113,7 +113,7 @@ WP_INSTALL_CMD="pnpm install"
 WP_BORROW_NOTE=""
 if [ "$BIN_ROOT" != "$ROOT" ]; then
   WP_INSTALL_CMD="cd $ROOT && pnpm install"
-  WP_BORROW_NOTE=" NOTE: this tree ($ROOT) has NO node_modules of its own, so the guard binary was inherited from $BIN_ROOT by walking up - which is only correct while the two agree on the version. Run the install HERE, in this tree, so it gets its own node_modules at its own pin."
+  WP_BORROW_NOTE=" NOTE: this tree ($ROOT) has NO node_modules of its own, so the guard binary was inherited from $BIN_ROOT by walking up. For a linked WORKTREE that is the DESIGNED state, not a gap - the guard hooks are registered absolute, so the main tree governs every tree and a worktree needs no install of its own. What matters is that the two trees agree on the VERSION, and because the pin is tracked in git the reliable way to get that is the same git hash in both, then ONE 'pnpm install' in the main tree. Installing HERE is legitimate too (adding a dependency does it), but then this tree's own @webpieces must match the main tree's. If you genuinely need a DIFFERENT version, use a separate clone rather than a worktree."
 fi
 # Read the tool payload ONCE, up front. The shim no longer exec's the bin (see RUN_BIN_SH), so it must
 # forward stdin to the bin itself — and it needs the payload again on the fail-closed path below.
@@ -187,7 +187,18 @@ wp_log() {                   # $1 = L0 fault code (D|X|K|-), $2 = verdict label
     _wp_sz="$(wc -c < "$_wp_f" 2>/dev/null | tr -d ' ')"
     case "$_wp_sz" in ''|*[!0-9]*) _wp_sz=0 ;; esac
     [ "$_wp_sz" -gt 524288 ] && mv -f "$_wp_f" "$_wp_sd/${_wp_pfx}.1.log" 2>/dev/null
-    printf '%s\t%s\t%s\t%s\t%s\t%s\t%s\n' "$(date '+%Y-%m-%dT%H:%M:%S%z' 2>/dev/null)" "$BIN_NAME" "$TOOL" "tree=$WP_TREE" "fault=$1" "$2" "$CMD_LOG" >> "$_wp_f"
+    # shim= and bin= are the two facts this log could not previously answer, and they are the ones that
+    # decide whether a tree was governed by its OWN release or a borrowed one:
+    #   shim= WHICH COPY OF ai-hook.sh RAN — $ROOT, resolved from $0. The file is TRACKED, so every
+    #         worktree carries the version at ITS commit; settings.json registers it ABSOLUTE, so the copy
+    #         that runs is the SESSION ROOT's. Logged rather than assumed.
+    #   bin=  WHICH TREE SUPPLIED THE BINARY — $BIN_ROOT, the upward walk's answer. A fresh linked
+    #         worktree has no node_modules, so this is normally the PRIMARY even when shim= is not:
+    #         per-tree governance is the script and the config, never the enforcement code.
+    # Until these existed, no log at any layer recorded either (L-1 logged neither, L0 logged neither,
+    # only L1 logged root=/projectDir=), so "which hook governed this call" had to be inferred. Compare
+    # shim= against bin= to see a borrow, and either against the tree to see a straddle.
+    printf '%s\t%s\t%s\t%s\t%s\t%s\t%s\t%s\t%s\n' "$(date '+%Y-%m-%dT%H:%M:%S%z' 2>/dev/null)" "$BIN_NAME" "$TOOL" "tree=$WP_TREE" "shim=$ROOT" "bin=$BIN_ROOT" "fault=$1" "$2" "$CMD_LOG" >> "$_wp_f"
   } 2>/dev/null || true
 }
 BROKEN_BIN=""

package/templates/claude-settings-hook.json

@@ -1,26 +1,16 @@
 {
-    "_comment": "The webpieces-managed PreToolUse wiring, for reference — install it with `wp-install-ai-hooks` (which lets you pick a location per hook) rather than copying this by hand. THREE hooks, and the asymmetry is the design: the Rules hook validates code-style on Write/Edit/MultiEdit and the Guards hook protects git/PR/branch — it matches Write|Edit|MultiEdit|Bash|Read so ALL guards run there (bash git/PR guards on Bash, file guards like feature-branch-guard on Write/Edit) plus a log-and-allow audit of Read (records opened files under .webpieces/logs; never blocks a read). Both are registered RELATIVE, `sh \".claude/webpieces/ai-hook.sh\" <bin>`, pointing at a checked-in shim that is generated and committed on purpose: relative means each git worktree runs its own release, its own binary and its own pin, and the shim turns a missing bin — fresh clone before `pnpm install`, or the package removed — into a friendly 'run pnpm install' line instead of a raw error on every tool call. The third hook, guarantee-root.sh, is registered ABSOLUTE via $CLAUDE_PROJECT_DIR because it is the one hook that must resolve from ANY cwd: a relative hook that cannot resolve exits 127, which per the hooks reference is a NON-BLOCKING error, i.e. a SILENT UNGUARDED ALLOW. It matches Bash alone, because only Bash can move the shell. A global ~/.claude/settings.json install instead uses the absolute `node <repoRoot>/node_modules/.bin/<bin>` and gets no L-1 hook, since it has no relative path that could fail to resolve.",
-    "_comment_env": "CLAUDE_BASH_MAINTAIN_PROJECT_WORKING_DIR=1 is the FOURTH webpieces-managed thing, and it is guard integrity rather than ergonomics: it pins the Bash cwd back to the project root after every Bash call, so the RELATIVE hooks above always resolve, and because settings `env` is INHERITED it puts the main agent and every subagent on the same cwd — same hook resolution, same guard verdict. The trade, said out loud: the cwd reset becomes silent and unconditional, so a deliberate `cd` no longer persists between Bash calls — chain instead (`cd <dir> && <cmd>`). `pnpm exec wp-upgrade-shim` regenerates all four of these and reports which it changed.",
+    "_comment": "The webpieces PreToolUse hook wiring, plus the managed env entry. Install with `wp-install-ai-hooks` (which lets you pick a location per hook); this file just shows the shape. THREE managed surfaces are enforced together and `wp-upgrade-shim` repairs all three: (1) the committed .claude/webpieces/ai-hook.sh, (2) these registration entries, (3) the env entry below. The Rules hook validates code-style on Write/Edit/MultiEdit; the Guards hook protects git/PR/branch and matches Write|Edit|MultiEdit|Bash|Read - Read carries no guard but the guards hook owns the per-invocation audit log, and a Read is never blocked. BOTH hooks are registered ABSOLUTE via $CLAUDE_PROJECT_DIR, so the MAIN tree governs every tree. This replaced a three-hook RELATIVE form whose third hook (guarantee-root.sh, L-1) existed only to keep the relative path resolvable, and paid for it by denying every `cd` into a subdirectory; an absolute path resolves from any cwd, so that hook is deleted and `wp-upgrade-shim` removes any stale entry and the file. A linked worktree never had its own release anyway - it has no node_modules, so the shim's upward walk already ran the main tree's binary. When a worktree PINS a different @webpieces, L1 row 8 (trinary-version-skew) blocks and names the fix. CLAUDE_BASH_MAINTAIN_PROJECT_WORKING_DIR pins the Bash cwd to the project root so a verdict never depends on where an earlier cd left the shell; settings env is inherited, so every subagent gets the same cwd and the same verdict.",
     "env": {
         "CLAUDE_BASH_MAINTAIN_PROJECT_WORKING_DIR": "1"
     },
     "hooks": {
         "PreToolUse": [
-            {
-                "matcher": "Bash",
-                "hooks": [
-                    {
-                        "type": "command",
-                        "command": "sh \"$CLAUDE_PROJECT_DIR/.claude/webpieces/guarantee-root.sh\""
-                    }
-                ]
-            },
             {
                 "matcher": "Write|Edit|MultiEdit",
                 "hooks": [
                     {
                         "type": "command",
-                        "command": "sh \".claude/webpieces/ai-hook.sh\" wp-ai-rules-hook"
+                        "command": "sh \"$CLAUDE_PROJECT_DIR/.claude/webpieces/ai-hook.sh\" wp-ai-rules-hook"
                     }
                 ]
             },
@@ -29,7 +19,7 @@
                 "hooks": [
                     {
                         "type": "command",
-                        "command": "sh \".claude/webpieces/ai-hook.sh\" wp-ai-guards-hook"
+                        "command": "sh \"$CLAUDE_PROJECT_DIR/.claude/webpieces/ai-hook.sh\" wp-ai-guards-hook"
                     }
                 ]
             }