@webpieces/rules-config 0.4.517 → 0.4.519

package/src/state-dir.d.ts

@@ -0,0 +1,131 @@
+import { StateDirMigrator } from './state-dir-migration';
+export declare const WORKTREE_STATE_DIR = "worktrees";
+/**
+ * Data-only carrier for the two paths git is asked for. Per CLAUDE.md: classes for data.
+ *
+ * `gitDir` is the PER-WORKTREE git dir (`<primary>/.git/worktrees/<name>` in a linked worktree,
+ * `<primary>/.git` in the primary clone). `commonDir` is the SHARED one — always `<primary>/.git`.
+ * They differ if and only if this is a linked worktree; that is git's own canonical test.
+ */
+export declare class GitDirs {
+    readonly gitDir: string;
+    readonly commonDir: string;
+    constructor(gitDir: string, commonDir: string);
+    get isLinkedWorktree(): boolean;
+}
+/**
+ * WHERE a piece of `.webpieces/` state belongs — the ONE resolver every reader and writer must go
+ * through, with TWO named methods because there are exactly two answers and a call site must DECLARE
+ * which one it means.
+ *
+ *   dotWebpieces.shared(dir) → <primary>/.webpieces                       (repo-wide facts)
+ *   dotWebpieces.local(dir)  → <primary>/.webpieces/worktrees/<name>      (this worktree only)
+ *                            → <primary>/.webpieces                       (…in the primary clone)
+ *
+ * ─── The bug ───────────────────────────────────────────────────────────────────────────────────────
+ * `.webpieces/` is gitignored, and it was anchored at the directory holding webpieces.config.json —
+ * which in a linked worktree is the WORKTREE. So a repo with seven worktrees had SEVEN independent
+ * copies of files that describe the WHOLE REPO. `merged-branches.json` holds verdicts for every branch
+ * AND every worktree in the repo; N copies is N divergent truths, and the guards read them as fact.
+ * Observed in the field: branch-creation-guard asserted "8 parked local branches" while
+ * `git branch --list` showed ONE — it was reading a cache written before deletions performed from a
+ * DIFFERENT worktree — and it then blocked a legitimate `git worktree add` on that fiction.
+ *
+ * ─── Why two explicit methods and not a symlink ────────────────────────────────────────────────────
+ * A `<worktree>/.webpieces` → `<primary>/…/worktrees/<name>` symlink would have left every call site
+ * untouched, which is seductive and wrong. Nothing hooks `git worktree add`, so the link needs LAZY
+ * creation that also has to handle "link already exists", "link points somewhere else", and "a real
+ * directory is already there" — invisible filesystem magic with a Windows failure mode. Worse, the safe
+ * way to write a shared file under concurrency is temp-file-then-`rename()`, and `rename(2)` acts on
+ * the PATH, not the link: it REPLACES a symlink with a real file. That silently works for one writer
+ * and diverges for everyone else — the exact bug being fixed, but invisible. An explicit call is
+ * greppable, testable, and forces each site to say which scope it means.
+ *
+ * ─── Which scope is which (the scope assignment is deliberate, not incidental) ─────────────────────
+ * shared():
+ *   • merged-branches.json — verdicts for every branch and worktree in the repo. Atomically written.
+ *   • main-sync-status.json AND main-sync.lock.json — there is one `main` and one `.git`, so there is
+ *     one refresher. A lock inside a per-worktree directory locks nothing.
+ * local():
+ *   • hooks/*.log, INCLUDING branch-mutations.log. A shared append-only log genuinely corrupts:
+ *     `O_APPEND` writes are indivisible only under PIPE_BUF, which is 512 bytes on macOS, and a
+ *     `recover=git worktree add -b <branch> <abs-path> <tag>` line with real paths exceeds that. A
+ *     per-worktree log has exactly ONE writer and cannot tear, and under this layout it already
+ *     survives the worktree's deletion — recovery is one glob over
+ *     `<primary>/.webpieces/worktrees/＊/hooks/branch-mutations.log`.
+ *   • merge-info/staged|merged/<branch>/ and its index.json, pr-review/<branch>/, instruct-ai/, and
+ *     every other per-tree scratch file.
+ *
+ * ─── The boundary that must not be blurred ─────────────────────────────────────────────────────────
+ * ONLY the gitignored `.webpieces/` STATE relocates. `webpieces.config.json` is TRACKED IN GIT and is
+ * therefore part of the BRANCH: a branch may legitimately change its own rules and that must keep
+ * working. Config resolution is untouched — still per-worktree, via findConfigFile /
+ * RepoRootFinder.resolveRepoRoot. Nothing in this class reads or moves config.
+ *
+ * ─── Why `--git-dir` / `--git-common-dir`, and not one of the existing services ────────────────────
+ * They are git's own answers, from any subdirectory, in one cheap local call, with no `.git`-file
+ * parsing by hand (which gets `--separate-git-dir` and submodules wrong). Two existing mechanisms do
+ * distinguish primary from linked, and neither is the right authority here:
+ *   • `WorktreeService` answers "what worktrees exist and what do they hold" — a repo-wide ENUMERATION
+ *     (`git worktree list --porcelain`) for the caps and the reaper. Using it for a path lookup would
+ *     run an enumeration on the hook's blocking path for every state access, and it fails SOFT to `[]`,
+ *     which here would read as "there is no primary clone" on exactly the degraded repo where the
+ *     answer matters most. It also does not expose the worktree's git NAME, which is the namespace key.
+ *   • `EffectiveTreeResolver` (#524) answers "which tree does this COMMAND act on" — it takes a command
+ *     string and is a policy input to the bash guards, not a filesystem-path resolver.
+ * Both remain authoritative for their own questions. This asks the narrowest one — two path strings —
+ * and lives in rules-config, UNDER both, which is where a primitive that pr-gate, ai-hook-rules and
+ * code-rules all need has to sit.
+ *
+ * Fails CLOSED to the pre-change behaviour: when git cannot answer, every path here collapses to
+ * `<startDir-root>/.webpieces` exactly as before. Degrading to merely-suboptimal beats throwing on a
+ * hook's blocking path.
+ */
+export declare class DotWebpieces {
+    private readonly migrator;
+    private readonly gitDirsByRoot;
+    private readonly migrated;
+    constructor(migrator?: StateDirMigrator);
+    /**
+     * REPO-WIDE state: `<primary>/.webpieces`. Use ONLY for facts about the repo rather than about one
+     * worktree — today that is merged-branches.json and the main-sync status + lock. Identical from
+     * every worktree, and never behind an indirection, so an atomic `rename()` into it is safe.
+     */
+    shared(startDir: string): string;
+    /** A path beneath the repo-wide state dir. */
+    sharedFile(startDir: string, ...segments: string[]): string;
+    /**
+     * THIS WORKTREE's private state: `<primary>/.webpieces/worktrees/<name>` for a linked worktree, and
+     * `<primary>/.webpieces` for the primary clone, which keeps its state exactly where it has always
+     * been. Fully isolated — two worktrees never write the same path, so nothing here needs a lock.
+     *
+     * The first call for a linked worktree also MIGRATES a legacy real `<worktree>/.webpieces/`
+     * directory into the namespace, so in-flight merge / pr-review state written under the old scheme
+     * (or by an older PUBLISHED build during the transition) is picked up rather than orphaned.
+     */
+    local(startDir: string): string;
+    /** A path beneath this worktree's private state dir. */
+    localFile(startDir: string, ...segments: string[]): string;
+    /** True when `startDir` sits in a LINKED worktree rather than the primary clone. */
+    isLinkedWorktree(startDir: string): boolean;
+    /**
+     * git's own name for this linked worktree — the basename of `<primary>/.git/worktrees/<name>`, and
+     * the namespace key under `worktrees/`. Empty for the primary clone. git's name rather than the
+     * directory's basename, so two worktrees checked out into same-named directories under different
+     * parents cannot collide.
+     */
+    worktreeName(startDir: string): string;
+    /** The primary clone's root, from any worktree. Falls back to git's toplevel-less best guess. */
+    primaryRoot(startDir: string): string;
+    /**
+     * The PRE-change location, `<treeRoot>/.webpieces` — what every call site used to compute. Public
+     * because the migrator and its specs must be able to name the thing being migrated FROM, and
+     * because the transition-window fallback readers need it.
+     */
+    legacyDir(treeRoot: string): string;
+    private migrateOnce;
+    private gitDirs;
+    private gitToplevel;
+    private revParse;
+}
+export declare const dotWebpieces: DotWebpieces;

