pi-gauntlet 4.2.3 → 4.3.0

package/CHANGELOG.md

@@ -1,5 +1,29 @@
 # Changelog
 
+## v4.3.0 - 2026-07-06
+
+DRY gauntlet settings resolution. All `piGauntlet.*` settings reads now route
+through one shared resolver (`extensions/lib/gauntlet-settings.ts`), consumed by
+a new `gauntlet_setting` tool (for skills) and by the extensions directly.
+
+- **New `gauntlet_setting` tool** (registered by `phase-tracker`, gauntlet-internal):
+  returns the resolved `specCouncil` or `closureReview` value from pi's merged
+  settings. Five skill call sites (`brainstorming`, `roasting-the-spec`,
+  `subagent-driven-development`, `conformance-check`, `settings-precedence`)
+  replace their hand-rolled two-file bash/prose merge with this tool. This fixes
+  an observed failure where the repo-only read fell back to the fresh `worker`
+  critique and silently skipped a configured spec council.
+- **Behavior change (latent-bug fix):** extensions previously read `pi.settings`,
+  which does not exist on the extension API - so every `closureReview`,
+  `flowGuards`, and `verifyBeforeShip` config read was dead (always `{}`) and
+  consumer overrides were silently ignored. These settings now take effect for
+  the first time. Most visible: `closureReview.model` now actually pins the
+  conformance-gate model (and the phase-tracker guard can block a mismatched
+  dispatch). If you set any of these keys expecting the prior no-op, review them.
+- `scripts/ci.mjs` now type-checks `extensions/lib/`, runs the resolver unit
+  tests, asserts the lib files are packed, and enforces a no-`pi.settings`
+  invariant.
+
 ## v4.2.3 - 2026-07-05
 
 Branding, funding, and gallery preview. No behavior change.

package/README.md

