pi-gauntlet 5.23.1 → 6.0.1

package/extensions/phase-tracker.ts

@@ -17,6 +17,7 @@ import { Text } from "@earendil-works/pi-tui";
 import { type Static, Type } from "@sinclair/typebox";
 import {
   mainLoopModel,
+  planDirsFor,
   resolveClosureReview,
   resolveEscalationLoop,
   resolveFlowGuards,
@@ -734,7 +735,7 @@ export default function (pi: ExtensionAPI) {
   });
 
   const GauntletSettingParams = Type.Object({
-    key: StringEnum(["specCouncil", "closureReview", "escalationLoop"] as const, {
+    key: StringEnum(["specCouncil", "closureReview", "escalationLoop", "flowGuards"] as const, {
       description: "Which gauntlet setting to resolve (merged repo-over-preset).",
     }),
   });
@@ -747,16 +748,19 @@ export default function (pi: ExtensionAPI) {
     executionMode: "sequential",
     async execute(_toolCallId, params, _signal, _onUpdate, ctx) {
       const { gauntlet, errors } = loadGauntletSettings(ctx.cwd);
+      const fg = resolveFlowGuards(gauntlet);
       const payload =
         params.key === "specCouncil"
           ? { key: "specCouncil" as const, ...resolveSpecCouncil(gauntlet), errors }
           : params.key === "closureReview"
             ? { key: "closureReview" as const, ...resolveClosureReview(gauntlet), errors }
-            : {
-                key: "escalationLoop" as const,
-                ...resolveEscalationLoop(gauntlet, mainLoopModel(ctx.model, ctx.thinkingLevel)),
-                errors,
-              };
+            : params.key === "flowGuards"
+              ? { key: "flowGuards" as const, ...fg, planDirs: planDirsFor(fg.specDirs), errors }
+              : {
+                  key: "escalationLoop" as const,
+                  ...resolveEscalationLoop(gauntlet, mainLoopModel(ctx.model, ctx.thinkingLevel)),
+                  errors,
+                };
       return {
         content: [{ type: "text", text: "```json\n" + JSON.stringify(payload, null, 2) + "\n```" }],
         details: payload,

package/extensions/telemetry.test.ts

@@ -4,7 +4,7 @@
   import { join } from "node:path";
   import { after, test } from "node:test";
   import registerTelemetry, { realFs, replayBranch, type Deps, type GitResult } from "./telemetry.ts";
-  import { DEFAULT_TELEMETRY_BUCKETS } from "./lib/gauntlet-settings.ts";
+  import { DEFAULT_TELEMETRY_BUCKETS, planDirsFor, resolveFlowGuards } from "./lib/gauntlet-settings.ts";
   import { emptyAccumulators, parseRecord, serializeRecord } from "./lib/telemetry-record.ts";
   import { guardReason } from "./lib/telemetry-ship.ts";
 
@@ -24,6 +24,7 @@
     const root = mkdtempSync(join(tmpdir(), "telemetry-test-"));
     tempDirs.push(root);
     mkdirSync(join(root, "doc/specs"), { recursive: true });
+    mkdirSync(join(root, "docs/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[]>();
@@ -31,6 +32,7 @@
     const gitCwds: string[] = [];
     const jjCalls: string[][] = [];
     const readFileCalls: string[] = [];
+    const specDirs = resolveFlowGuards({}).specDirs;
     let clock = Date.parse("2026-09-17T10:00:00Z");
     const deps: Deps = {
       fs: { ...realFs, readFile: (p) => { readFileCalls.push(p); return realFs.readFile(p); } },
@@ -56,7 +58,7 @@
         if (args[0] === "ls-files") return { code: 0, stdout: "", stderr: "" };
         return { code: 0, stdout: "", stderr: "" };
       },
-      settings: () => ({ telemetry: { enabled: o.enabled ?? true, dir: o.telemetryDir ?? ".pi/gauntlet/telemetry", buckets: DEFAULT_TELEMETRY_BUCKETS, warning: o.telemetryWarning }, errors: [], agentOverrides: { implementer: { model: "p/x" } }, versions: { pi: "0.85.1" } }),
+      settings: () => ({ specDirs, planDirs: planDirsFor(specDirs), telemetry: { enabled: o.enabled ?? true, dir: o.telemetryDir ?? ".pi/gauntlet/telemetry", buckets: DEFAULT_TELEMETRY_BUCKETS, warning: o.telemetryWarning }, errors: [], agentOverrides: { implementer: { model: "p/x" } }, versions: { pi: "0.85.1" } }),
       // A plain jj workspace: `jj root` answers the temp root while git rev-parse fails.
       jj: async (args, cwd) => {
         jjCalls.push(args);
@@ -180,6 +182,19 @@
     assert.equal(readFileSync(h.excludeFile(), "utf8"), ".pi/gauntlet/telemetry/\n", "exclude line is written once after rebind");
   });
 
+  test("a docs/specs write binds under the default dirs and the record lands under telemetry.dir/docs/specs", async () => {
+    const h = harness();
+    await h.phaseResult("start", P({ brainstorm: "in_progress" }));
+    assert.equal(existsSync(h.recordPath("docs/specs/x.md")), false);
+    await h.writeSpec("docs/specs/x.md");
+    assert.equal(h.recordPath("docs/specs/x.md"), join(h.root, ".pi/gauntlet/telemetry/docs/specs/x.yaml"));
+    assert.equal(h.readRecord("docs/specs/x.md").spec, "docs/specs/x.md");
+    await h.phaseResult("complete", P({ brainstorm: "complete" }));
+    const rec = h.readRecord("docs/specs/x.md");
+    assert.equal(rec.approved_at, rec.events.at(-1)!.ts);
+    assert.equal(h.gitWrites().length, 0);
+  });
+
   test("bind derives approved_at from a buffered brainstorm completion", async () => {
     const h = harness();
     await h.phaseResult("start", P({ brainstorm: "in_progress" }));
@@ -231,7 +246,7 @@
       { type: "message", message: { role: "toolResult", toolName: "write", toolCallId: "w1", isError: false } },
       { type: "message", message: { role: "toolResult", toolName: "write", toolCallId: "w2", isError: false } },
       { type: "message", message: { role: "toolResult", toolName: "write", toolCallId: "w3", isError: true } },
-    ]);
+    ], ["doc/specs", "docs/specs"]);
     assert.deepEqual(replay.phases, successfulPhases);
     assert.equal(replay.gauntletEntered, true);
     assert.equal(replay.planCheckSpec, "/repo/doc/specs/a.md");
@@ -246,7 +261,7 @@
     const unarmed = replayBranch([
       ...write("w1", "doc/specs/a.md"),
       { type: "message", message: { role: "toolResult", toolName: "plan_check", details: { status: "pass", specPath: "/repo/doc/specs/a.md" } } },
-    ]);
+    ], ["doc/specs", "docs/specs"]);
     assert.equal(unarmed.gauntletEntered, false);
     assert.equal(unarmed.lastSpecWrite, undefined);
     assert.equal(unarmed.planCheckSpec, undefined);
@@ -254,21 +269,31 @@
       ...write("w0", "doc/specs/before.md"),
       { type: "message", message: { role: "toolResult", toolName: "phase_tracker", details: { action: "start", phases: P({ brainstorm: "in_progress" }) } } },
       ...write("w1", "doc/specs/a.md", "edit"),
-    ]);
+    ], ["doc/specs", "docs/specs"]);
     assert.deepEqual([armed.gauntletEntered, armed.lastSpecWrite], [true, "doc/specs/a.md"]);
     const reset = replayBranch([
       { type: "message", message: { role: "toolResult", toolName: "phase_tracker", details: { action: "start", phases: P({ brainstorm: "in_progress" }) } } },
       ...write("w1", "doc/specs/a.md"),
       { type: "message", message: { role: "toolResult", toolName: "phase_tracker", details: { action: "reset", phases: P() } } },
-    ]);
+    ], ["doc/specs", "docs/specs"]);
     assert.deepEqual([reset.gauntletEntered, reset.lastSpecWrite], [false, undefined]);
     const resumed = replayBranch([
       { type: "message", message: { role: "toolResult", toolName: "phase_tracker", details: { action: "start", phases: P({ brainstorm: "in_progress" }) } } },
       { type: "message", message: { role: "toolResult", toolName: "phase_tracker", details: { action: "skip", phases: { ...P({ brainstorm: "skipped" }), brainstorm: { status: "skipped", reason: "resume: /repo/doc/specs/a.md" } } } } },
-    ]);
+    ], ["doc/specs", "docs/specs"]);
     assert.deepEqual([resumed.gauntletEntered, resumed.lastSpecWrite], [true, "/repo/doc/specs/a.md"]);
   });
 