package/src/state-dir.js

@@ -0,0 +1,234 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.dotWebpieces = exports.DotWebpieces = exports.GitDirs = exports.WORKTREE_STATE_DIR = 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 inversify_1 = require("inversify");
+const constants_1 = require("./constants");
+const state_dir_migration_1 = require("./state-dir-migration");
+// The per-worktree namespace inside the primary clone's `.webpieces/`. A LINKED worktree's local state
+// lives at `<primary>/.webpieces/worktrees/<worktreeName>/`; the primary clone keeps using
+// `<primary>/.webpieces/` directly, exactly as it always has.
+exports.WORKTREE_STATE_DIR = 'worktrees';
+// git prints the shared git dir as `<primary>/.git` for a conventional clone. Anything else (a bare
+// repo, `--separate-git-dir`) is a layout we decline to derive a working tree from.
+const GIT_DIR_NAME = '.git';
+/**
+ * Data-only carrier for the two paths git is asked for. Per CLAUDE.md: classes for data.
+ *
+ * `gitDir` is the PER-WORKTREE git dir (`<primary>/.git/worktrees/<name>` in a linked worktree,
+ * `<primary>/.git` in the primary clone). `commonDir` is the SHARED one — always `<primary>/.git`.
+ * They differ if and only if this is a linked worktree; that is git's own canonical test.
+ */
+class GitDirs {
+    gitDir;
+    commonDir;
+    constructor(gitDir, commonDir) {
+        this.gitDir = gitDir;
+        this.commonDir = commonDir;
+    }
+    get isLinkedWorktree() {
+        return path.resolve(this.gitDir) !== path.resolve(this.commonDir);
+    }
+}
+exports.GitDirs = GitDirs;
+/**
+ * WHERE a piece of `.webpieces/` state belongs — the ONE resolver every reader and writer must go
+ * through, with TWO named methods because there are exactly two answers and a call site must DECLARE
+ * which one it means.
+ *
+ *   dotWebpieces.shared(dir) → <primary>/.webpieces                       (repo-wide facts)
+ *   dotWebpieces.local(dir)  → <primary>/.webpieces/worktrees/<name>      (this worktree only)
+ *                            → <primary>/.webpieces                       (…in the primary clone)
+ *
+ * ─── The bug ───────────────────────────────────────────────────────────────────────────────────────
+ * `.webpieces/` is gitignored, and it was anchored at the directory holding webpieces.config.json —
+ * which in a linked worktree is the WORKTREE. So a repo with seven worktrees had SEVEN independent
+ * copies of files that describe the WHOLE REPO. `merged-branches.json` holds verdicts for every branch
+ * AND every worktree in the repo; N copies is N divergent truths, and the guards read them as fact.
+ * Observed in the field: branch-creation-guard asserted "8 parked local branches" while
+ * `git branch --list` showed ONE — it was reading a cache written before deletions performed from a
+ * DIFFERENT worktree — and it then blocked a legitimate `git worktree add` on that fiction.
+ *
+ * ─── Why two explicit methods and not a symlink ────────────────────────────────────────────────────
+ * A `<worktree>/.webpieces` → `<primary>/…/worktrees/<name>` symlink would have left every call site
+ * untouched, which is seductive and wrong. Nothing hooks `git worktree add`, so the link needs LAZY
+ * creation that also has to handle "link already exists", "link points somewhere else", and "a real
+ * directory is already there" — invisible filesystem magic with a Windows failure mode. Worse, the safe
+ * way to write a shared file under concurrency is temp-file-then-`rename()`, and `rename(2)` acts on
+ * the PATH, not the link: it REPLACES a symlink with a real file. That silently works for one writer
+ * and diverges for everyone else — the exact bug being fixed, but invisible. An explicit call is
+ * greppable, testable, and forces each site to say which scope it means.
+ *
+ * ─── Which scope is which (the scope assignment is deliberate, not incidental) ─────────────────────
+ * shared():
+ *   • merged-branches.json — verdicts for every branch and worktree in the repo. Atomically written.
+ *   • main-sync-status.json AND main-sync.lock.json — there is one `main` and one `.git`, so there is
+ *     one refresher. A lock inside a per-worktree directory locks nothing.
+ * local():
+ *   • hooks/*.log, INCLUDING branch-mutations.log. A shared append-only log genuinely corrupts:
+ *     `O_APPEND` writes are indivisible only under PIPE_BUF, which is 512 bytes on macOS, and a
+ *     `recover=git worktree add -b <branch> <abs-path> <tag>` line with real paths exceeds that. A
+ *     per-worktree log has exactly ONE writer and cannot tear, and under this layout it already
+ *     survives the worktree's deletion — recovery is one glob over
+ *     `<primary>/.webpieces/worktrees/＊/hooks/branch-mutations.log`.
+ *   • merge-info/staged|merged/<branch>/ and its index.json, pr-review/<branch>/, instruct-ai/, and
+ *     every other per-tree scratch file.
+ *
+ * ─── The boundary that must not be blurred ─────────────────────────────────────────────────────────
+ * ONLY the gitignored `.webpieces/` STATE relocates. `webpieces.config.json` is TRACKED IN GIT and is
+ * therefore part of the BRANCH: a branch may legitimately change its own rules and that must keep
+ * working. Config resolution is untouched — still per-worktree, via findConfigFile /
+ * RepoRootFinder.resolveRepoRoot. Nothing in this class reads or moves config.
+ *
+ * ─── Why `--git-dir` / `--git-common-dir`, and not one of the existing services ────────────────────
+ * They are git's own answers, from any subdirectory, in one cheap local call, with no `.git`-file
+ * parsing by hand (which gets `--separate-git-dir` and submodules wrong). Two existing mechanisms do
+ * distinguish primary from linked, and neither is the right authority here:
+ *   • `WorktreeService` answers "what worktrees exist and what do they hold" — a repo-wide ENUMERATION
+ *     (`git worktree list --porcelain`) for the caps and the reaper. Using it for a path lookup would
+ *     run an enumeration on the hook's blocking path for every state access, and it fails SOFT to `[]`,
+ *     which here would read as "there is no primary clone" on exactly the degraded repo where the
+ *     answer matters most. It also does not expose the worktree's git NAME, which is the namespace key.
+ *   • `EffectiveTreeResolver` (#524) answers "which tree does this COMMAND act on" — it takes a command
+ *     string and is a policy input to the bash guards, not a filesystem-path resolver.
+ * Both remain authoritative for their own questions. This asks the narrowest one — two path strings —
+ * and lives in rules-config, UNDER both, which is where a primitive that pr-gate, ai-hook-rules and
+ * code-rules all need has to sit.
+ *
+ * Fails CLOSED to the pre-change behaviour: when git cannot answer, every path here collapses to
+ * `<startDir-root>/.webpieces` exactly as before. Degrading to merely-suboptimal beats throwing on a
+ * hook's blocking path.
+ */
+let DotWebpieces = class DotWebpieces {
+    migrator;
+    // treeRoot → git's answer. One `git rev-parse` pair per root per process; every later path lookup
+    // in that invocation is a Map hit.
+    gitDirsByRoot = new Map();
+    // Roots whose legacy per-worktree `.webpieces/` has already been considered for migration.
+    migrated = new Set();
+    constructor(migrator = new state_dir_migration_1.StateDirMigrator()) {
+        this.migrator = migrator;
+    }
+    /**
+     * REPO-WIDE state: `<primary>/.webpieces`. Use ONLY for facts about the repo rather than about one
+     * worktree — today that is merged-branches.json and the main-sync status + lock. Identical from
+     * every worktree, and never behind an indirection, so an atomic `rename()` into it is safe.
+     */
+    shared(startDir) {
+        return path.join(this.primaryRoot(startDir), constants_1.WEBPIECES_TMP_DIR);
+    }
+    /** A path beneath the repo-wide state dir. */
+    sharedFile(startDir, ...segments) {
+        return path.join(this.shared(startDir), ...segments);
+    }
+    /**
+     * THIS WORKTREE's private state: `<primary>/.webpieces/worktrees/<name>` for a linked worktree, and
+     * `<primary>/.webpieces` for the primary clone, which keeps its state exactly where it has always
+     * been. Fully isolated — two worktrees never write the same path, so nothing here needs a lock.
+     *
+     * The first call for a linked worktree also MIGRATES a legacy real `<worktree>/.webpieces/`
+     * directory into the namespace, so in-flight merge / pr-review state written under the old scheme
+     * (or by an older PUBLISHED build during the transition) is picked up rather than orphaned.
+     */
+    local(startDir) {
+        const dirs = this.gitDirs(startDir);
+        if (dirs === null || !dirs.isLinkedWorktree)
+            return this.shared(startDir);
+        const target = path.join(this.shared(startDir), exports.WORKTREE_STATE_DIR, path.basename(dirs.gitDir));
+        this.migrateOnce(startDir, target);
+        return target;
+    }
+    /** A path beneath this worktree's private state dir. */
+    localFile(startDir, ...segments) {
+        return path.join(this.local(startDir), ...segments);
+    }
+    /** True when `startDir` sits in a LINKED worktree rather than the primary clone. */
+    isLinkedWorktree(startDir) {
+        const dirs = this.gitDirs(startDir);
+        return dirs !== null && dirs.isLinkedWorktree;
+    }
+    /**
+     * git's own name for this linked worktree — the basename of `<primary>/.git/worktrees/<name>`, and
+     * the namespace key under `worktrees/`. Empty for the primary clone. git's name rather than the
+     * directory's basename, so two worktrees checked out into same-named directories under different
+     * parents cannot collide.
+     */
+    worktreeName(startDir) {
+        const dirs = this.gitDirs(startDir);
+        if (dirs === null || !dirs.isLinkedWorktree)
+            return '';
+        return path.basename(dirs.gitDir);
+    }
+    /** The primary clone's root, from any worktree. Falls back to git's toplevel-less best guess. */
+    primaryRoot(startDir) {
+        const dirs = this.gitDirs(startDir);
+        if (dirs === null)
+            return startDir;
+        if (path.basename(dirs.commonDir) !== GIT_DIR_NAME)
+            return startDir;
+        const primary = path.dirname(dirs.commonDir);
+        return fs.existsSync(primary) ? primary : startDir;
+    }
+    /**
+     * The PRE-change location, `<treeRoot>/.webpieces` — what every call site used to compute. Public
+     * because the migrator and its specs must be able to name the thing being migrated FROM, and
+     * because the transition-window fallback readers need it.
+     */
+    legacyDir(treeRoot) {
+        return path.join(treeRoot, constants_1.WEBPIECES_TMP_DIR);
+    }
+    // Drain a legacy per-worktree `.webpieces/` into this worktree's namespace, at most once per tree
+    // per process. Migration is idempotent, but it touches the filesystem on the hook's blocking path.
+    migrateOnce(startDir, target) {
+        // Guard on the CHEAP key first. `local()` is called many times per invocation, and resolving the
+        // worktree toplevel costs a `git rev-parse` — doing that before the once-check would put a
+        // process spawn on the hook's blocking path for every single state-path lookup.
+        if (this.migrated.has(startDir))
+            return;
+        this.migrated.add(startDir);
+        const toplevel = this.gitToplevel(startDir);
+        if (toplevel === null)
+            return;
+        this.migrator.migrate(this.legacyDir(toplevel), target);
+    }
+    // Both git dirs for `startDir`, cached, or null when this is not a git repo / git is unavailable.
+    // `status !== 0` IS the expected "not a repo" answer (spawnSync does not throw on a non-zero exit),
+    // so there is no try/catch here swallowing a real git crash. Mirrors RepoRootFinder.gitToplevel.
+    gitDirs(startDir) {
+        const cached = this.gitDirsByRoot.get(startDir);
+        if (cached !== undefined)
+            return cached;
+        const gitDir = this.revParse(startDir, '--git-dir');
+        const commonDir = this.revParse(startDir, '--git-common-dir');
+        const dirs = gitDir === null || commonDir === null ? null : new GitDirs(gitDir, commonDir);
+        this.gitDirsByRoot.set(startDir, dirs);
+        return dirs;
+    }
+    gitToplevel(startDir) {
+        return this.revParse(startDir, '--show-toplevel');
+    }
+    // One `git rev-parse <flag>`, resolved to an absolute path (git prints a bare `.git`, relative to
+    // the tree, in the primary clone, and an absolute path from a linked worktree).
+    revParse(cwd, flag) {
+        const result = (0, child_process_1.spawnSync)('git', ['-C', cwd, 'rev-parse', flag], { encoding: 'utf8' });
+        if (result.status !== 0)
+            return null;
+        const printed = (result.stdout ?? '').trim();
+        if (printed === '')
+            return null;
+        return path.resolve(cwd, printed);
+    }
+};
+exports.DotWebpieces = DotWebpieces;
+exports.DotWebpieces = DotWebpieces = tslib_1.__decorate([
+    (0, inversify_1.injectable)(inversify_1.bindingScopeValues.Singleton),
+    tslib_1.__metadata("design:paramtypes", [state_dir_migration_1.StateDirMigrator])
+], DotWebpieces);
+// Process-wide instance for the many non-DI call sites (hooks, detached refreshers, wp-* bins, eslint
+// rules). Sharing one instance is what makes the git-resolution cache and the once-per-tree migration
+// worth having; inversify still injects the singleton wherever a container is in play.
+exports.dotWebpieces = new DotWebpieces();
+//# sourceMappingURL=state-dir.js.map

