pi-gauntlet 5.9.0 → 5.9.1

package/extensions/phase-tracker.ts

@@ -9,7 +9,6 @@
  * Use phase_tracker for "what stage am I in?", plan_tracker for "which task?".
  */
 
-import { execSync } from "node:child_process";
 import { existsSync, globSync, readdirSync, readFileSync, readFileSync as readFileBytes } from "node:fs";
 import { isAbsolute, join, resolve } from "node:path";
 import { StringEnum } from "@earendil-works/pi-ai";
@@ -25,6 +24,7 @@ import {
   settingsErrorWarning,
 } from "./lib/gauntlet-settings.ts";
 import { loadGauntletSettings } from "./lib/gauntlet-settings-loader.ts";
+import { checkoutOf, gitSync } from "./lib/checkout.ts";
 import { checkPlan, sha256, type FsPort, type PlanCheckFinding } from "./lib/plan-check.ts";
 import {
   checkSubstep,
@@ -34,6 +34,7 @@ import {
   implementWriteGuardApplies,
   markerBlockReason,
   nextGauntletEntered,
+  parseGitCommand,
   parseGitCommit,
   phaseLabel,
   recoverableEdge,
@@ -159,8 +160,8 @@ const GUARD_PHASES: Phase[] = ["brainstorm", "plan", "implement"];
 // Guard 2 — branch ops in place. `git switch` never targets a file path;
 // `git checkout -b/-B` is explicit branch creation. Bare `git checkout <x>`
 // is excluded (ambiguous with file checkout). `git worktree ...` is exempt.
-const BRANCH_SWITCH = new RegExp(STMT_START + "git\\s+switch\\b");
-const BRANCH_CHECKOUT = new RegExp(STMT_START + "git\\s+checkout\\s+-[bB]\\b");
+const SWITCH_SUB = /switch(?=\s|$)/;
+const CHECKOUT_BRANCH_SUB = /checkout\s+-[bB](?=\s|$)/;
 const GIT_WORKTREE = /\bgit\s+worktree\b/;
 
 // Guard 3 — bash mutation forms during brainstorm.
@@ -394,21 +395,6 @@ export default function (pi: ExtensionAPI) {
   // implementer's first write would trip a spurious advisory.
   const isSubagentChild = Number(process.env.PI_SUBAGENT_DEPTH ?? "0") > 0;
 
-  const inPrimaryCheckout = (() => {
-    try {
-      const lines = execSync("git rev-parse --git-dir --git-common-dir", {
-        encoding: "utf8",
-        stdio: ["ignore", "pipe", "ignore"],
-        timeout: 5000,
-      })
-        .trim()
-        .split("\n");
-      return lines.length === 2 && lines[0] === lines[1];
-    } catch {
-      return false;
-    }
-  })();
-
   // Auto-complete the implement phase from plan_tracker once every task is done,
   // but only when a skill has explicitly started it (TDD, or the SDD
   // execution preamble). The tracker never *fabricates* implement from task activity:
@@ -630,15 +616,16 @@ export default function (pi: ExtensionAPI) {
 
     const warnings: string[] = [];
 
-    // Guard 2 — branch op in place (primary checkout only, brainstorm/plan/implement).
+    // Guard 2 - branch op in the primary checkout (brainstorm/plan/implement). The target
+    // is the command's own -C / leading-cd dir, else the session cwd; a linked worktree
+    // target passes, an unresolvable one passes (the guard protects the primary only).
     const gphase = activeGuardPhase();
-    if (
-      inPrimaryCheckout &&
-      gphase &&
-      !GIT_WORKTREE.test(command) &&
-      (BRANCH_SWITCH.test(command) || BRANCH_CHECKOUT.test(command))
-    ) {
-      return { block: true, reason: branchBlockReason(gphase) };
+    if (gphase && !GIT_WORKTREE.test(command)) {
+      const form = parseGitCommand(command, SWITCH_SUB) ?? parseGitCommand(command, CHECKOUT_BRANCH_SUB);
+      if (form) {
+        const target = resolveRepoDir(form, ctx.cwd);
+        if ((await checkoutOf(target, gitSync))?.isPrimary === true) return { block: true, reason: branchBlockReason(gphase) };
+      }
     }
 
     // Marker commit guard — the context draft (brainstorming gather step) must be
@@ -805,6 +792,10 @@ export default function (pi: ExtensionAPI) {
         } catch {
           return fail([{ check: "input", line: 0, text: "", reason: `plan file unreadable at ${planAbs}` }], planAbs);
         }
+        const root = (await checkoutOf(planAbs, gitSync))?.toplevel;
+        if (!root) {
+          return fail([{ check: "input", line: 0, text: "", reason: "plan is not inside a git checkout" }], planAbs);
+        }
         const planText = planBytes.toString("utf8");
         const planLines = planText.split("\n");
         const planSeparatorIdx = planLines.findIndex((l) => l.trim() === "---");
@@ -820,7 +811,7 @@ export default function (pi: ExtensionAPI) {
             planAbs,
           );
         }
-        const specAbs = isAbsolute(specPathRaw) ? specPathRaw : resolve(ctx.cwd, specPathRaw);
+        const specAbs = isAbsolute(specPathRaw) ? specPathRaw : resolve(root, specPathRaw);
         let specBytes: Buffer;
         try {
           specBytes = readFileBytes(specAbs);
@@ -829,8 +820,8 @@ export default function (pi: ExtensionAPI) {
         }
         const specText = specBytes.toString("utf8");
         const port: FsPort = {
-          exists: (p) => existsSync(resolve(ctx.cwd, p)),
-          glob: (pattern) => globSync(pattern, { cwd: ctx.cwd }),
+          exists: (p) => existsSync(resolve(root, p)),
+          glob: (pattern) => globSync(pattern, { cwd: root }),
         };
         const findings = checkPlan(planText, specText, port);
         if (findings.length > 0) return fail(findings, planAbs);

package/extensions/telemetry.test.ts

@@ -20,13 +20,15 @@
 
   type Handler = (event: any, ctx: any) => unknown;
 
-  function harness(o: { branch?: unknown[]; enabled?: boolean; gitFail?: (args: string[]) => GitResult | undefined; cwdSub?: string; sessionId?: string; model?: { provider: string; id: string }; thinkingLevel?: string; contextTokens?: number | null; telemetryWarning?: string; telemetryDir?: string } = {}) {
+  function harness(o: { branch?: unknown[]; enabled?: boolean; gitFail?: (args: string[], cwd: string) => GitResult | undefined; cwdSub?: string; sessionId?: string; model?: { provider: string; id: string }; thinkingLevel?: string; contextTokens?: number | null; telemetryWarning?: string; telemetryDir?: string } = {}) {
     const root = mkdtempSync(join(tmpdir(), "telemetry-test-"));
     tempDirs.push(root);
     mkdirSync(join(root, "doc/specs"), { recursive: true });
     mkdirSync(join(root, "doc/plans"), { recursive: true });
+    mkdirSync(join(root, ".worktrees/x/doc/specs"), { recursive: true });
     const handlers = new Map<string, Handler[]>();
     const gitCalls: string[][] = [];
+    const gitCwds: string[] = [];
     const readFileCalls: string[] = [];
     let clock = Date.parse("2026-09-17T10:00:00Z");
     const deps: Deps = {
@@ -34,11 +36,15 @@
       now: () => new Date((clock += 1000)).toISOString().replace(/\.\d{3}Z$/, "Z"),
       git: async (args, cwd) => {
         gitCalls.push(args);
-        const forced = o.gitFail?.(args);
+        gitCwds.push(cwd);
+        const forced = o.gitFail?.(args, cwd);
         if (forced) return forced;
-        if (args[0] === "rev-parse" && args.includes("--show-toplevel")) {
-          const toplevel = o.cwdSub && cwd === join(root, o.cwdSub) ? root : cwd;
-          return { code: 0, stdout: toplevel + "\n", stderr: "" };
+        if (args[0] === "rev-parse" && args.includes("--path-format=absolute")) {
+          const wt = /^(.*\/\.worktrees\/[^/]+)(\/|$)/.exec(cwd)?.[1];
+          const primary = cwd === root || cwd.startsWith(root + "/") ? root : cwd.replace(/\/(?:doc|\.pi)(?:\/.*)?$/, "");
+          const toplevel = wt ?? primary;
+          const gitDir = wt ? `${primary}/.git/worktrees/${wt.split("/").pop()}` : `${primary}/.git`;
+          return { code: 0, stdout: `${toplevel}\n${gitDir}\n${primary}/.git\n`, stderr: "" };
         }
         if (args[0] === "rev-parse" && args.includes("--abbrev-ref")) return { code: 0, stdout: "gh-33\n", stderr: "" };
         if (args[0] === "config") return { code: 0, stdout: (args[1] === "user.name" ? "Tester" : "t@example.com") + "\n", stderr: "" };
@@ -71,7 +77,7 @@
       await emit("tool_call", { toolName: "write", toolCallId: "w", input: { path: rel, content: body } });
       return emit("tool_result", { toolName: "write", toolCallId: "w", input: { path: rel, content: body }, content: [], isError: false, details: undefined });
     };
-    return { root, handlers, emit, gitCalls, readFileCalls, commits, recordPath, readRecord, phaseResult, writeSpec, setBranch: (b: unknown[]) => (branch = b), ctx };
+    return { root, handlers, emit, gitCalls, gitCwds, readFileCalls, commits, recordPath, readRecord, phaseResult, writeSpec, setBranch: (b: unknown[]) => (branch = b), ctx };
   }
 
   const P = (over: Record<string, string> = {}) => Object.fromEntries(["brainstorm", "plan", "implement", "verify", "ship"].map((p) => [p, { status: over[p] ?? "pending" }]));
@@ -265,12 +271,47 @@
     fail = false;
     await h.phaseResult("complete", P({ brainstorm: "complete" }));
     assert.equal(h.commits().length, 2);
-    const nogit = harness({ gitFail: (args) => (args[0] === "rev-parse" ? { code: 128, stdout: "", stderr: "fatal: not a git repository" } : undefined) });
+    const outside = mkdtempSync(join(tmpdir(), "telemetry-outside-"));
+    tempDirs.push(outside);
+    const outsideSpec = join(outside, "doc/specs/outside.md");
+    const nogit = harness({ gitFail: (args, cwd) => (args[0] === "rev-parse" && cwd.startsWith(outside) ? { code: 128, stdout: "", stderr: "fatal: not a git repository" } : undefined) });
     await nogit.phaseResult("start", P({ brainstorm: "in_progress" }));
+    await nogit.emit("tool_result", { toolName: "write", toolCallId: "outside", input: { path: outsideSpec }, content: [], isError: false, details: undefined });
     await nogit.writeSpec("doc/specs/a.md");
-    rec = nogit.readRecord();
-    assert.equal(nogit.commits().length, 0);
-    assert.equal(rec.events.filter((e) => e.kind === "warning").length, 1);
+    assert.deepEqual(nogit.readRecord().events.filter((e) => e.kind === "warning").map((e: any) => e.message), [`spec ${outsideSpec} is outside a git checkout; telemetry not recorded`]);
+  });
+
+  test("worktree spec from a primary cwd: record keyed under the worktree, committed there (AC 8)", async () => {
+    const h = harness();
+    await h.emit("session_start", { type: "session_start", reason: "startup" });
+    await h.phaseResult("start", P({ brainstorm: "in_progress" }));
+    await h.writeSpec(".worktrees/x/doc/specs/a.md");
+    const wt = join(h.root, ".worktrees/x");
+    assert.ok(existsSync(join(wt, ".pi/gauntlet/telemetry/doc/specs/a.yaml")), "record lives under the worktree toplevel");
+    assert.equal(existsSync(join(h.root, ".pi/gauntlet")), false, "nothing written under the primary checkout");
+    assert.ok(h.gitCwds.every((c) => c === wt || c.startsWith(wt + "/")), "no git call runs in the primary");
+    const commitIdx = h.gitCalls.findIndex((a) => a[0] === "commit");
+    assert.ok(commitIdx >= 0);
+    assert.equal(h.gitCwds[commitIdx], wt);
+    assert.deepEqual(h.gitCalls[commitIdx].slice(-1), [".pi/gauntlet/telemetry/doc/specs/a.yaml"]);
+  });
+
+  test("a spec in another checkout is a fresh bind, never a git mv", async () => {
+    for (const tool of ["write", "edit"] as const) {
+      const h = harness();
+      await h.phaseResult("start", P({ brainstorm: "in_progress" }));
+      await h.writeSpec(".worktrees/x/doc/specs/a.md", "# CONTEXT DRAFT - NOT A SPEC - fully replaced at spec-writing\n");
+      if (tool === "write") {
+        await h.writeSpec("doc/specs/a.md");
+      } else {
+        writeFileSync(join(h.root, "doc/specs/a.md"), "# Spec\n");
+        await h.emit("tool_result", { toolName: "edit", toolCallId: "e", input: { path: "doc/specs/a.md", oldText: "# Old\n", newText: "# Spec\n" }, content: [], isError: false, details: undefined });
+      }
+      assert.ok(existsSync(h.recordPath("doc/specs/a.md")), `primary record created for ${tool}`);
+      assert.ok(existsSync(join(h.root, ".worktrees/x/.pi/gauntlet/telemetry/doc/specs/a.yaml")), `worktree record left in place for ${tool}`);
+      assert.equal(h.gitCalls.some((a) => a[0] === "mv"), false);
+      assert.equal(h.readRecord("doc/specs/a.md").events.some((e) => e.kind === "spec_renamed"), false);
+    }
   });
 
   test("second session rehydrates all derived accumulators with exactly total and live blocks", async () => {

package/extensions/telemetry.ts

@@ -9,12 +9,13 @@
   import { execFile } from "node:child_process";
   import { randomUUID } from "node:crypto";
   import * as nodeFs from "node:fs";
-  import { dirname, join, posix } from "node:path";
+  import { dirname, isAbsolute, join, posix, resolve } from "node:path";
   import * as piRuntime from "@earendil-works/pi-coding-agent";
   import { SettingsManager, getAgentDir } from "@earendil-works/pi-coding-agent";
   import type { ExtensionAPI, ExtensionContext } from "@earendil-works/pi-coding-agent";
   import { DEFAULT_TEST_COMMANDS, resolveTelemetry, settingsErrorWarning, type TelemetryResolved } from "./lib/gauntlet-settings.ts";
   import { loadGauntletSettings } from "./lib/gauntlet-settings-loader.ts";
+  import { checkoutOf } from "./lib/checkout.ts";
   import { CONTEXT_DRAFT_MARKER } from "./lib/phase-tracker-helpers.ts";
   import { sha256 } from "./lib/plan-check.ts";
   import { SUPERSEDED_BY_RE, aggregateNumstat, isPlanPath, isSpecPath, isSupersededByBanner, matchDiscardStatement, matchShipStatement, matchTestStatement, parseSpecLinks, planSpecHeader, recordPathFor, repoRelativeToolPath, toPosix, truncateCommand } from "./lib/telemetry-paths.ts";
@@ -100,9 +101,9 @@
   }
 
   function realSettings(cwd: string): SettingsSnapshot {
-    const { gauntlet, errors } = loadGauntletSettings(cwd);
+    const { gauntlet, errors, root } = loadGauntletSettings(cwd);
     const telemetry = resolveTelemetry(gauntlet);
-    const sm = SettingsManager.create(cwd, getAgentDir());
+    const sm = SettingsManager.create(root, getAgentDir());
     const layer = (s: unknown) => ((s as { subagents?: { agentOverrides?: unknown } })?.subagents?.agentOverrides ?? undefined) as Record<string, unknown> | undefined;
     const preset = layer(sm.getGlobalSettings());
     const repo = layer(sm.getProjectSettings());
@@ -158,8 +159,7 @@
 
   export default function (pi: ExtensionAPI, deps: Deps = realDeps) {
     let phases: PhaseMap = emptyPhases();
-    let toplevel: string | undefined;
-    let inGit = false;
+    let toplevel: string | undefined; // toplevel of the bound record's checkout; undefined until bind
     let boundSpec: string | undefined; // repo-relative
     let record: TelemetryRecord | undefined;
     const predecessorLinks = new Set<string>();
@@ -180,12 +180,13 @@
       return s;
     };
 
-    const ensureToplevel = async (ctx: ExtensionContext): Promise<string> => {
-      if (toplevel) return toplevel;
-      const r = await deps.git(["rev-parse", "--show-toplevel"], ctx.cwd);
-      inGit = r.code === 0 && r.stdout.trim() !== "";
-      toplevel = inGit ? r.stdout.trim() : ctx.cwd;
-      return toplevel;
+    // Resolves a tool path (relative to ctx.cwd or absolute) to its owning checkout and
+    // checkout-relative key. undefined outside any checkout.
+    const locate = async (ctx: ExtensionContext, p: string): Promise<{ toplevel: string; rel: string } | undefined> => {
+      const candidateAbs = isAbsolute(p) ? p : resolve(ctx.cwd, p);
+      const co = await checkoutOf(candidateAbs, deps.git);
+      const rel = co ? repoRelativeToolPath(co.toplevel, ctx.cwd, p) : undefined;
+      return co && rel ? { toplevel: co.toplevel, rel } : undefined;
     };
 
     const live = (): Accumulators => record
@@ -228,7 +229,7 @@
     };
 
     const commitRecord = async () => {
-      if (!record || !recordRel || frozen || !inGit) return;
+      if (!record || !recordRel || frozen || !toplevel) return;
       const text = deps.fs.readFile(abs(recordRel)) ?? "";
       if (text === lastCommitted) return;
       const paths = [recordRel, ...(oldRecordRel ? [oldRecordRel] : [])];
@@ -273,7 +274,8 @@
       return newRecord({ spec: specRel, session: sessionId, now: buffer[0]?.ts ?? deps.now(), runId: randomUUID() });
     };
 
-    const bind = async (specRel: string, snap: SettingsSnapshot) => {
+    const bind = async (specRel: string, snap: SettingsSnapshot, specToplevel: string) => {
+      toplevel = specToplevel;
       currentDir = snap.telemetry.dir;
       boundSpec = specRel;
       recordRel = recordPathFor(currentDir, specRel);
@@ -302,7 +304,6 @@
       const approval = record.events.find((e) => e.kind === "phase" && e.name === "brainstorm" && (e.action === "complete" || e.action === "skip"));
       if (approval) record.approved_at ??= approval.ts;
       buffer = [];
-      if (!inGit) warn("not a git repository: record is written but never committed");
       if (!settingsWarned && (snap.errors.length || snap.telemetry.warning)) {
         settingsWarned = true;
         if (snap.errors.length) warn(settingsErrorWarning(snap.errors));
@@ -312,6 +313,7 @@
     };
 
     const unbind = () => {
+      toplevel = undefined;
       boundSpec = undefined;
       record = undefined;
       recordRel = undefined;
@@ -347,8 +349,8 @@
         warn(`record move skipped: ${to} already exists`);
         return false;
       }
-      const trackedResult = inGit ? await deps.git(["ls-files", "--error-unmatch", "--", from], toplevel!) : undefined;
-      const tracked = trackedResult?.code === 0 && trackedResult.stdout.trim() !== "";
+      const trackedResult = await deps.git(["ls-files", "--error-unmatch", "--", from], toplevel!);
+      const tracked = trackedResult.code === 0 && trackedResult.stdout.trim() !== "";
       try {
         deps.fs.mkdirp(dirname(abs(to)));
         if (tracked) {
@@ -408,14 +410,13 @@
       const snap = enabledSettings(ctx);
       if (!snap) return;
       sessionId = ctx.sessionManager.getSessionId();
-      await ensureToplevel(ctx);
       currentDir = snap.telemetry.dir;
       const replay = replayBranch(ctx.sessionManager.getBranch());
       phases = replay.phases;
       const candidate = replay.planCheckSpec ?? replay.lastSpecWrite;
-      const rel = candidate ? repoRelativeToolPath(toplevel!, ctx.cwd, candidate) : undefined;
-      if (rel && isSpecPath(rel)) {
-        await bind(rel, snap);
+      const loc = candidate ? await locate(ctx, candidate) : undefined;
+      if (loc && isSpecPath(loc.rel)) {
+        await bind(loc.rel, snap, loc.toplevel);
         await flush(false);
       }
     });
@@ -436,19 +437,20 @@
       const snap = enabledSettings(ctx);
       if (!snap) return undefined;
       if (!sessionId) sessionId = ctx.sessionManager.getSessionId();
-      await ensureToplevel(ctx);
       if (event.toolName === "phase_tracker" && !event.isError) {
         await applyPhaseDetails(event.details as never, snap);
         return undefined;
       }
       if (event.toolName === "plan_check" && !event.isError) {
         const d = event.details as { status?: string; specPath?: string; planPath?: string } | undefined;
-        const spec = d?.specPath ? repoRelativeToolPath(toplevel!, ctx.cwd, d.specPath) : undefined;
-        const plan = d?.planPath ? repoRelativeToolPath(toplevel!, ctx.cwd, d.planPath) : undefined;
+        const specLoc = d?.specPath ? await locate(ctx, d.specPath) : undefined;
+        const planLoc = d?.planPath ? await locate(ctx, d.planPath) : undefined;
+        const spec = specLoc?.rel;
+        const plan = planLoc?.rel;
         const pass = d?.status === "pass";
-        if (pass && spec && spec !== boundSpec) {
+        if (pass && specLoc && (specLoc.rel !== boundSpec || specLoc.toplevel !== toplevel)) {
           if (record) unbind();
-          await bind(spec, snap);
+          await bind(specLoc.rel, snap, specLoc.toplevel);
         }
         live().gates.plan_rounds += 1;
         pushEvent({ kind: "plan_check", pass, spec, plan });
@@ -457,9 +459,12 @@
       }
       if ((event.toolName === "write" || event.toolName === "edit" || event.toolName === "read") && !event.isError) {
         const rawPath = (event.input as { path?: unknown }).path;
-        const rel = typeof rawPath === "string" ? repoRelativeToolPath(toplevel!, ctx.cwd, rawPath) : undefined;
-        if (!rel) return undefined;
-        return onSpecInteraction(event.toolName, rel, event, snap);
+        const loc = typeof rawPath === "string" ? await locate(ctx, rawPath) : undefined;
+        if (!loc) {
+          if (typeof rawPath === "string" && isSpecPath(toPosix(rawPath))) warn(`spec ${rawPath} is outside a git checkout; telemetry not recorded`);
+          return undefined;
+        }
+        return onSpecInteraction(event.toolName, loc, event, snap);
       }
       if (event.toolName === "subagent" && !event.isError) {
         await onSubagentResult(event.details, event.content);
@@ -493,23 +498,35 @@
     });
 
     // Binding + spec-write bookkeeping; the bound-spec hooks are defined in block 2.
-    const onSpecInteraction = async (tool: "write" | "edit" | "read", rel: string, event: { input: unknown; content: unknown[] }, snap: SettingsSnapshot): Promise<unknown> => {
+    const onSpecInteraction = async (tool: "write" | "edit" | "read", loc: { toplevel: string; rel: string }, event: { input: unknown; content: unknown[] }, snap: SettingsSnapshot): Promise<unknown> => {
+      const rel = loc.rel;
       if (!boundSpec) {
         if ((tool === "write" || tool === "edit") && isSpecPath(rel)) {
-          await bind(rel, snap);
+          await bind(rel, snap, loc.toplevel);
           const patch = onBoundSpecWrite(tool, rel, event);
           await flush(true);
           return patch;
         } else if (isPlanPath(rel)) {
-          const spec = planSpecHeader(deps.fs.readFile(abs(rel)) ?? "");
-          const specRel = spec ? repoRelativeToolPath(toplevel!, toplevel!, spec) : undefined;
-          if (specRel && deps.fs.exists(abs(specRel))) {
-            await bind(specRel, snap);
+          const spec = planSpecHeader(deps.fs.readFile(join(loc.toplevel, rel)) ?? "");
+          const specRel = spec ? repoRelativeToolPath(loc.toplevel, loc.toplevel, spec) : undefined;
+          if (specRel && deps.fs.exists(join(loc.toplevel, specRel))) {
+            await bind(specRel, snap, loc.toplevel);
             await flush(true);
           }
         }
         return undefined;
       }
+      if (loc.toplevel !== toplevel) {
+        // Another checkout: a fresh run, never a rename of this record.
+        if ((tool === "write" || tool === "edit") && isSpecPath(rel)) {
+          unbind();
+          await bind(rel, snap, loc.toplevel);
+          const patch = onBoundSpecWrite(tool, rel, event);
+          await flush(true);
+          return patch;
+        }
+        return undefined;
+      }
       if (tool === "read") return undefined;
       if (rel === boundSpec) {
         const patch = onBoundSpecWrite(tool, rel, event);
@@ -603,7 +620,7 @@
     let pendingShip: { id: string; option: "squash" | "pr" | "discard" } | undefined;
 
     const computeDiff = async (snap: SettingsSnapshot) => {
-      if (!record || !inGit) return;
+      if (!record || !toplevel) return;
       let baseRef: string | undefined;
       for (const ref of BASE_REFS) {
         if ((await deps.git(["rev-parse", "--verify", "--quiet", ref], toplevel!)).code === 0) {
@@ -665,13 +682,12 @@
       if (event.toolName === "write") {
         const rawPath = (event.input as { path?: unknown }).path;
         if (typeof rawPath === "string" && phases.brainstorm.status === "in_progress") {
-          await ensureToplevel(ctx);
-          const rel = repoRelativeToolPath(toplevel!, ctx.cwd, rawPath);
-          if (rel && isSpecPath(rel)) {
-            const recRel = recordPathFor(snap.telemetry.dir, rel);
-            const existing = deps.fs.readFile(join(toplevel!, recRel));
+          const loc = await locate(ctx, rawPath);
+          if (loc && isSpecPath(loc.rel)) {
+            const recRel = recordPathFor(snap.telemetry.dir, loc.rel);
+            const existing = deps.fs.readFile(join(loc.toplevel, recRel));
             const parsed = existing ? parseRecord(existing) : undefined;
-            if (parsed?.shipped_at) return { block: true, reason: guardReason(rel, parsed.shipped_at, recRel) };
+            if (parsed?.shipped_at) return { block: true, reason: guardReason(loc.rel, parsed.shipped_at, recRel) };
           }
         }
         return undefined;

package/extensions/verify-before-ship.test.ts

@@ -72,6 +72,22 @@ test("gh pr create warns when unverified", async () => {
   assert.match(warning ?? "", /ran without verification/);
 });
 
+test("git -C <worktree> push and merge --squash are ship events (AC 5)", async () => {
+  for (const cmd of ["git -C /p push -u origin HEAD", "git -C /p merge --squash f"]) {
+    const h = harness();
+    await editSource(h);
+    await h.emitEvent("tool_call", bashCall("s1", cmd));
+    assert.match(warningOf(await h.emitEvent("tool_result", bashResult("s1"))) ?? "", /ran without verification/, cmd);
+  }
+});
+
+test("a quoted mention of git push is not a ship event", async () => {
+  const h = harness();
+  await editSource(h);
+  await h.emitEvent("tool_call", bashCall("q1", 'rg "git push" skills/'));
+  assert.equal((await h.emitEvent("tool_result", bashResult("q1")))[0], undefined);
+});
+
 test("a passing recognised run clears the warning for push", async () => {
   const h = harness();
   await editSource(h);

package/extensions/verify-before-ship.ts

@@ -1,7 +1,8 @@
 /**
  * Verify-before-ship extension
  *
- * Single-session verification gate for shipping commands (git push / gh pr create).
+ * Single-session verification gate for statement-start shipping commands: git merge
+ * --squash, git push, and gh pr create (with any git global flags).
  * Local commits are not ship events; commit-time review-cadence advisories live in
  * phase-tracker. Tracks whether a recognised verification command has succeeded
  * since the last source-file write; injects an advisory warning into the tool
@@ -32,8 +33,7 @@ import {
   settingsErrorWarning,
 } from "./lib/gauntlet-settings.ts";
 import { loadGauntletSettings } from "./lib/gauntlet-settings-loader.ts";
-
-const SHIP_CMD = /\b(git\s+push|gh\s+pr\s+create)\b/;
+import { matchShipStatement } from "./lib/telemetry-paths.ts";
 
 const SOURCE_EXT = /\.(ts|tsx|js|jsx|py|rb|go|rs|java|swift|kt)$/;
 const TEST_PATH = /(^|\/)(tests?|__tests__)\/|\.(test|spec)\.|_test\.(py|go|rb)$/;
@@ -101,7 +101,7 @@ export default function (pi: ExtensionAPI) {
       return undefined;
     }
 
-    if (SHIP_CMD.test(command) && !verified) {
+    if (matchShipStatement(command) && !verified) {
       if (settingsWarned && !settingsErrShown) {
         addShipWarning(event.toolCallId, settingsWarned);
         settingsErrShown = true;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "pi-gauntlet",
-  "version": "5.9.0",
+  "version": "5.9.1",
   "description": "Opinionated, gated workflow skills, subagent personas, and runtime extensions for the pi coding agent.",
   "author": "Jacek Juraszek",
   "type": "module",

package/skills/brainstorming/SKILL.md

@@ -92,8 +92,8 @@ If the project's `AGENTS.md` calls out additional reading for a specific area (e
 The spec is the **first commit in a dedicated worktree**, not a separate commit on `main`. Before drafting any spec content:
 
 1. Invoke `/skill:using-git-worktrees`. Worktrees live under `.worktrees/` at the repo root, or wherever a project-native worktree script places them.
-2. Switch into the worktree.
-3. From there, write the spec, run self-review, commit, hand off.
+2. Carry the worktree path from the `using-git-worktrees` Step 4 report (`Worktree ready at <full-path>`) as a value: the spec path is `<full-path>/doc/specs/<filename>.md`, every dispatch below sets `cwd: "<full-path>"`, and git runs as `git -C <full-path> ...`. The process cwd stays where pi was launched.
+3. Write the spec at that path, run self-review, commit with `git -C <full-path>`, hand off.
 
 Spec doc, plan doc, and implementation are all developed in the same worktree; the squash ships the spec and the implementation, with the ephemeral plan stripped before landing (see `/skill:finishing-a-development-branch`).
 
@@ -103,6 +103,8 @@ Spec doc, plan doc, and implementation are all developed in the same worktree; t
 
 ### 1. Check git state
 
+Check git state in the primary checkout (the process cwd; no worktree exists yet):
+
 ```bash
 git status
 git --no-pager log --oneline -5
@@ -271,7 +273,7 @@ The first three checks — **placeholder scan**, **internal consistency**, and *
 - **Otherwise** → dispatch one fresh `worker` that applies the scope + ambiguity checks and fixes them in place:
 
   ```
-  subagent({ agent: "worker", context: "fresh", async: false, cwd: "<abs worktree path, from git rev-parse --show-toplevel>", task:
+  subagent({ agent: "worker", context: "fresh", async: false, cwd: "<abs worktree path, from the using-git-worktrees Step 4 report>", task:
     "Problem statement: <the problem the spec addresses + the user's stated intent>.\n" +
     "Read the spec at <abs path to doc/specs/...>. Edit ONLY that file. Apply two checks and\n" +
     "fix what you find in place: (1) Scope — does every paragraph serve the goal? Cut filler;\n" +
@@ -302,7 +304,7 @@ SUMMARY_PATH=$(mktemp "${TMPDIR:-/tmp}/gauntlet-spec-summary.XXXXXX")   # absolu
 ```
 
 ```
-subagent({ agent: "spec-summarizer", context: "fresh", async: false, cwd: "<abs worktree path, from git rev-parse --show-toplevel>",
+subagent({ agent: "spec-summarizer", context: "fresh", async: false, cwd: "<abs worktree path, from the using-git-worktrees Step 4 report>",
   output: "<SUMMARY_PATH>", outputMode: "file-only", task:
   "Summarize the spec at <abs path to doc/specs/...> for the user review gate. Read ONLY that file." })
 ```
@@ -354,7 +356,7 @@ phase_tracker({ action: "complete", phase: "brainstorm" })
 
 Execute this section in place from any later phase. Do not invoke `/skill:brainstorming` (its entry resets both trackers). Worktree, spec commits, and plan survive.
 
-1. Edit the spec. Show `git --no-pager diff -- <spec path>` and one line of impact (affected plan tasks / waves, or "no plan yet").
+1. Edit the spec. Show `git -C <abs worktree path> --no-pager diff -- <spec path>` and one line of impact (affected plan tasks / waves, or "no plan yet").
 2. Wait for approval. Change request -> revise, re-show.
 3. No plan yet -> commit the spec; continue. Plan exists -> update affected anchors and tasks: `plan_tracker` `add` for new tasks; anchor-changed completed tasks are reopened as `in_progress` and re-run the task loop (`update` never sets `pending`). A removed task is deleted from the plan; then re-`init` the tracker with `{ name, status }` elements: preserved tasks keep their order and statuses, reopened tasks are `in_progress` in place, every still-`pending` task (including newly added ones, whatever wave label they carry) trails the non-pending ones, removed tasks are the only deletions (the only permitted `init` after handoff; never `clear`). Re-run `plan_check` until it passes, commit spec + plan together; continue. A task reopened while `verify` or `ship` is in progress: `phase_tracker({ action: "skip", phase: "<current>", reason: "amendment reopened Task N" })`, then `phase_tracker({ action: "start", phase: "implement", force: true })`; later phases re-enter with `force: true` and rerun in full.