@webpieces/hook-runtime 0.0.1

package/src/core/strip-ts-noise.js

@@ -0,0 +1,191 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.stripTsNoise = stripTsNoise;
+class StripState {
+    source;
+    len;
+    out;
+    stack;
+    state;
+    braceDepth;
+    i;
+    constructor(source) {
+        this.source = source;
+        this.len = source.length;
+        this.out = new Array(source.length);
+        this.stack = [];
+        this.state = 'code';
+        this.braceDepth = 0;
+        this.i = 0;
+    }
+    ch() { return this.source[this.i]; }
+    next() { return this.i + 1 < this.len ? this.source[this.i + 1] : ''; }
+    emit(idx, ch) { this.out[idx] = ch; }
+    blank(idx, ch) { this.out[idx] = ch === '\n' ? '\n' : ' '; }
+    pushState(newState) {
+        this.stack.push({ state: this.state, braceDepth: this.braceDepth });
+        this.state = newState;
+    }
+    popState() {
+        const frame = this.stack.pop();
+        this.state = frame.state;
+        this.braceDepth = frame.braceDepth;
+    }
+}
+// webpieces-disable no-function-outside-class -- existing stateless module helper moved intact with its callers; ownership extraction preserves its functional API
+function handleCodeOrInterp(s) {
+    const ch = s.ch();
+    const next = s.next();
+    if (s.state === 'templateInterp') {
+        if (ch === '{') {
+            s.braceDepth += 1;
+            s.emit(s.i, ch);
+            s.i += 1;
+            return;
+        }
+        if (ch === '}') {
+            if (s.braceDepth === 0) {
+                s.emit(s.i, ch);
+                s.i += 1;
+                s.popState();
+                return;
+            }
+            s.braceDepth -= 1;
+            s.emit(s.i, ch);
+            s.i += 1;
+            return;
+        }
+    }
+    if (ch === '/' && next === '/') {
+        s.emit(s.i, '/');
+        s.emit(s.i + 1, '/');
+        s.i += 2;
+        s.pushState('lineComment');
+        return;
+    }
+    if (ch === '/' && next === '*') {
+        s.emit(s.i, '/');
+        s.emit(s.i + 1, '*');
+        s.i += 2;
+        s.pushState('blockComment');
+        return;
+    }
+    if (ch === '"') {
+        s.emit(s.i, '"');
+        s.i += 1;
+        s.pushState('dquote');
+        return;
+    }
+    if (ch === "'") {
+        s.emit(s.i, "'");
+        s.i += 1;
+        s.pushState('squote');
+        return;
+    }
+    if (ch === '`') {
+        s.emit(s.i, '`');
+        s.i += 1;
+        s.pushState('template');
+        return;
+    }
+    s.emit(s.i, ch);
+    s.i += 1;
+}
+// webpieces-disable no-function-outside-class -- existing stateless module helper moved intact with its callers; ownership extraction preserves its functional API
+function handleLineComment(s) {
+    if (s.ch() === '\n') {
+        s.emit(s.i, '\n');
+        s.i += 1;
+        s.popState();
+        return;
+    }
+    s.blank(s.i, s.ch());
+    s.i += 1;
+}
+// webpieces-disable no-function-outside-class -- existing stateless module helper moved intact with its callers; ownership extraction preserves its functional API
+function handleBlockComment(s) {
+    if (s.ch() === '*' && s.next() === '/') {
+        s.emit(s.i, '*');
+        s.emit(s.i + 1, '/');
+        s.i += 2;
+        s.popState();
+        return;
+    }
+    s.blank(s.i, s.ch());
+    s.i += 1;
+}
+// webpieces-disable no-function-outside-class -- existing stateless module helper moved intact with its callers; ownership extraction preserves its functional API
+function handleStringLiteral(s, quoteChar) {
+    const ch = s.ch();
+    if (ch === '\\' && s.i + 1 < s.len) {
+        s.blank(s.i, ch);
+        s.blank(s.i + 1, s.source[s.i + 1]);
+        s.i += 2;
+        return;
+    }
+    if (ch === quoteChar) {
+        s.emit(s.i, quoteChar);
+        s.i += 1;
+        s.popState();
+        return;
+    }
+    s.blank(s.i, ch);
+    s.i += 1;
+}
+// webpieces-disable no-function-outside-class -- existing stateless module helper moved intact with its callers; ownership extraction preserves its functional API
+function handleTemplate(s) {
+    const ch = s.ch();
+    if (ch === '\\' && s.i + 1 < s.len) {
+        s.blank(s.i, ch);
+        s.blank(s.i + 1, s.source[s.i + 1]);
+        s.i += 2;
+        return;
+    }
+    if (ch === '`') {
+        s.emit(s.i, '`');
+        s.i += 1;
+        s.popState();
+        return;
+    }
+    if (ch === '$' && s.next() === '{') {
+        s.emit(s.i, '$');
+        s.emit(s.i + 1, '{');
+        s.i += 2;
+        s.stack.push({ state: 'template', braceDepth: 0 });
+        s.state = 'templateInterp';
+        s.braceDepth = 0;
+        return;
+    }
+    s.blank(s.i, ch);
+    s.i += 1;
+}
+// webpieces-disable no-function-outside-class -- existing stateless module helper moved intact with its callers; ownership extraction preserves its functional API
+function stripTsNoise(source) {
+    const s = new StripState(source);
+    while (s.i < s.len) {
+        if (s.state === 'code' || s.state === 'templateInterp') {
+            handleCodeOrInterp(s);
+        }
+        else if (s.state === 'lineComment') {
+            handleLineComment(s);
+        }
+        else if (s.state === 'blockComment') {
+            handleBlockComment(s);
+        }
+        else if (s.state === 'dquote') {
+            handleStringLiteral(s, '"');
+        }
+        else if (s.state === 'squote') {
+            handleStringLiteral(s, "'");
+        }
+        else if (s.state === 'template') {
+            handleTemplate(s);
+        }
+        else {
+            s.emit(s.i, s.ch());
+            s.i += 1;
+        }
+    }
+    return s.out.join('');
+}
+//# sourceMappingURL=strip-ts-noise.js.map