package/src/state-dir.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"state-dir.js","sourceRoot":"","sources":["../../../../../packages/tooling/rules-config/src/state-dir.ts"],"names":[],"mappings":"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","sourcesContent":["import { spawnSync } from 'child_process';\nimport * as fs from 'fs';\nimport * as path from 'path';\nimport { injectable, bindingScopeValues } from 'inversify';\n\nimport { WEBPIECES_TMP_DIR } from './constants';\nimport { StateDirMigrator } from './state-dir-migration';\n\n// The per-worktree namespace inside the primary clone's `.webpieces/`. A LINKED worktree's local state\n// lives at `<primary>/.webpieces/worktrees/<worktreeName>/`; the primary clone keeps using\n// `<primary>/.webpieces/` directly, exactly as it always has.\nexport const WORKTREE_STATE_DIR = 'worktrees';\n\n// git prints the shared git dir as `<primary>/.git` for a conventional clone. Anything else (a bare\n// repo, `--separate-git-dir`) is a layout we decline to derive a working tree from.\nconst GIT_DIR_NAME = '.git';\n\n/**\n * Data-only carrier for the two paths git is asked for. Per CLAUDE.md: classes for data.\n *\n * `gitDir` is the PER-WORKTREE git dir (`<primary>/.git/worktrees/<name>` in a linked worktree,\n * `<primary>/.git` in the primary clone). `commonDir` is the SHARED one — always `<primary>/.git`.\n * They differ if and only if this is a linked worktree; that is git's own canonical test.\n */\nexport class GitDirs {\n    readonly gitDir: string;\n    readonly commonDir: string;\n\n    constructor(gitDir: string, commonDir: string) {\n        this.gitDir = gitDir;\n        this.commonDir = commonDir;\n    }\n\n    get isLinkedWorktree(): boolean {\n        return path.resolve(this.gitDir) !== path.resolve(this.commonDir);\n    }\n}\n\n/**\n * WHERE a piece of `.webpieces/` state belongs — the ONE resolver every reader and writer must go\n * through, with TWO named methods because there are exactly two answers and a call site must DECLARE\n * which one it means.\n *\n *   dotWebpieces.shared(dir) → <primary>/.webpieces                       (repo-wide facts)\n *   dotWebpieces.local(dir)  → <primary>/.webpieces/worktrees/<name>      (this worktree only)\n *                            → <primary>/.webpieces                       (…in the primary clone)\n *\n * ─── The bug ───────────────────────────────────────────────────────────────────────────────────────\n * `.webpieces/` is gitignored, and it was anchored at the directory holding webpieces.config.json —\n * which in a linked worktree is the WORKTREE. So a repo with seven worktrees had SEVEN independent\n * copies of files that describe the WHOLE REPO. `merged-branches.json` holds verdicts for every branch\n * AND every worktree in the repo; N copies is N divergent truths, and the guards read them as fact.\n * Observed in the field: branch-creation-guard asserted \"8 parked local branches\" while\n * `git branch --list` showed ONE — it was reading a cache written before deletions performed from a\n * DIFFERENT worktree — and it then blocked a legitimate `git worktree add` on that fiction.\n *\n * ─── Why two explicit methods and not a symlink ────────────────────────────────────────────────────\n * A `<worktree>/.webpieces` → `<primary>/…/worktrees/<name>` symlink would have left every call site\n * untouched, which is seductive and wrong. Nothing hooks `git worktree add`, so the link needs LAZY\n * creation that also has to handle \"link already exists\", \"link points somewhere else\", and \"a real\n * directory is already there\" — invisible filesystem magic with a Windows failure mode. Worse, the safe\n * way to write a shared file under concurrency is temp-file-then-`rename()`, and `rename(2)` acts on\n * the PATH, not the link: it REPLACES a symlink with a real file. That silently works for one writer\n * and diverges for everyone else — the exact bug being fixed, but invisible. An explicit call is\n * greppable, testable, and forces each site to say which scope it means.\n *\n * ─── Which scope is which (the scope assignment is deliberate, not incidental) ─────────────────────\n * shared():\n *   • merged-branches.json — verdicts for every branch and worktree in the repo. Atomically written.\n *   • main-sync-status.json AND main-sync.lock.json — there is one `main` and one `.git`, so there is\n *     one refresher. A lock inside a per-worktree directory locks nothing.\n * local():\n *   • hooks/*.log, INCLUDING branch-mutations.log. A shared append-only log genuinely corrupts:\n *     `O_APPEND` writes are indivisible only under PIPE_BUF, which is 512 bytes on macOS, and a\n *     `recover=git worktree add -b <branch> <abs-path> <tag>` line with real paths exceeds that. A\n *     per-worktree log has exactly ONE writer and cannot tear, and under this layout it already\n *     survives the worktree's deletion — recovery is one glob over\n *     `<primary>/.webpieces/worktrees/＊/hooks/branch-mutations.log`.\n *   • merge-info/staged|merged/<branch>/ and its index.json, pr-review/<branch>/, instruct-ai/, and\n *     every other per-tree scratch file.\n *\n * ─── The boundary that must not be blurred ─────────────────────────────────────────────────────────\n * ONLY the gitignored `.webpieces/` STATE relocates. `webpieces.config.json` is TRACKED IN GIT and is\n * therefore part of the BRANCH: a branch may legitimately change its own rules and that must keep\n * working. Config resolution is untouched — still per-worktree, via findConfigFile /\n * RepoRootFinder.resolveRepoRoot. Nothing in this class reads or moves config.\n *\n * ─── Why `--git-dir` / `--git-common-dir`, and not one of the existing services ────────────────────\n * They are git's own answers, from any subdirectory, in one cheap local call, with no `.git`-file\n * parsing by hand (which gets `--separate-git-dir` and submodules wrong). Two existing mechanisms do\n * distinguish primary from linked, and neither is the right authority here:\n *   • `WorktreeService` answers \"what worktrees exist and what do they hold\" — a repo-wide ENUMERATION\n *     (`git worktree list --porcelain`) for the caps and the reaper. Using it for a path lookup would\n *     run an enumeration on the hook's blocking path for every state access, and it fails SOFT to `[]`,\n *     which here would read as \"there is no primary clone\" on exactly the degraded repo where the\n *     answer matters most. It also does not expose the worktree's git NAME, which is the namespace key.\n *   • `EffectiveTreeResolver` (#524) answers \"which tree does this COMMAND act on\" — it takes a command\n *     string and is a policy input to the bash guards, not a filesystem-path resolver.\n * Both remain authoritative for their own questions. This asks the narrowest one — two path strings —\n * and lives in rules-config, UNDER both, which is where a primitive that pr-gate, ai-hook-rules and\n * code-rules all need has to sit.\n *\n * Fails CLOSED to the pre-change behaviour: when git cannot answer, every path here collapses to\n * `<startDir-root>/.webpieces` exactly as before. Degrading to merely-suboptimal beats throwing on a\n * hook's blocking path.\n */\n@injectable(bindingScopeValues.Singleton)\nexport class DotWebpieces {\n    // treeRoot → git's answer. One `git rev-parse` pair per root per process; every later path lookup\n    // in that invocation is a Map hit.\n    private readonly gitDirsByRoot = new Map<string, GitDirs | null>();\n    // Roots whose legacy per-worktree `.webpieces/` has already been considered for migration.\n    private readonly migrated = new Set<string>();\n\n    constructor(private readonly migrator: StateDirMigrator = new StateDirMigrator()) {}\n\n    /**\n     * REPO-WIDE state: `<primary>/.webpieces`. Use ONLY for facts about the repo rather than about one\n     * worktree — today that is merged-branches.json and the main-sync status + lock. Identical from\n     * every worktree, and never behind an indirection, so an atomic `rename()` into it is safe.\n     */\n    shared(startDir: string): string {\n        return path.join(this.primaryRoot(startDir), WEBPIECES_TMP_DIR);\n    }\n\n    /** A path beneath the repo-wide state dir. */\n    sharedFile(startDir: string, ...segments: string[]): string {\n        return path.join(this.shared(startDir), ...segments);\n    }\n\n    /**\n     * THIS WORKTREE's private state: `<primary>/.webpieces/worktrees/<name>` for a linked worktree, and\n     * `<primary>/.webpieces` for the primary clone, which keeps its state exactly where it has always\n     * been. Fully isolated — two worktrees never write the same path, so nothing here needs a lock.\n     *\n     * The first call for a linked worktree also MIGRATES a legacy real `<worktree>/.webpieces/`\n     * directory into the namespace, so in-flight merge / pr-review state written under the old scheme\n     * (or by an older PUBLISHED build during the transition) is picked up rather than orphaned.\n     */\n    local(startDir: string): string {\n        const dirs = this.gitDirs(startDir);\n        if (dirs === null || !dirs.isLinkedWorktree) return this.shared(startDir);\n\n        const target = path.join(this.shared(startDir), WORKTREE_STATE_DIR, path.basename(dirs.gitDir));\n        this.migrateOnce(startDir, target);\n        return target;\n    }\n\n    /** A path beneath this worktree's private state dir. */\n    localFile(startDir: string, ...segments: string[]): string {\n        return path.join(this.local(startDir), ...segments);\n    }\n\n    /** True when `startDir` sits in a LINKED worktree rather than the primary clone. */\n    isLinkedWorktree(startDir: string): boolean {\n        const dirs = this.gitDirs(startDir);\n        return dirs !== null && dirs.isLinkedWorktree;\n    }\n\n    /**\n     * git's own name for this linked worktree — the basename of `<primary>/.git/worktrees/<name>`, and\n     * the namespace key under `worktrees/`. Empty for the primary clone. git's name rather than the\n     * directory's basename, so two worktrees checked out into same-named directories under different\n     * parents cannot collide.\n     */\n    worktreeName(startDir: string): string {\n        const dirs = this.gitDirs(startDir);\n        if (dirs === null || !dirs.isLinkedWorktree) return '';\n        return path.basename(dirs.gitDir);\n    }\n\n    /** The primary clone's root, from any worktree. Falls back to git's toplevel-less best guess. */\n    primaryRoot(startDir: string): string {\n        const dirs = this.gitDirs(startDir);\n        if (dirs === null) return startDir;\n        if (path.basename(dirs.commonDir) !== GIT_DIR_NAME) return startDir;\n        const primary = path.dirname(dirs.commonDir);\n        return fs.existsSync(primary) ? primary : startDir;\n    }\n\n    /**\n     * The PRE-change location, `<treeRoot>/.webpieces` — what every call site used to compute. Public\n     * because the migrator and its specs must be able to name the thing being migrated FROM, and\n     * because the transition-window fallback readers need it.\n     */\n    legacyDir(treeRoot: string): string {\n        return path.join(treeRoot, WEBPIECES_TMP_DIR);\n    }\n\n    // Drain a legacy per-worktree `.webpieces/` into this worktree's namespace, at most once per tree\n    // per process. Migration is idempotent, but it touches the filesystem on the hook's blocking path.\n    private migrateOnce(startDir: string, target: string): void {\n        // Guard on the CHEAP key first. `local()` is called many times per invocation, and resolving the\n        // worktree toplevel costs a `git rev-parse` — doing that before the once-check would put a\n        // process spawn on the hook's blocking path for every single state-path lookup.\n        if (this.migrated.has(startDir)) return;\n        this.migrated.add(startDir);\n        const toplevel = this.gitToplevel(startDir);\n        if (toplevel === null) return;\n        this.migrator.migrate(this.legacyDir(toplevel), target);\n    }\n\n    // Both git dirs for `startDir`, cached, or null when this is not a git repo / git is unavailable.\n    // `status !== 0` IS the expected \"not a repo\" answer (spawnSync does not throw on a non-zero exit),\n    // so there is no try/catch here swallowing a real git crash. Mirrors RepoRootFinder.gitToplevel.\n    private gitDirs(startDir: string): GitDirs | null {\n        const cached = this.gitDirsByRoot.get(startDir);\n        if (cached !== undefined) return cached;\n\n        const gitDir = this.revParse(startDir, '--git-dir');\n        const commonDir = this.revParse(startDir, '--git-common-dir');\n        const dirs = gitDir === null || commonDir === null ? null : new GitDirs(gitDir, commonDir);\n        this.gitDirsByRoot.set(startDir, dirs);\n        return dirs;\n    }\n\n    private gitToplevel(startDir: string): string | null {\n        return this.revParse(startDir, '--show-toplevel');\n    }\n\n    // One `git rev-parse <flag>`, resolved to an absolute path (git prints a bare `.git`, relative to\n    // the tree, in the primary clone, and an absolute path from a linked worktree).\n    private revParse(cwd: string, flag: string): string | null {\n        const result = spawnSync('git', ['-C', cwd, 'rev-parse', flag], { encoding: 'utf8' });\n        if (result.status !== 0) return null;\n        const printed = (result.stdout ?? '').trim();\n        if (printed === '') return null;\n        return path.resolve(cwd, printed);\n    }\n}\n\n// Process-wide instance for the many non-DI call sites (hooks, detached refreshers, wp-* bins, eslint\n// rules). Sharing one instance is what makes the git-resolution cache and the once-per-tree migration\n// worth having; inversify still injects the singleton wherever a container is in play.\nexport const dotWebpieces = new DotWebpieces();\n"]}

