@monte3l/groundwork 0.1.0-next.1 → 1.0.0-rc.3

package/templates/packs/supply-chain/files/.github/workflows/gitleaks.yml

@@ -0,0 +1,52 @@
+name: Gitleaks
+
+# What this does: scans for secrets (API keys, tokens, private keys) using
+# gitleaks/gitleaks-action. On a push to the release branch it scans only
+# the pushed commits; on a pull request it scans the PR's commits; the
+# weekly schedule and manual dispatch scan the full history. Not a required
+# check by default -- see this pack's adoptNotes.
+#
+# gitleaks-action v3 needs a free GITLEAKS_LICENSE for an organization-owned
+# repository (gitleaks/gitleaks-action's own README) -- if this repository
+# accepts pull requests from forks, that secret is unavailable on a
+# fork-originated run and this job fails cleanly rather than scanning; a
+# collaborators-only PR policy avoids that case entirely.
+on:
+  push:
+    branches: [main]
+  pull_request:
+    branches: [main]
+  schedule:
+    - cron: "0 5 * * 1" # every Monday, full-history scan
+  workflow_dispatch:
+
+permissions: {}
+
+concurrency:
+  group: ${{ github.workflow }}-${{ github.ref }}
+  cancel-in-progress: true
+
+jobs:
+  scan:
+    name: Gitleaks
+    runs-on: ubuntu-latest
+    timeout-minutes: 10
+    permissions:
+      contents: read
+      pull-requests: read
+    steps:
+      - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7
+        with:
+          persist-credentials: false
+          fetch-depth: 0 # gitleaks needs full history to compute the commit range it scans
+
+      - uses: gitleaks/gitleaks-action@e0c47f4f8be36e29cdc102c57e68cb5cbf0e8d1e # v3.0.0
+        env:
+          GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
+          GITLEAKS_LICENSE: ${{ secrets.GITLEAKS_LICENSE }}
+          # Pinned above the action's own stale built-in default; Dependabot
+          # doesn't track this, so bump it by hand periodically.
+          GITLEAKS_VERSION: "8.30.1"
+          GITLEAKS_CONFIG: .gitleaks.toml
+          # Avoids needing pull-requests: write for a PR comment.
+          GITLEAKS_ENABLE_COMMENTS: "false"

package/templates/packs/supply-chain/files/.github/workflows/scorecard.yml

@@ -0,0 +1,48 @@
+name: Scorecard
+
+# What this does: runs OpenSSF Scorecard, a tool that scores a repository's
+# supply-chain security practices (branch protection, pinned dependencies,
+# signed releases, and similar checks) and can publish a badge from the
+# result. It runs weekly, on every push to the release branch, and on
+# manual dispatch -- not on every PR, since supply-chain posture doesn't
+# change per-commit the way tests do. Read-only: this workflow only
+# inspects the repo and uploads a report, it never writes to it.
+on:
+  push:
+    branches: [main]
+  schedule:
+    - cron: "30 4 * * 1" # every Monday
+  workflow_dispatch:
+
+permissions: read-all
+
+concurrency:
+  group: ${{ github.workflow }}-${{ github.ref }}
+  cancel-in-progress: true
+
+jobs:
+  analysis:
+    name: Scorecard analysis
+    runs-on: ubuntu-latest
+    timeout-minutes: 20
+    permissions:
+      # Required by ossf/scorecard-action's own documented minimum.
+      security-events: write # to upload SARIF results
+      id-token: write # to publish results and get a badge (publish_results: true)
+    steps:
+      - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7
+        with:
+          persist-credentials: false
+
+      - uses: ossf/scorecard-action@2d1146689b8cda280b9bc96326124645441f03bc # v2.4.4
+        with:
+          results_file: results.sarif
+          results_format: sarif
+          # `publish_results: true` is what makes a README badge resolve,
+          # and needs the repository to actually be public -- see this
+          # pack's adoptNotes. Set this `false` for a private repository.
+          publish_results: true
+
+      - uses: github/codeql-action/upload-sarif@2892aa5e19bbd11bc0cff5427e3b750a04d9e3c2 # v4
+        with:
+          sarif_file: results.sarif

package/templates/packs/supply-chain/files/.gitleaks.toml

@@ -0,0 +1,2 @@
+[extend]
+useDefault = true