@@ -232,6 +232,8 @@ A tool, not a hook. Skills call `phase_tracker({ action: "start" | "complete" |
 
 Distinct from `plan-tracker`: `phase-tracker` answers "what stage of the workflow am I in?"; `plan-tracker` answers "which task within the current stage am I on?"
 
+**`gauntlet_setting` tool.** `phase-tracker` also registers `gauntlet_setting({ key: "specCouncil" | "closureReview" })`, a gauntlet-internal tool through which skills resolve merged `piGauntlet.*` settings (repo `.pi/settings.json` over the agent preset, via pi's own `SettingsManager`). It returns the resolved value as a JSON block in the tool result — `specCouncil` yields the council-vs-worker verdict, `closureReview` yields the conformance-gate `model`/`enforce`/`maxFixRounds`. It introduces no new settings key. Every `piGauntlet.*` read — the skills via this tool, both extensions directly — routes through one shared helper (`extensions/lib/gauntlet-settings*.ts`); no code reads `pi.settings` by hand.
+
 **Closure-review gate.** `complete verify` is rejected unless a successful
 `conformance-reviewer` dispatch (a `subagent` result whose `results[]` contains
 `agent: "conformance-reviewer"` with `exitCode: 0`) has been observed since the

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

@@ -0,0 +1,23 @@
+// Isolates the pi runtime import so the pure resolver module stays importable by
+// ci.mjs unit tests. Only pi-loaded extensions import this file.
+import { SettingsManager, getAgentDir } from "@earendil-works/pi-coding-agent";
+import { mergeGauntlet, type PiGauntlet } from "./gauntlet-settings.ts";
+
+export interface LoadedGauntlet {
+  gauntlet: PiGauntlet;
+  errors: string[];
+}
+
+// Reads the preset (agentDir/settings.json) and repo (cwd/.pi/settings.json)
+// layers via pi's own SettingsManager and returns the whole-object second-level
+// merge (repo over preset). SettingsManager never throws on a bad file - it
+// substitutes {} for that layer and records the error, surfaced here via errors[]
+// so callers can report a degraded read instead of failing silent.
+export function loadGauntletSettings(cwd: string, agentDir: string = getAgentDir()): LoadedGauntlet {
+  const sm = SettingsManager.create(cwd, agentDir);
+  const preset = sm.getGlobalSettings() as { piGauntlet?: Record<string, unknown> };
+  const repo = sm.getProjectSettings() as { piGauntlet?: Record<string, unknown> };
+  const gauntlet = mergeGauntlet(preset?.piGauntlet, repo?.piGauntlet);
+  const errors = sm.drainErrors().map((e) => `${e.scope}: ${e.error.message}`);
+  return { gauntlet, errors };
+}

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

@@ -0,0 +1,118 @@
+import { test } from "node:test";
+import assert from "node:assert/strict";
+import {
+  mergeGauntlet,
+  resolveSpecCouncil,
+  resolveClosureReview,
+  resolveFlowGuards,
+  resolveVerifyBeforeShip,
+  settingsErrorWarning,
+  type PiGauntlet,
+} from "./gauntlet-settings.ts";
+
+const DEFAULT_TEST_COMMANDS = ["make ci", "pytest"];
+
+test("mergeGauntlet: repo key replaces preset key whole-object", () => {
+  const preset = { specCouncil: { members: ["a"], chair: "c" }, closureReview: { model: "m" } };
+  const repo = { specCouncil: { members: ["b"] } };
+  const merged = mergeGauntlet(preset, repo);
+  assert.deepEqual(merged.specCouncil, { members: ["b"] });
+  assert.deepEqual(merged.closureReview, { model: "m" });
+});
+
+test("mergeGauntlet: undefined layers -> {}", () => {
+  assert.deepEqual(mergeGauntlet(undefined, undefined), {});
+});
+
+test("specCouncil: non-empty string array -> council", () => {
+  const r = resolveSpecCouncil({ specCouncil: { members: ["p/m1", " p/m2 "], chair: "p/c" } });
+  assert.equal(r.verdict, "council");
+  assert.deepEqual(r.members, ["p/m1", "p/m2"]);
+  assert.equal(r.chair, "p/c");
+  assert.equal(r.malformed, false);
+  assert.equal(r.warning, undefined);
+});
+
+test("specCouncil: absent -> worker, not malformed", () => {
+  const r = resolveSpecCouncil({});
+  assert.equal(r.verdict, "worker");
+  assert.deepEqual(r.members, []);
+  assert.equal(r.malformed, false);
+});
+
+test("specCouncil: empty array -> worker, not malformed", () => {
+  const r = resolveSpecCouncil({ specCouncil: { members: [] } });
+  assert.equal(r.verdict, "worker");
+  assert.equal(r.malformed, false);
+});
+
+test("specCouncil: non-array members -> worker + malformed + warning", () => {
+  const r = resolveSpecCouncil({ specCouncil: { members: "p/m" as unknown as string[] } });
+  assert.equal(r.verdict, "worker");
+  assert.equal(r.malformed, true);
+  assert.ok(r.warning);
+});
+
+test("specCouncil: entry not a non-empty string -> worker + malformed", () => {
+  const r = resolveSpecCouncil({ specCouncil: { members: ["p/m", ""] } });
+  assert.equal(r.verdict, "worker");
+  assert.equal(r.malformed, true);
+});
+
+test("specCouncil: chair echoed in worker path", () => {
+  const r = resolveSpecCouncil({ specCouncil: { members: [], chair: "p/c" } });
+  assert.equal(r.verdict, "worker");
+  assert.equal(r.chair, "p/c");
+});
+
+test("specCouncil: non-string chair does NOT downgrade a valid members verdict", () => {
+  const r = resolveSpecCouncil({ specCouncil: { members: ["p/m"], chair: 5 as unknown as string } });
+  assert.equal(r.verdict, "council");
+  assert.equal(r.chair, undefined);
+  assert.equal(r.malformed, true);
+  assert.ok(r.warning);
+});
+
+test("closureReview: model present/non-string/absent", () => {
+  assert.equal(resolveClosureReview({ closureReview: { model: " m " } }).model, "m");
+  assert.equal(resolveClosureReview({ closureReview: { model: 5 as unknown as string } }).model, undefined);
+  assert.equal(resolveClosureReview({}).model, undefined);
+});
+
+test("closureReview: enforce default true; false only when explicitly false", () => {
+  assert.equal(resolveClosureReview({}).enforce, true);
+  assert.equal(resolveClosureReview({ closureReview: { enforce: false } }).enforce, false);
+  assert.equal(resolveClosureReview({ closureReview: { enforce: true } }).enforce, true);
+});
+
+test("closureReview: maxFixRounds default 2, <0 -> 0, non-int -> 2", () => {
+  assert.equal(resolveClosureReview({}).maxFixRounds, 2);
+  assert.equal(resolveClosureReview({ closureReview: { maxFixRounds: 5 } }).maxFixRounds, 5);
+  assert.equal(resolveClosureReview({ closureReview: { maxFixRounds: -3 } }).maxFixRounds, 0);
+  assert.equal(resolveClosureReview({ closureReview: { maxFixRounds: 1.5 } }).maxFixRounds, 2);
+});
+
+test("flowGuards: defaults + overrides", () => {
+  assert.deepEqual(resolveFlowGuards({}), { enforce: true, specDirs: ["doc/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"]);
+});
+
+test("settingsErrorWarning: includes prefix and joined errors", () => {
+  const w = settingsErrorWarning(["bad json", "missing field"]);
+  assert.match(w, /gauntlet settings load error \(using defaults\)/);
+  assert.ok(w.includes("bad json; missing field"));
+});
+
+test("verifyBeforeShip: default vs override", () => {
+  const d = resolveVerifyBeforeShip({}, DEFAULT_TEST_COMMANDS);
+  assert.deepEqual(d.testCommands, DEFAULT_TEST_COMMANDS);
+  assert.equal(d.warningReference, undefined);
+  const o = resolveVerifyBeforeShip(
+    { verifyBeforeShip: { testCommands: ["x"], warningReference: "doc/t.md" } },
+    DEFAULT_TEST_COMMANDS,
+  );
+  assert.deepEqual(o.testCommands, ["x"]);
+  assert.equal(o.warningReference, "doc/t.md");
+});

package/extensions/lib/gauntlet-settings.ts

@@ -0,0 +1,124 @@
+// Pure gauntlet-settings resolvers. NO pi runtime import: this module is imported
+// by ci.mjs unit tests (node --test) which run outside pi, where
+// @earendil-works/pi-coding-agent is unresolvable. The loader
+// (gauntlet-settings-loader.ts) owns the pi import.
+
+export interface PiGauntlet {
+  specCouncil?: { members?: unknown; chair?: unknown };
+  closureReview?: { enforce?: unknown; model?: unknown; maxFixRounds?: unknown };
+  flowGuards?: { enforce?: unknown; specDirs?: unknown };
+  verifyBeforeShip?: { testCommands?: unknown; warningReference?: unknown };
+}
+
+// Whole-object second-level merge: each piGauntlet key present in the repo layer
+// replaces the preset's wholesale; keys absent from repo fall through to preset.
+// Mirrors pi's own deepMergeSettings second-level spread (not exported).
+export function mergeGauntlet(
+  preset: Record<string, unknown> | undefined,
+  repo: Record<string, unknown> | undefined,
+): PiGauntlet {
+  return { ...(preset ?? {}), ...(repo ?? {}) } as PiGauntlet;
+}
+
+const nonEmptyString = (v: unknown): v is string => typeof v === "string" && v.trim().length > 0;
+const joinWarn = (ws: string[]): string | undefined => (ws.length ? ws.join("; ") : undefined);
+
+export interface SpecCouncilResolved {
+  verdict: "council" | "worker";
+  members: string[];
+  chair: string | undefined;
+  malformed: boolean;
+  warning: string | undefined;
+}
+
+export function resolveSpecCouncil(g: PiGauntlet): SpecCouncilResolved {
+  const sc = g.specCouncil;
+  const warnings: string[] = [];
+  let malformed = false;
+
+  let chair: string | undefined;
+  const rawChair = sc?.chair;
+  if (rawChair === undefined) {
+    chair = undefined;
+  } else if (nonEmptyString(rawChair)) {
+    chair = rawChair.trim();
+  } else {
+    chair = undefined;
+    malformed = true;
+    warnings.push("specCouncil.chair is not a non-empty string; ignoring it");
+  }
+
+  const rawMembers = sc?.members;
+  const worker = (extra?: string): SpecCouncilResolved => {
+    if (extra) {
+      malformed = true;
+      warnings.push(extra);
+    }
+    return { verdict: "worker", members: [], chair, malformed, warning: joinWarn(warnings) };
+  };
+
+  if (rawMembers === undefined) return worker();
+  if (!Array.isArray(rawMembers)) return worker("specCouncil.members is not an array; using the worker critique");
+  if (rawMembers.length === 0) return worker();
+  if (!rawMembers.every(nonEmptyString))
+    return worker("specCouncil.members has a non-string or empty entry; using the worker critique");
+
+  return {
+    verdict: "council",
+    members: rawMembers.map((m) => (m as string).trim()),
+    chair,
+    malformed,
+    warning: joinWarn(warnings),
+  };
+}
+
+export interface ClosureReviewResolved {
+  model: string | undefined;
+  enforce: boolean;
+  maxFixRounds: number;
+}
+
+export function resolveClosureReview(g: PiGauntlet): ClosureReviewResolved {
+  const cr = g.closureReview;
+  const model = nonEmptyString(cr?.model) ? cr!.model.trim() : undefined;
+  const enforce = cr?.enforce !== false;
+  const raw = cr?.maxFixRounds;
+  const maxFixRounds = typeof raw === "number" && Number.isInteger(raw) ? (raw < 0 ? 0 : raw) : 2;
+  return { model, enforce, maxFixRounds };
+}
+
+export interface FlowGuardsResolved {
+  enforce: boolean;
+  specDirs: string[];
+}
+
+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"];
+  return { enforce, specDirs };
+}
+
+export interface VerifyBeforeShipResolved {
+  testCommands: string[];
+  warningReference: string | undefined;
+}
+
+export function resolveVerifyBeforeShip(g: PiGauntlet, defaultTestCommands: string[]): VerifyBeforeShipResolved {
+  const vbs = g.verifyBeforeShip;
+  const rawCmds = vbs?.testCommands;
+  const testCommands =
+    Array.isArray(rawCmds) && rawCmds.length > 0 && rawCmds.every(nonEmptyString)
+      ? (rawCmds as string[])
+      : defaultTestCommands;
+  const warningReference = nonEmptyString(vbs?.warningReference) ? vbs!.warningReference.trim() : undefined;
+  return { testCommands, warningReference };
+}
+
+export function settingsErrorWarning(errors: string[]): string {
+  return `\u26a0\ufe0f gauntlet settings load error (using defaults): ${errors.join("; ")}`;
+}

package/extensions/phase-tracker.ts

@@ -14,6 +14,13 @@ import { StringEnum } from "@earendil-works/pi-ai";
 import type { ExtensionAPI, ExtensionContext, Theme } from "@earendil-works/pi-coding-agent";
 import { Text } from "@earendil-works/pi-tui";
 import { type Static, Type } from "@sinclair/typebox";
+import {
+  resolveClosureReview,
+  resolveFlowGuards,
+  resolveSpecCouncil,
+  settingsErrorWarning,
+} from "./lib/gauntlet-settings.ts";
+import { loadGauntletSettings } from "./lib/gauntlet-settings-loader.ts";
 
 const PHASES = ["brainstorm", "plan", "implement", "verify", "ship"] as const;
 type Phase = (typeof PHASES)[number];
@@ -32,19 +39,6 @@ interface PhaseTrackerDetails {
   error?: string;
 }
 
-type Settings = {
-  piGauntlet?: {
-    closureReview?: {
-      enforce?: boolean;
-      model?: string;
-    };
-    flowGuards?: {
-      enforce?: boolean;
-      specDirs?: string[];
-    };
-  };
-};
-
 // Qualification per spec "Qualifying dispatch": a successful conformance-reviewer
 // child run in the result details (pi-cohort SingleResult: { agent, exitCode }).
 // Management mode and async dispatches return results: [] and fail this check.
@@ -227,14 +221,6 @@ function formatStatus(phases: PhaseMap): string {
 export default function (pi: ExtensionAPI) {
   let phases: PhaseMap = emptyPhases();
   let conformanceDispatched = false;
-  const closureEnforced = () =>
-    ((pi.settings ?? {}) as Settings).piGauntlet?.closureReview?.enforce !== false;
-  const closureReviewModel = () =>
-    ((pi.settings ?? {}) as Settings).piGauntlet?.closureReview?.model;
-
-  const flowGuardsCfg = () => ((pi.settings ?? {}) as Settings).piGauntlet?.flowGuards ?? {};
-  const flowGuardsEnforced = () => flowGuardsCfg().enforce !== false;
-  const specDirs = () => flowGuardsCfg().specDirs ?? ["doc/specs"];
 
   // Warn-once-per-phase ledger; cleared on every phase transition and on reconstruct.
   const firedGuards = new Map<string, boolean>();
@@ -321,7 +307,25 @@ export default function (pi: ExtensionAPI) {
     });
   }
 
-  pi.on("tool_call", async (event) => {
+  pi.on("tool_call", async (event, ctx) => {
+    // D3.b: one fresh settings read per event, lazily, only if a guard needs it.
+    const addGuardWarning = (id: string, text: string) => {
+      const prior = pendingGuardWarnings.get(id);
+      pendingGuardWarnings.set(id, prior ? prior + "\n\n" + text : text);
+    };
+    let gauntletCache: ReturnType<typeof loadGauntletSettings> | undefined;
+    const g = () => {
+      if (!gauntletCache) {
+        gauntletCache = loadGauntletSettings(ctx.cwd);
+        if (gauntletCache.errors.length > 0) addGuardWarning(event.toolCallId, settingsErrorWarning(gauntletCache.errors));
+      }
+      return gauntletCache.gauntlet;
+    };
+    const closureEnforced = () => resolveClosureReview(g()).enforce;
+    const closureReviewModel = () => resolveClosureReview(g()).model;
+    const flowGuardsEnforced = () => resolveFlowGuards(g()).enforce;
+    const specDirs = () => resolveFlowGuards(g()).specDirs;
+
     // Closure-review model guard - independent of flowGuards, gated by closureReview.enforce.
     if (event.toolName === "subagent" && closureEnforced()) {
       const model = closureReviewModel();
@@ -338,12 +342,21 @@ export default function (pi: ExtensionAPI) {
           }
           const mismatched = [...new Set((models as string[]).filter((m) => m !== configured))];
           if (mismatched.length > 0) {
-            pendingGuardWarnings.set(event.toolCallId, closureModelMismatchWarning(configured, mismatched));
+            addGuardWarning(event.toolCallId, closureModelMismatchWarning(configured, mismatched));
           }
         }
       }
     }
 
+    // Flow guards apply only to write/edit/bash while a guard phase is active.
+    // Cheap in-memory gate BEFORE any settings load: phase state is in-memory, so an
+    // event no guard inspects (any read-only tool, or any tool in a dormant session)
+    // returns here without touching disk. Only genuinely guardable events pay for g().
+    const brainstormActive = phases.brainstorm.status === "in_progress";
+    const guardableWrite = (event.toolName === "write" || event.toolName === "edit") && brainstormActive;
+    const guardableBash = event.toolName === "bash" && activeGuardPhase() !== undefined;
+    if (!guardableWrite && !guardableBash) return undefined;
+
     if (!flowGuardsEnforced()) return undefined;
 
     // Guard 3 — write/edit outside the spec dir during brainstorm.
@@ -352,7 +365,7 @@ export default function (pi: ExtensionAPI) {
       const p = (event.input as { path?: unknown } | undefined)?.path;
       if (typeof p !== "string" || pathInSpecDirs(p, specDirs())) return undefined;
       firedGuards.set("brainstorm-write", true);
-      pendingGuardWarnings.set(event.toolCallId, brainstormWriteWarning(specDirs()));
+      addGuardWarning(event.toolCallId, brainstormWriteWarning(specDirs()));
       return undefined;
     }
 
@@ -392,7 +405,7 @@ export default function (pi: ExtensionAPI) {
       }
     }
 
-    if (warnings.length > 0) pendingGuardWarnings.set(event.toolCallId, warnings.join("\n\n"));
+    if (warnings.length > 0) addGuardWarning(event.toolCallId, warnings.join("\n\n"));
     return undefined;
   });
 
@@ -427,6 +440,34 @@ export default function (pi: ExtensionAPI) {
     updateWidget(ctx);
   });
 
+  const GauntletSettingParams = Type.Object({
+    key: StringEnum(["specCouncil", "closureReview"] as const, {
+      description: "Which gauntlet setting to resolve (merged repo-over-preset).",
+    }),
+  });
+
+  pi.registerTool({
+    name: "gauntlet_setting",
+    label: "Gauntlet Setting",
+    description:
+      "Gauntlet-internal, invoked by skills: resolve a merged piGauntlet.* setting " +
+      "(repo .pi/settings.json over the agent preset). Returns the resolved value as a " +
+      "JSON block in the result content - specCouncil yields the council-vs-worker verdict, " +
+      "closureReview yields the conformance-gate model/enforce/maxFixRounds. Not for ad-hoc use.",
+    parameters: GauntletSettingParams,
+    async execute(_toolCallId, params, _signal, _onUpdate, ctx) {
+      const { gauntlet, errors } = loadGauntletSettings(ctx.cwd);
+      const payload =
+        params.key === "specCouncil"
+          ? { key: "specCouncil" as const, ...resolveSpecCouncil(gauntlet), errors }
+          : { key: "closureReview" as const, ...resolveClosureReview(gauntlet), errors };
+      return {
+        content: [{ type: "text", text: "```json\n" + JSON.stringify(payload, null, 2) + "\n```" }],
+        details: payload,
+      };
+    },
+  });
+
   pi.registerTool({
     name: "phase_tracker",
     label: "Phase Tracker",
@@ -504,7 +545,11 @@ export default function (pi: ExtensionAPI) {
               } as PhaseTrackerDetails,
             };
           }
-          if (params.phase === "verify" && closureEnforced() && !conformanceDispatched) {
+          if (
+            params.phase === "verify" &&
+            resolveClosureReview(loadGauntletSettings(ctx.cwd).gauntlet).enforce &&
+            !conformanceDispatched
+          ) {
             return {
               content: [{ type: "text", text: CLOSURE_GATE_ERROR }],
               details: {

package/extensions/verify-before-ship.ts

@@ -24,6 +24,8 @@
  */
 
 import type { ExtensionAPI } from "@earendil-works/pi-coding-agent";
+import { resolveVerifyBeforeShip, settingsErrorWarning } from "./lib/gauntlet-settings.ts";
+import { loadGauntletSettings } from "./lib/gauntlet-settings-loader.ts";
 
 // Default verification entrypoints. Override via settings.
 const DEFAULT_TEST_COMMANDS = [
@@ -38,18 +40,10 @@ const DEFAULT_TEST_COMMANDS = [
 ];
 
 const SHIP_CMD = /\b(git\s+commit|git\s+push|gh\s+pr\s+create)\b/;
+
 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)$/;
 
-type Settings = {
-  piGauntlet?: {
-    verifyBeforeShip?: {
-      testCommands?: string[];
-      warningReference?: string;
-    };
-  };
-};
-
 const isSourceWrite = (filePath: string | undefined): boolean => {
   if (!filePath) return false;
   return SOURCE_EXT.test(filePath) && !TEST_PATH.test(filePath);
@@ -72,12 +66,6 @@ const formatWarning = (command: string, testCommands: string[], reference: strin
 };
 
 export default function (pi: ExtensionAPI) {
-  const settings = (pi.settings ?? {}) as Settings;
-  const cfg = settings.piGauntlet?.verifyBeforeShip ?? {};
-  const testCommands = cfg.testCommands ?? DEFAULT_TEST_COMMANDS;
-  const testRegex = buildTestCmdRegex(testCommands);
-  const reference = cfg.warningReference;
-
   let verified = false;
   let pendingTestCallId: string | null = null;
   const pendingShipWarnings = new Map<string, string>();
@@ -92,7 +80,7 @@ export default function (pi: ExtensionAPI) {
     return typeof input?.path === "string" ? input.path : undefined;
   };
 
-  pi.on("tool_call", async (event) => {
+  pi.on("tool_call", async (event, ctx) => {
     if (event.toolName === "write" || event.toolName === "edit") {
       if (isSourceWrite(getPath(event))) verified = false;
       return undefined;
@@ -102,13 +90,32 @@ export default function (pi: ExtensionAPI) {
     const command = getCommand(event);
     if (!command) return undefined;
 
+    const addShipWarning = (id: string, text: string) => {
+      const prior = pendingShipWarnings.get(id);
+      pendingShipWarnings.set(id, prior ? prior + "\n\n" + text : text);
+    };
+
+    const { gauntlet, errors } = loadGauntletSettings(ctx.cwd);
+    const { testCommands, warningReference } = resolveVerifyBeforeShip(gauntlet, DEFAULT_TEST_COMMANDS);
+    const settingsWarned = errors.length > 0 ? settingsErrorWarning(errors) : undefined;
+    let settingsErrShown = false;
+    const testRegex = buildTestCmdRegex(testCommands);
+
     if (testRegex.test(command)) {
       pendingTestCallId = event.toolCallId;
+      if (settingsWarned && !settingsErrShown) {
+        addShipWarning(event.toolCallId, settingsWarned);
+        settingsErrShown = true;
+      }
       return undefined;
     }
 
     if (SHIP_CMD.test(command) && !verified) {
-      pendingShipWarnings.set(event.toolCallId, formatWarning(command, testCommands, reference));
+      if (settingsWarned && !settingsErrShown) {
+        addShipWarning(event.toolCallId, settingsWarned);
+        settingsErrShown = true;
+      }
+      addShipWarning(event.toolCallId, formatWarning(command, testCommands, warningReference));
     }
     return undefined;
   });

package/package.json

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

@@ -18,11 +18,13 @@ Identify the target project → set up an isolated worktree → understand curre
 While this skill is active, do **not** take any implementation action until you have presented a design and the user has approved it. This applies to **every** change regardless of perceived simplicity. An implementation-heavy request ("test it end-to-end", "push a request to rabbit", "run the service") does not lift this gate — it just tells you what the spec must cover.
 
 You **may**:
+
 - Read code and docs
 - Run the existing system to observe its **current** behaviour — this is research and feeds the spec (boot a local service, replay a sample request, capture a baseline classification, etc.)
 - Write to the project's `doc/specs/` directory
 
 You may **not**:
+
 - Write or edit code outside `doc/specs/`
 - Scaffold a project, or take any action that builds, deploys, or validates the **proposed change** — running new/edited code, exercising behaviour that doesn't exist yet, or "testing the fix" before there is one
 - Run implementation skills (`/skill:test-driven-development`, `/skill:subagent-driven-development`, etc.)
@@ -38,11 +40,13 @@ This skill ends with a **written, user-reviewed spec inside a worktree**. Nothin
 Work through the items below **in order**. This is your own checklist to follow, not a `plan_tracker` plan — brainstorming is open-ended exploration, and `plan_tracker` is execution-only (the implement phase). The terminal state is the user review gate; after approval the **only** next skill is `/skill:writing-plans`. Do not jump to implementation, and do not silently drop the critique pass.
 
 1. **Start brainstorm tracking (fresh epoch)** — as the **first action on entry**, before reading code, setting up the worktree, or answering the user, reset **both** trackers and then start the phase. A new brainstorm is a new flow, so it owns a clean slate — clear any stale phases *and* tasks left in the session by earlier work:
+
    ```
    phase_tracker({ action: "reset" })   // clears all phases
    plan_tracker({ action: "clear" })    // clears all tasks
    phase_tracker({ action: "start", phase: "brainstorm" })
    ```
+
    Re-entering while a brainstorm is already in progress is safe: mid-brainstorm there are no tasks or later phases to lose, so the reset just re-establishes the same clean slate.
 2. **Set up the worktree** — see [Worktree First](#worktree-first)
 3. **Explore project context** — files, docs, recent commits, current behaviour
@@ -51,7 +55,7 @@ Work through the items below **in order**. This is your own checklist to follow,
 6. **Present the design** — in sections, get approval after each
 7. **Write the spec** — to `doc/specs/` (see [Filename Convention](#filename-convention))
 8. **Spec self-review (lint)** — placeholder scan + internal consistency + documentation named, run inline
-9. **Critique pass (auto-dispatched)** — scope + ambiguity; the spec council via `/skill:roasting-the-spec` when `members` is configured, else a fresh `worker` (see [Spec Council](#spec-council-optional))
+9. **Critique pass (auto-dispatched)** — scope + ambiguity; the spec council via `/skill:roasting-the-spec` when `gauntlet_setting` returns verdict `council`, else a fresh `worker` (see [Spec Council](#spec-council-optional))
 10. **Re-run placeholder scan** — after the critique pass returns, first inline any `external-ref:` flags it raised (see [Spec Self-Review](#spec-self-review-before-user-review-gate)), then re-scan for placeholders its edits may have introduced; surface any ambiguity the worker could not safely resolve at the user gate
 11. **Generate spec summary** — dispatch a fresh, spec-only `spec-summarizer` and render its returned text **verbatim** at the top of the gate message — do not paraphrase, condense, re-section, or rewrite it (see [User Review Gate](#user-review-gate)); this is part of the existing gate, not a new one
 12. **User review gate** — user reviews the committed spec
@@ -64,6 +68,7 @@ Before brainstorming, identify the target project. The match drives the spec dir
 Read the repo's top-level `AGENTS.md` (already in pi's context) and any service-level `AGENTS.md` for the area the user mentioned. If the project documents a routing table mapping subprojects to spec directories and verification commands, follow it. Otherwise rely on the conventions you find.
 
 Detection order:
+
 1. Issue tracker reference (Linear, Jira, GitHub Issues) → infer from labels, description, or mentioned file paths
 2. cwd inside a service / package directory → use that area
 3. Unclear → ask the developer
@@ -135,6 +140,7 @@ When sketching the design, prefer:
 Sections of 200-300 words. Ask after each whether it looks right.
 
 Cover at minimum:
+
 - Architecture overview
 - Components / responsibilities
 - Data flow (or request flow)
@@ -203,7 +209,7 @@ After writing the spec to `<project>/doc/specs/<filename>.md` (per [Filename Con
 
 The first three checks — **placeholder scan**, **internal consistency**, and **documentation named** — are the inline **lint**: run them here at the main loop and fix what they surface. The last two — **scope** and **ambiguity** — are **not** run inline; they are the **critique pass**, auto-dispatched (per [Spec Council](#spec-council-optional)):
 
-- **Council configured** (`piGauntlet.specCouncil.members` non-empty) → invoke `/skill:roasting-the-spec`; it runs the critique and proposes dispositions.
+- **Council** (`gauntlet_setting({ key: "specCouncil" })` returns verdict `council`) → invoke `/skill:roasting-the-spec`; it runs the critique and proposes dispositions.
 - **Otherwise** → dispatch one fresh `worker` that applies the scope + ambiguity checks and fixes them in place:
 
   ```
