pi-gauntlet 5.10.2 → 5.12.0

package/extensions/lib/checkout.ts

@@ -1,17 +1,23 @@
 // One checkout resolver for every extension that needs "which git checkout owns this
 // path" (#37): plan_check, the settings loader, Guard 2, telemetry. `--path-format=absolute`
 // (git >= 2.31) makes git-dir and common-dir comparable as strings from any subdirectory.
+// A plain (non-colocated) jj checkout has no .git for rev-parse, so when git fails the
+// resolver falls back to `jj root`; colocated jj repos still resolve through git first.
+// checkoutOfSync is the same resolution for sync callers (the settings loader).
 import { execFileSync } from "node:child_process";
 import { existsSync, statSync } from "node:fs";
-import { dirname } from "node:path";
+import { dirname, join } from "node:path";
 
 export type GitResult = { code: number; stdout: string };
-export type Checkout = { toplevel: string; isPrimary: boolean };
+// `via` records which binary resolved the checkout, so callers with git-only follow-ups
+// (telemetry's checkpoint commit) can skip them in a plain jj workspace.
+export type Checkout = { toplevel: string; isPrimary: boolean; via: "git" | "jj" };
+type ResolvedCheckout = { toplevel: string; isPrimary: boolean };
 
 export const CHECKOUT_ARGS = ["rev-parse", "--path-format=absolute", "--show-toplevel", "--git-dir", "--git-common-dir"];
 
 // isPrimary = gitDir === commonDir (both absolute thanks to --path-format).