package/src/core/strip-ts-noise.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"strip-ts-noise.js","sourceRoot":"","sources":["../../../../../../packages/tooling/hook-runtime/src/core/strip-ts-noise.ts"],"names":[],"mappings":"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","sourcesContent":["interface StackFrame {\n    readonly state: string;\n    readonly braceDepth: number;\n}\n\nclass StripState {\n    readonly source: string;\n    readonly len: number;\n    readonly out: string[];\n    readonly stack: StackFrame[];\n    state: string;\n    braceDepth: number;\n    i: number;\n\n    constructor(source: string) {\n        this.source = source;\n        this.len = source.length;\n        this.out = new Array<string>(source.length);\n        this.stack = [];\n        this.state = 'code';\n        this.braceDepth = 0;\n        this.i = 0;\n    }\n\n    ch(): string { return this.source[this.i]; }\n    next(): string { return this.i + 1 < this.len ? this.source[this.i + 1] : ''; }\n    emit(idx: number, ch: string): void { this.out[idx] = ch; }\n    blank(idx: number, ch: string): void { this.out[idx] = ch === '\\n' ? '\\n' : ' '; }\n\n    pushState(newState: string): void {\n        this.stack.push({ state: this.state, braceDepth: this.braceDepth });\n        this.state = newState;\n    }\n\n    popState(): void {\n        const frame = this.stack.pop()!;\n        this.state = frame.state;\n        this.braceDepth = frame.braceDepth;\n    }\n}\n\n// webpieces-disable no-function-outside-class -- existing stateless module helper moved intact with its callers; ownership extraction preserves its functional API\nfunction handleCodeOrInterp(s: StripState): void {\n    const ch = s.ch();\n    const next = s.next();\n\n    if (s.state === 'templateInterp') {\n        if (ch === '{') { s.braceDepth += 1; s.emit(s.i, ch); s.i += 1; return; }\n        if (ch === '}') {\n            if (s.braceDepth === 0) { s.emit(s.i, ch); s.i += 1; s.popState(); return; }\n            s.braceDepth -= 1; s.emit(s.i, ch); s.i += 1; return;\n        }\n    }\n    if (ch === '/' && next === '/') { s.emit(s.i, '/'); s.emit(s.i + 1, '/'); s.i += 2; s.pushState('lineComment'); return; }\n    if (ch === '/' && next === '*') { s.emit(s.i, '/'); s.emit(s.i + 1, '*'); s.i += 2; s.pushState('blockComment'); return; }\n    if (ch === '\"') { s.emit(s.i, '\"'); s.i += 1; s.pushState('dquote'); return; }\n    if (ch === \"'\") { s.emit(s.i, \"'\"); s.i += 1; s.pushState('squote'); return; }\n    if (ch === '`') { s.emit(s.i, '`'); s.i += 1; s.pushState('template'); return; }\n    s.emit(s.i, ch); s.i += 1;\n}\n\n// webpieces-disable no-function-outside-class -- existing stateless module helper moved intact with its callers; ownership extraction preserves its functional API\nfunction handleLineComment(s: StripState): void {\n    if (s.ch() === '\\n') { s.emit(s.i, '\\n'); s.i += 1; s.popState(); return; }\n    s.blank(s.i, s.ch()); s.i += 1;\n}\n\n// webpieces-disable no-function-outside-class -- existing stateless module helper moved intact with its callers; ownership extraction preserves its functional API\nfunction handleBlockComment(s: StripState): void {\n    if (s.ch() === '*' && s.next() === '/') { s.emit(s.i, '*'); s.emit(s.i + 1, '/'); s.i += 2; s.popState(); return; }\n    s.blank(s.i, s.ch()); s.i += 1;\n}\n\n// webpieces-disable no-function-outside-class -- existing stateless module helper moved intact with its callers; ownership extraction preserves its functional API\nfunction handleStringLiteral(s: StripState, quoteChar: string): void {\n    const ch = s.ch();\n    if (ch === '\\\\' && s.i + 1 < s.len) { s.blank(s.i, ch); s.blank(s.i + 1, s.source[s.i + 1]); s.i += 2; return; }\n    if (ch === quoteChar) { s.emit(s.i, quoteChar); s.i += 1; s.popState(); return; }\n    s.blank(s.i, ch); s.i += 1;\n}\n\n// webpieces-disable no-function-outside-class -- existing stateless module helper moved intact with its callers; ownership extraction preserves its functional API\nfunction handleTemplate(s: StripState): void {\n    const ch = s.ch();\n    if (ch === '\\\\' && s.i + 1 < s.len) { s.blank(s.i, ch); s.blank(s.i + 1, s.source[s.i + 1]); s.i += 2; return; }\n    if (ch === '`') { s.emit(s.i, '`'); s.i += 1; s.popState(); return; }\n    if (ch === '$' && s.next() === '{') {\n        s.emit(s.i, '$'); s.emit(s.i + 1, '{'); s.i += 2;\n        s.stack.push({ state: 'template', braceDepth: 0 });\n        s.state = 'templateInterp'; s.braceDepth = 0;\n        return;\n    }\n    s.blank(s.i, ch); s.i += 1;\n}\n\n// webpieces-disable no-function-outside-class -- existing stateless module helper moved intact with its callers; ownership extraction preserves its functional API\nexport function stripTsNoise(source: string): string {\n    const s = new StripState(source);\n    while (s.i < s.len) {\n        if (s.state === 'code' || s.state === 'templateInterp') { handleCodeOrInterp(s); }\n        else if (s.state === 'lineComment') { handleLineComment(s); }\n        else if (s.state === 'blockComment') { handleBlockComment(s); }\n        else if (s.state === 'dquote') { handleStringLiteral(s, '\"'); }\n        else if (s.state === 'squote') { handleStringLiteral(s, \"'\"); }\n        else if (s.state === 'template') { handleTemplate(s); }\n        else { s.emit(s.i, s.ch()); s.i += 1; }\n    }\n    return s.out.join('');\n}\n"]}

