pi-gauntlet 4.0.1 → 4.1.0

package/CHANGELOG.md

@@ -1,5 +1,24 @@
 # Changelog
 
+## v4.1.0 - 2026-07-02
+
+- **`closureReview` now resolves repo-local first.** The verify-step skills
+  (`subagent-driven-development`, `verification-before-completion/reference/conformance-check.md`)
+  resolve `piGauntlet.closureReview.model`/`maxFixRounds` from a repo's
+  `.pi/settings.json` over the agent preset, **whole-object** - matching how the
+  `phase-tracker.ts` guard already reads `pi.settings` (pi replaces the whole
+  `closureReview` block when a repo defines it). Previously they read the preset
+  only, so a repo-local `closureReview.model` was silently ignored and the
+  conformance gate ran on the parent's model.
+- **New shared reference `skills/verification-before-completion/reference/settings-precedence.md`.**
+  States the two-file source order and the whole-object merge rule once; `specCouncil`
+  and `closureReview` both resolve the same way and both point at it. `roasting-the-spec`
+  and `brainstorming` replace their duplicated lookup prose with a pointer.
+- **Closure guard upgraded from presence-check to match-check.** A
+  `conformance-reviewer` dispatch that omits `model:` is still blocked; one whose
+  `model:` differs from the configured `closureReview.model` now gets a non-blocking
+  warning appended to the result. Gated by `closureReview.enforce` as before.
+
 ## v4.0.1 - 2026-07-02
 
 No content change. Smoke-tests the tag-triggered CI publish path (OIDC trusted publishing to npm) added in v4.0.0's release machinery commit.

package/README.md

@@ -162,7 +162,7 @@ Unset → provider default thinking for that model. `conformance-reviewer` and t
 
 ### Conformance gate model
 
