@monte3l/groundwork 1.0.0-rc.2 → 1.0.0-rc.4

package/plugin/src/pack-map.ts

@@ -1,3 +1,6 @@
+// SPDX-FileCopyrightText: Copyright the m3l-groundwork contributors
+// SPDX-License-Identifier: MIT
+
 /**
  * The pack recommendation table `/customize` reads in Step 1 to pre-select
  * which `templates/packs/` pack(s) to offer, with the evidence shown
@@ -16,50 +19,169 @@ export interface PackRecommendation {
 }
 
 /**
- * `harness-extras`'s four artifacts (a type-design-analyzer agent, the
- * compaction-handoff hook pair, a read-only Bash guard, a file-budget gate)
- * are language- and harness-level, not domain-level -- they apply to any
- * TypeScript project regardless of what it's building.
+ * `harness-extras`'s remaining artifacts (the compaction-handoff hook pair
+ * and a read-only Bash guard) are harness-level, not domain-level -- they
+ * apply to any TypeScript project regardless of what it's building. The
+ * type-design-analyzer agent and the file-budget gate it once also carried
+ * now live in the separate `quality` pack. Its folded-in
+ * statusLine scripts read only the stdin payload, `.git/HEAD` (via
+ * `node:fs`, never a `git` subprocess) and `os.freemem()`/`os.totalmem()`,
+ * and `statusLine` is the only documented surface carrying live
+ * `context_window.used_percentage`: no hook event receives token or context
+ * data, so "when to compact" can live nowhere else.
  */
 function recommendHarnessExtras(): PackRecommendation {
   return {
     name: "harness-extras",
     recommended: true,
     because:
-      "its four artifacts (a type-design review agent, compaction-handoff " +
-      "hooks, a read-only Bash guard, a file-budget gate) are language- " +
-      "and harness-level, not tied to any particular project kind.",
+      "its compaction-handoff hooks (which carry work across a context " +
+      "compaction) and read-only Bash guard are harness-level, not tied " +
+      "to any particular project kind; its " +
+      "statusLine is the only surface that exposes live context-window " +
+      "pressure -- no hook event receives token data -- and reads only the " +
+      "stdin payload plus local git and memory state. It does occupy five " +
+      "terminal rows (session, model, context, quota, work).",
   };
 }
 
 /**
- * `statusline`'s three scripts read only the stdin payload, `.git/HEAD` (via
- * `node:fs`, never a `git` subprocess) and `os.freemem()`/`os.totalmem()` --
- * nothing about any project kind. `statusLine` is also the only documented
- * surface carrying live `context_window.used_percentage`: no hook event
- * receives token or context data, so "when to compact" can live nowhere else.
+ * `github`'s workflow assumes only GitHub, which this baseline's whole
+ * toolchain (CI, Dependency Review, rulesets) already does -- nothing about
+ * any project kind. Beyond the mention-mode Action (`claude.yml`) it ships a
+ * second workflow, `claude-pr-review.yml`, which posts an automated Claude
+ * review comment on every PR, plus three GitHub-operations skills:
+ * `reviewing-dependabot-prs` (classifies and batch-merges open Dependabot
+ * PRs), `triaging-scan-alerts` (triages open code-scanning alerts to
+ * file:line) and `watching-pr-checks`. It is not zero-setup: it adds two
+ * GitHub Actions workflows and needs an auth secret the pack cannot create
+ * itself.
  */