@@ -224,7 +230,7 @@ After the critique pass returns, scan it for load-bearing external references be
 
 ## Spec Council (Optional)
 
-After the inline lint and before the user review gate, **brainstorming owns the critique-pass gate**: resolve `piGauntlet.specCouncil` **repo-local first** — the repo's `.pi/settings.json` overrides the agent preset, **whole-object** (the first file that defines `specCouncil` wins; an empty `members` there is an explicit "no council here"). Full source order and mechanics: `verification-before-completion/reference/settings-precedence.md`. **Expand `$PI_CODING_AGENT_DIR`; never substitute a hardcoded project path for it.** **When `members` is non-empty, the council *is* the critique pass — invoke `/skill:roasting-the-spec` automatically (no offer, no prompt).** When it is absent or empty, run the fresh-`worker` critique instead (see [Spec Self-Review](#spec-self-review-before-user-review-gate)); if `specCouncil` is present but malformed, emit one warning line and fall back to the worker. Approved council edits (or the worker's in-place fixes) are applied to the spec and ride in the same worktree commit as the rest of this skill's output.
+After the inline lint and before the user review gate, **brainstorming owns the critique-pass gate**. Resolve the council with `gauntlet_setting({ key: "specCouncil" })` - the tool returns the merged (repo-over-preset) value as `{ verdict, members, chair, malformed, warning, errors }`. **Do not** hand-roll a settings read. When `verdict` is `"council"`, the council *is* the critique pass - invoke `/skill:roasting-the-spec` automatically (no offer, no prompt), passing `members`/`chair`. When `verdict` is `"worker"`, run the fresh-`worker` critique instead (see [Spec Self-Review](#spec-self-review-before-user-review-gate)). If `malformed` is true or `errors` is non-empty, emit the `warning`/error as one line, then branch strictly on `verdict` - `malformed` can accompany *either* verdict (e.g. a bad `chair` with valid `members` still returns `council`), so never infer the worker path from `malformed` alone. If `gauntlet_setting` is unavailable, stop and report - never fall back to a manual bash/JSON settings merge. Approved council edits (or the worker's in-place fixes) ride in the same worktree commit. The conceptual precedence rule lives in `verification-before-completion/reference/settings-precedence.md`.
 
 ## User Review Gate
 

package/skills/roasting-the-spec/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: roasting-the-spec
-description: Use after writing a spec, when a spec council is configured (piGauntlet.specCouncil in the repo's .pi/settings.json, else the active preset's settings). Auto-dispatched by /skill:brainstorming as the critique pass when members is non-empty (no longer offered). N members on different models critique in parallel, a neutral chair consolidates and adjudicates, the parent proposes dispositions, the user approves.
+description: Use after writing a spec, when a spec council is configured (the resolved piGauntlet.specCouncil council, via the gauntlet_setting tool, repo settings over the preset). Auto-dispatched by /skill:brainstorming as the critique pass when members is non-empty (no longer offered). N members on different models critique in parallel, a neutral chair consolidates and adjudicates, the parent proposes dispositions, the user approves.
 ---
 
 # Roasting the Spec (Spec Council)
@@ -24,7 +24,7 @@ This skill may read anything and edit **only** the spec under `doc/specs/`. It d
 
 ## Configuration and gating
 
-Resolve `piGauntlet.specCouncil` **repo-local first** — the repo's `.pi/settings.json` overrides the agent preset, **whole-object** (the first file that defines `specCouncil` wins outright; an empty `members` there is an explicit "no council for this repo"). Full source order, mechanics, and the per-key granularity rule live in `verification-before-completion/reference/settings-precedence.md`. Do not hardcode a path in place of `$PI_CODING_AGENT_DIR` — expand the env var. The resolved config looks like:
+The caller (`/skill:brainstorming`) already resolved the council via `gauntlet_setting({ key: "specCouncil" })` and dispatched this skill only when `verdict` was `"council"`, passing the resolved `members` and `chair`. This skill therefore receives `members`/`chair` from that resolved value and does **not** read settings files itself. The resolved config looks like:
 
 ```json
 {
@@ -40,7 +40,7 @@ Resolve `piGauntlet.specCouncil` **repo-local first** — the repo's `.pi/settin
 - `members` — array of `provider/model` strings. Council size = array length.
 - `chair` — optional model for the synthesizer; if omitted, the synthesizer inherits the parent's model.
 
-brainstorming owns the gate: it parses this config (it may contain comments — read it, do not pipe through a strict JSON parser), emits any malformed-config warning, and decides whether to invoke this skill. This skill is dispatched **only after** brainstorming confirms `members` is non-empty, so it runs the council unconditionally on entry — no offer, no numbered choice. Absent/empty/malformed config never reaches here (brainstorming runs the fresh-`worker` critique instead). A minimal defensive re-parse is fine, but ownership of "should the council run" lives in brainstorming, not here.
+brainstorming owns the gate: it resolves this config via `gauntlet_setting`, emits any malformed-config warning, and decides whether to invoke this skill. This skill is dispatched **only after** brainstorming confirms `verdict` is `council`, so it runs the council unconditionally on entry — no offer, no numbered choice. Absent/empty/malformed config never reaches here (brainstorming runs the fresh-`worker` critique instead). Ownership of "should the council run" lives in brainstorming, not here.
 
 ## The council run
 

package/skills/subagent-driven-development/SKILL.md

@@ -86,7 +86,7 @@ Pi-subagents accepts a per-task `model` override. Use it.
 | Hard / novel / large surface | Most capable | New subsystem, complex algorithm, cross-service contract change |
 | Spec review | Default | Reads diff + spec, mechanical comparison |
 | Code-quality review | Most capable | Judgment call on naming, design, complexity |
-| Conformance / closure | Most capable | Whole-deliverable-vs-origin intent gate (`conformance-reviewer`; model from `piGauntlet.closureReview.model`, resolved repo-first whole-object, injected call-site) |
+| Conformance / closure | Most capable | Whole-deliverable-vs-origin intent gate (`conformance-reviewer`; model from `gauntlet_setting({ key: "closureReview" }).model`, injected call-site) |
 
 ```ts
 subagent({
@@ -111,8 +111,9 @@ subagent({ agent: "spec-reviewer", task: "<diff range + spec excerpt + ask: does
 subagent({ agent: "code-reviewer", task: "<diff range + ask: production-ready?>" })
 
 // closing-loop conformance (origin vs deliverable) — its OWN dispatch, never fused with code quality
-// model from piGauntlet.closureReview.model — resolve repo-local .pi/settings.json over the preset, whole-object (see verification-before-completion/reference/settings-precedence.md); omit to inherit
-subagent({ agent: "conformance-reviewer", model: /* piGauntlet.closureReview.model, repo-first per settings-precedence.md, else omit to inherit */, task: "<spec path + verbatim original prompt + full diff vs main; per conformance-check.md>" })
+// model: call gauntlet_setting({ key: "closureReview" }) first; use the returned model (omit model: if undefined to inherit) and maxFixRounds
+// If gauntlet_setting is unavailable, stop and report - never fall back to a manual bash/JSON settings merge.
+subagent({ agent: "conformance-reviewer", model: /* gauntlet_setting({ key: "closureReview" }).model, else omit to inherit */, task: "<spec path + verbatim original prompt + full diff vs main; per conformance-check.md>" })
 ```
 
 Prompt templates live alongside this SKILL.md:
@@ -179,6 +180,7 @@ For the fan-out + worktree + patch-integration + conflict mechanics, see `dispat
 3. **After 2 failed attempts:** STOP. Report failure to the user. The task probably needs redesign.
 
 **NEVER:**
+
 - Write code yourself to "help" or "finish up"
 - Fix the subagent's work inline — that pollutes your context and defeats fresh-subagent isolation
 - Silently skip the failed task
@@ -188,7 +190,7 @@ For the fan-out + worktree + patch-integration + conflict mechanics, see `dispat
 
 0. Call `phase_tracker({ action: "start", phase: "verify" })`. (The `implement` phase was started at execution start and auto-completes from `plan_tracker` once all tasks are done; this flow runs its own verify gate instead of `/skill:verification-before-completion`, so it must mark verify itself.)
 1. **Run the whole-diff code review.** Dispatch `/skill:requesting-code-review` against the worktree's full diff vs `main` (already covered in [The Process](#the-process) step "After all tasks"). Address Critical and Moderate findings before handoff. (Consumers wanting an in-flow project-specific audit re-add it as an explicit step in `.pi/gauntlet-overrides.md`, or run `/self-audit` manually.)
-2. **Close the loop — conformance check.** The review in step 1 is plan-vs-code (single-step); it inherits any requirement the plan already dropped. Before marking verify complete, dispatch a fresh-context **`conformance-reviewer`** — its **own** dispatch, never fused into the step-1 review — to confront the deliverable (code **and** docs) against the *origin* — the spec **and** the original prompt — per `verification-before-completion/reference/conformance-check.md`. Pass the spec path, the verbatim original prompt, and the full diff. On `GAPS`, do not auto-fix or auto-proceed: run the remediation loop in `verification-before-completion/reference/conformance-check.md` "When the check finds gaps" (disposition menu → isolated fix waves → bounded delta re-audit, capped by `piGauntlet.closureReview.maxFixRounds`). Only when the verdict is `CONFORMS` (or every gap is dispositioned) call `phase_tracker({ action: "complete", phase: "verify" })`.
+2. **Close the loop — conformance check.** The review in step 1 is plan-vs-code (single-step); it inherits any requirement the plan already dropped. Before marking verify complete, dispatch a fresh-context **`conformance-reviewer`** — its **own** dispatch, never fused into the step-1 review — to confront the deliverable (code **and** docs) against the *origin* — the spec **and** the original prompt — per `verification-before-completion/reference/conformance-check.md`. Pass the spec path, the verbatim original prompt, and the full diff. On `GAPS`, do not auto-fix or auto-proceed: run the remediation loop in `verification-before-completion/reference/conformance-check.md` "When the check finds gaps" (disposition menu → isolated fix waves → bounded delta re-audit, capped by `gauntlet_setting({ key: "closureReview" }).maxFixRounds`). Only when the verdict is `CONFORMS` (or every gap is dispositioned) call `phase_tracker({ action: "complete", phase: "verify" })`.
 3. Summarize what was implemented (tasks completed, files changed, test counts, code-review verdict). Give the closing loop its **own section** — `Closure / conformance: CONFORMS` (or `GAPS` with each gap and its disposition) — so the user sees intent-fidelity as a first-class line before any finishing decision, not buried in the review verdict.
 4. **Proceed to finishing — no confirmation prompt.** When the verdict is `CONFORMS` (or every gap is dispositioned), invoke `/skill:finishing-a-development-branch` immediately. Its Step 4 menu (squash / PR / keep / discard) is the human gate; a separate "ready to finish?" prompt only stacks a second stop in front of it. Open gaps are already owned by step 2, so nothing is left to decide here. Manual testing is a follow-up after the finishing choice (on `<base-branch>` after a squash-merge, or on the PR branch), never a reason to hold this gate.
 
@@ -208,12 +210,14 @@ For the fan-out + worktree + patch-integration + conflict mechanics, see `dispat
 ## Integration
 
 **Required workflow skills:**
+
 - `/skill:using-git-worktrees` — set up isolation first (small changes can branch in place with user approval)
 - `/skill:writing-plans` — creates the plan this skill executes
 - `/skill:requesting-code-review` — review template for reviewer subagents
 - `/skill:finishing-a-development-branch` — invoked automatically once the conformance verdict is `CONFORMS` (or all gaps dispositioned)
 
 **Subagents follow by default:**
+
 - TDD — runtime warnings on source-before-test. Implementer agents receive the three-scenario TDD instructions (new feature / modifying tested code / trivial) via agent profile and prompt template.
 
 ## Project overrides

package/skills/verification-before-completion/reference/conformance-check.md

@@ -41,14 +41,14 @@ whole-PR code-quality review. Fusing the two subordinates intent-coverage to a
 code-quality system prompt and compresses the conformance result to an
 afterthought. Code quality is one dispatch; conformance is another.
 
-The persona ships model-free. Resolve `piGauntlet.closureReview.model` **repo-local
-first** — the repo's `.pi/settings.json` overrides the agent preset, whole-object (see
-sibling `settings-precedence.md`) — and inject it **call-site** on the dispatch
-(`model:` if set, else omit to inherit the parent's model) — the same mechanism the
-spec-council chair uses. If the configured model is unreachable, retry once with the
-inherited model. Point it at the strongest reasoning model the resolved config can
-reach — this is the last correctness gate. `thinking` stays frontmatter-pinned at
-`xhigh` and is not call-site overridable, so the config supplies only `model`.
+The persona ships model-free. Get the model from `gauntlet_setting({ key: "closureReview" }).model`.
+If `gauntlet_setting` is unavailable, stop and report - never fall back to a manual bash/JSON
+settings merge. Inject the model **call-site** on the dispatch (omit `model:` when it is `undefined` to inherit
+the parent's model) — the same mechanism the spec-council chair uses. If the configured model
+is unreachable, retry once with the inherited model. Point it at the strongest reasoning model
+the resolved config can reach — this is the last correctness gate. `thinking` stays
+frontmatter-pinned at `xhigh` and is not call-site overridable, so the config supplies only
+`model`.
 
 Self-checking in the main session is the fallback when delegation isn't possible.
 
@@ -205,9 +205,10 @@ still-open with its prior verdict, or introducing `Gn+1`.
   blocks a `conformance-reviewer` dispatch that omits `model:`, and warns — non-blocking —
   on one whose model differs from the configured value).
 - New or still-open gaps within the cap re-enter the menu above.
-- **Cap: read `piGauntlet.closureReview.maxFixRounds`** (default `2`; missing/non-integer
-  → `2`; `< 0` → `0`). `0` = audit-only: `GAPS` renders an accept/rescope-only menu and any
-  unresolved gap escalates instead of dispatching a fix.
+- **Cap: `gauntlet_setting({ key: "closureReview" }).maxFixRounds`** (the tool applies the
+  default `2`, floors negatives at `0`, and coerces non-integers to `2`). `0` = audit-only:
+  `GAPS` renders an accept/rescope-only menu and any unresolved gap escalates instead of
+  dispatching a fix.
 - **On non-convergence** (cap reached with open gaps): **escalate to human** with the
   per-gap round-by-round verdict trail. No silent re-loop, no auto-ship.
 

package/skills/verification-before-completion/reference/settings-precedence.md

@@ -1,44 +1,55 @@
 # Settings precedence: repo-local first
 
-How to resolve a `piGauntlet.<key>` settings value that both a repo and an agent
-preset may define. Both the spec-critique gate (`specCouncil`) and the conformance
-gate (`closureReview`) use this rule; it is stated once here.
+How a `piGauntlet.<key>` value is resolved when both a repo and an agent preset
+define it. Both the spec-critique gate (`specCouncil`) and the conformance gate
+(`closureReview`) use this rule; it is stated once here.
 
-## Source order (both keys)
+## The rule
 
-Read two files, **repo-local first**:
+Repo settings override the preset, **whole-object at the second level**:
 
-1. `<repo-root>/.pi/settings.json` - repo root from `git rev-parse --show-toplevel`
-   (inside a worktree this is the worktree root).
-2. `$PI_CODING_AGENT_DIR/settings.json` - the agent preset.
+- Preset: `$PI_CODING_AGENT_DIR/settings.json`.
+- Repo: `<repo-root>/.pi/settings.json`.
 
-Mechanics for both files: they may contain comments - read them, do not pipe
-through a strict JSON parser. Expand `$PI_CODING_AGENT_DIR`; never substitute a
-hardcoded path for it (reading the repo `.pi/settings.json` as if it were the
-preset is the classic miss - they are different files). On a malformed repo-local
-file, the reading agent emits one warning line in its response and falls back to
-the preset.
-
-## Merge granularity (same for both keys): whole-object
-
-Both `specCouncil` and `closureReview` resolve **whole-object**: if the repo file
-defines the key at all, that definition **replaces** the preset's entirely; the two
-are never merged leaf-by-leaf. If the repo file does not define the key, the
-preset's value is used unchanged.
-
-This is not a pi-gauntlet convention - it is exactly what pi's own settings merge
-does. `deepMergeSettings` (pi's `SettingsManager`) merges only the **top-level**
-Settings keys (of which `piGauntlet` is one) by a one-level spread
-`{ ...preset.piGauntlet, ...repo.piGauntlet }`. That spread replaces each
-**second-level** key (`closureReview`, `specCouncil`, `flowGuards`) wholesale when
-the repo defines it; it does **not** recurse into that key's leaves. So the
-`phase-tracker.ts` closure guard (which reads `pi.settings.piGauntlet.closureReview.model`)
-and the skills (which read repo-first, whole-object) resolve the same value.
+If the repo file defines a `piGauntlet.<key>` at all, that definition **replaces**
+the preset's for that key entirely - the two are never merged leaf-by-leaf. If the
+repo file does not define the key, the preset's value is used unchanged. This is
+exactly pi's own `deepMergeSettings` behaviour: it spreads the second-level keys
+(`specCouncil`, `closureReview`, `flowGuards`, `verifyBeforeShip`) wholesale, and
+does not recurse into their leaves.
 
 **Caveat - partial definitions drop siblings.** Because the replace is
 whole-object, a repo file that sets only *one* leaf of a key silently drops the
 preset's other leaves for that key. A repo `closureReview: { "model": "..." }` with
 no `enforce`/`maxFixRounds` makes those fall back to their code defaults
 (`enforce` true, `maxFixRounds` 2), **not** to the preset's values. Define every
-leaf you care about together in the file that owns the key. (Sibling keys like
-`specCouncil` are unaffected - only the key the repo redefines is replaced.)
+leaf you care about together in the file that owns the key. (Sibling keys are
+unaffected - only the key the repo redefines is replaced.)
+
+**Settings files are strict JSON.** pi's `SettingsManager` parses them with
+`JSON.parse`; comments make the file invalid to pi itself, so never add them.
+
+## The single operational path
+
+Do **not** read or merge these files by hand. Resolution is centralized:
+
+- **Skills** resolve `piGauntlet.*` via the `gauntlet_setting` tool (registered by
+  the `phase-tracker` extension): `gauntlet_setting({ key: "specCouncil" })` or
+  `gauntlet_setting({ key: "closureReview" })`. The tool returns the merged value
+  (repo over preset) in its result content. If the tool is unavailable, stop and
+  report - never fall back to a manual bash/JSON merge (that fallback is exactly
+  the failure mode this centralization removes).
+- **Extensions** call `loadGauntletSettings(ctx.cwd)` from
+  `extensions/lib/gauntlet-settings-loader.ts`, then the matching resolver in
+  `extensions/lib/gauntlet-settings.ts`.
+
+Both paths go through pi's own `SettingsManager`, so they resolve the same merged
+value. The `phase-tracker.ts` closure guard reads via `loadGauntletSettings` +
+`resolveClosureReview`, resolving the same value the tool returns.
+
+## Scope: launch directory
+
+The tool and loader read relative to pi's session/launch directory (`ctx.cwd`, the
+primary checkout), not a mid-session worktree. A per-branch `.pi/settings.json`
+that diverges from the launch checkout is not resolved and is an unsupported
+workflow - keep `piGauntlet` settings at the repo root or in the preset.