pi-gauntlet 5.9.0 → 5.9.1

package/CHANGELOG.md

@@ -1,5 +1,9 @@
 # Changelog
 
+## v5.9.1 - 2026-09-17
+
+- Process in primary, work by path: `plan_check` roots at the plan's checkout, settings load from the session cwd's checkout toplevel, the branch-switch guard evaluates the command's `-C`/`cd` target, telemetry commits on the spec's checkout, and ship detection accepts `git -C <worktree> push` / `merge --squash`. Stage skills carry the worktree path as a value (dispatch `cwd`, `git -C`, subshell) - a new CI lint keeps them that way; `finishing-a-development-branch` takes `<worktree-path>` as a mandatory argument. Requires git >= 2.31. ([#37](https://github.com/jjuraszek/pi-gauntlet/issues/37))
+
 ## v5.9.0 - 2026-09-17
 
 - Added `gauntlet-spec-index`, a build-on-query FTS5 search over root and one-level service spec corpora with a per-worktree cache and telemetry-enriched tabular results; brainstorming uses it to find predecessor specs. Requires Node >=24.15.0. (#34)

package/README.md

@@ -75,6 +75,8 @@ pi-gauntlet ships three kinds of pieces, layered on top of pi-cohort's dispatch:
 
 pi-gauntlet is **opinionated**: every non-trivial change is *meant* to ride this one pipeline, entered through `brainstorming`. Enforcement is opt-in by entry, not ambient: once brainstorming starts a flow, the phase-tracker extension mechanically blocks a phase from closing before its gate runs, and warns once if the main loop writes code during implement (subagents own implement-phase edits). A change made *without* entering the flow (a typo, a formatting run, a dependency bump - see "When to use / when NOT to use") is not gated; the discipline of routing real work through the pipeline is a convention the tooling supports, not a trap it springs on every edit.
 
+**Worktree contract.** pi runs in the primary checkout; the work happens in `.worktrees/<branch>`. Skills never `cd` there - the worktree path is a value from the `using-git-worktrees` report (or the handoff brief on `gauntlet-resume`), carried as dispatch `cwd: "<path>"`, as `git -C <path>`, or as `(cd "<path>" && <cmd>)` for other cwd-bound commands; the runtime extensions derive the checkout from the artifact path they act on. Requires git >= 2.31.
+
 ## Key concepts
 
 | Term | Meaning |

package/extensions/lib/checkout.test.ts

@@ -0,0 +1,59 @@
+import assert from "node:assert/strict";
+import { after, test } from "node:test";
+import { mkdtempSync, mkdirSync, rmSync, writeFileSync, realpathSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import { checkoutOf, parseCheckout, gitSync, type GitResult } from "./checkout.ts";
+
+const tempDirs: string[] = [];
+after(() => { for (const d of tempDirs) rmSync(d, { recursive: true, force: true }); });
+const tmp = () => { const d = realpathSync(mkdtempSync(join(tmpdir(), "checkout-test-"))); tempDirs.push(d); return d; };
+
+const out = (lines: string[]): GitResult => ({ code: 0, stdout: lines.join("\n") + "\n" });
+
+test("parseCheckout: primary checkout when git-dir equals common-dir", () => {
+  assert.deepEqual(parseCheckout(out(["/repo", "/repo/.git", "/repo/.git"])), { toplevel: "/repo", isPrimary: true });
+});
+
+test("parseCheckout: linked worktree when the dirs differ", () => {
+  assert.deepEqual(
+    parseCheckout(out(["/repo/.worktrees/x", "/repo/.git/worktrees/x", "/repo/.git"])),
+    { toplevel: "/repo/.worktrees/x", isPrimary: false },
+  );
+});
+
+test("parseCheckout: nonzero code or fewer than three lines -> undefined", () => {
+  assert.equal(parseCheckout({ code: 128, stdout: "" }), undefined);
+  assert.equal(parseCheckout(out(["/repo", "/repo/.git"])), undefined);
+});
+
+test("checkoutOf: a file path runs git in its dirname", async () => {
+  const dir = tmp();
+  writeFileSync(join(dir, "spec.md"), "# s\n");
+  const cwds: string[] = [];
+  const git = (_args: string[], cwd: string): GitResult => { cwds.push(cwd); return out([dir, dir + "/.git", dir + "/.git"]); };
+  assert.deepEqual(await checkoutOf(join(dir, "spec.md"), git), { toplevel: dir, isPrimary: true });
+  assert.deepEqual(cwds, [dir]);
+});
+
+test("checkoutOf: a nonexistent leaf walks up to the nearest existing ancestor", async () => {
+  const dir = tmp();
+  mkdirSync(join(dir, "doc"));
+  const cwds: string[] = [];
+  const git = async (_args: string[], cwd: string): Promise<GitResult> => { cwds.push(cwd); return out([dir, dir + "/.git", dir + "/.git"]); };
+  await checkoutOf(join(dir, "doc", "specs", "new.md"), git);
+  assert.deepEqual(cwds, [join(dir, "doc")]);
+});
+
+test("checkoutOf: an existing directory is used as-is", async () => {
+  const dir = tmp();
+  const cwds: string[] = [];
+  await checkoutOf(dir, (_a, cwd) => { cwds.push(cwd); return out([dir, dir + "/.git", dir + "/.git"]); });
+  assert.deepEqual(cwds, [dir]);
+});
+
+test("gitSync: never throws; nonzero code outside a repo", () => {
+  const r = gitSync(["rev-parse", "--path-format=absolute", "--show-toplevel", "--git-dir", "--git-common-dir"], tmp());
+  assert.notEqual(r.code, 0);
+  assert.equal(typeof r.stdout, "string");
+});

package/extensions/lib/checkout.ts

@@ -0,0 +1,57 @@
+// One checkout resolver for every extension that needs "which git checkout owns this
+// path" (#37): plan_check, the settings loader, Guard 2, telemetry. `--path-format=absolute`
+// (git >= 2.31) makes git-dir and common-dir comparable as strings from any subdirectory.
+import { execFileSync } from "node:child_process";
+import { existsSync, statSync } from "node:fs";
+import { dirname } from "node:path";
+
+export type GitResult = { code: number; stdout: string };
+export type Checkout = { toplevel: string; isPrimary: boolean };
+
+export const CHECKOUT_ARGS = ["rev-parse", "--path-format=absolute", "--show-toplevel", "--git-dir", "--git-common-dir"];
+
+// isPrimary = gitDir === commonDir (both absolute thanks to --path-format).
+export function parseCheckout(r: GitResult): Checkout | undefined {
+  if (r.code !== 0) return undefined;
+  const lines = r.stdout.trim().split("\n").map((l) => l.trim());
+  if (lines.length < 3 || !lines[0]) return undefined;
+  return { toplevel: lines[0], isPrimary: lines[1] === lines[2] };
+}
+
+const isDir = (p: string): boolean => {
+  try {
+    return statSync(p).isDirectory();
+  } catch {
+    return false;
+  }
+};
+
+// Nearest existing directory at or above absPath: the path itself when it is a directory,
+// else its dirname, walking up. Covers the first write into a not-yet-existing doc/specs/.
+export function nearestExistingDir(absPath: string): string {
+  let p = absPath;
+  while (!(existsSync(p) && isDir(p))) {
+    const parent = dirname(p);
+    if (parent === p) return p;
+    p = parent;
+  }
+  return p;
+}
+
+export async function checkoutOf(
+  absPath: string,
+  git: (args: string[], cwd: string) => GitResult | Promise<GitResult>,
+): Promise<Checkout | undefined> {
+  return parseCheckout(await git(CHECKOUT_ARGS, nearestExistingDir(absPath)));
+}
+
+// Never throws: any failure (not a repo, missing dir, old git) is a nonzero code.
+export const gitSync = (args: string[], cwd: string): GitResult => {
+  try {
+    const stdout = execFileSync("git", args, { cwd, encoding: "utf8", stdio: ["ignore", "pipe", "ignore"], timeout: 5000 });
+    return { code: 0, stdout };
+  } catch (e) {
+    const status = (e as { status?: unknown }).status;
+    return { code: typeof status === "number" ? status : 1, stdout: "" };
+  }
+};

package/extensions/lib/gauntlet-settings-loader.test.ts

@@ -0,0 +1,32 @@
+import assert from "node:assert/strict";
+import { after, test } from "node:test";
+import { execFileSync } from "node:child_process";
+import { mkdtempSync, mkdirSync, realpathSync, rmSync, writeFileSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import { loadGauntletSettings } from "./gauntlet-settings-loader.ts";
+
+const tempDirs: string[] = [];
+after(() => { for (const d of tempDirs) rmSync(d, { recursive: true, force: true }); });
+const tmp = () => { const d = realpathSync(mkdtempSync(join(tmpdir(), "settings-loader-test-"))); tempDirs.push(d); return d; };
+const gitRepo = () => { const d = tmp(); execFileSync("git", ["init", "-q", d]); return d; };
+
+test("settings resolve from the checkout root when cwd is a subdirectory (AC 2)", () => {
+  const repo = gitRepo();
+  mkdirSync(join(repo, ".pi"));
+  mkdirSync(join(repo, "doc"));
+  writeFileSync(join(repo, ".pi", "settings.json"), JSON.stringify({ piGauntlet: { specCouncil: { members: ["p/m"] } } }));
+  const loaded = loadGauntletSettings(join(repo, "doc"), "/tmp/pi-gauntlet-test-agent");
+  assert.equal(loaded.root, repo);
+  assert.deepEqual(loaded.gauntlet.specCouncil, { members: ["p/m"] });
+  assert.deepEqual(loaded.errors, []);
+});
+
+test("outside any checkout the loader falls back to cwd", () => {
+  const dir = tmp();
+  mkdirSync(join(dir, ".pi"));
+  writeFileSync(join(dir, ".pi", "settings.json"), JSON.stringify({ piGauntlet: { flowGuards: { enforce: false } } }));
+  const loaded = loadGauntletSettings(dir, "/tmp/pi-gauntlet-test-agent");
+  assert.equal(loaded.root, dir);
+  assert.deepEqual(loaded.gauntlet.flowGuards, { enforce: false });
+});

package/extensions/lib/gauntlet-settings-loader.ts

@@ -2,22 +2,26 @@
 // ci.mjs unit tests. Only pi-loaded extensions import this file.
 import { SettingsManager, getAgentDir } from "@earendil-works/pi-coding-agent";
 import { mergeGauntlet, type PiGauntlet } from "./gauntlet-settings.ts";
+import { gitSync, parseCheckout } from "./checkout.ts";
 
 export interface LoadedGauntlet {
   gauntlet: PiGauntlet;
   errors: string[];
+  // Checkout toplevel the repo layer was read from (cwd itself outside any checkout).
+  root: string;
 }
 
-// Reads the preset (agentDir/settings.json) and repo (cwd/.pi/settings.json)
-// layers via pi's own SettingsManager and returns the whole-object second-level
-// merge (repo over preset). SettingsManager never throws on a bad file - it
-// substitutes {} for that layer and records the error, surfaced here via errors[]
-// so callers can report a degraded read instead of failing silent.
+// Reads the preset (agentDir/settings.json) and repo (<root>/.pi/settings.json) layers
+// via pi's own SettingsManager, where <root> is the git toplevel of cwd - pi launched in a
+// subdirectory or a linked worktree still finds that checkout's file (#37). SettingsManager
+// never throws on a bad file - it substitutes {} for that layer and records the error,
+// surfaced here via errors[] so callers can report a degraded read instead of failing silent.
 export function loadGauntletSettings(cwd: string, agentDir: string = getAgentDir()): LoadedGauntlet {
-  const sm = SettingsManager.create(cwd, agentDir);
+  const root = parseCheckout(gitSync(["rev-parse", "--path-format=absolute", "--show-toplevel", "--git-dir", "--git-common-dir"], cwd))?.toplevel ?? cwd;
+  const sm = SettingsManager.create(root, agentDir);
   const preset = sm.getGlobalSettings() as { piGauntlet?: Record<string, unknown> };
   const repo = sm.getProjectSettings() as { piGauntlet?: Record<string, unknown> };
   const gauntlet = mergeGauntlet(preset?.piGauntlet, repo?.piGauntlet);
   const errors = sm.drainErrors().map((e) => `${e.scope}: ${e.error.message}`);
-  return { gauntlet, errors };
+  return { gauntlet, errors, root };
 }

package/extensions/lib/phase-tracker-helpers.test.ts

@@ -10,6 +10,7 @@ import {
   implementExemptDirs,
   nextGauntletEntered,
   phaseLabel,
+  parseGitCommand,
   parseGitCommit,
   resolveRepoDir,
   findMarkerFile,
@@ -78,6 +79,22 @@ test("phaseLabel: with and without substep", () => {
   assert.equal(phaseLabel("brainstorm", undefined), "brainstorm");
 });
 
+test("parseGitCommand: branch subcommands with and without global flags", () => {
+  const SWITCH = /switch(?=\s|$)/;
+  const CHECKOUT_B = /checkout\s+-[bB](?=\s|$)/;
+  assert.deepEqual(parseGitCommand("git switch -c y", SWITCH), { cPath: undefined, cdPath: undefined });
+  assert.deepEqual(parseGitCommand("git -C .worktrees/x switch -c y", SWITCH), { cPath: ".worktrees/x", cdPath: undefined });
+  assert.deepEqual(parseGitCommand("git --no-pager -C p checkout -b y", CHECKOUT_B), { cPath: "p", cdPath: undefined });
+  assert.deepEqual(parseGitCommand("cd .worktrees/x && git checkout -b y", CHECKOUT_B), { cPath: undefined, cdPath: ".worktrees/x" });
+  assert.equal(parseGitCommand("git checkout file.ts", CHECKOUT_B), undefined);
+  assert.equal(parseGitCommand("git switcheroo", SWITCH), undefined);
+  assert.equal(parseGitCommand("echo git switch", SWITCH), undefined);
+});
+
+test("parseGitCommit is parseGitCommand with the commit subcommand", () => {
+  assert.deepEqual(parseGitCommit("git -C /wt -c user.email=x commit"), parseGitCommand("git -C /wt -c user.email=x commit", /commit(?=\s|$)/));
+});
+
 test("parseGitCommit: plain, -am, chained after &&", () => {
   assert.ok(parseGitCommit('git commit -m "x"'));
   assert.ok(parseGitCommit("git commit -am 'x'"));

package/extensions/lib/phase-tracker-helpers.ts

@@ -37,18 +37,15 @@ export function phaseLabel(name: string, substep?: string): string {
 // Same statement-start anchor as the branch guards in phase-tracker.ts. Exported
 // so Wave 2 wiring in phase-tracker.ts can drop its duplicate copy.
 export const STMT_START = "(?:^|[\\n;&|(])\\s*";
-// `git commit`, tolerating any global flags between `git` and `commit` (e.g.
-// `-c user.email=x`, common in CI per-commit identity). Group 1 captures the
-// whole flags span as ONE opaque block rather than -C directly: nesting a
-// capture inside a repeated alternation resets it to undefined on iterations
-// that take the other branch (JS regex semantics), so -C after a later flag
-// (e.g. `-C /wt -c user.email=x commit`) would silently lose its capture.
-// DASH_C below re-extracts -C from that span once, outside any repetition.
-// `commit` must be followed by whitespace or end-of-string, not just a word
-// boundary, so `commit-graph` / `commit-tree` don't false-positive.
-const GIT_COMMIT = new RegExp(
-  STMT_START + "git\\s+((?:-\\S+(?:\\s+\\S+)?\\s+)*)commit(?=\\s|$)",
-);
+// `git <global flags> <subcommand>`, tolerating any global flags between `git` and the
+// subcommand (e.g. `-C /wt`, `-c user.email=x`). Group 1 captures the whole flags span as
+// ONE opaque block rather than -C directly: nesting a capture inside a repeated alternation
+// resets it to undefined on iterations that take the other branch (JS regex semantics).
+// DASH_C re-extracts -C from that span once, outside any repetition. Callers pass a
+// subcommand regex that ends in `(?=\s|$)` so `commit-graph` / `switcheroo` don't match.
+const GIT_FLAGS_SPAN = "git\\s+((?:-\\S+(?:\\s+\\S+)?\\s+)*)";
+const gitCommandRe = (subcommand: RegExp): RegExp => new RegExp(STMT_START + GIT_FLAGS_SPAN + "(?:" + subcommand.source + ")");
+const GIT_COMMIT_SUB = /commit(?=\s|$)/;
 const DASH_C = /(?:^|\s)-C\s+(\S+)/;
 // Global, lookaround-delimited (not consuming) so adjacent `cd a && cd b &&`
 // statements don't eat each other's anchor/`&&` and hide the second match.
@@ -61,11 +58,11 @@ export interface CommitForm {
   cdPath: string | undefined;
 }
 
-// Textual match anchored at statement starts (^ ; & | ( or newline). Quoted text
-// can still match when preceded by such a char (e.g. sh -c 'x; git commit') —
-// accepted heuristic, same tolerance as the existing Guard 3 mutation checks.
-export function parseGitCommit(command: string): CommitForm | undefined {
-  const m = GIT_COMMIT.exec(command);
+// Textual match anchored at statement starts (^ ; & | ( or newline). Quoted text can
+// still match when preceded by such a char (e.g. sh -c 'x; git commit') - accepted
+// heuristic, same tolerance as the existing Guard 3 mutation checks.
+export function parseGitCommand(command: string, subcommand: RegExp): CommitForm | undefined {
+  const m = gitCommandRe(subcommand).exec(command);
   if (!m) return undefined;
   let cdPath: string | undefined;
   for (const cd of command.matchAll(LEADING_CD)) {
@@ -74,6 +71,8 @@ export function parseGitCommit(command: string): CommitForm | undefined {
   return { cPath: DASH_C.exec(m[1])?.[1], cdPath };
 }
 
+export const parseGitCommit = (command: string): CommitForm | undefined => parseGitCommand(command, GIT_COMMIT_SUB);
+
 export function resolveRepoDir(form: CommitForm, sessionCwd: string): string {
   const base = form.cdPath ? resolve(sessionCwd, form.cdPath) : sessionCwd;
   return form.cPath ? resolve(base, form.cPath) : base;

package/extensions/lib/telemetry-paths.test.ts

@@ -57,6 +57,16 @@ test("matchDiscardStatement matches worktree remove and branch -D", () => {
   assert.equal(matchDiscardStatement("git branch -d gh-33"), undefined);
 });
 
+test("matchShipStatement/matchDiscardStatement accept git -C <path> global flags", () => {
+  assert.deepEqual(matchShipStatement("git -C /p merge --squash f"), { option: "squash", statement: "git -C /p merge --squash f" });
+  assert.equal(matchShipStatement("git -C /p push -u origin HEAD")?.option, "pr");
+  assert.equal(matchShipStatement("git -c user.name=t -C /p merge --squash f")?.option, "squash");
+  assert.equal(matchShipStatement("git -C /p log"), undefined);
+  assert.equal(matchDiscardStatement("git -C /p worktree remove x"), "git -C /p worktree remove x");
+  assert.equal(matchDiscardStatement("git -C /p branch -D f"), "git -C /p branch -D f");
+  assert.equal(matchDiscardStatement("git -C /p branch -d f"), undefined);
+});
+
 test("matchTestStatement returns the first statement matching a test fragment", () => {
   assert.equal(matchTestStatement("cd repo && npm test -- --grep x", DEFAULT_TEST_COMMANDS), "npm test -- --grep x");
   assert.equal(matchTestStatement("make test-smoke", DEFAULT_TEST_COMMANDS), undefined);

package/extensions/lib/telemetry-paths.ts

@@ -3,9 +3,9 @@
 //
 // Ship detection runs on a `bash` `tool_call` while `ship` is in progress and matches
 // the first statement against
-//   STMT_START + (git\s+merge\s+--squash|git\s+push|gh\s+pr\s+create)
+//   STMT_START + git <global flags> (merge --squash | push) | gh pr create
 // and discard against
-//   STMT_START + git\s+(worktree\s+remove|branch\s+-D)
+//   STMT_START + git <global flags> (worktree remove | branch -D)
 // with STMT_START from phase-tracker-helpers.ts:39.
 // Default bucket globs (DEFAULT_TELEMETRY_BUCKETS): test = **/test/**, **/tests/**,
 // **/__tests__/**, **/*.test.*, **/*.spec.*, **/*_test.*; docs = **/*.md;
@@ -40,8 +40,12 @@ export const planSpecHeader = (planBody: string): string | undefined => SPEC_HEA
 
 // ---- command matchers ----------------------------------------------------------
 
-const SHIP_RE = new RegExp(STMT_START + "(git\\s+merge\\s+--squash|git\\s+push|gh\\s+pr\\s+create)");
-const DISCARD_RE = new RegExp(STMT_START + "(git\\s+(?:worktree\\s+remove|branch\\s+-D))");
+// `git <global flags> <subcommand>`: same flags-span grammar as parseGitCommand in
+// phase-tracker-helpers.ts, so `git -C <worktree> push` from the primary checkout counts.
+const GIT_FLAGS = "git\\s+(?:-\\S+(?:\\s+\\S+)?\\s+)*";
+const SHIP_RE = new RegExp(STMT_START + "(" + GIT_FLAGS + "(?:merge\\s+--squash|push)(?=\\s|$)|gh\\s+pr\\s+create)");
+const DISCARD_RE = new RegExp(STMT_START + "(" + GIT_FLAGS + "(?:worktree\\s+remove|branch\\s+-D)(?=\\s|$))");
+const SQUASH_RE = new RegExp("^" + GIT_FLAGS + "merge\\s+--squash");
 const STATEMENT_END = /\n|;|&&|\|\||\|/;
 
 export const truncateCommand = (s: string): string => (s.length > 120 ? s.slice(0, 120) : s);
@@ -59,7 +63,7 @@ export type ShipOption = "squash" | "pr";
 export function matchShipStatement(command: string): { option: ShipOption; statement: string } | undefined {
   const statement = statementAt(command, SHIP_RE);
   if (!statement) return undefined;
-  return { option: /^git\s+merge\s+--squash/.test(statement) ? "squash" : "pr", statement };
+  return { option: SQUASH_RE.test(statement) ? "squash" : "pr", statement };
 }
 
 export const matchDiscardStatement = (command: string): string | undefined => statementAt(command, DISCARD_RE);

package/extensions/phase-tracker.test.ts

@@ -1,6 +1,7 @@
 import assert from "node:assert/strict";
 import { after, test } from "node:test";
-import { mkdtempSync, mkdirSync, writeFileSync, rmSync, readFileSync } from "node:fs";
+import { execFileSync } from "node:child_process";
+import { mkdtempSync, mkdirSync, writeFileSync, rmSync, readFileSync, realpathSync } from "node:fs";
 import { createHash } from "node:crypto";
 import { tmpdir } from "node:os";
 import { isAbsolute, join } from "node:path";
@@ -26,6 +27,18 @@ const tempCwd = (settings?: unknown) => {
   return dir;
 };
 
+// Primary checkout with one linked worktree at .worktrees/x. Real git: plan_check and Guard 2
+// resolve checkouts with gitSync, and macOS temp paths need realpath to compare toplevels.
+const gitPrimary = () => {
+  const primary = realpathSync(tempCwd());
+  const git = (...args: string[]) => execFileSync("git", ["-C", primary, ...args], { stdio: "pipe" });
+  git("init", "-q");
+  git("-c", "user.email=t@example.com", "-c", "user.name=t", "commit", "-q", "--allow-empty", "-m", "init");
+  mkdirSync(join(primary, "doc"));
+  git("worktree", "add", "-q", join(primary, ".worktrees", "x"), "-b", "x");
+  return { primary, worktree: join(primary, ".worktrees", "x") };
+};
+
 const PHASES = ["brainstorm", "plan", "implement", "verify", "ship"] as const;
 type Phase = (typeof PHASES)[number];
 type Status = "pending" | "in_progress" | "complete" | "skipped";
@@ -720,7 +733,7 @@ const FIXTURE_SPEC = [
 
 const FIXTURE_PLAN = `# Fixture Plan
 
-**Spec:** \`spec.md\`
+**Spec:** \`doc/specs/spec.md\`
 
 **Verification:** npm test
 
@@ -772,8 +785,10 @@ function writePlanFixture(
 ) {
   const planText = opts.mutatePlan ? opts.mutatePlan(FIXTURE_PLAN) : FIXTURE_PLAN;
   const specText = opts.mutateSpec ? opts.mutateSpec(FIXTURE_SPEC) : FIXTURE_SPEC;
-  const planPath = join(dir, "plan.md");
-  const specPath = join(dir, "spec.md");
+  const planPath = join(dir, "doc/plans/plan.md");
+  const specPath = join(dir, "doc/specs/spec.md");
+  mkdirSync(join(dir, "doc/plans"), { recursive: true });
+  mkdirSync(join(dir, "doc/specs"), { recursive: true });
   writeFileSync(planPath, planText);
   writeFileSync(specPath, specText);
   writeFileSync(join(dir, "file-a.ts"), "// a\n");
@@ -793,8 +808,45 @@ test("plan_check is registered", () => {
   assert.ok(h.tools.some((t) => t.name === "plan_check"));
 });
 
-test("plan_check pass: text, details, and stamp arming when a flow is entered", async () => {
+test("plan_check roots at the plan's checkout: worktree plan passes from <primary>/doc (AC 1)", async () => {
+  const { primary, worktree } = gitPrimary();
+  const { planPath } = writePlanFixture(worktree);
+  const h = harness({ cwd: join(primary, "doc") });
+  await h.emit("session_start");
+  const tool = h.tools.find((t) => t.name === "plan_check")!;
+  const res = (await tool.execute("t1", { planPath }, undefined, undefined, h.ctx)) as { content: { text: string }[]; details: { status: string; specPath: string } };
+  assert.match(res.content[0].text, /^PASS/);
+  assert.equal(res.details.specPath, join(worktree, "doc/specs/spec.md"));
+});
+
+test("plan_check outside any checkout: input finding", async () => {
   const dir = tempCwd();
+  const { planPath } = writePlanFixture(dir);
+  const h = harness({ cwd: dir });
+  await h.emit("session_start");
+  const tool = h.tools.find((t) => t.name === "plan_check")!;
+  const res = (await tool.execute("t1", { planPath }, undefined, undefined, h.ctx)) as { content: { text: string }[]; details: { status: string } };
+  assert.equal(res.details.status, "fail");
+  assert.match(res.content[0].text, /input @ line 0: plan is not inside a git checkout/);
+});
+
+const bashCall = (id: string, command: string) => ({ toolName: "bash", toolCallId: id, input: { command } });
+const blocked = (results: unknown[]) => (results[0] as { block?: boolean } | undefined)?.block === true;
+
+test("Guard 2 evaluates the command's target checkout (AC 3)", async () => {
+  const { primary, worktree } = gitPrimary();
+  const h = harness({ cwd: join(primary, "doc"), branch: [phaseResult("start", phases({ brainstorm: "in_progress" }))] });
+  await h.emit("session_start");
+  assert.ok(blocked(await h.emitEvent("tool_call", bashCall("b1", "git switch -c y"))), "bare switch from <primary>/doc blocks");
+  assert.ok(blocked(await h.emitEvent("tool_call", bashCall("b2", `git -C ${primary} switch -c y`))), "-C <primary> blocks");
+  assert.ok(!blocked(await h.emitEvent("tool_call", bashCall("b3", `git -C ${worktree} switch -c y`))), "-C <worktree> passes");
+  assert.ok(!blocked(await h.emitEvent("tool_call", bashCall("b4", `cd ${worktree} && git checkout -b y`))), "cd <worktree> passes");
+  assert.ok(!blocked(await h.emitEvent("tool_call", bashCall("b5", "git -C /nonexistent/dir switch -c y"))), "unresolvable target passes");
+  assert.ok(!blocked(await h.emitEvent("tool_call", bashCall("b6", "git worktree add .worktrees/y -b y"))), "git worktree is exempt");
+});
+
+test("plan_check pass: text, details, and stamp arming when a flow is entered", async () => {
+  const dir = gitPrimary().primary;
   const { planPath, specPath, planText, specText } = writePlanFixture(dir);
   const h = harness({ cwd: dir, branch: readyForImplementBranch });
   await h.emit("session_start");
@@ -824,7 +876,7 @@ test("plan_check pass: text, details, and stamp arming when a flow is entered",
 });
 
 test("plan_check pass outside a flow: no stamp, plain-linter text", async () => {
-  const dir = tempCwd();
+  const dir = gitPrimary().primary;
   const { planPath } = writePlanFixture(dir);
   const h = harness({ cwd: dir });
   await h.emit("session_start");
@@ -834,7 +886,7 @@ test("plan_check pass outside a flow: no stamp, plain-linter text", async () =>
 });
 
 test("plan_check fail: mutated plan body, no error key, clears stamp", async () => {
-  const dir = tempCwd();
+  const dir = gitPrimary().primary;
   const { planPath } = writePlanFixture(dir, {
     mutatePlan: (t) => t.replace("implements helperFn() for parsing.", "implements the helper for parsing."),
   });
@@ -857,9 +909,9 @@ test("plan_check fail: mutated plan body, no error key, clears stamp", async ()
 });
 
 test("plan_check fail: unresolvable spec path", async () => {
-  const dir = tempCwd();
+  const dir = gitPrimary().primary;
   const { planPath } = writePlanFixture(dir, {
-    mutatePlan: (t) => t.replace("**Spec:** `spec.md`", "**Spec:** `missing-spec.md`"),
+    mutatePlan: (t) => t.replace("**Spec:** `doc/specs/spec.md`", "**Spec:** `missing-spec.md`"),
   });
   const h = harness({ cwd: dir, branch: readyForImplementBranch });
   await h.emit("session_start");
@@ -881,11 +933,11 @@ test("plan_check fail: unresolvable spec path", async () => {
 });
 
 test("plan_check fail: header **Spec:** extraction is confined to the header (a path-only-looking line below the separator does not count)", async () => {
-  const dir = tempCwd();
+  const dir = gitPrimary().primary;
   const { planPath } = writePlanFixture(dir, {
     mutatePlan: (t) =>
       t
-        .replace("**Spec:** `spec.md`\n\n", "")
+        .replace("**Spec:** `doc/specs/spec.md`\n\n", "")
         .replace(
           "## Wave 1 - Two parallel tasks",
           "## Wave 1 - Two parallel tasks\n\n**Spec:** `not-the-header-spec.md`\n",
@@ -907,9 +959,9 @@ test("plan_check fail: header **Spec:** extraction is confined to the header (a
 });
 
 test("plan_check fail: plan header has no path-only **Spec:** line at all", async () => {
-  const dir = tempCwd();
+  const dir = gitPrimary().primary;
   const { planPath } = writePlanFixture(dir, {
-    mutatePlan: (t) => t.replace("**Spec:** `spec.md`\n\n", ""),
+    mutatePlan: (t) => t.replace("**Spec:** `doc/specs/spec.md`\n\n", ""),
   });
   const h = harness({ cwd: dir, branch: readyForImplementBranch });
   await h.emit("session_start");
@@ -942,7 +994,7 @@ test("implement-start gate: rejects with no stamp, names plan_check remedy", asy
 });
 
 test("implement-start gate: stale plan bytes rejected, names the stale file", async () => {
-  const dir = tempCwd();
+  const dir = gitPrimary().primary;
   const { planPath } = writePlanFixture(dir);
   const h = harness({ cwd: dir, branch: readyForImplementBranch });
   await h.emit("session_start");
@@ -958,7 +1010,7 @@ test("implement-start gate: stale plan bytes rejected, names the stale file", as
 });
 
 test("implement-start gate: stale spec bytes rejected, names the stale file", async () => {
-  const dir = tempCwd();
+  const dir = gitPrimary().primary;
   const { planPath, specPath } = writePlanFixture(dir);
   const h = harness({ cwd: dir, branch: readyForImplementBranch });
   await h.emit("session_start");
@@ -974,7 +1026,7 @@ test("implement-start gate: stale spec bytes rejected, names the stale file", as
 });
 
 test("implement-start gate: missing stamped file rejected, names the missing path", async () => {
-  const dir = tempCwd();
+  const dir = gitPrimary().primary;
   const { planPath } = writePlanFixture(dir);
   const h = harness({ cwd: dir, branch: readyForImplementBranch });
   await h.emit("session_start");
@@ -1002,7 +1054,7 @@ test("implement-start gate: enforce false skips the gate entirely", async () =>
 });
 
 test("replay: a passing plan_check result restores the stamp without re-running the tool", async () => {
-  const dir = tempCwd();
+  const dir = gitPrimary().primary;
   const { planPath, specPath } = writePlanFixture(dir);
   const passDetails = {
     status: "pass",
@@ -1022,7 +1074,7 @@ test("replay: a passing plan_check result restores the stamp without re-running
 });
 
 test("replay: pass then fail clears the stamp", async () => {
-  const dir = tempCwd();
+  const dir = gitPrimary().primary;
   const { planPath, specPath } = writePlanFixture(dir);
   const passDetails = {
     status: "pass",
@@ -1045,7 +1097,7 @@ test("replay: pass then fail clears the stamp", async () => {
 });
 
 test("replay: a plan_check pass observed before any flow entry does not arm the stamp, and a live walk with no live plan_check is rejected", async () => {
-  const dir = tempCwd();
+  const dir = gitPrimary().primary;
   const { planPath, specPath } = writePlanFixture(dir);
   const passDetails = {
     status: "pass",
@@ -1070,7 +1122,7 @@ test("replay: a plan_check pass observed before any flow entry does not arm the
 });
 
 test("replay: a phase_tracker reset clears the stamp", async () => {
-  const dir = tempCwd();
+  const dir = gitPrimary().primary;
   const { planPath, specPath } = writePlanFixture(dir);
   const passDetails = {
     status: "pass",
@@ -1097,7 +1149,7 @@ test("replay: a phase_tracker reset clears the stamp", async () => {
 });
 
 test("replay via session_fork: a passing plan_check result restores the stamp without re-running the tool", async () => {
-  const dir = tempCwd();
+  const dir = gitPrimary().primary;
   const { planPath, specPath } = writePlanFixture(dir);
   const passDetails = {
     status: "pass",
@@ -1124,7 +1176,7 @@ test("replay via session_fork: a passing plan_check result restores the stamp wi
 });
 
 test("replay via session_tree: a passing plan_check result restores the stamp without re-running the tool", async () => {
-  const dir = tempCwd();
+  const dir = gitPrimary().primary;
   const { planPath, specPath } = writePlanFixture(dir);
   const passDetails = {
     status: "pass",
@@ -1152,7 +1204,7 @@ test("replay via session_tree: a passing plan_check result restores the stamp wi
 });
 
 test("replay via session_switch: pass then fail clears the stamp, rebuilt from replay rather than a live run", async () => {
-  const dir = tempCwd();
+  const dir = gitPrimary().primary;
   const { planPath, specPath } = writePlanFixture(dir);
   const passDetails = {
     status: "pass",