package/templates/packs/supply-chain/pack.json

@@ -0,0 +1,19 @@
+{
+  "schemaVersion": 1,
+  "name": "supply-chain",
+  "description": "Secret scanning and an OpenSSF Scorecard run for any project hosted on GitHub, published or not: gitleaks.yml (gitleaks/gitleaks-action on push, pull request, weekly and manual dispatch) with a .gitleaks.toml, and scorecard.yml (ossf/scorecard-action, weekly, results published as code-scanning alerts). Pure file drop: no hooks, no settings, no scripts, no verify step. Read-only workflows, not required checks by default.",
+  "modes": ["fresh", "adopt"],
+  "budget": {
+    "agents": 0,
+    "skills": 0,
+    "hooks": 0,
+    "workflows": 2,
+    "scripts": 0
+  },
+  "wiring": {
+    "settings": {},
+    "packageScripts": {},
+    "verifySteps": []
+  },
+  "adoptNotes": "An adopted project that already has its own .github/workflows/gitleaks.yml or scorecard.yml surfaces as an ordinary file conflict -- keep the existing one if it already works, since this pack's version would just replace a configured setup with its generic defaults. gitleaks.yml needs a free GITLEAKS_LICENSE repo secret for an organization-owned repository (gitleaks-action's own requirement); scorecard.yml assumes a public repository (`publish_results: true` needs one) -- set it `false` for a private repo. Both are read-only and not required checks by default; add either to branch protection once it has a clean run. The SPDX/REUSE license-header gate is not part of this pack: it lives in the fresh-only `publishing` pack, because it fails an established project's `pnpm verify` until a one-time backfill touches every file. The two workflows ship without an SPDX header on purpose (a header would carry a project-name token that stays literal in an adopt-mode install); a project that also installs `publishing` gets the headers from that pack's `check-license-headers.mjs --fix` backfill."
+}

package/templates/packs/worktrees/files/.claude/hooks/ensure-worktree-deps.mjs

