pi-gauntlet 4.6.0 → 4.6.2

package/CHANGELOG.md

@@ -1,5 +1,27 @@
 # Changelog
 
+## v4.6.2 - 2026-08-07
+
+Trim the always-shipped tool descriptions of the gauntlet-internal tools to
+one-liners: `gauntlet_setting` -> "Resolve merged piGauntlet.* settings (repo
+over preset); for skill use only.", `phase_tracker` -> phase arrow + "ad-hoc
+calls do not arm gates. Not for ad-hoc use." Every call site is a skill body
+already in context, so the cut prose was pure duplication (~120-200
+tokens/request). Parameter schemas/descriptions and `plan_tracker` (whose long
+description deters ambient TODO-list misuse) are untouched.
+
+## v4.6.1 - 2026-08-04
+
+Lazy-load the conformance disposition protocol (#5). The carried-open disposition
+grammar (dense render, response grammar, execute order) moves out of
+`finishing-a-development-branch/SKILL.md` Step 3.5 into a new GAPS-only
+`reference/disposition-protocol.md`, so the common CONFORMS fast path no longer
+pays that grammar's token cost. The human decision menu and the CONFORMS/summary
+render stay inline. Byte-for-byte relocation, behavior unchanged. Also
+single-sources the `maxFixRounds: 0` / precondition-unavailable carry-OPEN rule
+in `conformance-check.md` (one authoritative statement plus four
+back-references), retaining every distinct contract.
+
 ## v4.6.0 - 2026-07-30
 
 Default supersession marking (#4). When a new spec replaces a known predecessor,

package/extensions/phase-tracker.ts

@@ -561,11 +561,7 @@ export default function (pi: ExtensionAPI) {
   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.",
+    description: "Resolve merged piGauntlet.* settings (repo over preset); for skill use only.",
     parameters: GauntletSettingParams,
     async execute(_toolCallId, params, _signal, _onUpdate, ctx) {
       const { gauntlet, errors } = loadGauntletSettings(ctx.cwd);
@@ -584,10 +580,8 @@ export default function (pi: ExtensionAPI) {
     name: "phase_tracker",
     label: "Phase Tracker",
     description:
-      "Track workflow phase progress (brainstorm → plan → implement → verify → ship). " +
-      "Actions: start (mark phase in_progress), complete (mark phase complete), " +
-      "skip (mark phase skipped with reason), status (show all phases), reset (clear all phases), substep (set/clear a substep label on an in_progress phase). " +
-      "Drives gauntlet-flow enforcement entered via brainstorming; the closure gate, closure-model guard, and flow guards arm only when brainstorming started the flow. Ad-hoc start verify/start implement calls do not arm the gates. Not for ad-hoc use.",
+      "Track workflow phase progress (brainstorm → plan → implement → verify → ship); " +
+      "ad-hoc calls do not arm gates. Not for ad-hoc use.",
     parameters: PhaseTrackerParams,
 
     async execute(_toolCallId, params, _signal, _onUpdate, ctx) {

package/package.json

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

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

@@ -88,17 +88,7 @@ Closure / conformance: CONFORMS
 
 then continue directly to Step 4. No approval prompt, no menu, no shared options line, no sign-off. If the run auto-applied fixes, surface the flat `auto-applied fix commits: <Gn: SHA>, ...` index from the durable block as **one informational, non-blocking line** with a one-line revert offer (see "Revert semantics") - a gap that auto-converged mid-verify has no bullet, so this index is the only place its fix commit stays revertable. Do not wait for acknowledgment.
 
-**Carried-open render (dense).** Read the `## Closure / conformance` block. Render a header with the decision count, one bullet per decision unit (a gap by default; a `Gn/Cn` concern only where the reference split it), then the shared options line, then the recommended-set reply. Never show durable-card internals (ownership, evidence tokens, identity, hashes) in the render.
-
-Each bullet:
-
-`* <handle> - <plain title>: <what's unresolved, one clause>. <short question> Recommended: <choice> (<one-clause why>).`
-
-- `<handle>` leads the bullet and is a short unique human word derived from the title (`Cache coverage` -> `cache`); on collision append a digit. It is the token option 2 targets. When a gap split and no clean word fits, use the bare `Gn/Cn`; a single-concern gap uses its gap ID `Gn`.
-- The shared options line sits below the bullets: `Other options per item: fix-now / accept / rescope / follow-up / custom`, listing the options **generally available across items**. When a specific item's availability deviates - an option unavailable for it, or an `UNAUTHORIZED` item whose `rescope` is unavailable and whose `fix-now` means removal - note that deviation as a short parenthetical on **that item's bullet** (one clause, not a block), e.g. `(rescope N/A: scope creep)`. The shared line appears **only in the carried-open render**, never in the zero-gap path. Full per-option effects only on request, or when option 2 targets an unclear choice.
-- Group items under one recommended line only when they share a disposition and rationale; each grouped handle repeats its title.
-- Availability per concern comes from the reference's single availability table - apply it against current context (worktree state, `maxFixRounds`, ownership, resource accessibility), do not restate it. `UNAUTHORIZED` bullets ask the reference's question verbatim (`Should this unrequested behavior become part of the current workflow?`); `rescope-into-spec` is shown **unavailable** (not dropped) and `fix-now` means **removal** of the unrequested code.
-- `revert conformance fix Gn`, when the gap has an auto-applied fix, renders on the shared options line as a **separate one-off action** - never inside a bullet's recommendation and never in the option-2 list. Name the parent gap and warn that revert undoes the entire gap-level commit (see "Revert semantics").
+**Carried-open (`status: GAPS (N open)`).** Read `reference/disposition-protocol.md` and follow it for the carried-open render (dense) grammar, the response grammar, and the 9-step execute order. Render the human decision menu in the shape below, drive the dispositions per that reference, then print the summary render and continue to Step 4. If that reference file cannot be read, stop and surface a blocking error — do **not** improvise the grammar from memory.
 
 Representative carried-open render (multi-concern gap split to `e2e`; single-concern gap `cache`; `UNAUTHORIZED` gap `auth`):
 
@@ -119,36 +109,7 @@ Other options per item: fix-now / accept / rescope / follow-up / custom.
 
 A single-concern render is identical minus the split: one bullet whose handle is the gap ID or word, no sibling.
 
-#### Response grammar
-
-```
-1                                  -> apply every recommendation
-2: cache=follow-up
-2: e2e=custom(open ticket after image lands), cache=follow-up
-```
-
-- `1` (or `apply recommended`) applies all recommendations.
-- `2:` takes a comma-separated override list, each `<handle>=<choice>`; omitted items keep their recommendation. A handle may appear at most once (repeat = invalid).
-- `custom(<concrete effect>)` supplies an inline effect. Manual fix-in-place is expressed only as `custom(...)` where isolated `fix-now` is unavailable.
-- `recommended: none` items follow the reference's preflight (linked, not restated): the item needs a `<handle>=custom(...)` decision, and option 1 is withheld until every open item has an executable recommendation; after the custom decision the menu re-renders for the remainder.
-- `revert conformance fix Gn` is a valid standalone reply, mutually exclusive with `1` and `2:`; it never appears inside a `2:` override list.
-- Invalid handle or choice -> focused reprompt naming only that item, retaining every valid pick and never reopening the gate. Unknown token: list the valid titled handles. Known item, bad choice: repeat its title + its available choices.
-
-#### Execute order
-
-Take **no** disposition action before the reply. Then, once, in order:
-
-1. **Normalize** every `custom(...)` into explicit operations; classify state-changing (edits code or spec) vs not. Clarify only an ambiguous or unexecutable effect.
-2. **Commit spec edits** (`accept-into-spec`, `rescope-into-spec`, state-changing spec `custom`) - the main session edits the spec directly, before any fix dispatch (a dirty tree rejects `worktree: true`, and the re-audit must read the amended spec).
-3. **Re-audit if step 2 changed the spec**; regenerate the inventory and re-render if it changed. Project `fix-now` only from the refreshed inventory.
-4. **fix-now + code-changing custom:** project the selected concerns per gap into the reference's concern-scoped fix contract (excluding accepted/rescoped/followed-up siblings); run the reference "Fix loop" (unchanged - do not re-describe it). A code-changing `custom` runs the project's tests + `code-reviewer` on its delta before proceeding. Re-run Step 1's canonical tests.
-5. **Re-audit after all state-changing work;** obtain fresh decisions **only if** the refreshed inventory differs from the approved one, else proceed.
-6. **follow-up** from the current inventory: create the item via the project's issue-tracker convention (`.pi/gauntlet-overrides.md`), record the ticket ID/URL; on failure keep the concern open.
-7. **Non-state-changing custom:** execute and record the result.
-8. **revert** (`revert conformance fix Gn`): light-revert the indexed commit, re-run Step 1's canonical tests; on failure stop; on pass re-audit and regenerate.
-9. Re-enter Step 3.5 with the re-audited block if any concern remains open.
-
-Record every final disposition with its **stable ID** as `Gn/Cn - <title>: <disposition>` (or `Gn - <title>: <disposition>` for a single-concern gap) - ticket ID/URL for `follow-up`, result for `custom`; never relabel a `custom` result as a recommendation. This durable record is the machine/audit surface; the interactive render stays handle-based. Then continue to Step 4:
+Execute the chosen dispositions per `reference/disposition-protocol.md` (Execute order), then print the closure summary and continue to Step 4:
 
 ```
 Closure / conformance: CONFORMS

package/skills/finishing-a-development-branch/reference/disposition-protocol.md

@@ -0,0 +1,46 @@
+# Carried-open disposition protocol
+
+Consumed by `finishing-a-development-branch` Step 3.5 on the **GAPS branch only** — the CONFORMS fast path never reads this file. Antecedent map for the relocated grammar below: "the reference" = `../../verification-before-completion/reference/conformance-check.md` (canonical for the availability table, the `UNAUTHORIZED` question, the `recommended: none` preflight, the freshness rule, and the concern-scoped fix projection); "Revert semantics", "the zero-gap path", and every `Step N` (`Step 1`, `Step 3.5`, `Step 4`) reference = `../SKILL.md`.
+
+**Carried-open render (dense).** Read the `## Closure / conformance` block. Render a header with the decision count, one bullet per decision unit (a gap by default; a `Gn/Cn` concern only where the reference split it), then the shared options line, then the recommended-set reply. Never show durable-card internals (ownership, evidence tokens, identity, hashes) in the render.
+
+Each bullet:
+
+`* <handle> - <plain title>: <what's unresolved, one clause>. <short question> Recommended: <choice> (<one-clause why>).`
+
+- `<handle>` leads the bullet and is a short unique human word derived from the title (`Cache coverage` -> `cache`); on collision append a digit. It is the token option 2 targets. When a gap split and no clean word fits, use the bare `Gn/Cn`; a single-concern gap uses its gap ID `Gn`.
+- The shared options line sits below the bullets: `Other options per item: fix-now / accept / rescope / follow-up / custom`, listing the options **generally available across items**. When a specific item's availability deviates - an option unavailable for it, or an `UNAUTHORIZED` item whose `rescope` is unavailable and whose `fix-now` means removal - note that deviation as a short parenthetical on **that item's bullet** (one clause, not a block), e.g. `(rescope N/A: scope creep)`. The shared line appears **only in the carried-open render**, never in the zero-gap path. Full per-option effects only on request, or when option 2 targets an unclear choice.
+- Group items under one recommended line only when they share a disposition and rationale; each grouped handle repeats its title.
+- Availability per concern comes from the reference's single availability table - apply it against current context (worktree state, `maxFixRounds`, ownership, resource accessibility), do not restate it. `UNAUTHORIZED` bullets ask the reference's question verbatim (`Should this unrequested behavior become part of the current workflow?`); `rescope-into-spec` is shown **unavailable** (not dropped) and `fix-now` means **removal** of the unrequested code.
+- `revert conformance fix Gn`, when the gap has an auto-applied fix, renders on the shared options line as a **separate one-off action** - never inside a bullet's recommendation and never in the option-2 list. Name the parent gap and warn that revert undoes the entire gap-level commit (see "Revert semantics").
+
+#### Response grammar
+
+```
+1                                  -> apply every recommendation
+2: cache=follow-up
+2: e2e=custom(open ticket after image lands), cache=follow-up
+```
+
+- `1` (or `apply recommended`) applies all recommendations.
+- `2:` takes a comma-separated override list, each `<handle>=<choice>`; omitted items keep their recommendation. A handle may appear at most once (repeat = invalid).
+- `custom(<concrete effect>)` supplies an inline effect. Manual fix-in-place is expressed only as `custom(...)` where isolated `fix-now` is unavailable.
+- `recommended: none` items follow the reference's preflight (linked, not restated): the item needs a `<handle>=custom(...)` decision, and option 1 is withheld until every open item has an executable recommendation; after the custom decision the menu re-renders for the remainder.
+- `revert conformance fix Gn` is a valid standalone reply, mutually exclusive with `1` and `2:`; it never appears inside a `2:` override list.
+- Invalid handle or choice -> focused reprompt naming only that item, retaining every valid pick and never reopening the gate. Unknown token: list the valid titled handles. Known item, bad choice: repeat its title + its available choices.
+
+#### Execute order
+
+Take **no** disposition action before the reply. Then, once, in order:
+
+1. **Normalize** every `custom(...)` into explicit operations; classify state-changing (edits code or spec) vs not. Clarify only an ambiguous or unexecutable effect.
+2. **Commit spec edits** (`accept-into-spec`, `rescope-into-spec`, state-changing spec `custom`) - the main session edits the spec directly, before any fix dispatch (a dirty tree rejects `worktree: true`, and the re-audit must read the amended spec).
+3. **Re-audit if step 2 changed the spec**; regenerate the inventory and re-render if it changed. Project `fix-now` only from the refreshed inventory.
+4. **fix-now + code-changing custom:** project the selected concerns per gap into the reference's concern-scoped fix contract (excluding accepted/rescoped/followed-up siblings); run the reference "Fix loop" (unchanged - do not re-describe it). A code-changing `custom` runs the project's tests + `code-reviewer` on its delta before proceeding. Re-run Step 1's canonical tests.
+5. **Re-audit after all state-changing work;** obtain fresh decisions **only if** the refreshed inventory differs from the approved one, else proceed.
+6. **follow-up** from the current inventory: create the item via the project's issue-tracker convention (`.pi/gauntlet-overrides.md`), record the ticket ID/URL; on failure keep the concern open.
+7. **Non-state-changing custom:** execute and record the result.
+8. **revert** (`revert conformance fix Gn`): light-revert the indexed commit, re-run Step 1's canonical tests; on failure stop; on pass re-audit and regenerate.
+9. Re-enter Step 3.5 with the re-audited block if any concern remains open.
+
+Record every final disposition with its **stable ID** as `Gn/Cn - <title>: <disposition>` (or `Gn - <title>: <disposition>` for a single-concern gap) - ticket ID/URL for `follow-up`, result for `custom`; never relabel a `custom` result as a recommendation. This durable record is the machine/audit surface; the interactive render stays handle-based. Then continue to Step 4:

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

@@ -103,8 +103,11 @@ No prompt, no menu: this partition is deterministic and exhaustive.
 3. **Every remaining `PARTIAL`/`MISSING`/`DRIFTED` gap**:
    - `recommended: fix` → auto-run the fix loop below — **unless a declared
      fix-loop precondition is unavailable** (`maxFixRounds: 0`, or no eligible
-     named-branch worktree), in which case carry the gap **OPEN** (see the fix
-     loop's precondition and `maxFixRounds: 0` notes).
+     named-branch worktree), in which case carry the gap **OPEN** and defer it
+     to the finish gate. This is the authoritative statement of the
+     precondition-unavailable carry-OPEN rule; the fix-loop precondition, the
+     `maxFixRounds: 0` note, the availability table, and the closure section
+     below all reference it.
    - `recommended: accept` or `recommended: rescope` → carry the gap **OPEN**,
      deferred to the finish gate. Do not apply a spec edit here — the finish
      gate owns disposition of deferred gaps.
@@ -131,7 +134,8 @@ Only the fan-out/integrate/review shape and `plan_tracker` are reused.
 **Precondition — worktree required.** The loop needs a worktree HEAD to branch
 fixes from. On the ad-hoc `finishing-a-development-branch` paths that run in a
 normal repo (`GIT_DIR == GIT_COMMON`) or detached HEAD, there is no such HEAD:
-skip this loop, carry every `fix` gap OPEN, and resolve it at finish via the
+skip this loop and carry every `fix` gap OPEN per the precondition-unavailable
+carry-OPEN rule in the partition step above, resolving it at finish via the
 canonical Disposition catalog and availability table below. `fix-now` is
 unavailable there; any other disposition is offered only when its table
 prerequisites hold.
@@ -184,11 +188,13 @@ Commit each per-gap fix with the message **`conformance fix Gn`** (durable,
 `git log`-readable pre-squash) so the finish gate and any revert can identify
 auto-applied fixes.
 
-**`maxFixRounds: 0`**: skip this loop entirely. Every `recommended: fix` gap
-becomes carried OPEN to the finish gate instead of auto-running — the user
-opted out of auto-fix, so treat `fix` gaps like any other deferred gap. This
-differs from a cap > 0 that is *exhausted*: that case escalates mid-verify
-because the loop tried and could not converge.
+**`maxFixRounds: 0`**: skip this loop entirely; every `recommended: fix` gap is
+carried OPEN to the finish gate per the precondition-unavailable
+carry-OPEN rule in the partition step above. The load-bearing distinction here
+is opted-out vs. exhausted: `maxFixRounds: 0` means the user opted out of
+auto-fix, so treat `fix` gaps like any other deferred gap — unlike a cap > 0
+that is *exhausted*, which escalates mid-verify because the loop tried and
+could not converge.
 
 ### `spec-reviewer` gap-block reference contract
 
@@ -284,7 +290,9 @@ prerequisite. `touched-files: unknown` makes `fix-now` unavailable until
 ownership is established. A normal checkout (`GIT_DIR == GIT_COMMON`) or detached
 HEAD cannot dispatch the isolated fix loop at all - it has no named-branch
 worktree to branch fixes from - so `fix-now` stays unavailable there regardless
-of ownership; resolve those concerns manually at finish. `maxFixRounds: 0`
+of ownership; those `fix` gaps are carried OPEN per the precondition-unavailable
+carry-OPEN rule in the partition step above and resolved manually at finish.
+`maxFixRounds: 0`
 (audit-only) likewise leaves `fix-now` visible but unavailable — the user
 configured no auto-fix loop, and finish-time selection never bypasses or resets
 that cap; a concrete `custom`/manual-fix disposition remains possible. `UNAUTHORIZED` cards
@@ -340,9 +348,8 @@ Emit this block in the verify completion summary. It is the durable handoff
 `finishing-a-development-branch` Step 3.5 consumes — parseable even if session
 context was pruned. Verify completes when every gap is either fixed
 (`CONFORMS`) or carried OPEN as a deferred gap - `accept`/`rescope`/`UNAUTHORIZED`,
-or a `recommended: fix` gap carried open because a declared fix-loop precondition
-was unavailable so the loop never started (`maxFixRounds: 0`, or no eligible
-named-branch worktree - normal checkout / detached HEAD). Escalation - a started
+or a `recommended: fix` gap carried OPEN per the precondition-unavailable
+carry-OPEN rule in the partition step above (the loop never started). Escalation - a started
 positive-cap loop that exhausted its rounds or blocked/failed with an open `fix`
 gap - is the one non-completing terminal state; the precondition-unavailable
 carried-open `fix` state is valid closure inventory, not escalation.