package/templates/webpieces.git-workflow.md

@@ -51,10 +51,54 @@ squash commit. If a command tells you the tree is dirty, commit or delete the li
 - **B = feature HEAD**: your branch tip
 - **C = main HEAD**: `origin/main`
 
-Never `git merge` or `git rebase` main into your branch directly — it breaks the fork point (A) that
-produces clean PR diffs. Sync only via the gated 3-point squash-update — `pnpm wp-start-update` when no
-PR is open, `pnpm wp-start-upsert-pr` when one is (see "Which flow?" below). This is enforced by the
-`redirect-how-to-merge-main` guard.
+### THE FORK POINT INVARIANT (read this once, it explains every rule below)
+
+> The fork point must be a **pure `main` commit containing none of your work**, AND your branch must
+> contain **none of main's commits after it**. Only then is `diff(fork point → HEAD)` *exactly* your
+> changes — no more and no less.
+
+The invariant is symmetric, and both halves matter. Pollute the fork point with your own work and the
+diff *understates* what you did; pull main's commits onto your branch and the diff *overstates* it with
+work other people already landed. Either way the answer to "what did this branch change?" stops being
+computable, and three separate consumers are asking exactly that question:
+
+1. **The 3-point merge.** `A` is the base, `B` is what *you* intended, `C` is what *main* intended, and
+   the whole method is reading `B−A` against `C−A` to see the two intentions side by side. If `A`
+   already contains your work, `B−A` no longer shows what you changed; if `B` already contains main's
+   commits, `C−A` is being compared against a branch that partly *is* main. The diffs stop describing
+   intentions and conflict resolution degrades into guessing which side a hunk came from.
+2. **`nx affected` — the build gate's scope.** The gate's `--base` is the fork point, not
+   `origin/main`, and the config states why verbatim:
+   > `--base is the FORK POINT via $(git merge-base origin/main HEAD), NOT origin/main: basing on origin/main marks projects from other people's already-merged PRs as 'affected' (your branch still has their pre-merge versions), wasting rebuilds. The fork point scopes affected to only your branch's work.`
+3. **The review diff.** `wp-review-upsert-pr` extracts this branch's diff for the reviewer subagents
+   from the same two endpoints. A polluted fork point hands reviewers changes nobody on this branch
+   made, and they will dutifully review them.
+
+**Why an ordinary `git merge main` breaks it:** it violates *both* halves in one command. Your branch
+now carries main's commits (so the diff shows work you did not do) and the base is no longer a clean
+main state. That is why the `redirect-how-to-merge-main` guard blocks `git merge` and `git rebase` in
+every form — the block is not stylistic, and there is nothing to work around.
+
+**Why the gated flow squash-rewrites and force-pushes:** it restores the invariant *by construction*.
+After a sync your branch is `current main + one commit that is precisely your work`, so the fork point
+is a real, unmodified main commit by definition. The rewrite **is** the mechanism, not a side effect of
+one — which is why the flow cannot politely skip it.
+
+**Why squash rather than rebase:** a rebase would restore the same invariant, but it preserves N
+commits and makes you resolve the same conflict once per commit. Squash gives you one resolution and
+one commit. And since this repo squash-merges PRs anyway, those individual commits were never going to
+survive into main's history — the `<feature>PreMerge<n>` snapshot branches exist precisely to preserve
+the original pre-squash history for debugging, which is their entire purpose.
+
+**Consequence — never sync a branch you do not own.** Because the flow rewrites history and
+force-pushes, **never run `pnpm wp-start-upsert-pr` (or `pnpm wp-start-update`) against a branch that
+another process, session, or agent owns.** This is not caution or etiquette, it is a correctness
+requirement: that other process's fork point and its `PreMerge<n>` snapshot trail would be replaced
+underneath it mid-flight, and the work it was holding becomes unrecoverable-by-construction. If you
+find yourself looking at an open PR on a branch this session did not create, leave it alone.
+
+Sync only via the gated 3-point squash-update — `pnpm wp-start-update` when no PR is open,
+`pnpm wp-start-upsert-pr` when one is (see "Which flow?" below).
 
 **AI never runs `git merge` or `git rebase` — at all.** The guard blocks both outright: on any branch,
 against any target, in any form (including `--squash` and `--ff-only`), and in any compound command