package/src/core/target-tree.d.ts

@@ -0,0 +1,84 @@
+import { EffectiveTree, EffectiveTreeResolver } from './effective-tree';
+/**
+ * WHICH TREE owns the FILE a Write/Edit/Read is aimed at? The file-path counterpart to
+ * EffectiveTreeResolver, which answers the same question for a Bash command's effective cwd.
+ *
+ * WHY IT HAS TO EXIST (issue #851). The bash half of this question has been answered by git since
+ * effective-tree.ts was written — `isLinkedWorktree` is `--git-dir !== --git-common-dir`, and its header
+ * states the principle in capitals: *PLACEMENT IS NOT IDENTITY*. The FILE half never consumed that
+ * answer. Every file-scoped guard judged `ctx.workspaceRoot`, which is the walk-up from the SESSION's
+ * cwd to whichever `webpieces.config.json` governs it — the PRIMARY clone, for a main-session edit into
+ * an agent worktree. Because Claude Code checks a worktree out INSIDE the repo at
+ * `<repo>/.claude/worktrees/agent-XXXX`, that walk-up answers "primary" for a path that is manifestly
+ * not the primary's, and nothing downstream re-examined it.
+ *
+ * Measured live on 2026-09-03: an Edit of one import line inside a worktree on a CLEAN branch was
+ * refused, citing `pnpm-lock.yaml` and `pnpm-workspace.yaml` — the PRIMARY clone's branch's conflict
+ * files. The main-sync cache is already keyed by branch and already held the correct, non-conflicting
+ * entry for the worktree's branch, one key over. Only the lookup key was wrong. So this class exists to
+ * make the lookup ask the same authority the bash half asks, rather than to introduce a second one.
+ *
+ * IT ASKS EffectiveTreeResolver, and adds NOTHING of its own beyond finding a directory to ask about.
+ * That is deliberate and it is the whole design: two resolvers WILL disagree about which tree a path is
+ * in, and this module exists precisely because two layers already did. There is no `.claude/worktrees`
+ * string match here and there must never be one — matching on placement is the bug, not the fix.
+ *
+ * The only thing worth naming is the walk-up: a Write legitimately names a file, and directories, that
+ * do not exist yet, and git cannot be asked about a directory that is not there. So we climb to the
+ * nearest EXISTING ancestor and ask about that. A parent directory is in the same worktree as the child
+ * it is about to contain — that is a property of the filesystem, not a guess.
+ */
+export declare class TargetTreeResolver {
+    private readonly trees;
+    constructor(trees?: EffectiveTreeResolver);
+    /**
+     * The tree that owns `targetPath`, classified exactly as a Bash command's cwd would be.
+     *
+     * `governedRoot` is the fallback for every case with no better answer — an empty path, a path with
+     * no existing ancestor at all — and is also what `EffectiveTree.governedRoot` keeps meaning: whose
+     * config and excludePaths apply. It is NOT the tree to judge; `EffectiveTree.root` is.
+     */
+    resolve(targetPath: string, governedRoot: string): EffectiveTree;
+    /**
+     * The two relative spellings of one target path, resolved together so a caller cannot accidentally
+     * use the wrong one. See GovernedPath for why there are two.
+     */
+    governedPath(targetPath: string, governedRoot: string): GovernedPath;
+    private nearestExistingDir;
+    /**
+     * `targetPath` made absolute AND symlink-resolved, including when it does not exist yet.
+     *
+     * `fs.realpathSync` throws on a missing path, and a Write's target is missing by definition, so the
+     * resolvable HEAD of the path (its nearest existing ancestor) is resolved and the not-yet-existing
+     * TAIL is re-appended verbatim. That keeps it comparable with `tree.root`, which is git's answer and
+     * always real.
+     */
+    private realAbsolute;
+    private realDir;
+}
+/**
+ * One target path, in the TWO relative spellings the hook path needs — data-only, per CLAUDE.md.
+ *
+ * They are different questions and conflating them is issue #851's secondary defect:
+ *
+ *   `relativePath`     — relative to the GOVERNED root. What `excludePaths`' globs are written against,
+ *                        and what the violation report prints.
+ *   `treeRelativePath` — relative to the tree that OWNS the file. What `isWebpiecesStateDir` must be
+ *                        asked about, because `.webpieces/` is the tooling's state dir *of a tree*, and
+ *                        a worktree has its own. Governed-root-relative, a reviewer subagent's
+ *                        `<primary>/.claude/worktrees/agent-X/.webpieces/pr-review/<branch>/summary.json`
+ *                        reads as `.claude/...` and was NOT exempt — while
+ *                        `<primary>/.webpieces/worktrees/agent-X/pr-review/.../review-1.json`, the same
+ *                        kind of file one directory over, was. `wp-review-upsert-pr` REQUIRES that file
+ *                        before `wp-finish-upsert-pr` will open a PR, so the guard could forbid a file
+ *                        the gate demands.
+ *
+ * In the primary clone the two strings are identical, which is why the gap was invisible for so long.
+ */
+export declare class GovernedPath {
+    readonly relativePath: string;
+    readonly treeRelativePath: string;
+    /** The git tree that owns the target path; policy still belongs to the separately loaded governed root. */
+    readonly treeRoot: string;
+    constructor(relativePath: string, treeRelativePath: string, treeRoot: string);
+}

