pi-gauntlet 6.0.0 → 6.0.1

package/bin/gauntlet-telemetry-seal.mjs

@@ -1,9 +1,9 @@
 #!/usr/bin/env node
 
 // src/bins/gauntlet-telemetry-seal.mjs
-import { existsSync, readFileSync, realpathSync, writeFileSync } from "node:fs";
+import { existsSync, readdirSync, readFileSync, realpathSync, writeFileSync } from "node:fs";
 import { homedir } from "node:os";
-import { isAbsolute as isAbsolute2, join } from "node:path";
+import { isAbsolute as isAbsolute2, join, relative as relative2 } from "node:path";
 import { spawnSync } from "node:child_process";
 import process from "node:process";
 
@@ -14,6 +14,24 @@ function mergeGauntlet(preset, repo) {
 }
 var nonEmptyString = (v) => typeof v === "string" && v.trim().length > 0;
 var joinWarn = (ws) => ws.length ? ws.join("; ") : void 0;
+var DEFAULT_SPEC_DIRS = ["doc/specs", "docs/specs"];
+var normalizeDir = (d) => d.trim().replace(/^\.\//, "").replace(/\/+$/, "");
+function resolveFlowGuards(g) {
+  const fg = g.flowGuards;
+  const enforce = fg?.enforce !== false;
+  const rawDirs = fg?.specDirs;
+  const specDirs = Array.isArray(rawDirs) && rawDirs.length > 0 && rawDirs.every(nonEmptyString) ? rawDirs.map(normalizeDir) : [...DEFAULT_SPEC_DIRS];
+  return { enforce, specDirs };
+}
+function planDirsFor(specDirs) {
+  const out = /* @__PURE__ */ new Set();
+  for (const dir of specDirs) {
+    const parts = dir.split("/").filter((c) => c.length > 0);
+    if (parts.length === 0) continue;
+    out.add([...parts.slice(0, -1), "plans"].join("/"));
+  }
+  return [...out];
+}
 var DEFAULT_TELEMETRY_DIR = ".pi/gauntlet/telemetry";
 var DEFAULT_TELEMETRY_BUCKETS = [
   ["test", ["**/test/**", "**/tests/**", "**/__tests__/**", "**/*.test.*", "**/*.spec.*", "**/*_test.*"]],
@@ -50,7 +68,6 @@ var STMT_START = "(?:^|[\\n;&|(])\\s*";
 
 // extensions/lib/telemetry-paths.ts
 var toPosix = (p) => p.split("\\").join("/");
-var isSpecPath = (rel) => /(^|\/)doc\/specs\/[^/]+\.md$/.test(rel);
 var recordPathFor = (dir, specRel) => `${dir}/${specRel.replace(/\.md$/, ".yaml")}`;
 function repoRelativeToolPath(toplevel, cwd, p) {
   const abs = isAbsolute(p) ? p : resolve(cwd, p);
@@ -72,9 +89,10 @@ function numstatPath(raw) {
 }
 
 // extensions/lib/telemetry-ship.ts
-function modifiedFilesFrom(nameOnly, spec, dir) {
+function modifiedFilesFrom(nameOnly, spec, dir, planDirs) {
   const dirPrefix = dir.replace(/\/+$/, "") + "/";
-  return nameOnly.split("\n").filter((f) => f && f !== spec && !/(^|\/)doc\/plans\//.test(f) && !f.startsWith(dirPrefix)).sort();
+  const planRes = planDirs.map((d) => new RegExp(`(^|/)${d.replace(/[.*+?^${}()|[\]\\]/g, "\\$&")}/`));
+  return nameOnly.split("\n").filter((f) => f && f !== spec && !planRes.some((re) => re.test(f)) && !f.startsWith(dirPrefix)).sort();
 }
 
 // extensions/lib/telemetry-diff.ts
@@ -99,7 +117,7 @@ async function computeGitDiff(o) {
   if (mb.code !== 0 || !mb.stdout.trim()) return { warning: `diff omitted: merge-base failed: ${firstLine(mb.stderr)}` };
   const base = mb.stdout.trim();
   const names = await o.git(["diff", "--name-only", `${base}...HEAD`], o.cwd);
-  const files = modifiedFilesFrom(names.stdout, o.spec, o.dir);
+  const files = modifiedFilesFrom(names.stdout, o.spec, o.dir, o.planDirs);
   const numstat = await o.git(["diff", "--numstat", `${base}...HEAD`], o.cwd);
   const count = await o.git(["rev-list", "--count", "--invert-grep", "--grep=^telemetry: ", `${base}..HEAD`], o.cwd);
   return { modified_files: files, diff: { base, commits: Number(count.stdout.trim()) || 0, buckets: aggregateNumstat(numstat.stdout, new Set(files), o.buckets) } };
@@ -281,11 +299,22 @@ function readLayer(file) {
     return {};
   }
 }
-function telemetrySettings(root) {
+function settings(root) {
   const agentDir = process.env.PI_CODING_AGENT_DIR || join(homedir(), ".pi", "agent");
   const preset = readLayer(join(agentDir, "settings.json"));
   const repo = readLayer(join(root, ".pi", "settings.json"));
-  return resolveTelemetry(mergeGauntlet(preset?.piGauntlet, repo?.piGauntlet));
+  const merged = mergeGauntlet(preset?.piGauntlet, repo?.piGauntlet);
+  return { telemetry: resolveTelemetry(merged), planDirs: planDirsFor(resolveFlowGuards(merged).specDirs) };
+}
+function walkRecords(absDir) {
+  if (!existsSync(absDir)) return [];
+  const out = [];
+  for (const e of readdirSync(absDir, { withFileTypes: true })) {
+    const p = join(absDir, e.name);
+    if (e.isDirectory()) out.push(...walkRecords(p));
+    else if (e.isFile() && e.name.endsWith(".yaml")) out.push(p);
+  }
+  return out;
 }
 var isoNow = () => (/* @__PURE__ */ new Date()).toISOString().replace(/\.\d{3}Z$/, "Z");
 var trackedAndClean = (root, rec) => git(root, ["ls-files", "--error-unmatch", "--", rec]).ok && git(root, ["diff", "--quiet", "HEAD", "--", rec]).ok;
@@ -302,7 +331,7 @@ async function seal(root, rec, o) {
     parsed.status = "shipped";
     parsed.shipped_at = now;
     parsed.events.push({ ts: now, session: parsed.sessions.at(-1) ?? "seal", phase: "ship", kind: "ship", option: o.option });
-    const out = await computeGitDiff({ git: gitRunner, cwd: root, spec: parsed.spec, dir: o.dir, buckets: o.buckets, base: o.base });
+    const out = await computeGitDiff({ git: gitRunner, cwd: root, spec: parsed.spec, dir: o.dir, buckets: o.buckets, base: o.base, planDirs: o.planDirs });
     if (out.warning) parsed.events.push({ ts: now, session: parsed.sessions.at(-1) ?? "seal", phase: "ship", kind: "warning", message: out.warning });
     parsed.derived.diff = out.diff;
     parsed.derived.modified_files = out.modified_files;
@@ -331,19 +360,25 @@ async function main() {
   if (opts.spec) {
     const specAbs = isAbsolute2(opts.spec) && existsSync(opts.spec) ? realpathSync(opts.spec) : opts.spec;
     rel = repoRelativeToolPath(root, root, specAbs);
-    if (!rel || !isSpecPath(rel)) usage();
+    if (!rel) usage();
   }
-  const telemetry = telemetrySettings(root);
+  const { telemetry, planDirs } = settings(root);
   if (telemetry.warning) process.stderr.write(`warning: ${telemetry.warning}
 `);
   if (!telemetry.enabled) return console.log("telemetry disabled");
   const dir = override?.dir ?? telemetry.dir;
   if (!git(root, ["rev-parse", "--verify", "-q", `${opts.base}^{commit}`]).ok) fail(1, `no base ref ${opts.base}`);
-  const o = { option: opts.option, base: opts.base, dir, buckets: telemetry.buckets };
+  const o = { option: opts.option, base: opts.base, dir, buckets: telemetry.buckets, planDirs };
   if (opts.spec) return seal(root, recordPathFor(dir, rel), o);
-  const diff = git(root, ["diff", "--name-only", `${opts.base}...HEAD`]);
+  const diff = git(root, ["diff", "--no-renames", "--name-only", `${opts.base}...HEAD`]);
   if (!diff.ok) fail(1, `git diff failed: ${diff.stderr}`);
-  const records = diff.stdout.split("\n").filter((f) => f && isSpecPath(f)).map((f) => recordPathFor(dir, f)).filter((rec) => existsSync(join(root, rec)));
+  const changed = new Set(diff.stdout.split("\n").filter(Boolean));
+  const records = walkRecords(join(root, dir)).filter((abs) => {
+    const parsed = parseRecord(readFileSync(abs, "utf8"));
+    if (!parsed) process.stderr.write(`warning: unparseable record ${toPosix(relative2(root, abs))}
+`);
+    return parsed && changed.has(parsed.spec);
+  }).map((abs) => toPosix(relative2(root, abs))).sort();
   if (records.length === 0) return console.log("no telemetry run");
   for (const rec of records) await seal(root, rec, o);
 }

package/bin/gauntlet-telemetry-seal.test.mjs

@@ -10,6 +10,8 @@ import { parse as parseYaml } from "yaml";
 const CLI = join(dirname(fileURLToPath(import.meta.url)), "gauntlet-telemetry-seal.mjs");
 const SPEC = "doc/specs/x.md";
 const REC = ".pi/gauntlet/telemetry/doc/specs/x.yaml";
+const SPEC2 = "docs/specs/y.md";
+const REC2 = ".pi/gauntlet/telemetry/docs/specs/y.yaml";
 const RECORD = [
   "schema: 1",
   "spec: doc/specs/x.md",
@@ -60,6 +62,19 @@ const repo = (options = {}) => {
   if (record !== undefined) write(root, REC, record);
   return root;
 };
+const docsRepo = () => {
+  const root = mkdtempSync(join(tmpdir(), "gts-"));
+  git(root, ["init", "-q", "-b", "main"]);
+  write(root, "README.md", "# fixture\n");
+  commit(root, "init", "README.md");
+  git(root, ["checkout", "-q", "-b", "feat"]);
+  write(root, SPEC2, "# Spec Y\n\n**Goal:** g.\n");
+  write(root, "src/a.ts", "export const a = 1;\n");
+  write(root, "docs/plans/x.md", "# Plan X\n");
+  commit(root, "Add spec and code", SPEC2, "src/a.ts", "docs/plans/x.md");
+  write(root, REC2, RECORD.replace("spec: doc/specs/x.md", `spec: ${SPEC2}`));
+  return root;
+};
 const EMPTY_AGENT = mkdtempSync(join(tmpdir(), "gts-empty-agent-"));
 process.on("exit", () => rmSync(EMPTY_AGENT, { recursive: true, force: true }));
 const IDENTITY = { GIT_AUTHOR_NAME: "t", GIT_AUTHOR_EMAIL: "t@t", GIT_COMMITTER_NAME: "t", GIT_COMMITTER_EMAIL: "t@t" };
@@ -100,6 +115,61 @@ test("seals an untracked in_progress record: stamp, ship event, diff, re-derived
   assert.equal(porcelain(root), "");
 });
 
+test("docs/specs record seals with --spec (no path classification)", (t) => {
+  const root = docsRepo(); cleanup(t, root);
+  const r = run(root, ["--spec", SPEC2]);
+  assert.equal(r.status, 0, r.stderr);
+  assert.deepEqual(r.lines, [`sealed ${REC2}`]);
+});
+
+test("docs/specs record seals without --spec: candidates are records whose spec: is in the changed set", (t) => {
+  const root = docsRepo(); cleanup(t, root);
+  const r = run(root);
+  assert.equal(r.status, 0, r.stderr);
+  assert.deepEqual(r.lines, [`sealed ${REC2}`]);
+  const rec = parseYaml(readFileSync(join(root, REC2), "utf8"));
+  assert.ok(!rec.derived.modified_files.includes("docs/plans/x.md"), "docs/plans excluded from modified_files");
+});
+
+test("renamed spec still selects the record at its old path", (t) => {
+  const root = mkdtempSync(join(tmpdir(), "gts-")); cleanup(t, root);
+  git(root, ["init", "-q", "-b", "main"]);
+  write(root, SPEC, "# Spec X\n\n**Goal:** g.\n");
+  commit(root, "Add original spec", SPEC);
+  git(root, ["checkout", "-q", "-b", "feat"]);
+  assert.equal(git(root, ["mv", SPEC, "doc/specs/renamed.md"]).status, 0);
+  commit(root, "Rename spec", SPEC, "doc/specs/renamed.md");
+  write(root, REC, RECORD);
+  const r = run(root);
+  assert.equal(r.status, 0, r.stderr);
+  assert.deepEqual(r.lines, [`sealed ${REC}`]);
+});
+
+test("unparseable walked record warns while another candidate seals", (t) => {
+  const root = repo(); cleanup(t, root);
+  const bad = ".pi/gauntlet/telemetry/bad.yaml";
+  write(root, bad, "schema: 1\nspec: doc/specs/x.md\n");
+  const r = run(root);
+  assert.equal(r.status, 0, r.stderr);
+  assert.equal(r.stderr, `warning: unparseable record ${bad}`);
+  assert.deepEqual(r.lines, [`sealed ${REC}`]);
+});
+
+test("shipped-but-uncommitted docs/specs record is committed on retry without --spec", (t) => {
+  const root = docsRepo(); cleanup(t, root);
+  write(root, REC2, RECORD.replace("spec: doc/specs/x.md", `spec: ${SPEC2}`).replace("status: in_progress", "status: shipped\nshipped_at: 2026-09-17T18:00:00Z"));
+  const r = run(root);
+  assert.equal(r.status, 0, r.stderr);
+  assert.deepEqual(r.lines, [`sealed ${REC2}`]);
+});
+
+test("a record whose spec did not change on the branch is ignored", (t) => {
+  const root = repo(); cleanup(t, root);
+  write(root, ".pi/gauntlet/telemetry/doc/specs/other.yaml", RECORD.replace("spec: doc/specs/x.md", "spec: doc/specs/other.md"));
+  const r = run(root);
+  assert.deepEqual(r.lines, [`sealed ${REC}`]);
+});
+
 test("seal preserves derived.council through the shipped stamp", (t) => {
   const council = { chair: { model: "p/chair:medium", dispatches: 1, clusters: 0, members_reported: 0 }, members: {} };
   const root = repo({ record: RECORD.replace("  spec_writes: {}", `  council: ${JSON.stringify(council)}\n  spec_writes: {}`) }); cleanup(t, root);
@@ -256,11 +326,12 @@ test("usage and environment errors exit 1", (t) => {
   const noBase = invoke(["--worktree", root, "--option", "squash", "--base", "nope"]);
   assert.equal(noBase.status, 1);
   assert.equal(noBase.stderr, "no base ref nope");
-  for (const spec of ["/tmp/elsewhere/doc/specs/x.md", "README.md"]) {
-    const invalid = run(root, ["--spec", spec]);
-    assert.equal(invalid.status, 1);
-    assert.match(invalid.stderr, /^usage:/);
-  }
+  const invalid = run(root, ["--spec", "/tmp/elsewhere/doc/specs/x.md"]);
+  assert.equal(invalid.status, 1);
+  assert.match(invalid.stderr, /^usage:/);
+  const noRec = run(root, ["--spec", "README.md"]);
+  assert.equal(noRec.status, 2);
+  assert.equal(noRec.stderr, "no record at .pi/gauntlet/telemetry/README.yaml");
   write(root, ".pi/settings.json", JSON.stringify({ piGauntlet: { telemetry: { enabled: false } } }));
   const disabledInvalid = run(root, ["--spec", "/tmp/elsewhere/doc/specs/x.md"]);
   assert.equal(disabledInvalid.status, 1);

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

@@ -7,6 +7,7 @@ import {
   resolveEscalationLoop,
   mainLoopModel,
   resolveFlowGuards,
+  planDirsFor,
   resolveVerifyBeforeShip,
   resolveTelemetry,
   DEFAULT_TELEMETRY_DIR,
@@ -135,11 +136,20 @@ test("closureReview: maxFixRounds default 3, <0 -> 0, non-int -> 3", () => {
   assert.equal(resolveClosureReview({ closureReview: { maxFixRounds: 1.5 } }).maxFixRounds, 3);
 });
 
-test("flowGuards: defaults + overrides", () => {
-  assert.deepEqual(resolveFlowGuards({}), { enforce: true, specDirs: ["doc/specs"] });
+test("flowGuards: defaults + overrides + normalization", () => {
+  assert.deepEqual(resolveFlowGuards({}), { enforce: true, specDirs: ["doc/specs", "docs/specs"] });
   assert.equal(resolveFlowGuards({ flowGuards: { enforce: false } }).enforce, false);
   assert.deepEqual(resolveFlowGuards({ flowGuards: { specDirs: ["a/b"] } }).specDirs, ["a/b"]);
-  assert.deepEqual(resolveFlowGuards({ flowGuards: { specDirs: [] } }).specDirs, ["doc/specs"]);
+  assert.deepEqual(resolveFlowGuards({ flowGuards: { specDirs: [] } }).specDirs, ["doc/specs", "docs/specs"]);
+  assert.deepEqual(resolveFlowGuards({ flowGuards: { specDirs: "x" } }).specDirs, ["doc/specs", "docs/specs"]);
+  assert.deepEqual(resolveFlowGuards({ flowGuards: { specDirs: ["docs/specs/", "./design/specs"] } }).specDirs, ["docs/specs", "design/specs"]);
+});
+
+test("planDirsFor: sibling plans dir per spec dir, deduplicated", () => {
+  assert.deepEqual(planDirsFor(["doc/specs", "design/specs"]), ["doc/plans", "design/plans"]);
+  assert.deepEqual(planDirsFor(["doc/specs", "docs/specs"]), ["doc/plans", "docs/plans"]);
+  assert.deepEqual(planDirsFor(["specs"]), ["plans"]);
+  assert.deepEqual(planDirsFor(["a/plans", "a/specs"]), ["a/plans"]);
 });
 
 test("settingsErrorWarning: includes prefix and joined errors", () => {

package/extensions/lib/gauntlet-settings.ts

@@ -119,17 +119,33 @@ export interface FlowGuardsResolved {
   specDirs: string[];
 }
 
+export const DEFAULT_SPEC_DIRS = ["doc/specs", "docs/specs"];
+
+// Strip a leading ./ and trailing slashes so "docs/specs/" and "./docs/specs" match the same paths.
+const normalizeDir = (d: string): string => d.trim().replace(/^\.\//, "").replace(/\/+$/, "");
+
 export function resolveFlowGuards(g: PiGauntlet): FlowGuardsResolved {
   const fg = g.flowGuards;
   const enforce = fg?.enforce !== false;
   const rawDirs = fg?.specDirs;
   const specDirs =
     Array.isArray(rawDirs) && rawDirs.length > 0 && rawDirs.every(nonEmptyString)
-      ? (rawDirs as string[]).map((d) => d.trim())
-      : ["doc/specs"];
+      ? (rawDirs as string[]).map(normalizeDir)
+      : [...DEFAULT_SPEC_DIRS];
   return { enforce, specDirs };
 }
 
+// Each spec dir's sibling `plans` dir (doc/specs -> doc/plans); plans live there per writing-plans.
+export function planDirsFor(specDirs: readonly string[]): string[] {
+  const out = new Set<string>();
+  for (const dir of specDirs) {
+    const parts = dir.split("/").filter((c) => c.length > 0);
+    if (parts.length === 0) continue;
+    out.add([...parts.slice(0, -1), "plans"].join("/"));
+  }
+  return [...out];
+}
+
 export interface VerifyBeforeShipResolved {
   testCommands: string[];
   warningReference: string | undefined;

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

@@ -1,5 +1,8 @@
 import { test } from "node:test";
 import assert from "node:assert/strict";
+import { spawnSync } from "node:child_process";
+import { fileURLToPath } from "node:url";
+import { dirname, join } from "node:path";
 import {
   CONTEXT_DRAFT_MARKER,
   checkSubstep,
@@ -255,3 +258,14 @@ test("implementExemptDirs: adds each spec dir's sibling plans dir, deduped", ()
 test("nextGauntletEntered: skip preserves the marker (resume gesture)", () => {
   assert.equal(nextGauntletEntered(true, "skip", "skipped"), true);
 });
+
+test("module order: telemetry-paths and phase-tracker-helpers initialize in either import order", () => {
+  const lib = dirname(fileURLToPath(import.meta.url));
+  const loader = join(lib, "..", "test-support", "pi-stubs.mjs");
+  const paths = join(lib, "telemetry-paths.ts");
+  const helpers = join(lib, "phase-tracker-helpers.ts");
+  for (const [a, b] of [[paths, helpers], [helpers, paths]]) {
+    const r = spawnSync(process.execPath, ["--experimental-loader", loader, "--input-type=module", "-e", `await import(${JSON.stringify(a)}); await import(${JSON.stringify(b)});`], { encoding: "utf8" });
+    assert.equal(r.status, 0, r.stderr);
+  }
+});

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

@@ -5,6 +5,7 @@
  */
 
 import { resolve } from "node:path";
+import { planDirsFor } from "./gauntlet-settings.ts";
 
 export const CONTEXT_DRAFT_MARKER = "# CONTEXT DRAFT - NOT A SPEC - fully replaced at spec-writing";
 
@@ -169,10 +170,10 @@ export function implementWriteGuardApplies(
 export function implementExemptDirs(specDirs: string[]): string[] {
   const dirs = new Set<string>();
   for (const dir of specDirs) {
-    const parts = dir.split("/").filter((c) => c.length > 0);
-    if (parts.length === 0) continue;
-    dirs.add(parts.join("/"));
-    dirs.add([...parts.slice(0, -1), "plans"].join("/"));
+    const spec = dir.split("/").filter((c) => c.length > 0).join("/");
+    if (!spec) continue;
+    dirs.add(spec);
+    for (const plan of planDirsFor([spec])) dirs.add(plan);
   }
   return [...dirs];
 }

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

@@ -5,6 +5,7 @@ import { JJ_MAINLINE, aggregateNumstat, computeGitDiff, computeJjDiff, type RunR
 
 const ok = (stdout: string): RunResult => ({ code: 0, stdout, stderr: "" });
 const DIR = ".pi/gauntlet/telemetry";
+const PLAN_DIRS = ["doc/plans", "docs/plans"];
 
 test("aggregateNumstat sums per bucket over the given file set; binary rows count 0 lines", () => {
   const numstat = ["10\t2\textensions/telemetry.ts", "5\t0\textensions/lib/telemetry-paths.test.ts", "-\t-\timg.png", "3\t3\tdoc/specs/a.md", "1\t1\t{old => new}/x.ts"].join("\n");
@@ -20,12 +21,12 @@ test("computeGitDiff: merge-base, name-only minus spec/plan/dir, numstat buckets
   const git = (args: string[]) => {
     calls.push(args);
     if (args[0] === "merge-base") return ok("abc123\n");
-    if (args[0] === "diff" && args.includes("--name-only")) return ok("extensions/telemetry.ts\nextensions/telemetry.test.ts\ndoc/specs/a.md\ndoc/plans/a.md\n.pi/gauntlet/telemetry/doc/specs/a.yaml\nREADME.md\n");
+    if (args[0] === "diff" && args.includes("--name-only")) return ok("extensions/telemetry.ts\nextensions/telemetry.test.ts\ndoc/specs/a.md\ndoc/plans/a.md\ndocs/plans/q.md\n.pi/gauntlet/telemetry/doc/specs/a.yaml\nREADME.md\n");
     if (args[0] === "diff" && args.includes("--numstat")) return ok("100\t5\textensions/telemetry.ts\n40\t0\textensions/telemetry.test.ts\n9\t9\tdoc/specs/a.md\n2\t1\tREADME.md\n");
     if (args[0] === "rev-list") return ok("9\n");
     return { code: 1, stdout: "", stderr: `unexpected ${args.join(" ")}` };
   };
-  const out = await computeGitDiff({ git, cwd: "/repo", spec: "doc/specs/a.md", dir: DIR, buckets: DEFAULT_TELEMETRY_BUCKETS, base: "main" });
+  const out = await computeGitDiff({ git, cwd: "/repo", spec: "doc/specs/a.md", dir: DIR, planDirs: PLAN_DIRS, buckets: DEFAULT_TELEMETRY_BUCKETS, base: "main" });
   assert.deepEqual(out.modified_files, ["README.md", "extensions/telemetry.test.ts", "extensions/telemetry.ts"]);
   assert.deepEqual(out.diff, { base: "abc123", commits: 9, buckets: { code: { files: 1, insertions: 100, deletions: 5 }, test: { files: 1, insertions: 40, deletions: 0 }, docs: { files: 1, insertions: 2, deletions: 1 } } });
   assert.equal(out.warning, undefined);
@@ -33,8 +34,20 @@ test("computeGitDiff: merge-base, name-only minus spec/plan/dir, numstat buckets
   assert.deepEqual(calls.at(-1), ["rev-list", "--count", "--invert-grep", "--grep=^telemetry: ", "abc123..HEAD"]);
 });
 
+test("computeGitDiff: custom plan dir excludes only configured plans", async () => {
+  const git = (args: string[]) => {
+    if (args[0] === "merge-base") return ok("abc123\n");
+    if (args.includes("--name-only")) return ok("design/plans/x.md\ndoc/plans/x.md\n");
+    if (args.includes("--numstat")) return ok("1\t0\tdesign/plans/x.md\n1\t0\tdoc/plans/x.md\n");
+    if (args[0] === "rev-list") return ok("1\n");
+    return { code: 1, stdout: "", stderr: `unexpected ${args.join(" ")}` };
+  };
+  const out = await computeGitDiff({ git, cwd: "/repo", spec: "design/specs/a.md", dir: DIR, planDirs: ["design/plans"], buckets: DEFAULT_TELEMETRY_BUCKETS, base: "main" });
+  assert.deepEqual(out.modified_files, ["doc/plans/x.md"]);
+});
+
 test("computeGitDiff: merge-base failure -> warning, both fields absent", async () => {
-  const out = await computeGitDiff({ git: () => ({ code: 128, stdout: "", stderr: "fatal: no merge base\nmore" }), cwd: "/repo", spec: "doc/specs/a.md", dir: DIR, buckets: DEFAULT_TELEMETRY_BUCKETS, base: "main" });
+  const out = await computeGitDiff({ git: () => ({ code: 128, stdout: "", stderr: "fatal: no merge base\nmore" }), cwd: "/repo", spec: "doc/specs/a.md", dir: DIR, planDirs: PLAN_DIRS, buckets: DEFAULT_TELEMETRY_BUCKETS, base: "main" });
   assert.deepEqual(out, { warning: "diff omitted: merge-base failed: fatal: no merge base" });
 });
 
@@ -55,6 +68,20 @@ const JJ_PATCH = [
   "+++ b/test/a.test.ts",
   "@@ -0,0 +1,5 @@",
   ...Array.from({ length: 5 }, (_, i) => `+t ${i}`),
+  "diff --git a/doc/plans/p.md b/doc/plans/p.md",
+  "new file mode 100644",
+  "index 0000000..4444444",
+  "--- /dev/null",
+  "+++ b/doc/plans/p.md",
+  "@@ -0,0 +1 @@",
+  "+plan",
+  "diff --git a/docs/plans/x.md b/docs/plans/x.md",
+  "new file mode 100644",
+  "index 0000000..4444444",
+  "--- /dev/null",
+  "+++ b/docs/plans/x.md",
+  "@@ -0,0 +1 @@",
+  "+plan",
   "",
 ].join("\n");
 
@@ -73,7 +100,7 @@ const jjStub = (over?: (args: string[]) => RunResult | undefined) => {
 };
 const runJj = (over?: (args: string[]) => RunResult | undefined) => {
   const s = jjStub(over);
-  return computeJjDiff({ jj: s.jj, cwd: "/ws", spec: "doc/specs/a.md", dir: DIR, buckets: DEFAULT_TELEMETRY_BUCKETS }).then((out) => ({ out, calls: s.calls }));
+  return computeJjDiff({ jj: s.jj, cwd: "/ws", spec: "doc/specs/a.md", dir: DIR, planDirs: PLAN_DIRS, buckets: DEFAULT_TELEMETRY_BUCKETS }).then((out) => ({ out, calls: s.calls }));
 };
 const isBaseLog = (args: string[]) => args.includes("log") && !args.includes("--count");
 
@@ -88,6 +115,27 @@ test("computeJjDiff: pinned flags, mainline revset, telemetry-only revisions exc
   assert.ok(calls[0].some((a) => a.includes(`fork_point(${JJ_MAINLINE} | @) ~ root() & ::${JJ_MAINLINE}`)));
 });
 
+test("computeJjDiff: custom plan dir excludes only configured plans", async () => {
+  const patch = [
+    "diff --git a/design/plans/x.md b/design/plans/x.md",
+    "new file mode 100644",
+    "--- /dev/null",
+    "+++ b/design/plans/x.md",
+    "@@ -0,0 +1 @@",
+    "+plan",
+    "diff --git a/doc/plans/x.md b/doc/plans/x.md",
+    "new file mode 100644",
+    "--- /dev/null",
+    "+++ b/doc/plans/x.md",
+    "@@ -0,0 +1 @@",
+    "+other plan",
+    "",
+  ].join("\n");
+  const { jj } = jjStub((args) => (args.includes("diff") ? ok(patch) : undefined));
+  const out = await computeJjDiff({ jj, cwd: "/ws", spec: "design/specs/a.md", dir: DIR, planDirs: ["design/plans"], buckets: DEFAULT_TELEMETRY_BUCKETS });
+  assert.deepEqual(out.modified_files, ["doc/plans/x.md"]);
+});
+
 test("computeJjDiff: empty mainline -> jj-named warning", async () => {
   const { out } = await runJj((args) => (isBaseLog(args) ? ok("") : undefined));
   assert.deepEqual(out, { warning: "diff omitted: jj mainline unresolved (trunk() is root(); no main/master bookmark)" });

package/extensions/lib/telemetry-diff.ts

@@ -27,7 +27,7 @@ export function aggregateNumstat(numstat: string, files: Set<string>, buckets: B
 export const JJ_MAINLINE = "coalesce(trunk() ~ root(), present(main), present(master))";
 const firstLine = (s: string): string => s.trim().split("\n")[0];
 
-export async function computeJjDiff(o: { jj: Runner; cwd: string; spec: string; dir: string; buckets: Buckets }): Promise<DiffOutcome> {
+export async function computeJjDiff(o: { jj: Runner; cwd: string; spec: string; dir: string; planDirs: readonly string[]; buckets: Buckets }): Promise<DiffOutcome> {
   const failed = (sub: string, r: RunResult): DiffOutcome => ({ warning: `diff omitted: jj ${sub} failed: ${firstLine(r.stderr) || "unknown error"}` });
   // Without the ::M guard an empty mainline resolves to @ and counts the full history.
   const baseR = await o.jj(["--color=never", "log", "-r", `fork_point(${JJ_MAINLINE} | @) ~ root() & ::${JJ_MAINLINE}`, "--no-graph", "-T", 'commit_id ++ "\\n"'], o.cwd);
@@ -44,17 +44,17 @@ export async function computeJjDiff(o: { jj: Runner; cwd: string; spec: string;
   if (count.code !== 0) return failed("log", count);
   const n = count.stdout.trim();
   if (!/^\d+$/.test(n)) return { warning: `diff omitted: jj log --count unparseable: ${n}` };
-  const files = modifiedFilesFrom(rows.map((r) => r.path).join("\n"), o.spec, o.dir);
+  const files = modifiedFilesFrom(rows.map((r) => r.path).join("\n"), o.spec, o.dir, o.planDirs);
   const numstat = rows.map((r) => `${r.added}\t${r.removed}\t${r.path}`).join("\n");
   return { modified_files: files, diff: { base, commits: Number(n), buckets: aggregateNumstat(numstat, new Set(files), o.buckets) } };
 }
 
-export async function computeGitDiff(o: { git: Runner; cwd: string; spec: string; dir: string; buckets: Buckets; base: string }): Promise<DiffOutcome> {
+export async function computeGitDiff(o: { git: Runner; cwd: string; spec: string; dir: string; planDirs: readonly string[]; buckets: Buckets; base: string }): Promise<DiffOutcome> {
   const mb = await o.git(["merge-base", "HEAD", o.base], o.cwd);
   if (mb.code !== 0 || !mb.stdout.trim()) return { warning: `diff omitted: merge-base failed: ${firstLine(mb.stderr)}` };
   const base = mb.stdout.trim();
   const names = await o.git(["diff", "--name-only", `${base}...HEAD`], o.cwd);
-  const files = modifiedFilesFrom(names.stdout, o.spec, o.dir);
+  const files = modifiedFilesFrom(names.stdout, o.spec, o.dir, o.planDirs);
   const numstat = await o.git(["diff", "--numstat", `${base}...HEAD`], o.cwd);
   const count = await o.git(["rev-list", "--count", "--invert-grep", "--grep=^telemetry: ", `${base}..HEAD`], o.cwd);
   return { modified_files: files, diff: { base, commits: Number(count.stdout.trim()) || 0, buckets: aggregateNumstat(numstat.stdout, new Set(files), o.buckets) } };

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

@@ -28,12 +28,23 @@ test("repoRelativeToolPath resolves like pi tools: relative to cwd, then repo-re
   assert.equal(repoRelativeToolPath("/repo", "/repo", "/elsewhere/x.md"), undefined);
 });
 
-test("isSpecPath / isPlanPath match **/doc/specs/*.md and **/doc/plans/*.md only", () => {
-  assert.ok(isSpecPath("doc/specs/a.md"));
-  assert.ok(isSpecPath("svc/doc/specs/a.md"));
-  assert.equal(isSpecPath("doc/specs/sub/a.md"), false);
-  assert.equal(isSpecPath("doc/plans/a.md"), false);
-  assert.ok(isPlanPath("doc/plans/a.md"));
+const DEFAULT_DIRS = ["doc/specs", "docs/specs"];
+const DEFAULT_PLANS = ["doc/plans", "docs/plans"];
+
+test("isSpecPath / isPlanPath: direct child .md of any configured dir, at root or under a service prefix", () => {
+  for (const p of ["doc/specs/x.md", "docs/specs/x.md", "svc/doc/specs/x.md", "svc/docs/specs/x.md"]) assert.ok(isSpecPath(p, DEFAULT_DIRS), p);
+  for (const p of ["docs/specs/sub/x.md", "docs/spec/x.md", "doc/plans/x.md", "xdocs/specs/x.md", "docs/specs/x.txt"]) assert.equal(isSpecPath(p, DEFAULT_DIRS), false, p);
+  for (const p of ["doc/plans/x.md", "docs/plans/x.md", "svc/doc/plans/x.md", "svc/docs/plans/x.md"]) assert.ok(isPlanPath(p, DEFAULT_PLANS), p);
+  for (const p of ["docs/plans/sub/x.md", "docs/plan/x.md", "doc/specs/x.md", "xdocs/plans/x.md", "docs/plans/x.txt"]) assert.equal(isPlanPath(p, DEFAULT_PLANS), false, p);
+  assert.ok(isPlanPath("design/plans/x.md", ["design/plans"]));
+  assert.equal(isPlanPath("doc/plans/x.md", ["design/plans"]), false);
+  assert.equal(isPlanPath("docs/plans/x.md", ["design/plans"]), false);
+  assert.ok(isSpecPath("design/specs/x.md", ["design/specs"]));
+  assert.equal(isSpecPath("doc/specs/x.md", ["design/specs"]), false);
+  assert.equal(isSpecPath("docs/specs/x.md", ["design/specs"]), false);
+  // regex metacharacters in a configured dir are matched literally
+  assert.ok(isSpecPath("docs/[draft]/specs/x.md", ["docs/[draft]/specs"]));
+  assert.equal(isSpecPath("docs/d/specs/x.md", ["docs/[draft]/specs"]), false);
 });
 
 test("planSpecHeader extracts the **Spec:** path", () => {

package/extensions/lib/telemetry-paths.ts

@@ -16,8 +16,13 @@ import { STMT_START } from "./phase-tracker-helpers.ts";
 
 export const toPosix = (p: string): string => p.split("\\").join("/");
 
-export const isSpecPath = (rel: string): boolean => /(^|\/)doc\/specs\/[^/]+\.md$/.test(rel);
-export const isPlanPath = (rel: string): boolean => /(^|\/)doc\/plans\/[^/]+\.md$/.test(rel);
+const escapeRe = (s: string): string => s.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
+// Direct child .md of one configured dir, at the repo root or under any service prefix.
+const inDirs = (rel: string, dirs: readonly string[]): boolean =>
+  dirs.some((d) => new RegExp(`(^|/)${escapeRe(d)}/[^/]+\\.md$`).test(rel));
+
+export const isSpecPath = (rel: string, specDirs: readonly string[]): boolean => inDirs(rel, specDirs);
+export const isPlanPath = (rel: string, planDirs: readonly string[]): boolean => inDirs(rel, planDirs);
 
 // <dir>/<spec path with trailing .md replaced by .yaml>, nesting preserved.
 export const recordPathFor = (dir: string, specRel: string): string => `${dir}/${specRel.replace(/\.md$/, ".yaml")}`;

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

@@ -9,11 +9,14 @@ test("guardReason names spec, timestamp and record path", () => {
   );
 });
 
-test("modifiedFilesFrom drops the spec, doc/plans/**, and the telemetry dir; sorts", () => {
-  const names = "extensions/telemetry.ts\nextensions/telemetry.test.ts\ndoc/specs/a.md\ndoc/plans/a.md\nsvc/doc/plans/b.md\n.pi/gauntlet/telemetry/doc/specs/a.yaml\nREADME.md\n\n";
-  assert.deepEqual(modifiedFilesFrom(names, "doc/specs/a.md", ".pi/gauntlet/telemetry"), ["README.md", "extensions/telemetry.test.ts", "extensions/telemetry.ts"]);
-  assert.deepEqual(modifiedFilesFrom("", "doc/specs/a.md", "t/"), []);
-  // Filenames with leading or trailing whitespace must be kept verbatim
+const PLANS = ["doc/plans", "docs/plans"];
+
+test("modifiedFilesFrom drops the spec, every configured plan dir, and the telemetry dir; sorts", () => {
+  const names = "extensions/telemetry.ts\nextensions/telemetry.test.ts\ndoc/specs/a.md\ndoc/plans/a.md\ndocs/plans/c.md\nsvc/doc/plans/b.md\n.pi/gauntlet/telemetry/doc/specs/a.yaml\nREADME.md\n\n";
+  assert.deepEqual(modifiedFilesFrom(names, "doc/specs/a.md", ".pi/gauntlet/telemetry", PLANS), ["README.md", "extensions/telemetry.test.ts", "extensions/telemetry.ts"]);
+  assert.deepEqual(modifiedFilesFrom("design/plans/x.md\nsrc/a.ts\n", "design/specs/a.md", "t/", ["design/plans"]), ["src/a.ts"]);
+  assert.deepEqual(modifiedFilesFrom("doc/plans/x.md\n", "design/specs/a.md", "t/", ["design/plans"]), ["doc/plans/x.md"]);
+  assert.deepEqual(modifiedFilesFrom("", "doc/specs/a.md", "t/", PLANS), []);
   const namesWithWhitespace = " lead.ts\ntrail.ts \nREADME.md\n";
-  assert.deepEqual(modifiedFilesFrom(namesWithWhitespace, "doc/specs/a.md", "t/"), [" lead.ts", "README.md", "trail.ts "]);
+  assert.deepEqual(modifiedFilesFrom(namesWithWhitespace, "doc/specs/a.md", "t/", PLANS), [" lead.ts", "README.md", "trail.ts "]);
 });

package/extensions/lib/telemetry-ship.ts

@@ -4,11 +4,12 @@ export const guardReason = (spec: string, shippedAt: string, recordRel: string):
   `spec ${spec} shipped at ${shippedAt} (record ${recordRel}). Write a new date-slugged spec that supersedes it instead of reusing this file.`;
 
 // derived.modified_files: `git diff --name-only <base>...HEAD` output minus the bound
-// spec, doc/plans/**, and <dir>/**; sorted repo-relative paths (renames -> new path).
-export function modifiedFilesFrom(nameOnly: string, spec: string, dir: string): string[] {
+// spec, every configured plan dir (<planDir>/** at any prefix), and <dir>/**; sorted repo-relative paths.
+export function modifiedFilesFrom(nameOnly: string, spec: string, dir: string, planDirs: readonly string[]): string[] {
   const dirPrefix = dir.replace(/\/+$/, "") + "/";
+  const planRes = planDirs.map((d) => new RegExp(`(^|/)${d.replace(/[.*+?^${}()|[\]\\]/g, "\\$&")}/`));
   return nameOnly
     .split("\n")
-    .filter((f) => f && f !== spec && !/(^|\/)doc\/plans\//.test(f) && !f.startsWith(dirPrefix))
+    .filter((f) => f && f !== spec && !planRes.some((re) => re.test(f)) && !f.startsWith(dirPrefix))
     .sort();
 }

package/extensions/phase-tracker.test.ts

@@ -290,6 +290,19 @@ test("brainstorm write guard is unchanged by the implement guard", async () => {
   }
 });
 
+test("brainstorm write confinement: a docs/specs write under the default dirs does not warn", async () => {
+  const priorDepth = process.env.PI_SUBAGENT_DEPTH;
+  delete process.env.PI_SUBAGENT_DEPTH;
+  try {
+    const h = harness({ cwd: tempCwd(), branch: [phaseResult("start", phases({ brainstorm: "in_progress" }))] });
+    await h.emit("session_start");
+    await h.emitEvent("tool_call", writeCall("t1", "docs/specs/x.md"));
+    assert.equal((await h.emitEvent("tool_result", writeResult("t1")))[0], undefined);
+  } finally {
+    if (priorDepth !== undefined) process.env.PI_SUBAGENT_DEPTH = priorDepth;
+  }
+});
+
 test("resumed session: plan-implement recovery edge fires (AC 3)", async () => {
   const h = harness({ cwd: tempCwd(), branch: [...resumedBranch({ plan: "complete" }), assistant()] });
   await settle(h);
@@ -1244,6 +1257,17 @@ test("gauntlet_setting escalationLoop: setting absent -> ctx-derived main-loop m
   assert.equal(res.details.implModel, "p/strong:high");
 });
 
+test("gauntlet_setting flowGuards: default dirs + derived plan dirs; repo override replaces them", async () => {
+  const h = harness({ cwd: tempCwd({ piGauntlet: {} }) });
+  const tool = h.tools.find((t) => t.name === "gauntlet_setting")!;
+  const def = (await tool.execute("f1", { key: "flowGuards" }, undefined, undefined, h.ctx)) as { details: unknown };
+  assert.deepEqual(def.details, { key: "flowGuards", enforce: true, specDirs: ["doc/specs", "docs/specs"], planDirs: ["doc/plans", "docs/plans"], errors: [] });
+  const set = harness({ cwd: tempCwd({ piGauntlet: { flowGuards: { specDirs: ["design/specs"] } } }) });
+  const res = (await set.tools.find((t) => t.name === "gauntlet_setting")!.execute("f2", { key: "flowGuards" }, undefined, undefined, set.ctx)) as { details: { specDirs: string[]; planDirs: string[] } };
+  assert.deepEqual(res.details.specDirs, ["design/specs"]);
+  assert.deepEqual(res.details.planDirs, ["design/plans"]);
+});
+
 // --- Conformance fix-loop dispatch guard (spec 2026-09-13-conformance-dispatch-guard) ---
 
 const verifyBranch = (extra: unknown[] = []) => [