pi-gauntlet 4.4.2 → 4.4.3

package/CHANGELOG.md

@@ -1,5 +1,25 @@
 # Changelog
 
+## v4.4.3 - 2026-07-19
+
+Brainstorming is the sole gauntlet entry point (#2): gate all three phase-tracker
+enforcement surfaces (closure completion gate, closure-model guard, flow guards) on a
+durable `gauntletEntered` marker so the gauntlet is dormant unless brainstorming started
+the flow. A reflexive `phase_tracker start verify` on an ad-hoc one-liner no longer trips
+the closure gate or forces a spurious conformance dispatch.
+
+The marker is derived in `reconstructState` from the session branch (mirroring
+`conformanceDispatched`: reset on reconstruct, threaded through replay, updated in the live
+start/reset handlers via one `nextGauntletEntered` transition), so it survives pi-condense
+pruning and `--session` resume. All three surfaces gate marker-first, so a dormant
+out-of-flow session short-circuits before any settings load; in-flow behavior is unchanged
+(`brainstormActive` implies `gauntletEntered`). New pure helpers `nextGauntletEntered` /
+`closureGateBlocks` / `closureModelGuardApplies` / `flowGuardApplies` are unit-tested; the
+two settings-dependent surfaces inline-match their predicate (the `markerGuardApplies`
+convention) to preserve marker-first laziness. Docs (README, configuration.md, AGENTS.md,
+conformance-check.md, the `phase_tracker` tool description) reworded: enforcement is opt-in
+by brainstorming entry, not ambient.
+
 ## v4.4.2 - 2026-07-15
 
 Condense the finish-time conformance disposition gate to a dense, human-readable

package/README.md

@@ -38,7 +38,7 @@ Concretely, one change through the gauntlet:
 1. You describe the change. **`brainstorming`** sets up an isolated worktree, explores the codebase, and turns your description into a written spec. A multi-model critique runs on it automatically. **You read and approve the spec - human gate 1.** No implementation code exists yet.
 2. **`writing-plans`** decomposes the approved spec into atomic, independently-verifiable tasks, grouped into parallel waves where they don't touch the same files.
 3. **`subagent-driven-development`** executes the plan one task at a time, each in a fresh subagent, behind spec-compliance review then code-quality review. TDD-locked: red, green, refactor.
-4. **verify**: a whole-diff code review, then the **conformance gate** - a subagent reads the finished code and docs against your *original words* from step 1, not the plan, and reports per-requirement: delivered, partial, missing, drifted, or unauthorized. This gate is machine-blocked from being skipped. Compatible executable recommendations auto-run through an isolated fix-and-re-audit loop with no prompt; anything still open surfaces as a dense list - one line per decision, plain-language, with its recommended choice inline. Reply `1` to take every recommendation, or `2:` with per-item overrides; a current `CONFORMS` / no-concerns result goes straight to the branch options with no extra conformance sign-off.
+4. **verify**: a whole-diff code review, then the **conformance gate** - a subagent reads the finished code and docs against your *original words* from step 1, not the plan, and reports per-requirement: delivered, partial, missing, drifted, or unauthorized. Inside a brainstorming-entered flow this gate is machine-blocked from being skipped. Compatible executable recommendations auto-run through an isolated fix-and-re-audit loop with no prompt; anything still open surfaces as a dense list - one line per decision, plain-language, with its recommended choice inline. Reply `1` to take every recommendation, or `2:` with per-item overrides; a current `CONFORMS` / no-concerns result goes straight to the branch options with no extra conformance sign-off.
 5. **`finishing-a-development-branch`**: squash, PR, keep, or discard. **Human gate 2** - the only other decision you make.
 
 ```mermaid
@@ -66,13 +66,13 @@ pi-gauntlet ships three kinds of pieces, layered on top of pi-cohort's dispatch:
 - **7 subagent personas** - the specialized child agents the skills dispatch via pi-cohort: `implementer`, `code-reviewer`, `spec-reviewer`, `conformance-reviewer`, `spec-summarizer`, `spec-council-member`, `spec-council-synthesizer`. See [doc/personas.md](./doc/personas.md) for what each one does and why its permissions are scoped the way they are.
 - **3 runtime extensions** - the enforcement layer. `plan-tracker` and `phase-tracker` are tools skills call to track progress (with a TUI widget); `verify-before-ship` is a hook that warns if you commit/push without a passing test run since your last edit. See [doc/configuration.md](./doc/configuration.md) for the settings each one reads.
 
-pi-gauntlet is **opinionated**: every non-trivial change rides this one pipeline. There's no separate "just edit a file and commit" path - the skills gate each other, so the phase-tracker extension mechanically blocks a phase from closing before its gate runs. Reach for a shortcut and a gate stops you; that's the design, not friction.
+pi-gauntlet is **opinionated**: every non-trivial change is *meant* to ride this one pipeline, entered through `brainstorming`. Enforcement is opt-in by entry, not ambient: once brainstorming starts a flow, the phase-tracker extension mechanically blocks a phase from closing before its gate runs. A change made *without* entering the flow (a typo, a formatting run, a dependency bump - see "When to use / when NOT to use") is not gated; the discipline of routing real work through the pipeline is a convention the tooling supports, not a trap it springs on every edit.
 
 ## Key concepts
 
 | Term | Meaning |
 | --- | --- |
-| Gate | A machine-enforced checkpoint between phases (e.g. `complete verify` is blocked until conformance review has run). Not a suggestion. |
+| Gate | A machine-enforced checkpoint between phases (e.g. within a brainstorming-entered flow, `complete verify` is blocked until conformance review has run). Not a suggestion. |
 | Spec council | Multi-model critique of the spec before you see it (`roasting-the-spec`); falls back to a single-model critique if no council is configured. |
 | Conformance gate | The closing check: does the delivered code + docs match your *original prompt*, not the derived plan? Compatible executable recommendations auto-fix first; anything still open renders as a dense one-line-per-decision list with each recommended choice inline. Reply `1` to accept all recommendations or `2:` with per-item overrides; a current `CONFORMS` / no-concerns handoff goes straight to branch options with no extra sign-off. |
 | Wave | A batch of plan tasks that don't touch the same files, dispatched to implementers in parallel. |

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

@@ -3,6 +3,10 @@ import assert from "node:assert/strict";
 import {
   CONTEXT_DRAFT_MARKER,
   checkSubstep,
+  closureGateBlocks,
+  closureModelGuardApplies,
+  flowGuardApplies,
+  nextGauntletEntered,
   phaseLabel,
   parseGitCommit,
   resolveRepoDir,
@@ -118,3 +122,48 @@ test("markerGuardApplies: gated by flowGuards.enforce and brainstorm in_progress
   assert.equal(markerGuardApplies(true, "in_progress"), true);
   assert.equal(markerGuardApplies(true, "pending"), false);
 });
+
+test("nextGauntletEntered: arms only when a start makes brainstorm in_progress", () => {
+  assert.equal(nextGauntletEntered(false, "start", "in_progress"), true);
+  assert.equal(nextGauntletEntered(true, "start", "in_progress"), true); // re-arm idempotent
+});
+
+test("nextGauntletEntered: reset always disarms", () => {
+  assert.equal(nextGauntletEntered(true, "reset", "pending"), false);
+  assert.equal(nextGauntletEntered(true, "reset", "in_progress"), false);
+  assert.equal(nextGauntletEntered(false, "reset", "pending"), false);
+});
+
+test("nextGauntletEntered: marker survives downstream actions", () => {
+  assert.equal(nextGauntletEntered(true, "start", "complete"), true); // start plan/implement (brainstorm already complete)
+  assert.equal(nextGauntletEntered(true, "complete", "complete"), true);
+  assert.equal(nextGauntletEntered(true, "substep", "in_progress"), true);
+});
+
+test("nextGauntletEntered: a non-brainstorm start never arms a dormant flow", () => {
+  assert.equal(nextGauntletEntered(false, "start", "complete"), false); // cold start verify/implement
+  assert.equal(nextGauntletEntered(false, "start", "skipped"), false);
+  assert.equal(nextGauntletEntered(false, "complete", "pending"), false);
+});
+
+test("closureGateBlocks: blocks only for verify + entered + enforce + not-yet-dispatched", () => {
+  assert.equal(closureGateBlocks("verify", true, true, false), true);
+  assert.equal(closureGateBlocks("verify", false, true, false), false); // incident: not entered -> no block
+  assert.equal(closureGateBlocks("verify", true, true, true), false); // already dispatched
+  assert.equal(closureGateBlocks("verify", true, false, false), false); // enforce off
+  assert.equal(closureGateBlocks("plan", true, true, false), false); // wrong phase
+});
+
+test("flowGuardApplies: requires both an active guard phase and an entered flow", () => {
+  assert.equal(flowGuardApplies(true, true), true);
+  assert.equal(flowGuardApplies(true, false), false); // not entered
+  assert.equal(flowGuardApplies(false, true), false); // phase not active
+  assert.equal(flowGuardApplies(false, false), false);
+});
+
+test("closureModelGuardApplies: requires both an entered flow and closure enforcement", () => {
+  assert.equal(closureModelGuardApplies(true, true), true);
+  assert.equal(closureModelGuardApplies(false, true), false); // not entered -> dormant
+  assert.equal(closureModelGuardApplies(true, false), false); // enforce off
+  assert.equal(closureModelGuardApplies(false, false), false);
+});

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

@@ -90,6 +90,46 @@ export function markerGuardApplies(flowGuardsEnforced: boolean, brainstormStatus
   return flowGuardsEnforced && brainstormStatus === "in_progress";
 }
 
+// Flow-entry marker (spec 2026-07-19-sole-gauntlet-entry-point). The gauntlet is
+// opt-in: enforcement is dormant unless brainstorming started this flow. A `start`
+// that leaves brainstorm in_progress is the unique arming signal (exactly one phase
+// is in_progress at a time; the start target is not stored but is inferable). `reset`
+// disarms; every other action preserves the running marker so it survives brainstorm
+// -> plan -> implement -> verify. brainstormStatus is the phase status AFTER the action.
+export function nextGauntletEntered(prev: boolean, action: string, brainstormStatus: string): boolean {
+  if (action === "reset") return false;
+  if (action === "start" && brainstormStatus === "in_progress") return true;
+  return prev;
+}
+
+// Closure completion-gate decision. Marker-first: a non-entered flow never blocks
+// `complete verify`. Executable contract for the extension's inlined check (same
+// define-and-test-but-inline pattern as markerGuardApplies).
+export function closureGateBlocks(
+  phase: string,
+  gauntletEntered: boolean,
+  closureEnforced: boolean,
+  conformanceDispatched: boolean,
+): boolean {
+  return phase === "verify" && gauntletEntered && closureEnforced && !conformanceDispatched;
+}
+
+// Closure-model-guard applicability. Marker-first: the extension inlines this with the
+// settings read (closureEnforced()) as a lazy call AFTER gauntletEntered, so a dormant
+// (out-of-flow) session performs no settings I/O. This predicate is the tested contract
+// for that inlined check (same define-test-and-inline pattern as markerGuardApplies /
+// closureGateBlocks); it takes the already-resolved booleans, never triggering the read.
+export function closureModelGuardApplies(gauntletEntered: boolean, closureEnforced: boolean): boolean {
+  return gauntletEntered && closureEnforced;
+}
+
+// Flow-guard applicability: a guard fires only when its phase is active AND the flow
+// was entered via brainstorming. Both inputs are in-memory, so the extension calls
+// this directly with no settings-load cost.
+export function flowGuardApplies(phaseActive: boolean, gauntletEntered: boolean): boolean {
+  return phaseActive && gauntletEntered;
+}
+
 export const markerBlockReason = (file: string): string =>
   `Blocked: ${file} still begins with the context-draft marker - the spec-writing ` +
   `overwrite has not happened. Overwrite the draft with the real spec (write tool, ` +

package/extensions/phase-tracker.ts

@@ -26,7 +26,9 @@ import { loadGauntletSettings } from "./lib/gauntlet-settings-loader.ts";
 import {
   checkSubstep,
   findMarkerFile,
+  flowGuardApplies,
   markerBlockReason,
+  nextGauntletEntered,
   parseGitCommit,
   phaseLabel,
   resolveRepoDir,
@@ -239,6 +241,7 @@ function formatStatus(phases: PhaseMap): string {
 export default function (pi: ExtensionAPI) {
   let phases: PhaseMap = emptyPhases();
   let conformanceDispatched = false;
+  let gauntletEntered = false;
 
   // Warn-once-per-phase ledger; cleared on every phase transition and on reconstruct.
   const firedGuards = new Map<string, boolean>();
@@ -286,6 +289,7 @@ export default function (pi: ExtensionAPI) {
   const reconstructState = (ctx: ExtensionContext) => {
     phases = emptyPhases();
     conformanceDispatched = false;
+    gauntletEntered = false;
     firedGuards.clear();
     pendingGuardWarnings.clear();
     for (const entry of ctx.sessionManager.getBranch()) {
@@ -296,6 +300,7 @@ export default function (pi: ExtensionAPI) {
         const details = msg.details as PhaseTrackerDetails | undefined;
         if (details && !details.error) {
           phases = details.phases;
+          gauntletEntered = nextGauntletEntered(gauntletEntered, details.action, details.phases.brainstorm.status);
           if (details.action === "reset") conformanceDispatched = false;
         }
       } else if (msg.toolName === "subagent") {
@@ -345,7 +350,11 @@ export default function (pi: ExtensionAPI) {
     const specDirs = () => resolveFlowGuards(g()).specDirs;
 
     // Closure-review model guard - independent of flowGuards, gated by closureReview.enforce.
-    if (event.toolName === "subagent" && closureEnforced()) {
+    // gating contract: closureModelGuardApplies (see helpers). Marker-first: gauntletEntered
+    // short-circuits before closureEnforced()'s settings load, so an ad-hoc (out-of-flow)
+    // subagent dispatch never loads settings or leaks a settingsErrorWarning onto its result.
+    // Inline-matched (not called) so closureEnforced() stays a lazy second conjunct.
+    if (event.toolName === "subagent" && gauntletEntered && closureEnforced()) {
       const model = closureReviewModel();
       // Only execution-mode dispatches carry a model; management/control modes
       // (action: list/get/create/update/delete/status/...) execute nothing, so skip them.
@@ -371,8 +380,10 @@ export default function (pi: ExtensionAPI) {
     // 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;
+    const guardableWrite =
+      (event.toolName === "write" || event.toolName === "edit") && flowGuardApplies(brainstormActive, gauntletEntered);
+    const guardableBash =
+      event.toolName === "bash" && flowGuardApplies(activeGuardPhase() !== undefined, gauntletEntered);
     if (!guardableWrite && !guardableBash) return undefined;
 
     if (!flowGuardsEnforced()) return undefined;
@@ -527,7 +538,8 @@ export default function (pi: ExtensionAPI) {
     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).",
+      "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.",
     parameters: PhaseTrackerParams,
 
     async execute(_toolCallId, params, _signal, _onUpdate, ctx) {
@@ -572,6 +584,7 @@ export default function (pi: ExtensionAPI) {
             };
           }
           phases = { ...phases, [params.phase]: transitionPhaseState("in_progress") as PhaseState };
+          gauntletEntered = nextGauntletEntered(gauntletEntered, "start", phases.brainstorm.status);
           firedGuards.clear();
           updateWidget(ctx);
           return {
@@ -598,8 +611,12 @@ export default function (pi: ExtensionAPI) {
               } as PhaseTrackerDetails,
             };
           }
+          // gating contract: closureGateBlocks (see helpers). gauntletEntered is the leading
+          // conjunct so a cold-session `complete verify` (the #2 incident) neither blocks nor
+          // loads settings; the remaining conjuncts match closureGateBlocks exactly.
           if (
             params.phase === "verify" &&
+            gauntletEntered &&
             resolveClosureReview(loadGauntletSettings(ctx.cwd).gauntlet).enforce &&
             !conformanceDispatched
           ) {
@@ -694,6 +711,7 @@ export default function (pi: ExtensionAPI) {
             PHASES.map((p) => [p, transitionPhaseState("pending")]),
           ) as PhaseMap;
           conformanceDispatched = false;
+          gauntletEntered = nextGauntletEntered(gauntletEntered, "reset", phases.brainstorm.status);
           firedGuards.clear();
           updateWidget(ctx);
           return {

package/package.json

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

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

@@ -168,10 +168,10 @@ Per round:
    including DELIVERED rows and their `evidence` `file:line`) and the round's
    fix diff. Inject `model:` call-site per `gauntlet_setting({ key:
    "closureReview" }).model` — same mechanism as the initial audit; omit
-   `model:` when it is `undefined` to inherit the parent's model. The
-   phase-tracker closure guard blocks a dispatch that omits `model:` when
-   `closureReview.model` is set, and warns (non-blocking) on one whose model
-   differs.
+   `model:` when it is `undefined` to inherit the parent's model. Inside a
+   brainstorming-entered flow, the phase-tracker closure guard blocks a dispatch
+   that omits `model:` when `closureReview.model` is set, and warns (non-blocking)
+   on one whose model differs.
 7. **Converge or continue**: verdict `CONFORMS` → record it, done. Open gaps
    within the cap → re-partition (per the rule above) and start the next
    round. Cap (`gauntlet_setting({ key: "closureReview" }).maxFixRounds`,