package/src/core/target-tree.js

@@ -0,0 +1,148 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.GovernedPath = exports.TargetTreeResolver = void 0;
+const tslib_1 = require("tslib");
+const fs = tslib_1.__importStar(require("fs"));
+const path = tslib_1.__importStar(require("path"));
+const effective_tree_1 = require("./effective-tree");
+/**
+ * WHICH TREE owns the FILE a Write/Edit/Read is aimed at? The file-path counterpart to
+ * EffectiveTreeResolver, which answers the same question for a Bash command's effective cwd.
+ *
+ * WHY IT HAS TO EXIST (issue #851). The bash half of this question has been answered by git since
+ * effective-tree.ts was written — `isLinkedWorktree` is `--git-dir !== --git-common-dir`, and its header
+ * states the principle in capitals: *PLACEMENT IS NOT IDENTITY*. The FILE half never consumed that
+ * answer. Every file-scoped guard judged `ctx.workspaceRoot`, which is the walk-up from the SESSION's
+ * cwd to whichever `webpieces.config.json` governs it — the PRIMARY clone, for a main-session edit into
+ * an agent worktree. Because Claude Code checks a worktree out INSIDE the repo at
+ * `<repo>/.claude/worktrees/agent-XXXX`, that walk-up answers "primary" for a path that is manifestly
+ * not the primary's, and nothing downstream re-examined it.
+ *
+ * Measured live on 2026-09-03: an Edit of one import line inside a worktree on a CLEAN branch was
+ * refused, citing `pnpm-lock.yaml` and `pnpm-workspace.yaml` — the PRIMARY clone's branch's conflict
+ * files. The main-sync cache is already keyed by branch and already held the correct, non-conflicting
+ * entry for the worktree's branch, one key over. Only the lookup key was wrong. So this class exists to
+ * make the lookup ask the same authority the bash half asks, rather than to introduce a second one.
+ *
+ * IT ASKS EffectiveTreeResolver, and adds NOTHING of its own beyond finding a directory to ask about.
+ * That is deliberate and it is the whole design: two resolvers WILL disagree about which tree a path is
+ * in, and this module exists precisely because two layers already did. There is no `.claude/worktrees`
+ * string match here and there must never be one — matching on placement is the bug, not the fix.
+ *
+ * The only thing worth naming is the walk-up: a Write legitimately names a file, and directories, that
+ * do not exist yet, and git cannot be asked about a directory that is not there. So we climb to the
+ * nearest EXISTING ancestor and ask about that. A parent directory is in the same worktree as the child
+ * it is about to contain — that is a property of the filesystem, not a guess.
+ */
+class TargetTreeResolver {
+    trees;
+    constructor(trees = new effective_tree_1.EffectiveTreeResolver()) {
+        this.trees = trees;
+    }
+    /**
+     * The tree that owns `targetPath`, classified exactly as a Bash command's cwd would be.
+     *
+     * `governedRoot` is the fallback for every case with no better answer — an empty path, a path with
+     * no existing ancestor at all — and is also what `EffectiveTree.governedRoot` keeps meaning: whose
+     * config and excludePaths apply. It is NOT the tree to judge; `EffectiveTree.root` is.
+     */
+    resolve(targetPath, governedRoot) {
+        // REAL paths on BOTH sides, or git's answers cannot be compared with each other. Identity here
+        // is `commonDir(target) === commonDir(governed)`, and git prints an ABSOLUTE, symlink-resolved
+        // path from a linked worktree while printing a bare relative `.git` from the primary clone. So
+        // on any repo reached through a symlink — `/var/folders/...` on macOS, which is `/private/var`,
+        // and every `os.tmpdir()` path under it — the two strings differ for the same `.git` and the
+        // repo's OWN worktree classifies as `foreign`, i.e. every guard silently off. Resolving both
+        // sides first is what makes the comparison an answer about git rather than about spelling.
+        const governed = this.realDir(governedRoot);
+        return this.trees.resolve('', this.nearestExistingDir(targetPath, governed), governed);
+    }
+    /**
+     * The two relative spellings of one target path, resolved together so a caller cannot accidentally
+     * use the wrong one. See GovernedPath for why there are two.
+     */
+    governedPath(targetPath, governedRoot) {
+        const absolute = this.realAbsolute(targetPath);
+        const tree = this.resolve(targetPath, governedRoot);
+        // `tree.root` and `tree.governedRoot` are already resolved by resolve() above, so both
+        // subtractions are real-against-real. Mixing one resolved side with one unresolved one produces
+        // a `../../../..` climb out of the filesystem — which reads as "outside the workspace" and
+        // would quietly hand every path the wrong verdict on a symlinked checkout.
+        return new GovernedPath(path.relative(tree.governedRoot, absolute), path.relative(tree.root, absolute), tree.root);
+    }
+    // The nearest ancestor directory of `targetPath` that EXISTS — the deepest directory git can be
+    // asked about — with symlinks resolved. Bounded by the filesystem root (path.dirname is its own
+    // fixed point at `/`), so the loop terminates without a counter.
+    nearestExistingDir(targetPath, governedRoot) {
+        if (targetPath === '')
+            return governedRoot;
+        let dir = path.dirname(path.resolve(targetPath));
+        for (;;) {
+            if (fs.existsSync(dir))
+                return fs.realpathSync(dir);
+            const parent = path.dirname(dir);
+            if (parent === dir)
+                return governedRoot;
+            dir = parent;
+        }
+    }
+    /**
+     * `targetPath` made absolute AND symlink-resolved, including when it does not exist yet.
+     *
+     * `fs.realpathSync` throws on a missing path, and a Write's target is missing by definition, so the
+     * resolvable HEAD of the path (its nearest existing ancestor) is resolved and the not-yet-existing
+     * TAIL is re-appended verbatim. That keeps it comparable with `tree.root`, which is git's answer and
+     * always real.
+     */
+    realAbsolute(targetPath) {
+        const absolute = path.resolve(targetPath);
+        const tail = [];
+        let dir = absolute;
+        for (;;) {
+            if (fs.existsSync(dir))
+                return path.join(fs.realpathSync(dir), ...tail);
+            const parent = path.dirname(dir);
+            if (parent === dir)
+                return absolute;
+            tail.unshift(path.basename(dir));
+            dir = parent;
+        }
+    }
+    // A directory made real when it is there, and merely absolute when it is not.
+    realDir(dir) {
+        return fs.existsSync(dir) ? fs.realpathSync(dir) : path.resolve(dir);
+    }
+}
+exports.TargetTreeResolver = TargetTreeResolver;
+/**
+ * One target path, in the TWO relative spellings the hook path needs — data-only, per CLAUDE.md.
+ *
+ * They are different questions and conflating them is issue #851's secondary defect:
+ *
+ *   `relativePath`     — relative to the GOVERNED root. What `excludePaths`' globs are written against,
+ *                        and what the violation report prints.
+ *   `treeRelativePath` — relative to the tree that OWNS the file. What `isWebpiecesStateDir` must be
+ *                        asked about, because `.webpieces/` is the tooling's state dir *of a tree*, and
+ *                        a worktree has its own. Governed-root-relative, a reviewer subagent's
+ *                        `<primary>/.claude/worktrees/agent-X/.webpieces/pr-review/<branch>/summary.json`
+ *                        reads as `.claude/...` and was NOT exempt — while
+ *                        `<primary>/.webpieces/worktrees/agent-X/pr-review/.../review-1.json`, the same
+ *                        kind of file one directory over, was. `wp-review-upsert-pr` REQUIRES that file
+ *                        before `wp-finish-upsert-pr` will open a PR, so the guard could forbid a file
+ *                        the gate demands.
+ *
+ * In the primary clone the two strings are identical, which is why the gap was invisible for so long.
+ */
+class GovernedPath {
+    relativePath;
+    treeRelativePath;
+    /** The git tree that owns the target path; policy still belongs to the separately loaded governed root. */
+    treeRoot;
+    constructor(relativePath, treeRelativePath, treeRoot) {
+        this.relativePath = relativePath;
+        this.treeRelativePath = treeRelativePath;
+        this.treeRoot = treeRoot;
+    }
+}
+exports.GovernedPath = GovernedPath;
+//# sourceMappingURL=target-tree.js.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"target-tree.js","sourceRoot":"","sources":["../../../../../../packages/tooling/hook-runtime/src/core/target-tree.ts"],"names":[],"mappings":"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","sourcesContent":["import * as fs from 'fs';\nimport * as path from 'path';\n\nimport { EffectiveTree, EffectiveTreeResolver } from './effective-tree';\n\n/**\n * WHICH TREE owns the FILE a Write/Edit/Read is aimed at? The file-path counterpart to\n * EffectiveTreeResolver, which answers the same question for a Bash command's effective cwd.\n *\n * WHY IT HAS TO EXIST (issue #851). The bash half of this question has been answered by git since\n * effective-tree.ts was written — `isLinkedWorktree` is `--git-dir !== --git-common-dir`, and its header\n * states the principle in capitals: *PLACEMENT IS NOT IDENTITY*. The FILE half never consumed that\n * answer. Every file-scoped guard judged `ctx.workspaceRoot`, which is the walk-up from the SESSION's\n * cwd to whichever `webpieces.config.json` governs it — the PRIMARY clone, for a main-session edit into\n * an agent worktree. Because Claude Code checks a worktree out INSIDE the repo at\n * `<repo>/.claude/worktrees/agent-XXXX`, that walk-up answers \"primary\" for a path that is manifestly\n * not the primary's, and nothing downstream re-examined it.\n *\n * Measured live on 2026-09-03: an Edit of one import line inside a worktree on a CLEAN branch was\n * refused, citing `pnpm-lock.yaml` and `pnpm-workspace.yaml` — the PRIMARY clone's branch's conflict\n * files. The main-sync cache is already keyed by branch and already held the correct, non-conflicting\n * entry for the worktree's branch, one key over. Only the lookup key was wrong. So this class exists to\n * make the lookup ask the same authority the bash half asks, rather than to introduce a second one.\n *\n * IT ASKS EffectiveTreeResolver, and adds NOTHING of its own beyond finding a directory to ask about.\n * That is deliberate and it is the whole design: two resolvers WILL disagree about which tree a path is\n * in, and this module exists precisely because two layers already did. There is no `.claude/worktrees`\n * string match here and there must never be one — matching on placement is the bug, not the fix.\n *\n * The only thing worth naming is the walk-up: a Write legitimately names a file, and directories, that\n * do not exist yet, and git cannot be asked about a directory that is not there. So we climb to the\n * nearest EXISTING ancestor and ask about that. A parent directory is in the same worktree as the child\n * it is about to contain — that is a property of the filesystem, not a guess.\n */\nexport class TargetTreeResolver {\n    constructor(private readonly trees: EffectiveTreeResolver = new EffectiveTreeResolver()) {}\n\n    /**\n     * The tree that owns `targetPath`, classified exactly as a Bash command's cwd would be.\n     *\n     * `governedRoot` is the fallback for every case with no better answer — an empty path, a path with\n     * no existing ancestor at all — and is also what `EffectiveTree.governedRoot` keeps meaning: whose\n     * config and excludePaths apply. It is NOT the tree to judge; `EffectiveTree.root` is.\n     */\n    resolve(targetPath: string, governedRoot: string): EffectiveTree {\n        // REAL paths on BOTH sides, or git's answers cannot be compared with each other. Identity here\n        // is `commonDir(target) === commonDir(governed)`, and git prints an ABSOLUTE, symlink-resolved\n        // path from a linked worktree while printing a bare relative `.git` from the primary clone. So\n        // on any repo reached through a symlink — `/var/folders/...` on macOS, which is `/private/var`,\n        // and every `os.tmpdir()` path under it — the two strings differ for the same `.git` and the\n        // repo's OWN worktree classifies as `foreign`, i.e. every guard silently off. Resolving both\n        // sides first is what makes the comparison an answer about git rather than about spelling.\n        const governed = this.realDir(governedRoot);\n        return this.trees.resolve('', this.nearestExistingDir(targetPath, governed), governed);\n    }\n\n    /**\n     * The two relative spellings of one target path, resolved together so a caller cannot accidentally\n     * use the wrong one. See GovernedPath for why there are two.\n     */\n    governedPath(targetPath: string, governedRoot: string): GovernedPath {\n        const absolute = this.realAbsolute(targetPath);\n        const tree = this.resolve(targetPath, governedRoot);\n        // `tree.root` and `tree.governedRoot` are already resolved by resolve() above, so both\n        // subtractions are real-against-real. Mixing one resolved side with one unresolved one produces\n        // a `../../../..` climb out of the filesystem — which reads as \"outside the workspace\" and\n        // would quietly hand every path the wrong verdict on a symlinked checkout.\n        return new GovernedPath(\n            path.relative(tree.governedRoot, absolute),\n            path.relative(tree.root, absolute),\n            tree.root,\n        );\n    }\n\n    // The nearest ancestor directory of `targetPath` that EXISTS — the deepest directory git can be\n    // asked about — with symlinks resolved. Bounded by the filesystem root (path.dirname is its own\n    // fixed point at `/`), so the loop terminates without a counter.\n    private nearestExistingDir(targetPath: string, governedRoot: string): string {\n        if (targetPath === '') return governedRoot;\n        let dir = path.dirname(path.resolve(targetPath));\n        for (;;) {\n            if (fs.existsSync(dir)) return fs.realpathSync(dir);\n            const parent = path.dirname(dir);\n            if (parent === dir) return governedRoot;\n            dir = parent;\n        }\n    }\n\n    /**\n     * `targetPath` made absolute AND symlink-resolved, including when it does not exist yet.\n     *\n     * `fs.realpathSync` throws on a missing path, and a Write's target is missing by definition, so the\n     * resolvable HEAD of the path (its nearest existing ancestor) is resolved and the not-yet-existing\n     * TAIL is re-appended verbatim. That keeps it comparable with `tree.root`, which is git's answer and\n     * always real.\n     */\n    private realAbsolute(targetPath: string): string {\n        const absolute = path.resolve(targetPath);\n        const tail: string[] = [];\n        let dir = absolute;\n        for (;;) {\n            if (fs.existsSync(dir)) return path.join(fs.realpathSync(dir), ...tail);\n            const parent = path.dirname(dir);\n            if (parent === dir) return absolute;\n            tail.unshift(path.basename(dir));\n            dir = parent;\n        }\n    }\n\n    // A directory made real when it is there, and merely absolute when it is not.\n    private realDir(dir: string): string {\n        return fs.existsSync(dir) ? fs.realpathSync(dir) : path.resolve(dir);\n    }\n}\n\n/**\n * One target path, in the TWO relative spellings the hook path needs — data-only, per CLAUDE.md.\n *\n * They are different questions and conflating them is issue #851's secondary defect:\n *\n *   `relativePath`     — relative to the GOVERNED root. What `excludePaths`' globs are written against,\n *                        and what the violation report prints.\n *   `treeRelativePath` — relative to the tree that OWNS the file. What `isWebpiecesStateDir` must be\n *                        asked about, because `.webpieces/` is the tooling's state dir *of a tree*, and\n *                        a worktree has its own. Governed-root-relative, a reviewer subagent's\n *                        `<primary>/.claude/worktrees/agent-X/.webpieces/pr-review/<branch>/summary.json`\n *                        reads as `.claude/...` and was NOT exempt — while\n *                        `<primary>/.webpieces/worktrees/agent-X/pr-review/.../review-1.json`, the same\n *                        kind of file one directory over, was. `wp-review-upsert-pr` REQUIRES that file\n *                        before `wp-finish-upsert-pr` will open a PR, so the guard could forbid a file\n *                        the gate demands.\n *\n * In the primary clone the two strings are identical, which is why the gap was invisible for so long.\n */\nexport class GovernedPath {\n    readonly relativePath: string;\n    readonly treeRelativePath: string;\n    /** The git tree that owns the target path; policy still belongs to the separately loaded governed root. */\n    readonly treeRoot: string;\n\n    constructor(relativePath: string, treeRelativePath: string, treeRoot: string) {\n        this.relativePath = relativePath;\n        this.treeRelativePath = treeRelativePath;\n        this.treeRoot = treeRoot;\n    }\n}\n"]}