-`conformance-reviewer` ships without a `model:` in its frontmatter — like the spec-council personas, its model is supplied per preset so each profile points the last correctness gate at the strongest reasoning model its providers can reach. The verify-step skills read it from `piGauntlet.closureReview.model` and inject it **call-site** on the conformance dispatch (the same mechanism the spec-council chair uses). Add it to each preset's `settings.json`:
+`conformance-reviewer` ships without a `model:` in its frontmatter — like the spec-council personas, its model is supplied per preset so each profile points the last correctness gate at the strongest reasoning model its providers can reach. The verify-step skills resolve `piGauntlet.closureReview.model` **repo-local first** (a repo's `.pi/settings.json` overrides the preset whole-object - defining `closureReview` there replaces the preset's entire block, so set every leaf you need together) and inject it **call-site** on the conformance dispatch (the same mechanism the spec-council chair uses). Add it to each preset's `settings.json` (or a repo's `.pi/settings.json` to override per repo):
 
 ```json
 {
@@ -174,7 +174,7 @@ Unset → provider default thinking for that model. `conformance-reviewer` and t
 
 Frontmatter pins `thinking: xhigh` and `defaultContext: fresh` (the gate always runs cold, with max reasoning) and `thinking` is not call-site overridable, so the config supplies only `model`. If `closureReview.model` is unset the dispatch omits `model:` and the gate inherits the parent's model; if the configured model is unreachable it retries once inherited.
 
-When `closureReview.model` **is** set, the phase-tracker enforces call-site injection: a `subagent` dispatch of `conformance-reviewer` that omits `model:` is **blocked at tool-call time** (before it runs) so the gate can never silently degrade to the parent's builder model. The documented one-retry fallback still works - pass the inherited model *explicitly* and it is allowed; only a bare omission is blocked. Disabling `closureReview.enforce` disables this guard too.
+When `closureReview.model` **is** set, the phase-tracker match-checks call-site injection: a `subagent` dispatch of `conformance-reviewer` that omits `model:` is **blocked at tool-call time** (before it runs) so the gate can never silently degrade to the parent's builder model, and a dispatch whose `model:` **differs** from the configured value gets a non-blocking **warning** appended to the result (drift is surfaced, not blocked). The documented one-retry fallback still works - pass an explicit model and it runs (with a warning if it differs). Disabling `closureReview.enforce` disables this guard too.
 
 `closureReview.enforce` (default `true`) controls the phase-tracker gate that
 blocks `complete verify` until the conformance-reviewer has run; set `false` to
@@ -202,7 +202,7 @@ If you want to know what's in each persona before using it, see [`agents/`](./ag
 - `members` (required) — roster of `provider/model` strings; council size = array length, one critique per model. Empty or absent → the council never runs; brainstorming falls back to a single fresh-`worker` critique (scope + ambiguity, auto-applied).
 - `chair` (optional) — model for the consolidating synthesizer; defaults to the inherited model when omitted.
 
-Rosters are per-preset: each pi profile (`agent`, `agent.anthropic`, `agent.bedrock`, …) reads its own `settings.json`, so list only models that profile's providers can reach. The two personas it dispatches — `spec-council-member` and `spec-council-synthesizer` — are model-free; their model is injected per task from this config.
+Rosters resolve **repo-local first**: a repo's `.pi/settings.json` overrides the preset (whole-object — the first file that defines `specCouncil` wins), otherwise each pi profile (`agent`, `agent.anthropic`, `agent.bedrock`, …) reads its own `settings.json`. List only models the resolving config's providers can reach. The two personas it dispatches — `spec-council-member` and `spec-council-synthesizer` — are model-free; their model is injected per task from this config.
 
 ## Extensions
 

package/extensions/phase-tracker.ts

@@ -98,19 +98,21 @@ const branchBlockReason = (phase: Phase): string =>
   "To override, set piGauntlet.flowGuards.enforce: false.";
 
 // Closure-review model guard: when piGauntlet.closureReview.model is configured,
-// a conformance-reviewer dispatch MUST inject that model call-site. The persona ships
-// model-free, so a bare omission silently inherits the parent session's builder model -
-// defeating the point of an independent closing gate on a different model. Walk the
-// single / tasks / chain / parallel dispatch shapes and report any conformance-reviewer
-// entry that carries no model. An explicit model (even a fallback) is fine; only a bare
-// omission is caught - that preserves the documented "retry once inherited" escape hatch,
-// which the orchestrator takes by passing the inherited model explicitly.
-const conformanceEntriesMissingModel = (input: unknown): boolean => {
-  const entries: { agent?: unknown; model?: unknown }[] = [];
+// a conformance-reviewer dispatch should inject that model call-site. The persona
+// ships model-free, so a bare omission silently inherits the parent session's
+// builder model - defeating the point of an independent closing gate. Walk the
+// single / tasks / chain / parallel dispatch shapes and collect the model of every
+// conformance-reviewer entry (undefined = absent/empty/non-string). A bare omission
+// is BLOCKED; an explicit model that differs from the configured one is WARNED
+// (non-blocking), preserving the documented retry-with-fallback hatch while
+// surfacing drift.
+const conformanceModels = (input: unknown): (string | undefined)[] => {
+  const models: (string | undefined)[] = [];
+  const norm = (m: unknown) => (typeof m === "string" && m.trim() ? m.trim() : undefined);
   const collect = (node: unknown): void => {
     if (!node || typeof node !== "object") return;
     const o = node as Record<string, unknown>;
-    if (typeof o.agent === "string") entries.push({ agent: o.agent, model: o.model });
+    if (o.agent === "conformance-reviewer") models.push(norm(o.model));
     for (const key of ["tasks", "chain", "parallel"] as const) {
       const v = o[key];
       if (Array.isArray(v)) for (const item of v) collect(item);
@@ -118,19 +120,28 @@ const conformanceEntriesMissingModel = (input: unknown): boolean => {
     }
   };
   collect(input);
-  return entries.some((e) => e.agent === "conformance-reviewer" && !e.model);
+  return models;
 };
 
-const closureModelBlockReason = (model: string): string =>
-  `Blocked: conformance-reviewer dispatched without a model while ` +
-  `piGauntlet.closureReview.model is set to "${model}".\n` +
+const closureModelBlockReason = (model: string, missing: number, total: number): string =>
+  `Blocked: ${missing} of ${total} conformance-reviewer ${total === 1 ? "dispatch" : "entries"} ` +
+  `omitted a model while piGauntlet.closureReview.model is set to "${model}".\n` +
   `The persona ships model-free, so a bare omission silently inherits this session's ` +
   `builder model - the closing gate would then run on the same model that built the work, ` +
-  `not the independent one the preset pins. Re-dispatch with model: "${model}" injected ` +
-  `call-site. If that model is unreachable, pass an explicit fallback model (the documented ` +
-  `one-retry escape hatch) - only a bare omission is blocked.\n` +
+  `not the independent one configured (repo .pi/settings.json, else the preset). Re-dispatch ` +
+  `with model: "${model}" injected call-site on every conformance-reviewer entry. If that ` +
+  `model is unreachable, pass an explicit fallback model (the documented one-retry escape ` +
+  `hatch) - only a bare omission is blocked.\n` +
   `To disable this gate, set piGauntlet.closureReview.enforce: false.`;
 
+const closureModelMismatchWarning = (configured: string, mismatched: string[]): string =>
+  `⚠️ conformance-reviewer dispatched with ${mismatched.length === 1 ? "model" : "models"} ` +
+  `${mismatched.map((m) => `"${m}"`).join(", ")} while ` +
+  `piGauntlet.closureReview.model is set to "${configured}".\n` +
+  `If this is the documented one-retry fallback (the configured model was ` +
+  `unreachable), ignore this. Otherwise the closing gate is running on an ` +
+  `unintended model - re-dispatch with model: "${configured}".`;
+
 const brainstormWriteWarning = (specDirs: string[]): string =>
   "⚠️ Writing outside the spec directory during the brainstorm phase.\n" +
   `Brainstorming may only edit the spec under ${specDirs.join(", ")}. Implementation\n` +