-function recommendStatusline(): PackRecommendation {
+function recommendGithub(): PackRecommendation {
   return {
-    name: "statusline",
+    name: "github",
     recommended: true,
     because:
-      "statusLine is the only surface that exposes live context-window " +
-      "pressure -- no hook event receives token data -- and its scripts " +
-      "read only the stdin payload plus local git and memory state, so " +
-      "they apply to any project kind. It does occupy five terminal rows.",
+      "the baseline's toolchain already assumes GitHub (CI, Dependency " +
+      "Review, rulesets), so a Claude Code Action integration applies to " +
+      "any project kind. Alongside the mention-mode Action it adds a " +
+      "second workflow (claude-pr-review.yml) that posts an automated " +
+      "Claude review comment on every PR, plus skills for classifying and " +
+      "batch-merging open Dependabot PRs (reviewing-dependabot-prs), " +
+      "triaging open code-scanning alerts to file:line " +
+      "(triaging-scan-alerts) and watching a PR's checks " +
+      "(watching-pr-checks). It does add two GitHub Actions workflows and " +
+      "needs an auth secret configured by hand -- the pack cannot create it.",
+  };
+}
+
+/**
+ * `publishing` is the one kind-scoped pack: a release pipeline (a changesets
+ * version PR, then a staged, provenance-attested npm publish via trusted
+ * publishing) plus SPDX/REUSE license headers. Secret scanning and OpenSSF
+ * Scorecard are not part of it -- they are the separate `supply-chain` pack,
+ * since they apply to any repo, published or not. A `library` or `cli`
+ * typically publishes an npm package; a
+ * `frontend` or `service` is typically deployed instead, so it is not
+ * pre-selected there -- but it stays on offer. It is fresh-mode only and
+ * needs one-time npm and GitHub setup the pack cannot perform itself.
+ */
+function recommendPublishing(answers: InterviewAnswers): PackRecommendation {
+  const recommended = answers.kind === "library" || answers.kind === "cli";
+  return {
+    name: "publishing",
+    recommended,
+    because: recommended
+      ? "a library or CLI typically ships an npm package, so this pack's " +
+        "release pipeline applies: a changesets version PR, then a staged, " +
+        "provenance-attested npm publish via trusted publishing -- plus " +
+        "SPDX/REUSE license headers. The repository-hygiene scans that " +
+        "apply to any project, published or not, are the separate " +
+        "supply-chain pack. It is fresh-mode only and needs one-time npm and GitHub setup (the " +
+        "trusted publisher, the release credentials) the pack cannot do " +
+        "itself."
+      : "a frontend or service is typically deployed rather than published " +
+        "to a package registry, so a changesets/npm release pipeline is not " +
+        "recommended by default -- it is still available if this project " +
+        "does publish an npm package.",
+  };
+}
+
+/**
+ * `worktrees` is opt-in for every project kind: rather than adding a
+ * nicety on top of the existing workflow, it changes the workflow itself --
+ * every `src/`/`tests/` write must happen inside a git worktree, not the
+ * main checkout. That is a day-to-day process decision for the maintainer,
+ * not something any interview answer can infer, so it is never pre-selected
+ * -- but it stays on offer.
+ */
+function recommendWorktrees(): PackRecommendation {
+  return {
+    name: "worktrees",
+    recommended: false,
+    because:
+      "it changes the day-to-day workflow rather than adding a nicety on " +
+      "top of it: every src/ and tests/ write has to happen inside a git " +
+      "worktree instead of the main checkout. That is a process choice " +
+      "for whoever works in this repo, not something any project kind " +
+      "implies, so it is opt-in -- still available if parallel, isolated " +
+      "worktree sessions are how this project wants to work.",
+  };
+}
+
+/**
+ * `supply-chain` is the half carved out of `publishing`: gitleaks secret
+ * scanning and an OpenSSF Scorecard run. Neither depends on shipping to a
+ * registry -- a deployed frontend or service leaks a secret or drifts on
+ * Scorecard's checks just as easily as a published library -- so it is
+ * recommended for every project kind. Both are CI workflows only, so it
+ * installs into an already-established project without touching its code.
+ */
+function recommendSupplyChain(): PackRecommendation {
+  return {
+    name: "supply-chain",
+    recommended: true,
+    because:
+      "secret scanning (gitleaks) and an OpenSSF Scorecard run are useful " +
+      "to any project on GitHub, published or not, and install into an " +
+      "already-established project without touching its code.",
+  };
+}
+
+/**
+ * `quality` is the half carved out of `harness-extras`: a per-file size
+ * ratchet (`check-file-budget`) over `src/` and `tests/`, and the
+ * type-design-analyzer agent reviewing exported symbols' type design. Both
+ * are language-level -- they apply to any TypeScript project whatever it is
+ * building -- so it is recommended for every project kind.
+ */
+function recommendQuality(): PackRecommendation {
+  return {
+    name: "quality",
+    recommended: true,
+    because:
+      "its per-file size ratchet (check-file-budget) stops src/ and tests/ " +
+      "files growing unchecked and its type-design-analyzer agent reviews " +
+      "the type design of exported symbols -- both are language-level, not " +
+      "tied to any project kind.",
   };
 }
 
 /**
- * Every pack's recommendation for the given interview answers. `answers`
- * is currently unused by either pack (neither recommendation varies by
- * kind), but the parameter exists now so a future kind-scoped pack (e.g.
- * a `publishing` pack recommended only for `kind: "library"`) needs no API
- * change here.
+ * Every pack's recommendation for the given interview answers. Only
+ * `publishing` varies by `answers.kind` today; `harness-extras`, `github`,
+ * `supply-chain` and `quality` are recommended for every kind, and
+ * `worktrees` is opt-in for every kind.
  */
 export function recommendPacks(
-  _answers: InterviewAnswers,
+  answers: InterviewAnswers,
 ): PackRecommendation[] {
-  return [recommendHarnessExtras(), recommendStatusline()];
+  return [
+    recommendHarnessExtras(),
+    recommendGithub(),
+    recommendPublishing(answers),
+    recommendWorktrees(),
+    recommendSupplyChain(),
+    recommendQuality(),
+  ];
 }

package/plugin/src/plugin-map.ts

@@ -0,0 +1,236 @@
+// SPDX-FileCopyrightText: Copyright the m3l-groundwork contributors
+// SPDX-License-Identifier: MIT
+
+/**
+ * The plugin recommendation table `/customize` reads in Step 3 to pre-select
+ * which built-in `claude-plugins-official` marketplace plugin(s) to offer,
+ * with the evidence shown alongside each recommendation -- the same
+ * "inference happens once, visibly, with its reasoning attached" principle
+ * `pack-map.ts` applies to `templates/packs/` bundles. A stored, unit-tested
+ * module rather than a judgment made afresh each run, so the same interview
+ * answers and context always produce the same recommendation.
+ */
+import type { InterviewAnswers } from "./kind-facet-map.js";
+
+/** The marketplace every plugin in this table ships from. */
+const MARKETPLACE = "claude-plugins-official";
+
+/**
+ * One plugin's recommendation: its fully-qualified `name@marketplace` id,
+ * whether `/customize` pre-selects it, the reasoning shown to the user, and
+ * any host prerequisite the plugin cannot install for itself.
+ */
+export interface PluginRecommendation {
+  readonly id: string;
+  readonly recommended: boolean;
+  readonly because: string;
+  readonly prerequisites?: readonly string[];
+}
+
+/**
+ * What `/customize` knows beyond the interview answers by the time it
+ * recommends plugins: which packs the user chose, and whether the project
+ * authors its own skills. Both are optional; an absent field reads as "no".
+ */
+export interface PluginRecommendationContext {
+  readonly chosenPacks?: readonly string[];
+  readonly hasCustomSkills?: boolean;
+}
+
+function pluginId(name: string): string {
+  return `${name}@${MARKETPLACE}`;
+}
+
+/**
+ * `context7` is not optional for a project bootstrapped from this baseline:
+ * `templates/core/.claude/agents/code-implementer.md` declares
+ * `mcpServers: [context7]`, and an agent's MCP grant names a server that
+ * some installed source must actually provide -- without the plugin enabled
+ * the grant resolves to nothing and fails silently (the gap the
+ * `agent-mcp-source` harness rubric rule flags). It works anonymously; an
+ * API key only raises rate limits.
+ */
+function recommendContext7(): PluginRecommendation {
+  return {
+    id: pluginId("context7"),
+    recommended: true,
+    because:
+      "the baseline's code-implementer agent declares mcpServers: " +
+      "[context7], so without this plugin enabled that grant silently " +
+      "resolves to nothing -- the agent loses the library-docs lookup it " +
+      "was written to rely on. It works anonymously; a CONTEXT7_API_KEY is " +
+      "optional and only raises the rate limit.",
+  };
+}
+
+/**
+ * Every project this bootstrapper produces is TypeScript, so a TypeScript
+ * language server gives Claude go-to-definition, references and live
+ * diagnostics on any of them. The plugin wires the server up but does not
+ * ship the binary itself -- it must already be on `PATH`.
+ */
+function recommendTypescriptLsp(): PluginRecommendation {
+  return {
+    id: pluginId("typescript-lsp"),
+    recommended: true,
+    because:
+      "every project this bootstrapper emits is TypeScript, so a language " +
+      "server gives Claude real go-to-definition, find-references and " +
+      "compiler diagnostics instead of text search, whatever the project " +
+      "kind. The plugin only wires the server up -- the binary itself has " +
+      "to be installed separately.",
+    prerequisites: [
+      "the typescript-language-server binary on PATH (for example via " +
+        "`pnpm add -g typescript-language-server typescript`)",
+    ],
+  };
+}
+
+/**
+ * The baseline ships a `CLAUDE.md` that is only useful while it stays true.
+ * `harness-guidance` refreshes the harness against upstream in periodic
+ * sweeps; `claude-md-management` covers the other half -- keeping the file
+ * in step with what the project itself learns between those sweeps.
+ */
+function recommendClaudeMdManagement(): PluginRecommendation {
+  return {
+    id: pluginId("claude-md-management"),
+    recommended: true,
+    because:
+      "the baseline's CLAUDE.md only helps while it stays accurate; this " +
+      "plugin audits and updates it as the project changes, complementing " +
+      "harness-guidance's periodic refresh sweeps, which check the harness " +
+      "against upstream guidance rather than against the project's own " +
+      "day-to-day drift.",
+  };
+}
+
+/**
+ * The `github` plugin is the natural companion to the `github` pack: that
+ * pack's skills (`reviewing-dependabot-prs`, `triaging-scan-alerts`,
+ * `watching-pr-checks`) are `gh`-CLI workflows, and the plugin gives Claude
+ * structured GitHub access alongside them. Without the pack there is no
+ * GitHub-operations workflow in the project for it to serve, so it is only
+ * offered, not pre-selected.
+ */
+function recommendGithub(
+  context: PluginRecommendationContext | undefined,
+): PluginRecommendation {
+  const recommended = context?.chosenPacks?.includes("github") ?? false;
+  return {
+    id: pluginId("github"),
+    recommended,
+    because: recommended
+      ? "the github pack was chosen, and its skills are gh-CLI GitHub " +
+        "workflows -- reviewing and batch-merging Dependabot PRs, triaging " +
+        "code-scanning alerts to file:line, watching a PR's checks -- so " +
+        "structured GitHub access through this plugin serves them directly."
+      : "not preselected because the github pack was not chosen: without " +
+        "its GitHub-operations skills there is no workflow here that needs " +
+        "structured GitHub access. It stays on offer if the project works " +
+        "heavily with issues and PRs anyway.",
+  };
+}
+
+/**
+ * `security-guidance` earns its cost where the attack surface or the
+ * rigor bar is highest: a `service` handles untrusted network input, and a
+ * `thorough` CI depth is the user asking for the stricter posture
+ * explicitly. The cost is real and named rather than hidden -- Edit/Write
+ * pattern hooks, a Stop-hook LLM review that spends tokens on every turn,
+ * and a commit reviewer -- so it is not pre-selected elsewhere.
+ */
+function recommendSecurityGuidance(
+  answers: InterviewAnswers,
+): PluginRecommendation {
+  const recommended =
+    answers.kind === "service" || answers.ciDepth === "thorough";
+  return {
+    id: pluginId("security-guidance"),
+    recommended,
+    because: recommended
+      ? "a service handles untrusted input, or thorough CI depth asks for " +
+        "the stricter posture, so security review is worth its cost here. " +
+        "That cost is real: pattern hooks on every Edit/Write, a Stop-hook " +
+        "LLM review that spends tokens at the end of every turn, and a " +
+        "commit reviewer."
+      : "for a non-service project at standard or minimal CI depth, its " +
+        "Edit/Write pattern hooks, per-turn Stop-hook LLM review (tokens " +
+        "on every turn) and commit reviewer cost more than the added " +
+        "scrutiny is likely to return -- still available if the project " +
+        "handles sensitive data.",
+    prerequisites: ["Python 3.8+ on PATH (its hooks are Python scripts)"],
+  };
+}
+
+/**
+ * `skill-creator` scaffolds, evaluates and iterates on skills. The baseline's
+ * own skills are maintained by this repo, not by the project, so it only
+ * pays for itself in a project that writes skills of its own.
+ */
+function recommendSkillCreator(
+  context: PluginRecommendationContext | undefined,
+): PluginRecommendation {
+  const recommended = context?.hasCustomSkills === true;
+  return {
+    id: pluginId("skill-creator"),
+    recommended,
+    because: recommended
+      ? "this project authors its own skills, and skill-creator helps " +
+        "draft, evaluate and tune them -- including their triggering " +
+        "descriptions -- rather than iterating on them by hand."
+      : "only useful to a project that authors its own skills; the " +
+        "baseline's skills come maintained from upstream, so there is " +
+        "nothing here for it to work on yet.",
+  };
+}
+
+/**
+ * `claude-code-setup` recommends automations (hooks, skills, MCP servers,
+ * subagents) for a codebase -- which is exactly the job `/customize` is
+ * already doing, against a baseline designed for it. Running both would
+ * produce two competing sets of suggestions, so it is never pre-selected;
+ * it is listed with that reason rather than silently omitted, so the user
+ * can see why. TypeScript-toolchain gaps are a distinct question from Claude
+ * Code automation and are answered instead by the baseline
+ * `typescript-guidance` skill's `gaps` mode.
+ */
+function recommendClaudeCodeSetup(): PluginRecommendation {
+  return {
+    id: pluginId("claude-code-setup"),
+    recommended: false,
+    because:
+      "its automation recommender overlaps what /customize is already " +
+      "doing -- tailoring hooks, skills and agents to this project against " +
+      "the baseline -- so enabling it would produce a second, competing " +
+      "set of suggestions. TypeScript-toolchain gaps are a separate " +
+      "question from Claude Code automation, and are answered instead by " +
+      "the baseline typescript-guidance skill's gaps mode with " +
+      "live-researched, cited recommendations. " +
+      "Listed so the choice is visible, not silently left out.",
+  };
+}
+
+/**
+ * Every built-in marketplace plugin's recommendation for the given interview
+ * answers and context, always the same seven in the same order: `context7`,
+ * `typescript-lsp` and `claude-md-management` unconditionally; `github` when
+ * the `github` pack was chosen; `security-guidance` for a `service` or a
+ * `thorough` CI depth; `skill-creator` when the project has its own skills;
+ * `claude-code-setup` never. A pure function -- identical inputs always
+ * produce an equal result.
+ */
+export function recommendPlugins(
+  answers: InterviewAnswers,
+  context?: PluginRecommendationContext,
+): PluginRecommendation[] {
+  return [
+    recommendContext7(),
+    recommendTypescriptLsp(),
+    recommendClaudeMdManagement(),
+    recommendGithub(context),
+    recommendSecurityGuidance(answers),
+    recommendSkillCreator(context),
+    recommendClaudeCodeSetup(),
+  ];
+}

package/templates/core/.claude/agents/Explore.md

@@ -4,7 +4,6 @@ description: Fast read-only search agent for locating and understanding code. Us
 tools: Read, Grep, Glob, Bash, WebSearch, WebFetch
 disallowedTools: Agent
 model: claude-haiku-4-5
-effort: low
 maxTurns: 40
 color: cyan
 ---

package/templates/core/.claude/agents/code-implementer.md

@@ -4,8 +4,8 @@ description: Writer spoke for the TDD build pipeline. Given a contract and a set
 tools: Read, Write, Edit, Grep, Glob, Bash, mcp__context7__resolve-library-id, mcp__context7__query-docs
 disallowedTools: Agent
 mcpServers: [context7]
-model: claude-sonnet-5
-effort: high
+model: claude-opus-5-5
+effort: medium
 permissionMode: acceptEdits
 maxTurns: 40
 color: cyan
@@ -111,8 +111,8 @@ id first, then query for the specific behavior in question — don't fetch
 broad documentation you won't use.
 
 **Precedence: installed types are the pinned truth and win on conflict.**
-This project pins exact dependency versions, while context7 returns docs for
-whatever version it has indexed — a disagreement between the two is expected
+The installed dependency version (see `pnpm-lock.yaml`) is what runs, while
+context7 returns docs for whatever version it has indexed — a disagreement between the two is expected
 and is not evidence the types are wrong. Never widen or reinterpret a type
 based on context7 output alone; use it to understand behavior the types are
 silent on, not to override them.

package/templates/core/.claude/agents/code-reviewer.md

@@ -3,8 +3,8 @@ name: code-reviewer
 description: Read-only reviewer for this project's source changes. Applies the four-part quality checklist and SOLID checks to a diff. Use after writing or changing source code, before commit.
 tools: Read, Grep, Glob, Bash
 disallowedTools: Agent
-model: claude-sonnet-5
-effort: high
+model: claude-opus-5-5
+effort: medium
 maxTurns: 40
 color: blue
 ---
@@ -69,8 +69,8 @@ on it.
   a PreToolUse hook then exits 0, which means _allow_, and a verify gate goes
   green having checked nothing. `.pathname` is percent-encoded while
   `process.argv[1]` is a decoded path, so it also never matches on a path with
-  spaces or non-ASCII characters. Inline the helper; a shared module would cost
-  a hook slot against the baseline's cap.
+  spaces or non-ASCII characters. Inline the helper: every hook carries its own copy of this guard block,
+  so each one stays an independent entrypoint.
 - The package's `exports` map is the public contract — flag any change to it
   as a semver event and check the Conventional Commit matches.
 - TSDoc on exported symbols.

package/templates/core/.claude/agents/silent-failure-hunter.md

@@ -3,8 +3,8 @@ name: silent-failure-hunter
 description: Read-only error-handling auditor. Hunts for silent failures — swallowed exceptions, unchained causes, empty catch blocks, optional-chaining that masks errors, and retry/poll logic that exhausts without surfacing — against this project's error hierarchy and error-handling rules. Use after implementing or changing any code that has try/catch, async/await, optional chaining on fallible calls, or retry/poll loops. Complements code-reviewer (general quality).
 tools: Read, Grep, Glob, Bash
 disallowedTools: Agent
-model: claude-sonnet-5
-effort: high
+model: claude-opus-5-5
+effort: medium
 maxTurns: 40
 color: yellow
 ---

package/templates/core/.claude/agents/test-author.md

@@ -3,8 +3,8 @@ name: test-author
 description: Writes Vitest tests for a source export — happy path, failure path, and expectTypeOf type-level tests where the type is the contract. This is the tests-first (RED) spoke of the TDD loop; it writes tests from the documented contract before the implementation exists and confirms they fail for the right reason. Also usable to backfill tests for existing code. It writes tests only — never the implementation, and never reviews implementation quality.
 tools: Read, Grep, Glob, Edit, Write, Bash
 disallowedTools: Agent
-model: claude-sonnet-5
-effort: high
+model: claude-sonnet-5-5
+effort: medium
 permissionMode: acceptEdits
 maxTurns: 40
 color: green
@@ -180,9 +180,11 @@ expect(() =>
   so the hub can dispatch `code-implementer` precisely. This keeps the suite
   green and self-resolves visibly: once the real fix lands, `test.fails`
   reports an XPASS, the signal to flip it to a normal `test`.
-- Do not use real filesystem mutations in tests (`mkdtempSync`, `mkdirSync`,
-  `writeFileSync`, `rmSync`, etc.); mock the filesystem instead
-  (`vi.spyOn(fs, method)` or `vi.mock('node:fs')`).
+- Mock the filesystem by default (`vi.spyOn(fs, method)` or
+  `vi.mock('node:fs')`). The one exception, matching `tests.md`: when the
+  unit under test's contract IS real filesystem behavior (a walker, a
+  parser reading files), use a per-test `mkdtemp` sandbox torn down in the
+  same test -- never a fixed path, and never a mutation outside it.
 - **The mock target must track the implementation's I/O primitive.** If the
   implementation moves from one primitive to another, your tests must
   re-mock the **new** one — the old mock silently stops intercepting

package/templates/core/.claude/hooks/guard-branch-isolation.mjs

@@ -26,11 +26,15 @@
  * Blocks by exiting 2 with a message on stderr.
  */
 import process from "node:process";
-import { realpathSync } from "node:fs";
+import { existsSync, realpathSync } from "node:fs";
 import { execFileSync } from "node:child_process";
 import { dirname, relative, resolve } from "node:path";
 import { fileURLToPath } from "node:url";
-import { isProtectedPath } from "../../bin/lib/protected-paths.mjs";
+import {
+  canonicalize,
+  isAbsoluteLike,
+  isProtectedPath,
+} from "../../bin/lib/protected-paths.mjs";
 export { isProtectedPath };
 
 /**
@@ -73,11 +77,13 @@ export function isMainOrDetachedOnMain(git = defaultGit) {
   return false;
 }
 
-// Deliberately inlined in every hook rather than shared: caps.ts counts
-// .claude/hooks/*.mjs files against a hard limit, so a helper module would
-// cost a hook slot. `import.meta.url` is symlink-resolved but `process.argv[1]`
-// is not, so comparing them directly is false under any symlinked path and the
-// guard body would never run -- exit 0, i.e. fail open.
+// Kept as a duplicated, self-contained block in every hook file rather than
+// imported from a shared helper -- each hook stays a single independent
+// file, which keeps this project's hook count easy to reason about against
+// CLAUDE.md's hook budget. `import.meta.url` is symlink-resolved but
+// `process.argv[1]` is not, so comparing them directly would be false under
+// a symlinked invocation path -- and the guard below would then never run,
+// i.e. silently fail open (exit 0) instead of blocking.
 function isEntryPoint() {
   try {
     return realpathSync(process.argv[1]) === fileURLToPath(import.meta.url);
@@ -98,13 +104,53 @@ if (isEntryPoint()) {
   }
 
   const filePath = input.tool_input?.file_path ?? "";
+  // Cheap, unscoped pre-check first (same cost as before this file's
+  // scoping fix): anything that can't possibly be a src/tests path by raw
+  // substring is dismissed with no git shell-out at all.
   if (!isProtectedPath(filePath)) process.exit(0);
 
-  const fileDir = dirname(resolve(filePath));
-  const git = defaultGitFor(fileDir);
+  // Bind git to the nearest EXISTING ancestor of the write target, not the
+  // target directory itself -- a Write creating a brand-new nested
+  // directory (e.g. `src/newdir/a.ts` where `newdir/` doesn't exist yet)
+  // means `git -C <that dir>` fails outright ("cannot change to ... No
+  // such file or directory"), which would silently break EVERY git call
+  // below, including branch detection -- the guard would then never learn
+  // it's on `main` at all and allow the write through unblocked. Any
+  // ancestor within the same worktree resolves the same repo root and
+  // branch, so walking up costs nothing in accuracy.
+  let probeDir = dirname(resolve(filePath));
+  while (!existsSync(probeDir)) {
+    const parent = dirname(probeDir);
+    if (parent === probeDir) break; // filesystem root; let git fail naturally
+    probeDir = parent;
+  }
+  const git = defaultGitFor(probeDir);
+  const worktreeRoot = git(["rev-parse", "--show-toplevel"]);
+  // Re-check scoped to the file's OWN worktree root (more accurate than a
+  // guess from CLAUDE_PROJECT_DIR/cwd, and what this guard already resolves
+  // everything else against): a checkout whose own path merely contains the
+  // substring "/src/" above the worktree root (e.g. a clone at
+  // ~/src/other-project) must not count as protected just because of that.
+  // A non-git directory leaves worktreeRoot "" and skips this re-check,
+  // same as the header comment's existing "never blocks" behavior. Both
+  // sides go through `canonicalize` (case-correct, symlinks resolved)
+  // before comparing -- see its own doc comment for why a raw string
+  // comparison isn't safe here (macOS's case-insensitive filesystem and its
+  // `/tmp`/`/var` symlinks both make two spellings of the identical file
+  // compare as different paths otherwise). Only attempted for an ABSOLUTE
+  // filePath: canonicalize() resolves a relative one against this process's
+  // own cwd, which isn't necessarily the anchor a relative payload was
+  // meant against -- the fast pre-check above already matched it correctly
+  // as-is, so a relative path just keeps that verdict.
+  if (
+    worktreeRoot !== "" &&
+    isAbsoluteLike(filePath) &&
+    !isProtectedPath(canonicalize(filePath), canonicalize(worktreeRoot))
+  ) {
+    process.exit(0);
+  }
 
   if (isMainOrDetachedOnMain(git)) {
-    const worktreeRoot = git(["rev-parse", "--show-toplevel"]);
     const inDifferentTree =
       worktreeRoot !== "" && resolve(worktreeRoot) !== resolve(process.cwd());
     const location = inDifferentTree