package/src/core/types.d.ts

@@ -0,0 +1,149 @@
+import { RuleOptions } from '@webpieces/rules-config';
+import { ToolKind } from '../protocol';
+import { FixHint } from './fix-hint';
+export type RuleScope = 'edit' | 'file' | 'bash';
+export type IsLineDisabled = (lineNum: number, ruleName: string) => boolean;
+export declare class Violation {
+    readonly line: number;
+    readonly snippet: string;
+    readonly message: string | undefined;
+    editIndex: number | undefined;
+    editCount: number | undefined;
+    constructor(line: number, snippet: string, message?: string);
+}
+export declare class EditContext {
+    readonly tool: ToolKind;
+    readonly editIndex: number;
+    readonly editCount: number;
+    readonly filePath: string;
+    readonly relativePath: string;
+    readonly workspaceRoot: string;
+    readonly addedContent: string;
+    readonly strippedContent: string;
+    readonly lines: readonly string[];
+    readonly strippedLines: readonly string[];
+    readonly removedContent: string;
+    readonly isLineDisabled: IsLineDisabled;
+    options: RuleOptions;
+    constructor(tool: ToolKind, editIndex: number, editCount: number, filePath: string, relativePath: string, workspaceRoot: string, addedContent: string, strippedContent: string, lines: readonly string[], strippedLines: readonly string[], removedContent: string, isLineDisabled: IsLineDisabled);
+}
+export declare class BashContext {
+    readonly tool: 'Bash';
+    readonly command: string;
+    /**
+     * `command` with heredoc bodies and prose-in-quotes removed — what a guard should MATCH on, while
+     * `command` stays raw for the violation message (a human needs to see what they actually typed).
+     *
+     * A commit message that merely MENTIONS a blocked command is not that command. This repo's whole
+     * subject matter is the git workflow, so its commit messages, docs and the guards' own fix-hint
+     * text are full of `git push` / `gh pr …` strings; matching raw text blocks writing about the
+     * tooling. A guard that cries wolf is a guard someone eventually turns OFF, which costs far more
+     * than the theoretical bypass this opens (`sh -c '<blocked command>'` stops matching). That trade
+     * is deliberate: these guards exist to catch a FORGETFUL agent, not an adversarial one.
+     *
+     * ONLY for blocklist-shaped guards ("if the command matches X, block"), where stripping can only
+     * ever block LESS. Never use it in an allowlist-shaped guard such as merged-branch-bash-guard,
+     * where stripping could turn a permitted recovery command into a blocked one and deadlock the
+     * session — there, match on the raw `command`.
+     */
+    readonly commandCode: string;
+    /**
+     * The tree this command is JUDGED against — the root of the worktree it actually acts on, which
+     * is NOT the shell's cwd whenever the command carries a leading `cd <path> &&` (see
+     * EffectiveTreeResolver). Guards read git state, the main-sync cache and the decision log from
+     * here, so a command aimed at a linked worktree is judged on that worktree's branch, never the
+     * primary clone's.
+     */
+    readonly workspaceRoot: string;
+    /** The directory the command really runs in (post-`cd`). Relative paths resolve against THIS. */
+    readonly effectiveCwd: string;
+    /** The root owning webpieces.config.json. Equals workspaceRoot except in a linked worktree. */
+    readonly governedRoot: string;
+    options: RuleOptions;
+    constructor(command: string, workspaceRoot: string, effectiveCwd?: string, governedRoot?: string);
+    /**
+     * A quoted span WITHOUT whitespace is kept: `git checkout "main"` is a real command with a quoted
+     * argument, not prose. One containing whitespace is a sentence, and becomes a single space.
+     *
+     * ONE exception, and it is a false positive that actually fired: a whitespace-free span carrying
+     * SHELL METACHARACTERS is dropped too. Keeping the content strips only the quotes, so a jq filter —
+     * `--jq '[.[]|select(.title|test("x"))]|length'` — was handed to the guards as bare shell syntax.
+     * Every guard then split it on its `|`, `(` and `;` and saw a segment reading exactly `test`, which
+     * whole-repo-build-guard classified as the workspace-wide test script and BLOCKED. There was no
+     * build anywhere in that command; it polled npm and GitHub.
+     *
+     * Quoting is precisely how a shell says "this is DATA, not syntax", so honouring the quotes is the
+     * correct reading. And because commandCode only ever feeds blocklist-shaped guards, dropping more
+     * can only ever block LESS — never turn an allowed command into a refused one.
+     */
+    private stripProse;
+}
+export declare class FileContext {
+    readonly tool: ToolKind;
+    readonly filePath: string;
+    readonly relativePath: string;
+    readonly workspaceRoot: string;
+    /** The git tree that owns filePath. workspaceRoot remains the root that owns policy/config. */
+    readonly targetRoot: string;
+    /** filePath relative to targetRoot, independent of its governed-root spelling. */
+    readonly targetRelativePath: string;
+    readonly currentFileLines: number;
+    readonly linesAdded: number;
+    readonly linesRemoved: number;
+    readonly projectedFileLines: number;
+    options: RuleOptions;
+    constructor(tool: ToolKind, filePath: string, relativePath: string, workspaceRoot: string, currentFileLines: number, linesAdded: number, linesRemoved: number, projectedFileLines: number, targetRoot?: string, targetRelativePath?: string);
+}
+/**
+ * The shape of a custom rule loaded from a `rulesDir` (a plain object returned by require()).
+ * It carries only metadata + a `check` method — no on/off logic of its own.
+ */
+export interface PlainRule {
+    readonly name: string;
+    readonly description: string;
+    readonly scope: RuleScope;
+    readonly files: readonly string[];
+    readonly defaultOptions: RuleOptions;
+    readonly fixHint: FixHint;
+    check(ctx: EditContext | FileContext | BashContext): readonly Violation[];
+}
+/**
+ * The runtime contract the runner iterates. Both the built-in rule classes (which extend
+ * EditRuleBase/FileRuleBase/BashRuleBase) and the custom-rule adapter satisfy this: they add
+ * `shouldRun()` (mode + escape-hatch decision) on top of the PlainRule metadata.
+ */
+export interface Rule extends PlainRule {
+    /**
+     * The webpieces.config.json key whose entry configures this rule — NOT necessarily `name`.
+     *
+     * `name` is the operator identity (what a decision-log line and a deny report carry); `configKey`
+     * is the switch. They differ wherever several classes implement one POLICY: all four branch-state
+     * guards read `branch-state-guard`, all four PR-lifecycle guards read `pr-lifecycle-guard`. Every
+     * consumer that asks "which section does this live in?" (filterByMode) or "does this have an
+     * entry?" (the fault-Y config-sync check) must read THIS field, because asking for `name` there
+     * demands entries under keys the validator rejects as retired.
+     */
+    readonly configKey: string;
+    shouldRun(): boolean;
+}
+export declare class RuleGroup {
+    readonly ruleName: string;
+    readonly ruleDescription: string;
+    readonly fixHint: FixHint;
+    readonly violations: readonly Violation[];
+    constructor(ruleName: string, ruleDescription: string, fixHint: FixHint, violations: readonly Violation[]);
+}
+export declare class BlockedResult {
+    readonly report: string;
+    /**
+     * The L0 fault this block IS, in the codebook's own letter (see core/l0-fault-codes.ts), or `-` for
+     * an ordinary rule block.
+     *
+     * It rides on the result rather than being re-derived from the report text because the block is
+     * decided deep in the runner (fault C in configMissingBlock, fault Y in checkConfigSync) and
+     * STAMPED by the adapter at the terminal boundary, several frames up. Scraping the report for a
+     * fault would be a second answer to a question the producer already knows.
+     */
+    readonly fault: string;
+    constructor(report: string, fault?: string);
+}