+  test("replayBranch honors a custom spec dir list", () => {
+    const branch = [
+      { type: "message", message: { role: "toolResult", toolName: "phase_tracker", details: { action: "start", phases: P({ brainstorm: "in_progress" }) } } },
+      { type: "message", message: { role: "assistant", content: [{ type: "toolCall", id: "w1", name: "write", arguments: { path: "design/specs/a.md" } }] } },
+      { type: "message", message: { role: "toolResult", toolName: "write", toolCallId: "w1", isError: false } },
+    ];
+    assert.equal(replayBranch(branch, ["design/specs"]).lastSpecWrite, "design/specs/a.md");
+    assert.equal(replayBranch(branch, ["doc/specs"]).lastSpecWrite, undefined);
+  });
+
   test("session_start replay binds from plan_check details with no spec write, extends sessions, preserves run_id", async () => {
     const first = harness();
     await first.phaseResult("start", P({ brainstorm: "in_progress" }));

package/extensions/telemetry.ts

@@ -14,7 +14,7 @@
   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 { DEFAULT_TEST_COMMANDS, planDirsFor, resolveFlowGuards, 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, nextGauntletEntered } from "./lib/phase-tracker-helpers.ts";
@@ -43,6 +43,8 @@
   }
   export interface SettingsSnapshot {
     telemetry: TelemetryResolved;
+    specDirs: string[];
+    planDirs: string[];
     errors: string[];
     agentOverrides?: Record<string, unknown>;
     versions: Record<string, string>;
@@ -118,6 +120,8 @@
   function realSettings(cwd: string): SettingsSnapshot {
     const { gauntlet, errors, root } = loadGauntletSettings(cwd);
     const telemetry = resolveTelemetry(gauntlet);
+    const { specDirs } = resolveFlowGuards(gauntlet);
+    const planDirs = planDirsFor(specDirs);
     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());
@@ -125,7 +129,7 @@
     const agentOverrides = preset || repo ? { ...(preset ?? {}), ...(repo ?? {}) } : undefined;
     const rawCmds = gauntlet.verifyBeforeShip?.testCommands;
     const testCommands = Array.isArray(rawCmds) && rawCmds.length > 0 && rawCmds.every((c) => typeof c === "string" && c.trim()) ? (rawCmds as string[]) : undefined;
-    return { telemetry, errors, agentOverrides, versions: realVersions(), testCommands };
+    return { telemetry, specDirs, planDirs, errors, agentOverrides, versions: realVersions(), testCommands };
   }
 
   export const realDeps: Deps = { fs: realFs, git: realGit, jj: realJj, now: isoNow, settings: realSettings };
@@ -142,16 +146,16 @@
   // gauntlet-resume's reconstruction skips brainstorm with `resume: <spec path>`; the path
   // is the bind candidate on that route because no spec write follows.
   const RESUME_REASON_RE = /^resume: (\S+)$/;
-  export function resumeSpecOf(phases: PhaseMap | undefined): string | undefined {
+  export function resumeSpecOf(phases: PhaseMap | undefined, specDirs: readonly string[]): string | undefined {
     const b = phases?.brainstorm;
     const m = b?.status === "skipped" && typeof b.reason === "string" ? RESUME_REASON_RE.exec(b.reason) : null;
-    return m && isSpecPath(toPosix(m[1])) ? m[1] : undefined;
+    return m && isSpecPath(toPosix(m[1]), specDirs) ? m[1] : undefined;
   }
 
   // Walks the session branch like phase-tracker.ts: successful phase_tracker results set
   // the phase map and the flow-entry marker; bind candidates are taken only while armed
   // and dropped on reset. Silent: no events are emitted.
-  export function replayBranch(entries: Iterable<unknown>): ReplayResult {
+  export function replayBranch(entries: Iterable<unknown>, specDirs: readonly string[]): ReplayResult {
     const out: ReplayResult = { phases: emptyPhases(), gauntletEntered: false };
     const calls = new Map<string, { name: string; args: unknown }>();
     for (const raw of entries) {
@@ -173,14 +177,14 @@
           out.planCheckSpec = undefined;
           out.lastSpecWrite = undefined;
         }
-        const resumed = d.action === "skip" ? resumeSpecOf(d.phases) : undefined;
+        const resumed = d.action === "skip" ? resumeSpecOf(d.phases, specDirs) : undefined;
         if (out.gauntletEntered && resumed) out.lastSpecWrite = resumed;
       } else if (msg.toolName === "plan_check") {
         const d = msg.details as { status?: string; specPath?: string } | undefined;
         if (out.gauntletEntered && d?.status === "pass" && typeof d.specPath === "string") out.planCheckSpec = d.specPath;
       } else if ((msg.toolName === "write" || msg.toolName === "edit") && !msg.isError && msg.toolCallId) {
         const p = (calls.get(msg.toolCallId)?.args as { path?: unknown } | undefined)?.path;
-        if (out.gauntletEntered && typeof p === "string" && isSpecPath(toPosix(p))) out.lastSpecWrite = p;
+        if (out.gauntletEntered && typeof p === "string" && isSpecPath(toPosix(p), specDirs)) out.lastSpecWrite = p;
       }
     }
     return out;
@@ -328,7 +332,7 @@
       predecessorLinks.clear();
       record = loadOrCreate(specRel);
       for (const link of record.supersedes ?? []) {
-        if (!isSafeSpecLink(link)) continue;
+        if (!isSafeSpecLink(link, snap.specDirs)) continue;
         const predecessor = deps.fs.readFile(abs(link));
         if (predecessor !== undefined && isSupersededByBanner(predecessor, record.spec)) predecessorLinks.add(link);
       }
@@ -369,9 +373,9 @@
       councilPending = undefined;
     };
 
-    const isSafeSpecLink = (link: string): boolean => {
+    const isSafeSpecLink = (link: string, specDirs: readonly string[]): boolean => {
       const normalized = posix.normalize(link);
-      return isSpecPath(link) && !posix.isAbsolute(link) && normalized !== ".." && !normalized.startsWith("../");
+      return isSpecPath(link, specDirs) && !posix.isAbsolute(link) && normalized !== ".." && !normalized.startsWith("../");
     };
 
     const refreshLinks = () => {
@@ -449,9 +453,9 @@
       }
       phases = details.phases;
       if (action === "skip" && !boundSpec && canBind() && lastCtx) {
-        const resumed = resumeSpecOf(details.phases);
+        const resumed = resumeSpecOf(details.phases, snap.specDirs);
         const loc = resumed ? await locate(lastCtx, resumed) : undefined;
-        if (loc && isSpecPath(loc.rel)) {
+        if (loc && isSpecPath(loc.rel, snap.specDirs)) {
           await bind(loc.rel, snap, loc.toplevel, loc.via);
           flush();
         }
@@ -481,13 +485,13 @@
       pendingTest.clear();
       sessionId = ctx.sessionManager.getSessionId();
       currentDir = snap.telemetry.dir;
-      const replay = replayBranch(ctx.sessionManager.getBranch());
+      const replay = replayBranch(ctx.sessionManager.getBranch(), snap.specDirs);
       phases = replay.phases;
       gauntletEntered = replay.gauntletEntered;
       if (!canBind()) return;
       const candidate = replay.planCheckSpec ?? replay.lastSpecWrite;
       const loc = candidate ? await locate(ctx, candidate) : undefined;
-      if (loc && isSpecPath(loc.rel)) {
+      if (loc && isSpecPath(loc.rel, snap.specDirs)) {
         await bind(loc.rel, snap, loc.toplevel, loc.via);
         flush();
       }
@@ -537,7 +541,7 @@
         const rawPath = (event.input as { path?: unknown }).path;
         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`);
+          if (typeof rawPath === "string" && isSpecPath(toPosix(rawPath), snap.specDirs)) warn(`spec ${rawPath} is outside a git checkout; telemetry not recorded`);
           return undefined;
         }
         return onSpecInteraction(event.toolName, loc, event, snap);
@@ -568,13 +572,13 @@
     const onSpecInteraction = async (tool: "write" | "edit" | "read", loc: { toplevel: string; rel: string; via: "git" | "jj" }, event: { input: unknown; content: unknown[] }, snap: SettingsSnapshot): Promise<unknown> => {
       const rel = loc.rel;
       if (!boundSpec) {
-        if ((tool === "write" || tool === "edit") && isSpecPath(rel)) {
+        if ((tool === "write" || tool === "edit") && isSpecPath(rel, snap.specDirs)) {
           await bind(rel, snap, loc.toplevel, loc.via);
           if (!boundSpec) return undefined;
           const patch = onBoundSpecWrite(tool, rel, event);
           flush();
           return patch;
-        } else if (isPlanPath(rel)) {
+        } else if (isPlanPath(rel, snap.planDirs)) {
           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))) {
@@ -586,7 +590,7 @@
       }
       if (loc.toplevel !== toplevel) {
         // Another checkout: a fresh run, never a rename of this record.
-        if ((tool === "write" || tool === "edit") && isSpecPath(rel) && canBind() && !sealedOnDisk(loc.toplevel, rel, snap.telemetry.dir)) {
+        if ((tool === "write" || tool === "edit") && isSpecPath(rel, snap.specDirs) && canBind() && !sealedOnDisk(loc.toplevel, rel, snap.telemetry.dir)) {
           unbind();
           await bind(rel, snap, loc.toplevel, loc.via);
           if (!boundSpec) return undefined;
@@ -602,13 +606,13 @@
         flush();
         return patch;
       }
-      if (tool === "write" && isSpecPath(rel) && phases.brainstorm.status === "in_progress" && isDraftOrMissing(boundSpec)) {
+      if (tool === "write" && isSpecPath(rel, snap.specDirs) && phases.brainstorm.status === "in_progress" && isDraftOrMissing(boundSpec)) {
         if (await rebind(rel)) onBoundSpecWrite(tool, rel, event);
         flush();
         return undefined;
       }
-      if (tool === "edit" && isSpecPath(rel)) {
-        onOtherSpecEdit(rel, event);
+      if (tool === "edit" && isSpecPath(rel, snap.specDirs)) {
+        onOtherSpecEdit(rel, event, snap.specDirs);
         flush();
       }
       return undefined;
@@ -616,7 +620,7 @@
 
     // Defined in block 2.
     let onBoundSpecWrite: (tool: "write" | "edit", rel: string, event: { input: unknown; content: unknown[] }) => unknown;
-    let onOtherSpecEdit: (rel: string, event: { input: unknown }) => void;
+    let onOtherSpecEdit: (rel: string, event: { input: unknown }, specDirs: string[]) => void;
 
     let amendmentOpen = false;
     let lastPlanTasks: { status: string }[] | undefined;
@@ -728,7 +732,7 @@
       if (!record || !toplevel || liveShipEvent(record.events)) return;
       record.status = "shipped";
       record.shipped_at = deps.now();
-      const out = await computeJjDiff({ jj: deps.jj ?? realJj, cwd: toplevel, spec: record.spec, dir: currentDir, buckets: snap.telemetry.buckets });
+      const out = await computeJjDiff({ jj: deps.jj ?? realJj, cwd: toplevel, spec: record.spec, dir: currentDir, buckets: snap.telemetry.buckets, planDirs: snap.planDirs });
       if (out.warning) warn(out.warning);
       record.derived.modified_files = out.modified_files;
       record.derived.diff = out.diff;
@@ -743,7 +747,7 @@
         const rawPath = (event.input as { path?: unknown }).path;
         if (typeof rawPath === "string" && phases.brainstorm.status === "in_progress") {
           const loc = await locate(ctx, rawPath);
-          if (loc && isSpecPath(loc.rel)) {
+          if (loc && isSpecPath(loc.rel, snap.specDirs)) {
             const recRel = recordPathFor(snap.telemetry.dir, loc.rel);
             const existing = deps.fs.readFile(join(loc.toplevel, recRel));
             const parsed = existing ? parseRecord(existing) : undefined;
@@ -832,8 +836,8 @@
       return undefined;
     };
 
-    onOtherSpecEdit = (rel, event) => {
-      if (!record || !boundSpec || !isSafeSpecLink(rel)) return;
+    onOtherSpecEdit = (rel, event, specDirs) => {
+      if (!record || !boundSpec || !isSafeSpecLink(rel, specDirs)) return;
       if (!isSupersededByBanner(insertedText(event.input), boundSpec)) return;
       predecessorLinks.add(rel);
       refreshLinks();

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "pi-gauntlet",
-  "version": "5.23.1",
+  "version": "6.0.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

@@ -17,9 +17,9 @@ Identify the target project → set up an isolated worktree → understand curre
 
 Do **not** implement until the design is presented and approved, regardless of simplicity. Implementation-heavy requests define spec scope; they do not lift this gate.
 
-You **may** read code/docs, run the existing system to observe current behavior, write under `doc/specs/`, and `edit` a predecessor spec there to add a [supersession banner](reference/superseding.md).
+You **may** read code/docs, run the existing system to observe current behavior, write under a resolved spec dir (`gauntlet_setting({ key: "flowGuards" })` -> `specDirs`), and `edit` a predecessor spec there to add a [supersession banner](reference/superseding.md).
 
-You may **not** write outside `doc/specs/`; build, deploy, validate, or exercise the proposed change; run implementation skills; commit the spec on `main`; or start `/skill:writing-plans`.
+You may **not** write outside the resolved spec dirs; build, deploy, validate, or exercise the proposed change; run implementation skills; commit the spec on `main`; or start `/skill:writing-plans`.
 
 The line: current-system observation is research; exercising the proposed change waits for approval.
 
@@ -63,7 +63,7 @@ Detection order: (1) infer from ticket labels, description, or paths; (2) use th
 The spec is the first commit in a dedicated worktree, never a separate commit on `main`.
 
 1. Invoke `/skill:using-git-worktrees`; use `.worktrees/` or the project-native location.
-2. Carry its `Worktree ready at <full-path>` value: spec path `<full-path>/doc/specs/<filename>.md`; every dispatch uses that `cwd`; git uses `git -C <full-path>`. Keep the process cwd unchanged.
+2. Carry its `Worktree ready at <full-path>` value: spec path `<full-path>/<spec dir>/<filename>.md`; every dispatch uses that `cwd`; git uses `git -C <full-path>`. Keep the process cwd unchanged.
 3. Write, review, and commit there.
 
 Spec, plan, and implementation share this worktree. The spec and its telemetry record (`<telemetry.dir>/<spec path with .md -> .yaml>`, default `.pi/gauntlet/telemetry/doc/specs/<spec>.yaml`) are deliverables and ship in the squash; only the plan is stripped. `/skill:finishing-a-development-branch` strips the plan, then seals and commits the record before landing. Explicit trivial one-off edits outside this flow need no worktree.
@@ -146,7 +146,7 @@ Shared schemas, contracts, and invariants require a spec. If work is mechanical
 
 ## Filename Convention
 
-Write under the routed `doc/specs/`: ticketed `YYYY-MM-DD-<ticket-id>-<topic>.md`, otherwise `YYYY-MM-DD-<topic>.md`. Use a filename-safe tracker slug (`E-12345`, `gh-123`), but native references in plan headers and commits. `<topic>` is 3-6 kebab-case words without `-design` or another suffix.
+Write under the routed spec dir: pick the routing prose's dir (overrides file, `AGENTS.md`) when it is one of the resolved dirs, else the one resolved dir from `gauntlet_setting({ key: "flowGuards" })` that already exists in the repo, else the first resolved dir (`doc/specs` under the default). Name ticketed files `YYYY-MM-DD-<ticket-id>-<topic>.md`, otherwise `YYYY-MM-DD-<topic>.md`. Use a filename-safe tracker slug (`E-12345`, `gh-123`), but native references in plan headers and commits. `<topic>` is 3-6 kebab-case words without `-design` or another suffix.
 
 Mint the slug once during gather and reuse it. If questionary invalidates it, write to the new path and delete the uncommitted draft.
 
@@ -293,7 +293,7 @@ One question at a time, YAGNI, 2-3 approaches, two design rounds, clarify freely
 
 ## Red Flags — STOP
 
-- Writes outside `doc/specs/` ([owner](#hard-constraint)).
+- Writes outside the resolved spec dirs ([owner](#hard-constraint)).
 - Draft overwrite without the same-turn full read, or overwrite via `edit` ([owner](#spec-self-review-before-user-review-gate)).
 - Dispatch while line 1 is the context-draft marker ([owner](#spec-self-review-before-user-review-gate)).
 - Inline scope or ambiguity checks ([owner](#spec-council-optional)).

package/skills/finishing-a-development-branch/SKILL.md

@@ -185,11 +185,11 @@ Rows 1-2 run the Option 1/2 blocks; row 3 runs the Keep block and row 4 the Disc
 
 Run this on the feature branch before any landing path. The spec and its telemetry record (`<telemetry.dir>/<spec path with .md -> .yaml>`, default `.pi/gauntlet/telemetry/doc/specs/<spec>.yaml`) are deliverables and ship in the squash; only the plan is stripped. The record is an untracked, git-excluded file until this step commits it. `<bin>` is `<directory of this skill's SKILL.md>/../../bin`, resolved from the skill's `<location>` in the system prompt.
 
-Read the plan's `**Spec:**` header (repo-relative, backticks stripped) before the strip; that value is `--spec`.
+Read the plan's `**Spec:**` header (repo-relative, backticks stripped) before the strip; pass that value as `--spec`. Resolve the spec dirs with `gauntlet_setting({ key: "flowGuards" })` and use their sibling `plans` dirs for plan paths.
 
 ```bash
 # Plans are ephemeral - if one was committed on this branch, remove it before landing.
-PLAN_PATH=doc/plans/<plan-file>.md   # or <service>/doc/plans/<plan-file>.md
+PLAN_PATH=<sibling-plans-dir>/<plan-file>.md   # the sibling plans dir of the spec's dir
 if git -C "$WORKTREE" ls-files --error-unmatch "$PLAN_PATH" >/dev/null 2>&1; then
   git -C "$WORKTREE" rm "$PLAN_PATH" && git -C "$WORKTREE" commit -m "Remove ephemeral plan doc"
 fi

package/skills/forge-skill/SKILL.md

@@ -0,0 +1,68 @@
+---
+name: forge-skill
+description: Use when creating or editing a SKILL.md, a skill's reference file, an agent persona, a prompt template, or a slash command in pi or Claude Code - including one-line edits - or when such a file exceeds 500 lines, gains if/else branching, or drifts from imperative voice; the authoring skill for repos that follow gauntlet's conventions.
+---
+
+# Forge Skill
+
+## Overview
+
+This skill governs every file a model reads as instructions: `SKILL.md` and its reference files, agent personas, prompt templates, and slash commands, in pi and in Claude Code. Every sentence below is a rule to apply or a fact to check.
+
+## Conventions
+
+Sources: pi - `docs/skills` in `@earendil-works/pi-coding-agent`; Claude Code - `code.claude.com/docs/en/skills`.
+
+| Item | pi | Claude Code |
+|---|---|---|
+| Frontmatter | `---` on line 1, `name` and `description`, closing `---` | Same; an unknown field is ignored silently; unparseable YAML loads the skill with no fields |
+| `name` | Lowercase letters, digits, hyphens; no leading, trailing, or doubled hyphen; at most 64 chars; match the directory name (Agent Skills standard; pi does not enforce it) | Display label for a personal or project skill (the command is the directory name); the last command segment for a plugin skill |
+| `description` | At most 1024 chars; a skill without one is not loaded | Recommended; `description` plus `when_to_use` is cut at 1536 chars in the listing |
+| Harness-only fields | `license`, `compatibility`, `metadata`, `allowed-tools` (spec-listed, not enforced) | `when_to_use`, `argument-hint`, `arguments`, `user-invocable`, `allowed-tools` (enforced) |
+| `disable-model-invocation: true` | Command-only skill | Same; also excluded from subagent preload |
+| Invocation | `/skill:name [args]` | `/name [args]`, or `/plugin:name` for a plugin skill |
+| Supporting files | `reference/<topic>.md` (gauntlet convention; pi docs show `references/`), read at the step that names it; dispatch payloads sit beside `SKILL.md` | Any file linked by relative path; `references/`, `scripts/`, `assets/` by convention; `scripts/` files are executed, not loaded |
+| Substitutions | None; the body is read as written | Argument tokens and `CLAUDE_*` variables in the dollar form expand before the model reads the body. In prose, prefix an argument token with one backslash (backslash, dollar, ARGUMENTS) and name a variable bare (`CLAUDE_SKILL_DIR`) |
+| Locations | `.pi/skills/`, `~/.pi/agent/skills/`, `.agents/skills/`, `~/.agents/skills/`, a package's `skills/` dir | `.claude/skills/`, `~/.claude/skills/`, a plugin's `skills/` dir; `.agents/skills/` is not read |
+| Reload after edit | `/reload` | Watched for `.claude/skills/` and `~/.claude/skills/`; a plugin skill needs a new session |
+
+## Authoring rules
+
+These rules bind the lines an edit adds or changes. Leave other lines alone.
+
+- Imperative voice. Write instructions as commands. Never "should", "consider", "you may want to", "it is recommended".
+- Low conditionality. One path per step: branch only on a runtime fact the model can observe - a tool result, a file's presence, a settings value - never on the reader's judgment. Two branches is the ceiling; a third goes into a table or a `reference/` file.
+- Minimal diff. A rule change touches the sentence that owns the rule, not the section. Never restate a rule in a second place; link the owner.
+- Oversized file. A change touching a file over 500 lines extracts the concern it touches - or the largest self-contained `##` section - into `reference/<topic>.md` in the same change, and leaves a one-line "read X now" pointer at the step that needs it.
+- Recipe over prohibition. A shape or quality problem gets a statement of what the output is; a discipline problem gets one explicit rule. Never a list of things to avoid.
+- No nuance clauses. "Unless it matters", "when appropriate", "if needed" reopen the decision; delete them or name the observable condition.
+- Description is a trigger. State when to load the skill (symptoms, file types, situations); never summarize its steps.
+- One example. One concrete example per rule, never three.
+- Skip what the model knows. No explanations of git, shell, or the harness.
+- Never force-load. Cross-reference a skill by its invocation name (pi `/skill:name`, Claude Code `/name` or `/plugin:name`); never with `@`.
+- ASCII punctuation, compact `|---|` table separators, present tense.
+
+## Edit procedure
+
+1. Read the whole file.
+2. Locate and edit the sentence that owns the rule you are changing (see Minimal diff).
+3. Read the changed lines back against `## Authoring rules`.
+4. Run `wc -l` on the file; over 500 lines, extract per the oversized-file rule.
+5. pi: run `/reload`. Claude Code: start a new session.
+
+## Test (optional)
+
+Run after adding a rule or rewording a discipline rule.
+
+1. Write one scenario prompt the rule governs.
+2. In one turn dispatch two fresh workers: the loaded worker's task is the scenario plus the full `SKILL.md` body; the baseline worker's task is the scenario alone.
+3. Compare the two outputs. Fold every excuse the baseline gives into the rule sentence it evades.
+
+| Harness | Dispatch |
+|---|---|
+| pi | `subagent({ agent: "worker", context: "fresh", task })` twice, one task with the body appended |
+| Claude Code | The harness's subagent dispatch tool, twice, same split |
+
+## Project overrides
+
+If a gauntlet overrides file exists - checked in order: `.pi/gauntlet-overrides.md`, `<repo root>/gauntlet-overrides.md`, `<repo root>/doc/gauntlet-overrides.md`; first found wins - read it. Read and apply `## conventions` whenever present, without a relevance judgment. Give this skill's named section precedence over conflicting `## conventions` rules. Use other relevant sections - by name match, by topic (routing, verification, worktrees, etc.), or by workflow convention - to override or extend the instructions above. Project-local `AGENTS.md` is already in context - check it for project-specific routing tables, service paths, and verification commands.

package/skills/gauntlet-resume/reference/reconstruction.md

@@ -25,10 +25,7 @@ for a base ref before reading any artifact.
 
 A pinned spec (seed route, `seed.md`) skips this section.
 
-Spec/plan directories: `piGauntlet.flowGuards.specDirs` plus each one's sibling `plans` directory. Resolve with the precedence `doc/configuration.md` documents for every `piGauntlet.*` key: the session cwd's `.pi/settings.json` if it defines `flowGuards`,
-else the active pi profile's `settings.json`, else the default `["doc/specs"]` (sibling
-`doc/plans`). An empty array is the default. `<dirs>` below is that resolved list,
-space-separated - never the literal defaults when a setting is present.
+Resolve with `gauntlet_setting({ key: "flowGuards" })`; `<dirs>` below is its `specDirs` plus `planDirs` (each spec dir's sibling `plans` dir), space-separated.
 
 ```bash
 git -C <worktree> diff --diff-filter=A --name-only <base>..HEAD -- <dirs>

package/skills/writing-plans/SKILL.md

@@ -17,13 +17,14 @@ DRY. YAGNI. TDD. Frequent commits.
 
 Before drafting the plan, check `phase_tracker({ action: "status" })`. If `plan` is already `in_progress` (a flow restored by `/skill:gauntlet-resume` arrives this way), do **not** call `start` again - a repeat `start` on the in_progress phase resets its guard ledger. Otherwise call `phase_tracker({ action: "start", phase: "plan" })`.
 
-**Input:** an approved spec in `<project>/doc/specs/<filename>.md` — produced by `/skill:brainstorming` in this session, or restored from another session by `/skill:gauntlet-resume`. Those two are the only entry points.
+**Input:** an approved spec in a resolved spec dir from `gauntlet_setting({ key: "flowGuards" })` - produced by `/skill:brainstorming` in this session, or restored from another session by `/skill:gauntlet-resume`. Those two are the only entry points.
 
-**Save plans to:** the sibling `doc/plans/` directory next to the spec. The plan filename matches the spec filename exactly — same date, same ticket ID (if any), same topic slug, no `-design` suffix. The plan path is absolute under the worktree (`<abs worktree path>/doc/plans/<filename>.md`, the path reported by `using-git-worktrees`), and `plan_check({ planPath })` receives that absolute path - the tool roots its checks at the plan's own checkout, not at the session cwd.
+**Save plans to:** the sibling `plans/` directory next to the spec's resolved dir (`doc/specs` -> `doc/plans`, `docs/specs` -> `docs/plans`). The plan filename matches the spec filename exactly - same date, same ticket ID (if any), same topic slug, no `-design` suffix. Use the absolute plan path under the worktree (`<abs worktree path>/<sibling plans dir>/<filename>.md`, using the path reported by `using-git-worktrees`), and `plan_check({ planPath })` receives that absolute path - the tool roots its checks at the plan's own checkout, not at the session cwd.
 
 | Spec path | Plan path |
 |---|---|
 | `doc/specs/2025-05-26-foo.md` | `doc/plans/2025-05-26-foo.md` |
+| `docs/specs/2025-05-26-foo.md` | `docs/plans/2025-05-26-foo.md` |
 | `doc/specs/2025-05-26-PROJ-1234-foo.md` | `doc/plans/2025-05-26-PROJ-1234-foo.md` |
 | `<service>/doc/specs/<name>.md` | `<service>/doc/plans/<name>.md` |
 
@@ -32,7 +33,7 @@ If no spec exists, send the work back to `/skill:brainstorming`. Do not invent a
 ## Boundaries
 
 - Read code and docs: yes
-- Write the plan to the sibling `doc/plans/` of the spec: yes
+- Write the plan to the sibling `plans/` dir of the spec: yes
 - Edit or create any other files: no
 - Write implementation code: never inside this skill. After Self-Review + `phase_tracker` complete, auto-invoke `/skill:subagent-driven-development` to execute.
 - Land the plan on `main`: no — the plan commit goes on the worktree branch (same branch as the spec)