-export function parseCheckout(r: GitResult): Checkout | undefined {
+export function parseCheckout(r: GitResult): ResolvedCheckout | undefined {
   if (r.code !== 0) return undefined;
   const lines = r.stdout.trim().split("\n").map((l) => l.trim());
   if (lines.length < 3 || !lines[0]) return undefined;
@@ -38,20 +44,54 @@ export function nearestExistingDir(absPath: string): string {
   return p;
 }
 
+export const JJ_ROOT_ARGS = ["root"];
+
+// Added jj workspaces keep .jj/repo as a pointer file into the main repo; the primary
+// checkout keeps it as the real directory.
+function parseJjRoot(r: GitResult): ResolvedCheckout | undefined {
+  if (r.code !== 0) return undefined;
+  const toplevel = r.stdout.trim();
+  if (!toplevel) return undefined;
+  return { toplevel, isPrimary: isDir(join(toplevel, ".jj", "repo")) };
+}
+
 export async function checkoutOf(
   absPath: string,
   git: (args: string[], cwd: string) => GitResult | Promise<GitResult>,
+  jj: (args: string[], cwd: string) => GitResult | Promise<GitResult> = jjSync,
 ): Promise<Checkout | undefined> {
-  return parseCheckout(await git(CHECKOUT_ARGS, nearestExistingDir(absPath)));
+  const cwd = nearestExistingDir(absPath);
+  const g = parseCheckout(await git(CHECKOUT_ARGS, cwd));
+  if (g) return { ...g, via: "git" };
+  const j = parseJjRoot(await jj(JJ_ROOT_ARGS, cwd));
+  return j ? { ...j, via: "jj" } : undefined;
 }
 
-// Never throws: any failure (not a repo, missing dir, old git) is a nonzero code.
-export const gitSync = (args: string[], cwd: string): GitResult => {
-  try {
-    const stdout = execFileSync("git", args, { cwd, encoding: "utf8", stdio: ["ignore", "pipe", "ignore"], timeout: 5000 });
-    return { code: 0, stdout };
-  } catch (e) {
-    const status = (e as { status?: unknown }).status;
-    return { code: typeof status === "number" ? status : 1, stdout: "" };
-  }
-};
+// Same git-then-jj resolution for sync callers; either side injectable for tests.
+export function checkoutOfSync(
+  absPath: string,
+  git: (args: string[], cwd: string) => GitResult = gitSync,
+  jj: (args: string[], cwd: string) => GitResult = jjSync,
+): Checkout | undefined {
+  const cwd = nearestExistingDir(absPath);
+  const g = parseCheckout(git(CHECKOUT_ARGS, cwd));
+  if (g) return { ...g, via: "git" };
+  const j = parseJjRoot(jj(JJ_ROOT_ARGS, cwd));
+  return j ? { ...j, via: "jj" } : undefined;
+}
+
+// Never throws: any failure (not a repo, missing dir, missing binary) is a nonzero code.
+const commandSync =
+  (bin: string) =>
+  (args: string[], cwd: string): GitResult => {
+    try {
+      const stdout = execFileSync(bin, args, { cwd, encoding: "utf8", stdio: ["ignore", "pipe", "ignore"], timeout: 5000 });
+      return { code: 0, stdout };
+    } catch (e) {
+      const status = (e as { status?: unknown }).status;
+      return { code: typeof status === "number" ? status : 1, stdout: "" };
+    }
+  };
+
+export const gitSync = commandSync("git");
+export const jjSync = commandSync("jj");

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

@@ -30,3 +30,16 @@ test("outside any checkout the loader falls back to cwd", () => {
   assert.equal(loaded.root, dir);
   assert.deepEqual(loaded.gauntlet.flowGuards, { enforce: false });
 });
+
+test("settings resolve through the jj fallback in a plain jj workspace (no .git)", () => {
+  const dir = tmp();
+  mkdirSync(join(dir, ".jj", "repo"), { recursive: true }); // primary jj checkout marker
+  mkdirSync(join(dir, ".pi"));
+  mkdirSync(join(dir, "doc"));
+  writeFileSync(join(dir, ".pi", "settings.json"), JSON.stringify({ piGauntlet: { specCouncil: { members: ["p/jj"] } } }));
+  const jjCheckout = () => ({ toplevel: dir, isPrimary: true, via: "jj" as const });
+  const loaded = loadGauntletSettings(join(dir, "doc"), "/tmp/pi-gauntlet-test-agent", jjCheckout);
+  assert.equal(loaded.root, dir);
+  assert.deepEqual(loaded.gauntlet.specCouncil, { members: ["p/jj"] });
+  assert.deepEqual(loaded.errors, []);
+});

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

@@ -2,7 +2,7 @@
 // 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";
-import { gitSync, parseCheckout } from "./checkout.ts";
+import { checkoutOfSync, type Checkout } from "./checkout.ts";
 
 export interface LoadedGauntlet {
   gauntlet: PiGauntlet;
@@ -12,12 +12,13 @@ export interface LoadedGauntlet {
 }
 
 // Reads the preset (agentDir/settings.json) and repo (<root>/.pi/settings.json) layers
-// via pi's own SettingsManager, where <root> is the git toplevel of cwd - pi launched in a
-// subdirectory or a linked worktree still finds that checkout's file (#37). SettingsManager
+// via pi's own SettingsManager, where <root> is the checkout toplevel of cwd (git, falling
+// back to `jj root` in a plain jj workspace) - pi launched in a subdirectory or a linked
+// worktree still finds that checkout's file (#37). 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 root = parseCheckout(gitSync(["rev-parse", "--path-format=absolute", "--show-toplevel", "--git-dir", "--git-common-dir"], cwd))?.toplevel ?? cwd;
+export function loadGauntletSettings(cwd: string, agentDir: string = getAgentDir(), checkout: (path: string) => Checkout | undefined = checkoutOfSync): LoadedGauntlet {
+  const root = checkout(cwd)?.toplevel ?? cwd;
   const sm = SettingsManager.create(root, agentDir);
   const preset = sm.getGlobalSettings() as { piGauntlet?: Record<string, unknown> };
   const repo = sm.getProjectSettings() as { piGauntlet?: Record<string, unknown> };

package/extensions/telemetry.test.ts

@@ -20,7 +20,7 @@
 
   type Handler = (event: any, ctx: any) => unknown;
 
-  function harness(o: { branch?: unknown[]; enabled?: boolean; gitFail?: (args: string[], cwd: string) => GitResult | undefined; cwdSub?: string; sessionId?: string; model?: { provider: string; id: string }; thinkingLevel?: string; contextTokens?: number | null; telemetryWarning?: string; telemetryDir?: string } = {}) {
+  function harness(o: { branch?: unknown[]; enabled?: boolean; gitFail?: (args: string[], cwd: string) => GitResult | undefined; jjWorkspace?: boolean; cwdSub?: string; sessionId?: string; model?: { provider: string; id: string }; thinkingLevel?: string; contextTokens?: number | null; telemetryWarning?: string; telemetryDir?: string } = {}) {
     const root = mkdtempSync(join(tmpdir(), "telemetry-test-"));
     tempDirs.push(root);
     mkdirSync(join(root, "doc/specs"), { recursive: true });
@@ -52,6 +52,8 @@
         return { code: 0, stdout: "", stderr: "" };
       },
       settings: () => ({ telemetry: { enabled: o.enabled ?? true, dir: o.telemetryDir ?? ".pi/gauntlet/telemetry", buckets: DEFAULT_TELEMETRY_BUCKETS, warning: o.telemetryWarning }, errors: [], agentOverrides: { implementer: { model: "p/x" } }, versions: { pi: "0.85.1" } }),
+      // A plain jj workspace: `jj root` answers the temp root while git rev-parse fails.
+      ...(o.jjWorkspace ? { jj: async () => ({ code: 0, stdout: root + "\n", stderr: "" }) } : {}),
     };
     let branch = o.branch ?? [];
     const ctx = {
@@ -281,6 +283,25 @@
     assert.deepEqual(nogit.readRecord().events.filter((e) => e.kind === "warning").map((e: any) => e.message), [`spec ${outsideSpec} is outside a git checkout; telemetry not recorded`]);
   });
 
+  test("jj-bound checkout: record is written, never committed, and the warning fires once", async () => {
+    const h = harness({
+      jjWorkspace: true,
+      gitFail: (args) =>
+        args[0] === "rev-parse" && args.includes("--path-format=absolute")
+          ? { code: 128, stdout: "", stderr: "fatal: not a git repository" }
+          : undefined,
+    });
+    await h.phaseResult("start", P({ brainstorm: "in_progress" }));
+    await h.writeSpec("doc/specs/a.md");
+    await h.phaseResult("complete", P({ brainstorm: "complete" }));
+    const rec = h.readRecord();
+    assert.deepEqual(
+      rec.events.filter((e) => e.kind === "warning").map((e: any) => e.message),
+      ["record written, not committed: not a git checkout"],
+    );
+    assert.equal(h.commits().length, 0);
+  });
+
   test("worktree spec from a primary cwd: record keyed under the worktree, committed there (AC 8)", async () => {
     const h = harness();
     await h.emit("session_start", { type: "session_start", reason: "startup" });

package/extensions/telemetry.ts

@@ -48,6 +48,8 @@
   export interface Deps {
     fs: FsPort;
     git: (args: string[], cwd: string) => Promise<GitResult>;
+    // Optional jj override for tests; production resolves plain jj workspaces via jjSync.
+    jj?: (args: string[], cwd: string) => GitResult | Promise<GitResult>;
     now: () => string;
     settings: (cwd: string) => SettingsSnapshot;
   }
@@ -160,6 +162,7 @@
   export default function (pi: ExtensionAPI, deps: Deps = realDeps) {
     let phases: PhaseMap = emptyPhases();
     let toplevel: string | undefined; // toplevel of the bound record's checkout; undefined until bind
+    let checkoutVia: "git" | "jj" | undefined; // which binary resolved toplevel; undefined until bind
     let boundSpec: string | undefined; // repo-relative
     let record: TelemetryRecord | undefined;
     const predecessorLinks = new Set<string>();
@@ -170,6 +173,7 @@
     let lastCommitted = "";
     let frozen = false;
     let settingsWarned = false;
+    let notGitWarned = false;
     let sessionId = "";
 
     // Per-event settings read; undefined => this event is a no-op.
@@ -182,11 +186,11 @@
 
     // Resolves a tool path (relative to ctx.cwd or absolute) to its owning checkout and
     // checkout-relative key. undefined outside any checkout.
-    const locate = async (ctx: ExtensionContext, p: string): Promise<{ toplevel: string; rel: string } | undefined> => {
+    const locate = async (ctx: ExtensionContext, p: string): Promise<{ toplevel: string; rel: string; via: "git" | "jj" } | undefined> => {
       const candidateAbs = isAbsolute(p) ? p : resolve(ctx.cwd, p);
-      const co = await checkoutOf(candidateAbs, deps.git);
+      const co = await checkoutOf(candidateAbs, deps.git, deps.jj);
       const rel = co ? repoRelativeToolPath(co.toplevel, ctx.cwd, p) : undefined;
-      return co && rel ? { toplevel: co.toplevel, rel } : undefined;
+      return co && rel ? { toplevel: co.toplevel, rel, via: co.via } : undefined;
     };
 
     const live = (): Accumulators => record
@@ -230,6 +234,15 @@
 
     const commitRecord = async () => {
       if (!record || !recordRel || frozen || !toplevel) return;
+      if (checkoutVia === "jj") {
+        // A jj-bound checkout has no .git to commit into; say so once per session instead
+        // of failing `git commit` at every checkpoint.
+        if (!notGitWarned) {
+          notGitWarned = true;
+          warn("record written, not committed: not a git checkout");
+        }
+        return;
+      }
       const text = deps.fs.readFile(abs(recordRel)) ?? "";
       if (text === lastCommitted) return;
       const paths = [recordRel, ...(oldRecordRel ? [oldRecordRel] : [])];
@@ -274,8 +287,9 @@
       return newRecord({ spec: specRel, session: sessionId, now: buffer[0]?.ts ?? deps.now(), runId: randomUUID() });
     };
 
-    const bind = async (specRel: string, snap: SettingsSnapshot, specToplevel: string) => {
+    const bind = async (specRel: string, snap: SettingsSnapshot, specToplevel: string, via: "git" | "jj") => {
       toplevel = specToplevel;
+      checkoutVia = via;
       currentDir = snap.telemetry.dir;
       boundSpec = specRel;
       recordRel = recordPathFor(currentDir, specRel);
@@ -314,6 +328,7 @@
 
     const unbind = () => {
       toplevel = undefined;
+      checkoutVia = undefined;
       boundSpec = undefined;
       record = undefined;
       recordRel = undefined;
@@ -416,7 +431,7 @@
       const candidate = replay.planCheckSpec ?? replay.lastSpecWrite;
       const loc = candidate ? await locate(ctx, candidate) : undefined;
       if (loc && isSpecPath(loc.rel)) {
-        await bind(loc.rel, snap, loc.toplevel);
+        await bind(loc.rel, snap, loc.toplevel, loc.via);
         await flush(false);
       }
     });
@@ -450,7 +465,7 @@
         const pass = d?.status === "pass";
         if (pass && specLoc && (specLoc.rel !== boundSpec || specLoc.toplevel !== toplevel)) {
           if (record) unbind();
-          await bind(specLoc.rel, snap, specLoc.toplevel);
+          await bind(specLoc.rel, snap, specLoc.toplevel, specLoc.via);
         }
         live().gates.plan_rounds += 1;
         pushEvent({ kind: "plan_check", pass, spec, plan });
@@ -498,11 +513,11 @@
     });
 
     // Binding + spec-write bookkeeping; the bound-spec hooks are defined in block 2.
-    const onSpecInteraction = async (tool: "write" | "edit" | "read", loc: { toplevel: string; rel: string }, event: { input: unknown; content: unknown[] }, snap: SettingsSnapshot): Promise<unknown> => {
+    const onSpecInteraction = async (tool: "write" | "edit" | "read", loc: { toplevel: string; rel: string; via: "git" | "jj" }, event: { input: unknown; content: unknown[] }, snap: SettingsSnapshot): Promise<unknown> => {
       const rel = loc.rel;
       if (!boundSpec) {
         if ((tool === "write" || tool === "edit") && isSpecPath(rel)) {
-          await bind(rel, snap, loc.toplevel);
+          await bind(rel, snap, loc.toplevel, loc.via);
           const patch = onBoundSpecWrite(tool, rel, event);
           await flush(true);
           return patch;
@@ -510,7 +525,7 @@
           const spec = planSpecHeader(deps.fs.readFile(join(loc.toplevel, rel)) ?? "");
           const specRel = spec ? repoRelativeToolPath(loc.toplevel, loc.toplevel, spec) : undefined;
           if (specRel && deps.fs.exists(join(loc.toplevel, specRel))) {
-            await bind(specRel, snap, loc.toplevel);
+            await bind(specRel, snap, loc.toplevel, loc.via);
             await flush(true);
           }
         }
@@ -520,7 +535,7 @@
         // Another checkout: a fresh run, never a rename of this record.
         if ((tool === "write" || tool === "edit") && isSpecPath(rel)) {
           unbind();
-          await bind(rel, snap, loc.toplevel);
+          await bind(rel, snap, loc.toplevel, loc.via);
           const patch = onBoundSpecWrite(tool, rel, event);
           await flush(true);
           return patch;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "pi-gauntlet",
-  "version": "5.10.2",
+  "version": "5.12.0",
   "description": "Opinionated, gated workflow skills, subagent personas, and runtime extensions for the pi coding agent.",
   "author": "Jacek Juraszek",
   "type": "module",
@@ -33,7 +33,8 @@
   ],
   "bin": {
     "gauntlet-spec-index": "bin/gauntlet-spec-index.mjs",
-    "gauntlet-telemetry-salvage": "bin/gauntlet-telemetry-salvage.mjs"
+    "gauntlet-telemetry-salvage": "bin/gauntlet-telemetry-salvage.mjs",
+    "gauntlet-performance": "bin/gauntlet-performance.mjs"
   },
   "engines": {
     "node": ">=24.15.0"

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

@@ -177,7 +177,7 @@ fi
 node <bin>/gauntlet-telemetry-salvage.mjs --worktree "$WORKTREE" --base <base-branch>
 ```
 
-The salvage prints one line per spec on the branch (`present`, `restored <path> from <sha>`, `no telemetry run`, `never written`, `restore failed <path>: <reason>`) and always exits 0. Print its stdout verbatim in the ship completion message. A `restore failed` line is reported, never retried, and never blocks the ship - the record stays recoverable from the branch ref.
+The salvage prints one line per spec on the branch (`present`, `present <path> (marked shipped)`, `restored <path> from <sha>`, `restored <path> from <sha> (marked shipped)`, `no telemetry run`, `never written`, `restore failed <path>: <reason>`) and always exits 0. `(marked shipped)` means the record was still `in_progress` with no ship phase (the recorder lost its binding) and the salvage committed `status: shipped` + `shipped_at` as one `telemetry:` commit; it rides the squash or push like any branch commit. Print its stdout verbatim in the ship completion message. A `restore failed` line is reported, never retried, and never blocks the ship - the record stays recoverable from the branch ref.
 
 #### Option 1: Squash-merge to base
 

package/skills/gatekeep-pr/SKILL.md

@@ -174,6 +174,7 @@ verification command may write to the tree while the Reviewer reads it):
   squash. On a cell with no push row (fork overlay, report-only states) the same
   finding is a non-blocking follow-up instead: the record stays recoverable from the
   PR head ref after merge, and blocking would stop a ship the gate cannot repair.
+  `unfinished <path>` (record still `in_progress` with no ship phase) also lands in `## Evidence` as one line and is non-blocking: pre-landing `in_progress` is normal, and the merge course's salvage run stamps it.
 - **Evidence:** On the CI path, list each satisfying check's name, conclusion, assessed SHA, and run URL - there is no command or raw_tail to paste. On the local path, paste each run's `command` and `raw_tail` verbatim, fenced - never
   paraphrased. Any authored summary is labeled as a summary and never substitutes for
   `raw_tail`.
@@ -256,7 +257,7 @@ are never bundled into one selection, with one scoped exception: the selected me
 course first runs `node <bin>/gauntlet-telemetry-salvage.mjs --worktree <provisioned
 path> --base origin/<baseRefName>` (no `--check`). `present` -> merge as-is. `restored
 <path> from <sha>` -> push that single `telemetry: restore` commit as part of this
-course, re-fetch `headRefOid`, and pass the new SHA to `--match-head-commit`. `restore
+course, re-fetch `headRefOid`, and pass the new SHA to `--match-head-commit`. A line ending `(marked shipped)` (`present` or `restored`) is handled the same way: push that single `telemetry:` commit, re-fetch `headRefOid`, pass the new SHA. `restore
 failed` -> merge proceeds, the reason is printed, and the follow-up names recovery
 from the PR head ref.
 
@@ -508,7 +509,7 @@ The menu is a state machine, not a one-shot report:
    reviewed doc edits selected alongside them (one commit, or one per batch
    sequentially; subjects name the fixes) - then re-resolves the evidence for the new head **once** (the brief's stale-head row: prior evidence is stale; the local command executes only on a fallback/opt-out resolution). Before the push, run
    `node <bin>/gauntlet-telemetry-salvage.mjs --worktree <provisioned path> --base
-   origin/<baseRefName>` (no `--check`); a `restored` commit rides the wave's single
+   origin/<baseRefName>` (no `--check`); a `restored` or `(marked shipped)` commit rides the wave's single
    push and the pushed SHA becomes the assessed head under the course's-own-push rule
    in step 1. Print its stdout in the re-rendered report's `## Evidence`. **On
    green**, push **once**; gate and push are per-wave invariants, never per-fix or

package/skills/gauntlet-performance/SKILL.md

@@ -0,0 +1,43 @@
+---
+name: gauntlet-performance
+description: Use when a human asks how gauntlet runs perform across the recorded telemetry - explicit invocation only (/skill:gauntlet-performance [--dir <path>]... [--since <version>]).
+disable-model-invocation: true
+---
+
+# Gauntlet Performance
+
+The CLI parses and aggregates; you reason. Never open a telemetry YAML record yourself.
+
+## Run the digest
+
+1. Resolve the CLI: `<directory of this SKILL.md>/../../bin/gauntlet-performance.mjs`.
+2. Run it from the repo root, passing the user's `--dir` and `--since` arguments verbatim:
+   `node <bin>/gauntlet-performance.mjs [--dir <path>]... [--since <version>]`.
+   Default corpus is the current repo; each `--dir` adds a repo root or a telemetry dir.
+3. If the command is missing or the output contains `no records found`, relay that line and stop - no menu.
+
+## Read the digest
+
+`runs` has one row per record; `shipped*` marks a truncated run (no ship phase recorded - salvage stamped it at landing; its `wall` is `-` and it feeds no aggregate). `by version` groups by pi-gauntlet version: `n` counts every row, `shipped` counts the rows behind the p50/max columns. `grants` is `fix_round_grants` - the fix-round proxy (human-granted extra review rounds); schema 1 has no code-review round count.
+
+## Reply - exactly this, in this order
+
+1. **Recommendation** (2-4 sentences). One claim, led by the run that exemplifies it: quote its `spec` slug, `run_id`, and the 1-3 numbers that carry the claim. When `grants` is the evidence, call it the fix-round proxy. If no version group has `shipped >= 2`, the recommendation is "sample too small" with the `n`/`shipped` counts per version.
+2. **Cornerstones**: 3-5 bullets of aggregate facts from `by version` - corpus size, truncated count, the p50s and model tallies that moved between versions.
+3. **Menu**, numbered, at most 3 items, rendered exactly as:
+   - `1. render report` - ask for a target path; write markdown there: the digest verbatim, then the recommendation and cornerstones above. If the file exists, ask before overwriting. Write nothing unless this item is chosen.
+   - `2. open recommendation as ticket` - hand the claim and its numbers to `/skill:shape-ticket`; never create a ticket directly.
+   - `3. drill into <slug>` - re-run the CLI with `--json` and show that run's fields.
+
+Nothing else: no preamble, no restated digest, no file written before item 1 is chosen.
+
+## Project overrides
+
+If a gauntlet overrides file exists - checked in order:
+`.pi/gauntlet-overrides.md`, `<repo root>/gauntlet-overrides.md`,
+`<repo root>/doc/gauntlet-overrides.md`; first found wins - read it. Any
+sections relevant to this skill - by name match, by topic (routing,
+verification, worktrees, etc.), or by workflow convention - override or
+extend the instructions above. Project-local `AGENTS.md` is already in
+context - check it for project-specific routing tables, service paths, and
+verification commands.