@@ -0,0 +1,283 @@
+#!/usr/bin/env node
+/**
+ * SessionStart (startup|resume): installs dependencies into a freshly
+ * created git worktree automatically, so the first edit made there doesn't
+ * hit `post-edit-verify.mjs`'s own "no node_modules" exit-2 guard.
+ *
+ * This is a BACKSTOP, not the primary install path. It only fires on
+ * `claude --worktree`/a resumed session already inside a worktree --
+ * `SessionStart` does not fire on a mid-session `EnterWorktree`
+ * (code.claude.com/docs/en/worktrees: "SessionStart ... does not fire on a
+ * mid-session EnterWorktree"), which is the more common way a worktree gets
+ * created in this project (the `working-in-worktrees` skill's start mode
+ * runs `pnpm install` itself for exactly that reason). Both paths converge
+ * on the same guarantee: by the time any edit happens, dependencies exist.
+ *
+ * Does nothing unless ALL of these hold:
+ *   - `cwd` is a LINKED worktree (its `--git-dir` differs from its
+ *     `--git-common-dir` -- a plain checkout's are identical).
+ *   - `node_modules` is not a symlink (if the project sets
+ *     `worktree.symlinkDirectories: ["node_modules"]`, installing here
+ *     would write through the symlink into the MAIN checkout's own
+ *     node_modules, which is not this hook's job to do).
+ *   - A lockfile is present (nothing to install against otherwise).
+ *   - `node_modules/.modules.yaml` (pnpm's own install marker) is missing.
+ *
+ * Always exits 0 -- this is advisory infrastructure, never a gate. A git
+ * failure that isn't "not a git repository" still gets a stderr hint rather
+ * than silent failure -- see `defaultGitFor`.
+ */
+import process from "node:process";
+import path from "node:path";
+import {
+  existsSync,
+  lstatSync,
+  openSync,
+  closeSync,
+  rmSync,
+  realpathSync,
+} from "node:fs";
+import { execFileSync, spawnSync } from "node:child_process";
+import { fileURLToPath } from "node:url";
+import { canonicalize } from "../../bin/lib/protected-paths.mjs";
+
+/**
+ * Same pattern as `guard-worktree-only.mjs`'s `defaultGitFor`, but this
+ * hook is advisory (a SessionStart backstop), not an enforcement guard, so
+ * an unexpected git failure stays fail-OPEN -- it just gets a stderr hint
+ * instead of silently doing nothing, the same posture `post-edit-verify.mjs`
+ * takes for the identical reason.
+ */
+export function defaultGitFor(dir) {
+  return function git(args) {
+    try {
+      return execFileSync("git", ["-C", dir, ...args], {
+        encoding: "utf8",
+        stdio: ["ignore", "pipe", "pipe"],
+        env: { ...process.env, LC_ALL: "C", LANGUAGE: "C" },
+      }).trim();
+    } catch (cause) {
+      const message = String(cause?.stderr || cause?.message || "").trim();
+      if (!/not a git repository \(or any /i.test(message)) {
+        process.stderr.write(
+          `ensure-worktree-deps: git lookup failed in \`${dir}\` (${message.split("\n")[0]}); ` +
+            "skipping the dependency-install check.\n",
+        );
+      }
+      return "";
+    }
+  };
+}
+
+/** See `guard-worktree-only.mjs`'s identical helper for why this matters. */
+function gitAbsPath(git, boundDir, args) {
+  const raw = git(args);
+  if (raw === "") return "";
+  return canonicalize(path.resolve(boundDir, raw));
+}
+
+/**
+ * Resolves `root`'s own `--git-dir` ONCE, used both to decide whether it's
+ * a linked worktree and as the lock file's parent directory (unique per
+ * worktree, since a linked worktree's `.git` is a file pointing at
+ * `<mainRepoRoot>/.git/worktrees/<name>`).
+ *
+ * @param {string} root
+ * @param {(dir: string) => (args: string[]) => string} [gitFactory]
+ * @returns {{ gitDir: string; isLinked: boolean }}
+ */
+function resolveWorktreeGitDir(root, gitFactory) {
+  const git = gitFactory(root);
+  const gitDir = gitAbsPath(git, root, ["rev-parse", "--git-dir"]);
+  if (gitDir === "") return { gitDir: "", isLinked: false };
+  const commonDir = gitAbsPath(git, root, ["rev-parse", "--git-common-dir"]);
+  return { gitDir, isLinked: gitDir !== commonDir };
+}
+
+/**
+ * True when `dir` is the root of a LINKED git worktree (not the main
+ * checkout, and not a plain non-git directory).
+ *
+ * @param {string} dir
+ * @param {(dir: string) => (args: string[]) => string} [gitFactory]
+ * @returns {boolean}
+ */
+export function isLinkedWorktree(dir, gitFactory = defaultGitFor) {
+  return resolveWorktreeGitDir(dir, gitFactory).isLinked;
+}
+
+/**
+ * `.git` for a linked worktree is a FILE, not a directory -- `git rev-parse
+ * --git-dir` resolves it to the real, unique-per-worktree directory
+ * `<mainRepoRoot>/.git/worktrees/<name>`, a safe, collision-free lock
+ * location. Returns "" when git can't resolve one at all (not a repo, or an
+ * unexpected failure `defaultGitFor` already reported).
+ *
+ * @param {string} root
+ * @param {(dir: string) => (args: string[]) => string} [gitFactory]
+ * @returns {string}
+ */
+export function gitDirFor(root, gitFactory = defaultGitFor) {
+  return resolveWorktreeGitDir(root, gitFactory).gitDir;
+}
+
+/**
+ * True when dependencies should be installed in `root`: no existing pnpm
+ * install marker, a lockfile is present, and `node_modules` (if it exists
+ * at all) is a real directory, not a symlink. Checks `lstatSync` directly
+ * rather than `existsSync` + `lstatSync` -- `existsSync` follows a symlink
+ * and reports `false` for a DANGLING one, which would skip the very check
+ * meant to catch it and let the install proceed through the broken link.
+ *
+ * @param {string} root
+ * @returns {boolean}
+ */
+export function needsInstall(root) {
+  const nodeModules = path.join(root, "node_modules");
+  const stat = lstatSync(nodeModules, { throwIfNoEntry: false });
+  if (stat !== undefined && stat.isSymbolicLink()) return false;
+  const marker = path.join(nodeModules, ".modules.yaml");
+  if (existsSync(marker)) return false;
+  return existsSync(path.join(root, "pnpm-lock.yaml"));
+}
+
+/**
+ * Runs `pnpm install --frozen-lockfile --prefer-offline` in `root`,
+ * serialized against a concurrent SessionStart/subagent hitting the same
+ * worktree via a lock file opened with the `wx` flag (fails if it already
+ * exists -- "create exclusively", no separate lock library required). The
+ * lock is ALWAYS removed once the attempt finishes, success or failure: the
+ * only thing it protects against is two installs running at the exact same
+ * moment, not a retry across time, and a lock left behind after a failed
+ * install would report "another session is installing" forever afterward
+ * with no way to clear it short of a manual `rm`.
+ *
+ * @param {string} root
+ * @returns {{ installed: boolean; message: string }}
+ */
+export function installIfNeeded(root) {
+  if (!needsInstall(root)) {
+    return { installed: false, message: "" };
+  }
+
+  const gitDir = gitDirFor(root);
+  if (gitDir === "") {
+    return {
+      installed: false,
+      message:
+        "ensure-worktree-deps: could not resolve this worktree's git " +
+        "directory -- run `pnpm install` here by hand.",
+    };
+  }
+
+  const lockPath = path.join(gitDir, "worktree-deps.lock");
+  let fd;
+  try {
+    fd = openSync(lockPath, "wx");
+  } catch (cause) {
+    if (cause?.code === "EEXIST") {
+      return {
+        installed: false,
+        message:
+          `ensure-worktree-deps: lock \`${lockPath}\` exists -- another ` +
+          "session is already installing here, or a previous attempt was " +
+          "interrupted before it could clean up (remove the lock and run " +
+          "`pnpm install` by hand if so).",
+      };
+    }
+    return {
+      installed: false,
+      message:
+        `ensure-worktree-deps: could not create the install lock at ` +
+        `\`${lockPath}\` (${cause?.code ?? cause?.message}).`,
+    };
+  }
+
+  try {
+    const res = spawnSync(
+      "pnpm",
+      ["install", "--frozen-lockfile", "--prefer-offline"],
+      {
+        cwd: root,
+        encoding: "utf8",
+        // A chatty install's combined output can exceed the default 1 MiB
+        // buffer, which would otherwise report an unrelated ENOBUFS failure
+        // instead of the real one.
+        maxBuffer: 64 * 1024 * 1024,
+      },
+    );
+    if (res.error) {
+      return {
+        installed: false,
+        message: `ensure-worktree-deps: could not run pnpm install (${res.error.message}).`,
+      };
+    }
+    if (res.status !== 0) {
+      const cause =
+        res.status === null
+          ? `killed by ${res.signal}`
+          : `exit code ${res.status}`;
+      // Both streams, not just one -- pnpm's real failure can land on
+      // either, and a chatty install's combined output is capped so a
+      // large log doesn't blow past whatever a hook's context budget is.
+      const combined = [res.stdout, res.stderr]
+        .filter((s) => typeof s === "string" && s.length > 0)
+        .join("\n")
+        .trim()
+        .slice(-4000);
+      return {
+        installed: false,
+        message:
+          `ensure-worktree-deps: \`pnpm install\` failed in this worktree ` +
+          `(${cause}) -- run it by hand:\n${combined}`,
+      };
+    }
+    return {
+      installed: true,
+      message: "ensure-worktree-deps: installed dependencies in this worktree.",
+    };
+  } finally {
+    closeSync(fd);
+    rmSync(lockPath, { force: true });
+  }
+}
+
+function isEntryPoint() {
+  try {
+    return realpathSync(process.argv[1]) === fileURLToPath(import.meta.url);
+  } catch {
+    return false;
+  }
+}
+
+if (isEntryPoint()) {
+  const chunks = [];
+  for await (const chunk of process.stdin) chunks.push(chunk);
+  let input;
+  try {
+    input = JSON.parse(Buffer.concat(chunks).toString("utf8"));
+  } catch {
+    process.exit(0);
+  }
+
+  const root = typeof input?.cwd === "string" ? input.cwd : "";
+  if (root === "" || !isLinkedWorktree(root)) process.exit(0);
+
+  const { installed, message } = installIfNeeded(root);
+  if (message === "") process.exit(0);
+
+  const reminder =
+    "Reminder: this project requires all src/tests development inside a " +
+    "worktree -- run the TDD pipeline sequentially in this same worktree " +
+    "(no per-spoke isolation), and never `git stash` here (the stash stack " +
+    "is shared across every worktree of this repository).";
+
+  const output = {
+    hookSpecificOutput: {
+      hookEventName: "SessionStart",
+      additionalContext: installed ? `${message}\n\n${reminder}` : message,
+    },
+  };
+  process.stdout.write(JSON.stringify(output));
+  process.exit(0);
+}

package/templates/packs/worktrees/files/.claude/hooks/guard-worktree-only.mjs

@@ -0,0 +1,245 @@
+#!/usr/bin/env node
+/**
+ * PreToolUse guard (Write|Edit): blocks a src/tests write outside a linked
+ * git worktree under `.claude/worktrees/` -- for ANY caller (hub or writer
+ * spoke), on ANY branch. This is stricter than the two guards it sits
+ * alongside:
+ *
+ *   - `guard-branch-isolation.mjs` only blocks while `HEAD` is `main`.
+ *   - `guard-hub-src-writes.mjs` only blocks the hub; a writer spoke passes.
+ *
+ * Installing this pack means every src/tests write -- feature branch or
+ * `main`, hub or spoke -- must happen inside a worktree this project
+ * creates under `.claude/worktrees/`. A sibling worktree made with a plain
+ * `git worktree add ../foo` is deliberately NOT enough: it also closes the
+ * gap `bin/lib/protected-paths.mjs`'s own doc comment names -- `isProtectedPath`
+ * only ever compares one absolute path's PREFIX against `projectDir`, so a
+ * checkout that lives entirely outside `projectDir` can never be recognised
+ * as protected by that function alone, no matter where it sits.
+ *
+ * Detection: a linked worktree's `git rev-parse --git-dir` differs from its
+ * `git rev-parse --git-common-dir` (a plain checkout's are identical). The
+ * worktree only counts as sanctioned when its own toplevel sits under
+ * `<mainRepoRoot>/.claude/worktrees/` -- `mainRepoRoot` being the parent of
+ * `--git-common-dir` (a linked worktree's common dir is always
+ * `<mainRepoRoot>/.git`).
+ *
+ * `isProtectedPath` is ALWAYS scoped to `toplevel` (the checkout that
+ * actually contains the file -- a worktree's own root, not the main repo's
+ * root), never called bare -- an unscoped call treats any absolute path
+ * with a literal `/src/` or `/tests/` segment as protected, which would
+ * wrongly block every write in a completely unrelated repository cloned
+ * at, say, `~/src/other-project`. `guard-branch-isolation.mjs` avoids this
+ * the same way (its own header comment names the same hazard). Scoping to
+ * `mainRepoRoot` instead of `toplevel` was tried and is WRONG: a sibling
+ * worktree's own root is not a path-prefix of `mainRepoRoot` at all, so
+ * that scoping silently reopens the sibling-worktree gap this guard exists
+ * to close -- see `shouldBlock`'s own comment for the reasoning.
+ *
+ * A git lookup failure for a reason OTHER than "not a git repository" (git
+ * missing, EACCES, a corrupt worktree pointer) is NOT treated as "allow" --
+ * unlike an advisory hook (`post-edit-verify.mjs`, which stays informative
+ * on a git failure since it's a nudge, not a gate), this is an ENFORCEMENT
+ * guard, so an ambiguous git state fails CLOSED (blocks, with a diagnostic)
+ * rather than silently turning enforcement off.
+ *
+ * Blocks by exiting 2 with a self-contained message -- hooks run in
+ * parallel with no defined order, so this message can't assume any other
+ * guard's message was seen first.
+ */
+import process from "node:process";
+import { existsSync, realpathSync } from "node:fs";
+import { execFileSync } from "node:child_process";
+import { dirname, isAbsolute, relative, resolve, sep } from "node:path";
+import { fileURLToPath } from "node:url";
+import {
+  canonicalize,
+  isProtectedPath,
+} from "../../bin/lib/protected-paths.mjs";
+
+/** Thrown by the git runner for any failure that ISN'T "not a git repository". */
+export class GitLookupError extends Error {}
+
+/**
+ * Returns a git runner bound to `git -C dir`. Distinguishes the expected,
+ * silent case (`dir` genuinely isn't in a git repository -- returns `""`)
+ * from every other failure (git missing, EACCES, a `dubious ownership`
+ * refusal, a corrupt worktree pointer, which prints a DIFFERENT "not a git
+ * repository: <path>" form with no "(or any ...)" suffix): those THROW
+ * `GitLookupError` rather than returning `""`, so the caller can fail
+ * closed instead of silently allowing.
+ *
+ * @param {string} dir Absolute directory path.
+ * @returns {(args: string[]) => string}
+ */
+export function defaultGitFor(dir) {
+  return function git(args) {
+    try {
+      return execFileSync("git", ["-C", dir, ...args], {
+        encoding: "utf8",
+        // Don't let git's own stderr leak to this process's stderr.
+        // `LC_ALL`/`LANGUAGE` pin git's message to English so the pattern
+        // match below doesn't depend on the caller's locale.
+        stdio: ["ignore", "pipe", "pipe"],
+        env: { ...process.env, LC_ALL: "C", LANGUAGE: "C" },
+      }).trim();
+    } catch (cause) {
+      const message = String(cause?.stderr || cause?.message || "").trim();
+      if (/not a git repository \(or any /i.test(message)) return "";
+      throw new GitLookupError(message.split("\n")[0], { cause });
+    }
+  };
+}
+
+/**
+ * `git rev-parse --git-dir`/`--git-common-dir` return a path RELATIVE TO
+ * THE `-C` DIRECTORY whenever that directory is inside the working tree --
+ * only `--show-toplevel` is documented to always return absolute. Resolved
+ * against `boundDir`, then canonicalized (symlinks resolved) so a `boundDir`
+ * reached through a symlink (macOS's `/tmp` -> `/private/tmp`) doesn't make
+ * an already-absolute, already-canonical git output compare unequal to a
+ * resolved-but-not-canonicalized one -- exactly the class of bug this
+ * pack's own `post-edit-verify.mjs`-adjacent fix (PR1) closed for the same
+ * reason.
+ *
+ * @param {(args: string[]) => string} git
+ * @param {string} boundDir
+ * @param {string[]} args
+ * @returns {string} Canonicalized absolute path, or "" if the command
+ *   returned "" (the expected not-a-repo case; a real failure THROWS
+ *   instead, see `defaultGitFor`).
+ */
+function gitAbsPath(git, boundDir, args) {
+  const raw = git(args);
+  if (raw === "") return "";
+  return canonicalize(resolve(boundDir, raw));
+}
+
+/**
+ * Pure decision function -- exported for unit testing. Can throw
+ * `GitLookupError` (propagated from `git`) when git itself fails
+ * unexpectedly; the caller decides what that means (see `isEntryPoint`
+ * body below: fail closed).
+ *
+ * @param {string} filePath The file_path from the tool_input payload.
+ * @param {(args: string[]) => string} git A git runner bound to `boundDir`
+ *   (see `defaultGitFor`).
+ * @param {string} boundDir The same directory `git` was bound to -- the
+ *   nearest existing ancestor of `filePath`.
+ * @returns {boolean} true = block, false = allow.
+ */
+export function shouldBlock(filePath, git, boundDir) {
+  const gitDir = gitAbsPath(git, boundDir, ["rev-parse", "--git-dir"]);
+  if (gitDir === "") return false; // not in a git repo; nothing to enforce
+
+  const commonDir = gitAbsPath(git, boundDir, [
+    "rev-parse",
+    "--git-common-dir",
+  ]);
+  const isLinkedWorktree = gitDir !== commonDir;
+  // The checkout that actually CONTAINS `filePath` -- the worktree's own
+  // root for a linked worktree, the same as `mainRepoRoot` below otherwise.
+  const toplevel = canonicalize(git(["rev-parse", "--show-toplevel"])); // always absolute
+
+  // Scoped to the file's OWN checkout root (`toplevel`), never called bare
+  // and never scoped to `mainRepoRoot` (the ORIGINAL main checkout's root,
+  // computed below) -- both matter for different reasons. An unscoped
+  // isProtectedPath(filePath) would treat ANY absolute path containing a
+  // literal "/src/" or "/tests/" segment as protected, including a
+  // completely unrelated repository the session happens to touch. Scoping
+  // to `mainRepoRoot` INSTEAD of `toplevel` would be equally wrong the
+  // other way: a sibling worktree's own root is not a path-prefix of
+  // `mainRepoRoot` at all (it typically lives in a sibling directory), so
+  // that scoping would wrongly report its real src/ files as "not
+  // protected" and silently reopen the exact sibling-worktree gap this
+  // guard exists to close -- confirmed by a regression test built for
+  // exactly this case.
+  if (!isProtectedPath(canonicalize(filePath), toplevel)) return false;
+
+  if (!isLinkedWorktree) return true; // the main checkout itself; always blocked
+
+  const mainRepoRoot = dirname(commonDir); // a linked worktree's common-dir is always <mainRepoRoot>/.git
+  const sanctionedPrefix = resolve(mainRepoRoot, ".claude", "worktrees");
+  const rel = relative(sanctionedPrefix, toplevel);
+  // Inside sanctionedPrefix iff `rel` doesn't escape upward via a literal
+  // ".." segment and isn't an absolute path (which `relative()` returns
+  // instead of a ".."-prefixed one on Windows when the two paths are on
+  // different drives). `rel === ""` (the sanctioned directory ITSELF, not a
+  // named worktree under it) is correctly treated as NOT inside -- nothing
+  // should ever write directly into `.claude/worktrees/` itself.
+  const insideSanctioned =
+    rel !== "" &&
+    rel !== ".." &&
+    !rel.startsWith(`..${sep}`) &&
+    !isAbsolute(rel);
+  return !insideSanctioned;
+}
+
+// Kept as a duplicated, self-contained block rather than a shared helper --
+// see `post-edit-verify.mjs`'s equivalent comment. `import.meta.url` is
+// symlink-resolved by Node's ESM loader but `process.argv[1]` is not.
+function isEntryPoint() {
+  try {
+    return realpathSync(process.argv[1]) === fileURLToPath(import.meta.url);
+  } catch {
+    return false;
+  }
+}
+
+if (isEntryPoint()) {
+  const chunks = [];
+  for await (const chunk of process.stdin) chunks.push(chunk);
+  let input;
+  try {
+    input = JSON.parse(Buffer.concat(chunks).toString("utf8"));
+  } catch {
+    process.exit(0);
+  }
+
+  const filePath = input?.tool_input?.file_path ?? "";
+  if (typeof filePath !== "string" || filePath.length === 0) process.exit(0);
+
+  // Cheap, unscoped pre-check first -- this can only produce a false
+  // NEGATIVE (an obviously-unrelated path skips the git shell-out
+  // entirely), never a false positive, so it's safe ahead of the properly
+  // scoped check inside `shouldBlock`.
+  if (!isProtectedPath(filePath)) process.exit(0);
+
+  // Bind git to the nearest EXISTING ancestor of the write target -- a
+  // Write creating a brand-new nested directory means `git -C <that dir>`
+  // would otherwise fail outright.
+  let probeDir = dirname(resolve(filePath));
+  while (!existsSync(probeDir)) {
+    const parent = dirname(probeDir);
+    if (parent === probeDir) break;
+    probeDir = parent;
+  }
+  const git = defaultGitFor(probeDir);
+
+  let blocked;
+  let lookupFailure;
+  try {
+    blocked = shouldBlock(filePath, git, probeDir);
+  } catch (cause) {
+    if (cause instanceof GitLookupError) {
+      blocked = true;
+      lookupFailure = cause.message;
+    } else {
+      throw cause; // truly unexpected -- surface as a visible hook crash, never silent
+    }
+  }
+
+  if (!blocked) process.exit(0);
+
+  process.stderr.write(
+    lookupFailure !== undefined
+      ? `guard-worktree-only: Blocked: git lookup failed for \`${filePath}\` ` +
+          `(${lookupFailure}) -- refusing the write rather than allowing it ` +
+          "with unknown worktree state.\n"
+      : `guard-worktree-only: Blocked: refusing to write \`${filePath}\` outside a ` +
+          "linked worktree under `.claude/worktrees/`. This project requires every " +
+          "src/tests change to happen inside a worktree -- run the " +
+          "`working-in-worktrees` skill's start mode first.\n",
+  );
+  process.exit(2);
+}