@@ -317,8 +328,19 @@ export default function (pi: ExtensionAPI) {
       // Only execution-mode dispatches carry a model; management/control modes
       // (action: list/get/create/update/delete/status/...) execute nothing, so skip them.
       const hasAction = !!(event.input as { action?: unknown })?.action;
-      if (model && !hasAction && conformanceEntriesMissingModel(event.input)) {
-        return { block: true, reason: closureModelBlockReason(model) };
+      if (model && !hasAction) {
+        const configured = model.trim();
+        const models = conformanceModels(event.input);
+        if (models.length > 0) {
+          const missing = models.filter((m) => m === undefined).length;
+          if (missing > 0) {
+            return { block: true, reason: closureModelBlockReason(configured, missing, models.length) };
+          }
+          const mismatched = [...new Set((models as string[]).filter((m) => m !== configured))];
+          if (mismatched.length > 0) {
+            pendingGuardWarnings.set(event.toolCallId, closureModelMismatchWarning(configured, mismatched));
+          }
+        }
       }
     }
 
@@ -377,6 +399,11 @@ export default function (pi: ExtensionAPI) {
   pi.on("tool_result", async (event) => {
     if (event.toolName === "subagent") {
       if (qualifiesAsClosureDispatch(event.details)) conformanceDispatched = true;
+      const warning = pendingGuardWarnings.get(event.toolCallId);
+      if (warning) {
+        pendingGuardWarnings.delete(event.toolCallId);
+        return { content: [{ type: "text" as const, text: warning }, ...event.content] };
+      }
       return undefined;
     }
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "pi-gauntlet",
-  "version": "4.0.1",
+  "version": "4.1.0",
   "description": "Opinionated, gated workflow skills, subagent personas, and runtime extensions for the pi coding agent.",
   "type": "module",
   "license": "MIT",

package/skills/brainstorming/SKILL.md

@@ -215,14 +215,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` from **two** settings files, repo-local first, and select the path.
-
-Lookup order (first file that **defines** `specCouncil` wins — do not merge across files):
-
-1. `<repo-root>/.pi/settings.json` — repo root from `git rev-parse --show-toplevel` (the worktree root inside a worktree). A repo that defines `specCouncil` overrides the preset, even with empty `members` (explicit "no council here").
-2. `$PI_CODING_AGENT_DIR/settings.json` — agent preset; consulted only when the repo file does not define `specCouncil`.
-
-Both files may contain comments — read them, don't strict-parse. **Expand `$PI_CODING_AGENT_DIR`; never substitute a hardcoded project path for it** (reading the repo `.pi/settings.json` as if it were the preset file is the classic miss — repo-local and preset are different files). **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 `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.
 
 ## User Review Gate
 

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

@@ -24,12 +24,7 @@ This skill may read anything and edit **only** the spec under `doc/specs/`. It d
 
 ## Configuration and gating
 
-Resolve `piGauntlet.specCouncil` from **two** settings files, repo-local first:
-
-1. `<repo-root>/.pi/settings.json` (repo root = `git rev-parse --show-toplevel`, which inside a worktree is the worktree root). **If this file defines `specCouncil`, it wins** — even an empty `members` here is an explicit "no council for this repo".
-2. `$PI_CODING_AGENT_DIR/settings.json` (agent preset) — consulted **only** when the repo file does not define `specCouncil` at all.
-
-The first file that defines the key wins; do not merge member lists across files. Do not hardcode a project path in place of `$PI_CODING_AGENT_DIR` — expand the env var. The resolved config looks like:
+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:
 
 ```json
 {

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

@@ -87,7 +87,7 @@ Pi-subagents accepts a per-task `model` override. Use it.
 | Spec review | Default | Reads diff + spec, mechanical comparison |
 | Code-quality review | Most capable | Judgment call on naming, design, complexity |
 | Final reviewer | Most capable | Whole-PR-scope review |
-| Conformance / closure | Most capable | Whole-deliverable-vs-origin intent gate (`conformance-reviewer`; model from `piGauntlet.closureReview.model`, injected call-site) |
+| 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) |
 
 ```ts
 subagent({
@@ -112,8 +112,8 @@ 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 (read $PI_CODING_AGENT_DIR/settings.json); omit to inherit
-subagent({ agent: "conformance-reviewer", model: /* piGauntlet.closureReview.model from config, else omit to inherit */, task: "<spec path + verbatim original prompt + full diff vs main; per conformance-check.md>" })
+// 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>" })
 ```
 
 Prompt templates live alongside this SKILL.md:

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

@@ -36,14 +36,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. Read the active preset's settings at
-`$PI_CODING_AGENT_DIR/settings.json` for `piGauntlet.closureReview.model` 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 preset 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. 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`.
 
 Self-checking in the main session is the fallback when delegation isn't possible.
 
@@ -197,7 +197,8 @@ still-open with its prior verdict, or introducing `Gn+1`.
 
 - The re-audit dispatch carries the **same call-site `model:` injection** as the initial
   audit (when `piGauntlet.closureReview.model` is set, the phase-tracker closure guard
-  requires every `conformance-reviewer` dispatch to specify `model:`).
+  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

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

@@ -0,0 +1,44 @@
+# 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.
+
+## Source order (both keys)
+
+Read two files, **repo-local first**:
+
+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.
+
+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.
+
+**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.)