pi-gauntlet 5.12.0 → 5.13.0

package/CHANGELOG.md

@@ -1,5 +1,13 @@
 # Changelog
 
+## v5.13.0 - 2026-09-19
+
+- Post-approval spec amendments go through a reviewer-first funnel (`skills/brainstorming/reference/amendment-surface.md`): a fresh `spec-council-member` in `Mode: amendment-review` clears evidence-backed factual corrections that touch no human-owned section, a deterministic prefilter sends descopes and acceptance-criteria edits to the human, and escalations render as one readable batch (what / why / example / recommended, real alternatives only) with a one-reply grammar and the standing-grant offer; each batch lands as one `amend:` commit with per-item records. The spec gate offers the grant. `finishing-a-development-branch` runs eligible conformance `accept` gaps through the same funnel before the disposition menu and lists auto-applied amendments above the ship options. `brainstorming/SKILL.md` shrinks; `scripts/ci.mjs` pins the new tokens.
+
+## v5.12.1 - 2026-09-19
+
+- Fixed: `gauntlet-telemetry-salvage` and `gauntlet-performance` no longer crash with `ERR_UNSUPPORTED_NODE_MODULES_TYPE_STRIPPING` when run from an npm-installed copy - both bins are now committed esbuild bundles (sources in `src/bins/`, rebuild with `npm run build:bins`), guarded by a CI freshness check, bundle pack assertions, and a packed-install smoke test. (#39)
+
 ## v5.12.0 - 2026-09-19
 
 - New human-only `/skill:gauntlet-performance` and parse-only `gauntlet-performance` bin: the CLI digests committed telemetry records (current repo, plus `--dir <path>` repos; `--since <version>` narrows; `--json`) into per-run rows and per-version p50/max, and the skill turns the digest into one example-led recommendation, cornerstones, and a three-item menu (render on request, ticket via `shape-ticket`, drill-down). `gauntlet-telemetry-salvage` now stamps a record still `in_progress` with no ship phase as `status: shipped` + `shipped_at` at landing (`present`/`restored ... (marked shipped)`, `unfinished` under `--check`); `finishing-a-development-branch` and `gatekeep-pr` carry the new lines. The gh-37 record on this repo is backfilled to `shipped`. (#35)

package/README.md

@@ -63,7 +63,7 @@ flowchart LR
 
 <!-- TODO GIF: a real gauntlet run end to end -->
 
-Everything between gate 1 and gate 2 - task breakdown, implementation, both review passes - runs without you in the loop. Changing an approved spec later is a conditional diff-approval stop (brainstorming's `Amending an approved spec`) - or, under a standing grant, a diff render that continues - not a third numbered gate. That's the mechanism. What follows is the machinery behind it.
+Everything between gate 1 and gate 2 - task breakdown, implementation, both review passes - runs without you in the loop. Changing an approved spec later goes through brainstorming's `Amending an approved spec`: a fresh-context reviewer clears evidence-backed factual corrections on its own, escalations reach you as one readable batch, and only a redraw is a full stop - not a third numbered gate. That's the mechanism. What follows is the machinery behind it.
 
 ## Architecture
 

package/agents/spec-council-member.md

@@ -1,6 +1,6 @@
 ---
 name: spec-council-member
-description: Adversarial single-model spec critic dispatched by the roasting-the-spec or shape-ticket skills; assesses whether a spec is sound, complete, and actionable. Not for direct dispatch.
+description: Adversarial single-model spec critic dispatched by the roasting-the-spec or shape-ticket skills, and in `Mode: amendment-review` by brainstorming's amendment surface to clear or escalate proposed spec amendments; assesses whether a spec is sound, complete, and actionable. Not for direct dispatch.
 tools: read, grep, find, ls, bash
 thinking: xhigh
 defaultContext: fresh
@@ -18,6 +18,16 @@ You are read-only: you never modify the repository or any input artifact; your o
 
 When your dispatching task asks for codebase verification, verify - do not trust assertions about existing files, APIs, or conventions - but bounded: prefer `rg` (it respects `.gitignore`) over recursive `grep`, use `rg`-native bounds (`--max-count`, explicit paths); scope every scan to explicit paths, never a repository root; bound each scan with `timeout` (or `gtimeout`) when available, and do not run it unbounded when neither exists. A scan that times out or cannot be bounded is reported as unverified - never retried broader. End every finding with `probed:`; `none` is a normal answer.
 
+## Amendment-review mode
+
+When the first line of your task is `Mode: amendment-review`, this section replaces everything below it. You judge proposed amendments to an approved spec, not the spec. The task carries the rubric, the spec path, and per item a handle, a spec location, the `old -> new` text, and cited evidence (a command and its output, a `file:line`, a test result, a fixture measurement). Read the spec around each location; probe cited evidence read-only, bounded as above; judge scope from the spec's `## Human input` section when the task supplies it, else from its Goal, Problem, scope and acceptance sections. Emit exactly one line per item and nothing else:
+
+```
+<handle>: auto-apply | escalate - <one-line reason> - probed: <check> - <result>
+```
+
+`auto-apply` only when every rubric predicate holds on evidence you probed. Uncited, unverifiable, uncertain, or touching a human-owned section -> `escalate`. You never edit anything.
+
 Assess the spec on five axes:
 
 1. **Addresses the problem.** Does the spec actually solve the problem in the problem statement? Answer yes / partial / no and say why. A well-written spec for the wrong problem is unsound.

package/bin/gauntlet-performance.mjs

@@ -1,82 +1,109 @@
 #!/usr/bin/env node
-// Digest committed gauntlet telemetry records: one row per run plus p50/max per pi-gauntlet
-// version. Parse and aggregate only; the gauntlet-performance skill reasons over the output.
+
+// src/bins/gauntlet-performance.mjs
 import { existsSync, readdirSync, readFileSync, realpathSync, statSync } from "node:fs";
 import { homedir } from "node:os";
 import { basename, join, resolve } from "node:path";
 import { spawnSync } from "node:child_process";
 import process from "node:process";
 import { parse as parseYaml } from "yaml";
-import { mergeGauntlet, resolveTelemetry } from "../extensions/lib/gauntlet-settings.ts";
 
-const PHASES = ["brainstorm", "plan", "implement", "verify", "ship"];
-const TOKEN_KEYS = ["input", "output", "cache_read", "cache_write"];
-const RUN_HEADER = ["run_id", "repo", "spec", "version", "status", "wall", "b/p/i/v/s min", "tokens", "cost", "models", "disp", "grants", "reopens", "loops", "findings", "council"];
-const VERSION_HEADER = ["version", "n", "shipped", "truncated", "wall p50/max", "tokens p50/max", "cost p50/max", "disp p50", "grants p50/max", "reopens p50/max", "loops p50/max", "findings p50 b/M/m", "models"];
+// extensions/lib/gauntlet-settings.ts
+import path from "node:path";
+function mergeGauntlet(preset, repo) {
+  return { ...preset ?? {}, ...repo ?? {} };
+}
+var nonEmptyString = (v) => typeof v === "string" && v.trim().length > 0;
+var joinWarn = (ws) => ws.length ? ws.join("; ") : void 0;
+var DEFAULT_TELEMETRY_DIR = ".pi/gauntlet/telemetry";
+var DEFAULT_TELEMETRY_BUCKETS = [
+  ["test", ["**/test/**", "**/tests/**", "**/__tests__/**", "**/*.test.*", "**/*.spec.*", "**/*_test.*"]],
+  ["docs", ["**/*.md"]],
+  ["config", ["**/*.json", "**/*.yaml", "**/*.yml", "**/*.toml", "**/*.lock", "**/*-lock.*"]]
+];
+function resolveTelemetry(g) {
+  const t = g.telemetry;
+  const warnings = [];
+  const enabled = t?.enabled !== false;
+  let dir = DEFAULT_TELEMETRY_DIR;
+  if (t?.dir !== void 0) {
+    const value = nonEmptyString(t.dir) ? t.dir.trim().replace(/\/+$/, "") : "";
+    const canonical = value.replace(/\\/g, "/");
+    const normalized = path.posix.normalize(canonical);
+    if (value && path.win32.parse(canonical).root === "" && normalized !== ".." && !normalized.startsWith("../")) dir = normalized;
+    else warnings.push("telemetry.dir must be a non-empty path relative to the git toplevel; using the default");
+  }
+  let buckets = DEFAULT_TELEMETRY_BUCKETS;
+  if (t?.buckets !== void 0) {
+    const b = t.buckets;
+    const valid = b !== null && typeof b === "object" && !Array.isArray(b) && Object.keys(b).length > 0 && Object.values(b).every((v) => Array.isArray(v) && v.length > 0 && v.every(nonEmptyString));
+    if (valid) buckets = Object.entries(b).map(([name, globs]) => [name, [...globs]]);
+    else warnings.push("telemetry.buckets is not an object of non-empty glob arrays; using the defaults");
+  }
+  return { enabled, dir, buckets, warning: joinWarn(warnings) };
+}
 
-const usage = () => {
+// src/bins/gauntlet-performance.mjs
+var PHASES = ["brainstorm", "plan", "implement", "verify", "ship"];
+var TOKEN_KEYS = ["input", "output", "cache_read", "cache_write"];
+var RUN_HEADER = ["run_id", "repo", "spec", "version", "status", "wall", "b/p/i/v/s min", "tokens", "cost", "models", "disp", "grants", "reopens", "loops", "findings", "council"];
+var VERSION_HEADER = ["version", "n", "shipped", "truncated", "wall p50/max", "tokens p50/max", "cost p50/max", "disp p50", "grants p50/max", "reopens p50/max", "loops p50/max", "findings p50 b/M/m", "models"];
+var usage = () => {
   process.stderr.write("usage: gauntlet-performance [--dir <repo root or telemetry dir>]... [--since <version>] [--json]\n");
   process.exit(1);
 };
-
-const semver = (s) => {
+var semver = (s) => {
   const m = /^(0|[1-9]\d*)\.(0|[1-9]\d*)\.(0|[1-9]\d*)$/.exec(typeof s === "string" ? s.trim() : "");
-  return m ? [Number(m[1]), Number(m[2]), Number(m[3])] : undefined;
+  return m ? [Number(m[1]), Number(m[2]), Number(m[3])] : void 0;
 };
-const cmpSemver = (a, b) => a[0] - b[0] || a[1] - b[1] || a[2] - b[2];
-
+var cmpSemver = (a, b) => a[0] - b[0] || a[1] - b[1] || a[2] - b[2];
 function parseArgs(argv) {
-  const opts = { dirs: [], since: undefined, json: false };
+  const opts = { dirs: [], since: void 0, json: false };
   for (let i = 0; i < argv.length; i++) {
     const a = argv[i];
-    if (a === "--dir" && argv[i + 1] !== undefined && !argv[i + 1].startsWith("--")) opts.dirs.push(argv[++i]);
-    else if (a === "--since" && argv[i + 1] !== undefined && !argv[i + 1].startsWith("--")) opts.since = argv[++i];
+    if (a === "--dir" && argv[i + 1] !== void 0 && !argv[i + 1].startsWith("--")) opts.dirs.push(argv[++i]);
+    else if (a === "--since" && argv[i + 1] !== void 0 && !argv[i + 1].startsWith("--")) opts.since = argv[++i];
     else if (a === "--json") opts.json = true;
     else usage();
   }
-  if (opts.since !== undefined && !semver(opts.since)) usage();
+  if (opts.since !== void 0 && !semver(opts.since)) usage();
   return opts;
 }
-
 function readLayer(file) {
   if (!existsSync(file)) return {};
   try {
     return JSON.parse(readFileSync(file, "utf8"));
   } catch (e) {
-    process.stderr.write(`warning: ${file}: ${e.message}; using {} for this layer\n`);
+    process.stderr.write(`warning: ${file}: ${e.message}; using {} for this layer
+`);
     return {};
   }
 }
-
-// Same two layers the recorder and salvage read.
 function telemetryDirOf(root) {
   const agentDir = process.env.PI_CODING_AGENT_DIR || join(homedir(), ".pi", "agent");
   const preset = readLayer(join(agentDir, "settings.json"));
   const repo = readLayer(join(root, ".pi", "settings.json"));
   const t = resolveTelemetry(mergeGauntlet(preset?.piGauntlet, repo?.piGauntlet));
-  if (t.warning) process.stderr.write(`warning: ${t.warning}\n`);
+  if (t.warning) process.stderr.write(`warning: ${t.warning}
+`);
   return join(root, t.dir);
 }
-
-const gitToplevel = (cwd) => {
-  const r = spawnSync("git", ["-C", cwd, "rev-parse", "--show-toplevel"], { encoding: "utf8", timeout: 10_000 });
-  return r.status === 0 ? r.stdout.trim() : undefined;
+var gitToplevel = (cwd) => {
+  const r = spawnSync("git", ["-C", cwd, "rev-parse", "--show-toplevel"], { encoding: "utf8", timeout: 1e4 });
+  return r.status === 0 ? r.stdout.trim() : void 0;
 };
-
-// A git toplevel contributes its resolved telemetry dir; anything else is a telemetry dir itself.
-function corpusFor(path) {
-  const label = basename(resolve(path));
-  if (!existsSync(path)) return { label, skip: "not found" };
-  const abs = realpathSync(path);
+function corpusFor(path2) {
+  const label = basename(resolve(path2));
+  if (!existsSync(path2)) return { label, skip: "not found" };
+  const abs = realpathSync(path2);
   const top = gitToplevel(abs);
-  if (top !== undefined && realpathSync(top) === abs) {
+  if (top !== void 0 && realpathSync(top) === abs) {
     const dir = telemetryDirOf(abs);
     return existsSync(dir) ? { label, dir } : { label, skip: "no telemetry dir" };
   }
   if (!statSync(abs).isDirectory()) return { label, skip: "not a directory" };
   return { label, dir: abs };
 }
-
 function* yamlFiles(dir) {
   if (!existsSync(dir)) return;
   for (const e of readdirSync(dir, { withFileTypes: true }).sort((a, b) => a.name.localeCompare(b.name))) {
@@ -85,15 +112,13 @@ function* yamlFiles(dir) {
     else if (e.isFile() && e.name.endsWith(".yaml")) yield p;
   }
 }
-
-const num = (v) => (typeof v === "number" && Number.isFinite(v) ? v : null);
-const str = (v) => (typeof v === "string" ? v : null);
-const obj = (v) => (v && typeof v === "object" && !Array.isArray(v) ? v : null);
-const sumOrNull = (vals) => {
+var num = (v) => typeof v === "number" && Number.isFinite(v) ? v : null;
+var str = (v) => typeof v === "string" ? v : null;
+var obj = (v) => v && typeof v === "object" && !Array.isArray(v) ? v : null;
+var sumOrNull = (vals) => {
   const xs = vals.filter((v) => v !== null);
   return xs.length ? xs.reduce((a, b) => a + b, 0) : null;
 };
-
 function loadRecord(file, label) {
   let doc;
   try {
@@ -103,7 +128,7 @@ function loadRecord(file, label) {
   }
   const d = obj(doc);
   if (!d) return { skip: "unparseable" };
-  if (d.schema !== 1) return { skip: `schema ${d.schema === undefined ? "missing" : String(d.schema)}` };
+  if (d.schema !== 1) return { skip: `schema ${d.schema === void 0 ? "missing" : String(d.schema)}` };
   if (typeof d.spec !== "string" || typeof d.run_id !== "string") return { skip: "not a record" };
   const derived = obj(d.derived) ?? {};
   const phases = obj(derived.phases) ?? {};
@@ -114,21 +139,17 @@ function loadRecord(file, label) {
   const gates = obj(derived.gates) ?? {};
   const version = str(obj(d.versions)?.["pi-gauntlet"]);
   const reviewEntries = reviews === null ? null : Object.values(reviews);
-  const findings = reviewEntries === null
-    ? null
-    : reviewEntries.length === 0
-      ? { blocker: 0, major: 0, minor: 0 }
-      : Object.fromEntries(["blocker", "major", "minor"].map((severity) => {
-        const counters = reviewEntries.map((r) => {
-          const review = obj(r);
-          if (review === null) return null;
-          if (!Object.hasOwn(review, "findings")) return 0;
-          const reviewFindings = obj(review.findings);
-          if (reviewFindings === null) return null;
-          return Object.hasOwn(reviewFindings, severity) ? num(reviewFindings[severity]) : 0;
-        });
-        return [severity, counters.includes(null) ? null : counters.reduce((a, b) => a + b, 0)];
-      }));
+  const findings = reviewEntries === null ? null : reviewEntries.length === 0 ? { blocker: 0, major: 0, minor: 0 } : Object.fromEntries(["blocker", "major", "minor"].map((severity) => {
+    const counters = reviewEntries.map((r) => {
+      const review = obj(r);
+      if (review === null) return null;
+      if (!Object.hasOwn(review, "findings")) return 0;
+      const reviewFindings = obj(review.findings);
+      if (reviewFindings === null) return null;
+      return Object.hasOwn(reviewFindings, severity) ? num(reviewFindings[severity]) : 0;
+    });
+    return [severity, counters.includes(null) ? null : counters.reduce((a, b) => a + b, 0)];
+  }));
   const truncated = ph("ship") === null;
   return {
     row: {
@@ -157,27 +178,25 @@ function loadRecord(file, label) {
       findings,
       council: num(obj(personas["spec-council-member"])?.dispatches),
       ship_option: str(gates.ship_option),
-      tests: str(obj(derived.tests)?.result),
-    },
+      tests: str(obj(derived.tests)?.result)
+    }
   };
 }
-
-const p50 = (xs) => {
+var p50 = (xs) => {
   const s = [...xs].sort((a, b) => a - b);
   const m = s.length >> 1;
   return s.length % 2 ? s[m] : (s[m - 1] + s[m]) / 2;
 };
-const stat = (rows, pick) => {
-  const xs = rows.map(pick).filter((v) => v !== null && v !== undefined);
+var stat = (rows, pick) => {
+  const xs = rows.map(pick).filter((v) => v !== null && v !== void 0);
   return xs.length ? { p50: p50(xs), max: Math.max(...xs) } : { p50: null, max: null };
 };
-const versionOrder = (a, b) => {
+var versionOrder = (a, b) => {
   const x = semver(a), y = semver(b);
   return x && y ? cmpSemver(x, y) : x ? -1 : y ? 1 : 0;
 };
-
 function aggregate(rows) {
-  const groups = new Map();
+  const groups = /* @__PURE__ */ new Map();
   for (const r of rows) {
     if (!groups.has(r.version)) groups.set(r.version, []);
     groups.get(r.version).push(r);
@@ -201,58 +220,84 @@ function aggregate(rows) {
       findings: {
         blocker: { p50: stat(shipped, (r) => r.findings?.blocker ?? null).p50 },
         major: { p50: stat(shipped, (r) => r.findings?.major ?? null).p50 },
-        minor: { p50: stat(shipped, (r) => r.findings?.minor ?? null).p50 },
+        minor: { p50: stat(shipped, (r) => r.findings?.minor ?? null).p50 }
       },
-      models,
+      models
     };
   });
 }
-
-const dash = (v) => (v === null || v === undefined ? "-" : String(v));
-const fmtMin = (s) => (s === null ? "-" : `${Math.round(s / 60)}m`);
-const fmtCount = (n) => (n === null ? "-" : n >= 1e6 ? `${(n / 1e6).toFixed(1)}M` : n >= 1e3 ? `${(n / 1e3).toFixed(1)}k` : String(n));
-const fmtCost = (c) => (c === null ? "-" : c.toFixed(2));
-const pair = (s, f) => `${f(s.p50)}/${f(s.max)}`;
-const findingsCell = (f) => (f === null ? "-" : `${dash(f.blocker)}/${dash(f.major)}/${dash(f.minor)}`);
-const table = (header, rows) => {
+var dash = (v) => v === null || v === void 0 ? "-" : String(v);
+var fmtMin = (s) => s === null ? "-" : `${Math.round(s / 60)}m`;
+var fmtCount = (n) => n === null ? "-" : n >= 1e6 ? `${(n / 1e6).toFixed(1)}M` : n >= 1e3 ? `${(n / 1e3).toFixed(1)}k` : String(n);
+var fmtCost = (c) => c === null ? "-" : c.toFixed(2);
+var pair = (s, f) => `${f(s.p50)}/${f(s.max)}`;
+var findingsCell = (f) => f === null ? "-" : `${dash(f.blocker)}/${dash(f.major)}/${dash(f.minor)}`;
+var table = (header, rows) => {
   const w = header.map((h, i) => Math.max(h.length, ...rows.map((r) => r[i].length)));
   return [header, ...rows].map((r) => r.map((c, i) => c.padEnd(w[i])).join("  ").trimEnd()).join("\n");
 };
-const runRow = (r) => [
-  r.run_id.slice(0, 8), r.repo, r.spec, r.version, `${dash(r.status)}${r.truncated ? "*" : ""}`, fmtMin(r.wall_s),
-  PHASES.map((p) => (r.phase_min[p] === null ? "-" : String(Math.round(r.phase_min[p])))).join("/"),
-  fmtCount(r.tokens), fmtCost(r.cost), r.models.join(",") || "-", dash(r.dispatches), dash(r.grants), dash(r.reopens), dash(r.loops),
-  findingsCell(r.findings), dash(r.council),
+var runRow = (r) => [
+  r.run_id.slice(0, 8),
+  r.repo,
+  r.spec,
+  r.version,
+  `${dash(r.status)}${r.truncated ? "*" : ""}`,
+  fmtMin(r.wall_s),
+  PHASES.map((p) => r.phase_min[p] === null ? "-" : String(Math.round(r.phase_min[p]))).join("/"),
+  fmtCount(r.tokens),
+  fmtCost(r.cost),
+  r.models.join(",") || "-",
+  dash(r.dispatches),
+  dash(r.grants),
+  dash(r.reopens),
+  dash(r.loops),
+  findingsCell(r.findings),
+  dash(r.council)
 ];
-const versionRow = (g) => [
-  g.version, String(g.n), String(g.shipped), String(g.truncated), pair(g.wall_s, fmtMin), pair(g.tokens, fmtCount), pair(g.cost, fmtCost),
-  dash(g.dispatches.p50), pair(g.grants, dash), pair(g.reopens, dash), pair(g.loops, dash),
+var versionRow = (g) => [
+  g.version,
+  String(g.n),
+  String(g.shipped),
+  String(g.truncated),
+  pair(g.wall_s, fmtMin),
+  pair(g.tokens, fmtCount),
+  pair(g.cost, fmtCost),
+  dash(g.dispatches.p50),
+  pair(g.grants, dash),
+  pair(g.reopens, dash),
+  pair(g.loops, dash),
   `${dash(g.findings.blocker.p50)}/${dash(g.findings.major.p50)}/${dash(g.findings.minor.p50)}`,
-  Object.entries(g.models).map(([m, n]) => `${m}:${n}`).join(",") || "-",
+  Object.entries(g.models).map(([m, n]) => `${m}:${n}`).join(",") || "-"
 ];
-
 function main() {
   const opts = parseArgs(process.argv.slice(2));
   const corpora = [];
   const skipped = [];
   const top = gitToplevel(process.cwd());
-  if (top === undefined) process.stderr.write(`not a git checkout: ${process.cwd()}\n`);
+  if (top === void 0) process.stderr.write(`not a git checkout: ${process.cwd()}
+`);
   else corpora.push({ label: basename(top), dir: telemetryDirOf(top) });
   for (const p of opts.dirs) {
     const c = corpusFor(p);
     if (c.skip) skipped.push({ file: p, reason: c.skip });
     else corpora.push(c);
   }
-  const since = opts.since === undefined ? undefined : semver(opts.since);
-  const seen = new Set();
+  const since = opts.since === void 0 ? void 0 : semver(opts.since);
+  const seen = /* @__PURE__ */ new Set();
   const corpus = {};
   const rows = [];
   for (const c of corpora) {
     corpus[c.label] = corpus[c.label] ?? 0;
     for (const file of yamlFiles(c.dir)) {
       const res = loadRecord(file, c.label);
-      if (res.skip) { skipped.push({ file, reason: res.skip }); continue; }
-      if (seen.has(res.row.run_id)) { skipped.push({ file, reason: "duplicate run_id" }); continue; }
+      if (res.skip) {
+        skipped.push({ file, reason: res.skip });
+        continue;
+      }
+      if (seen.has(res.row.run_id)) {
+        skipped.push({ file, reason: "duplicate run_id" });
+        continue;
+      }
       seen.add(res.row.run_id);
       const v = semver(res.row.version);
       if (since && (!v || cmpSemver(v, since) < 0)) continue;
@@ -266,7 +311,7 @@ function main() {
     console.log(JSON.stringify({ corpus, since: opts.since ?? null, runs: rows, by_version: byVersion, skipped }, null, 2));
     return;
   }
-  console.log(`corpus: ${Object.entries(corpus).map(([k, v]) => `${k}=${v}`).join(", ")}${opts.since === undefined ? "" : `   since: ${opts.since}`}`);
+  console.log(`corpus: ${Object.entries(corpus).map(([k, v]) => `${k}=${v}`).join(", ")}${opts.since === void 0 ? "" : `   since: ${opts.since}`}`);
   if (rows.length === 0) {
     console.log(`no records found in ${corpora.map((c) => c.dir).join(", ") || process.cwd()}`);
   } else {
@@ -279,5 +324,4 @@ function main() {
   if (rows.length && skipped.length) console.log("");
   if (rows.length) for (const s of skipped) console.log(`skipped: ${s.file}: ${s.reason}`);
 }
-
 main();

package/bin/gauntlet-telemetry-salvage.mjs

@@ -1,86 +1,182 @@
 #!/usr/bin/env node
-// Restore a gauntlet telemetry record that a plan strip or a gate fix commit removed
-// from the branch. The recorder pathspec-commits the record at every checkpoint, so the
-// newest copy is always in the deleting commit's parent. An in_progress record with no
-// ship phase is stamped shipped at landing. Exit 0 on every outcome: the callers are ship
-// paths and this script never blocks one.
+
+// src/bins/gauntlet-telemetry-salvage.mjs
 import { existsSync, readFileSync, rmSync, writeFileSync } from "node:fs";
 import { homedir } from "node:os";
 import { isAbsolute, join } from "node:path";
 import { spawnSync } from "node:child_process";
 import process from "node:process";
-import { mergeGauntlet, resolveTelemetry } from "../extensions/lib/gauntlet-settings.ts";
-import { isSpecPath, recordPathFor } from "../extensions/lib/telemetry-paths.ts";
-import { BASE_REFS } from "../extensions/lib/telemetry-ship.ts";
-import { parseRecord, serializeRecord } from "../extensions/lib/telemetry-record.ts";
 
-const GIT_TIMEOUT_MS = 10_000;
-const COMMIT_TIMEOUT_MS = Number(process.env.GAUNTLET_SALVAGE_COMMIT_TIMEOUT_MS) || 30_000;
-const GIT_ENV = { ...process.env, GIT_TERMINAL_PROMPT: "0", GIT_EDITOR: "true" };
+// extensions/lib/gauntlet-settings.ts
+import path from "node:path";
+function mergeGauntlet(preset, repo) {
+  return { ...preset ?? {}, ...repo ?? {} };
+}
+var nonEmptyString = (v) => typeof v === "string" && v.trim().length > 0;
+var joinWarn = (ws) => ws.length ? ws.join("; ") : void 0;
+var DEFAULT_TELEMETRY_DIR = ".pi/gauntlet/telemetry";
+var DEFAULT_TELEMETRY_BUCKETS = [
+  ["test", ["**/test/**", "**/tests/**", "**/__tests__/**", "**/*.test.*", "**/*.spec.*", "**/*_test.*"]],
+  ["docs", ["**/*.md"]],
+  ["config", ["**/*.json", "**/*.yaml", "**/*.yml", "**/*.toml", "**/*.lock", "**/*-lock.*"]]
+];
+function resolveTelemetry(g) {
+  const t = g.telemetry;
+  const warnings = [];
+  const enabled = t?.enabled !== false;
+  let dir = DEFAULT_TELEMETRY_DIR;
+  if (t?.dir !== void 0) {
+    const value = nonEmptyString(t.dir) ? t.dir.trim().replace(/\/+$/, "") : "";
+    const canonical = value.replace(/\\/g, "/");
+    const normalized = path.posix.normalize(canonical);
+    if (value && path.win32.parse(canonical).root === "" && normalized !== ".." && !normalized.startsWith("../")) dir = normalized;
+    else warnings.push("telemetry.dir must be a non-empty path relative to the git toplevel; using the default");
+  }
+  let buckets = DEFAULT_TELEMETRY_BUCKETS;
+  if (t?.buckets !== void 0) {
+    const b = t.buckets;
+    const valid = b !== null && typeof b === "object" && !Array.isArray(b) && Object.keys(b).length > 0 && Object.values(b).every((v) => Array.isArray(v) && v.length > 0 && v.every(nonEmptyString));
+    if (valid) buckets = Object.entries(b).map(([name, globs]) => [name, [...globs]]);
+    else warnings.push("telemetry.buckets is not an object of non-empty glob arrays; using the defaults");
+  }
+  return { enabled, dir, buckets, warning: joinWarn(warnings) };
+}
+
+// extensions/lib/phase-tracker-helpers.ts
+var STMT_START = "(?:^|[\\n;&|(])\\s*";
+
+// extensions/lib/telemetry-paths.ts
+var isSpecPath = (rel) => /(^|\/)doc\/specs\/[^/]+\.md$/.test(rel);
+var recordPathFor = (dir, specRel) => `${dir}/${specRel.replace(/\.md$/, ".yaml")}`;
+var GIT_FLAGS = "git\\s+(?:-\\S+(?:\\s+\\S+)?\\s+)*";
+var SHIP_RE = new RegExp(STMT_START + "(" + GIT_FLAGS + "(?:merge\\s+--squash|push)(?=\\s|$)|gh\\s+pr\\s+create)");
+var DISCARD_RE = new RegExp(STMT_START + "(" + GIT_FLAGS + "(?:worktree\\s+remove|branch\\s+-D)(?=\\s|$))");
+var SQUASH_RE = new RegExp("^" + GIT_FLAGS + "merge\\s+--squash");
+
+// extensions/lib/telemetry-ship.ts
+var BASE_REFS = ["origin/HEAD", "main", "master"];
+
+// extensions/lib/telemetry-record.ts
+import { Document, isCollection, isMap, isSeq, parse as parseYaml, stringify as stringifyYaml } from "yaml";
+var emptyAccumulators = () => ({ phases: {}, personas: {}, reviews: {}, spec_writes: {}, gates: { spec_rounds: 0, plan_rounds: 0, fix_round_grants: 0, task_reopens: 0 }, conformance_loops: 0, amendments: 0, spec_edits_after_ship: 0, events_dropped: 0 });
+function newRecord(o) {
+  return { schema: 1, spec: o.spec, run_id: o.runId, branch: o.branch, status: "in_progress", created_at: o.now, sessions: [o.session], derived: { duration_s: 0, phases: {}, personas: {}, conformance_loops: 0, gates: { spec_rounds: 0, plan_rounds: 0, fix_round_grants: 0, task_reopens: 0 }, amendments: 0, spec_edits_after_ship: 0, spec_writes: {}, events_dropped: 0 }, accumulators: {}, events: [] };
+}
+var stripUndefined = (v) => {
+  if (Array.isArray(v)) return v.map(stripUndefined);
+  if (v && typeof v === "object") return Object.fromEntries(Object.entries(v).filter(([, x]) => x !== void 0).map(([k, x]) => [k, stripUndefined(x)]));
+  return v;
+};
+var flowLeafChildren = (map, blockLists = /* @__PURE__ */ new Set()) => {
+  for (const pair of map.items) {
+    const key = String(pair.key);
+    const child = pair.value;
+    if (!isCollection(child) || blockLists.has(key)) continue;
+    if (isMap(child) && child.items.length > 0 && child.items.every((item) => isMap(item.value))) {
+      for (const item of child.items) if (isCollection(item.value)) item.value.flow = true;
+    } else {
+      child.flow = true;
+    }
+  }
+};
+var flowModelLists = (node) => {
+  if (isMap(node)) {
+    for (const pair of node.items) {
+      if (String(pair.key) === "models" && isSeq(pair.value)) pair.value.flow = true;
+      flowModelLists(pair.value);
+    }
+  } else if (isSeq(node)) {
+    for (const item of node.items) flowModelLists(item);
+  }
+};
+function serializeRecord(rec) {
+  const { derived, accumulators, events, ...head } = rec;
+  const body = stripUndefined({ ...head, derived, accumulators });
+  const doc = new Document(body);
+  const derivedNode = doc.get("derived", true);
+  if (isMap(derivedNode)) flowLeafChildren(derivedNode, /* @__PURE__ */ new Set(["modified_files"]));
+  const accumulatorNode = doc.get("accumulators", true);
+  if (isMap(accumulatorNode)) {
+    for (const session of accumulatorNode.items) if (isMap(session.value)) flowLeafChildren(session.value);
+  }
+  flowModelLists(doc.contents);
+  const bodyText = doc.toString({ lineWidth: 0 });
+  const eventLines = events.map((e) => "  - " + stringifyYaml(stripUndefined(e), { collectionStyle: "flow", lineWidth: 0 }).trim());
+  return bodyText + "events:\n" + (eventLines.length ? eventLines.join("\n") + "\n" : "");
+}
+function parseRecord(text) {
+  let doc;
+  try {
+    doc = parseYaml(text);
+  } catch {
+    return void 0;
+  }
+  if (!doc || typeof doc !== "object") return void 0;
+  const d = doc;
+  if (d.schema !== 1 || typeof d.spec !== "string" || typeof d.run_id !== "string") return void 0;
+  const accumulators = Object.fromEntries(Object.entries(d.accumulators ?? {}).flatMap(
+    ([session, block]) => block && typeof block === "object" && !Array.isArray(block) ? [[session, { ...emptyAccumulators(), ...block }]] : []
+  ));
+  return { ...d, sessions: Array.isArray(d.sessions) ? d.sessions : [], derived: d.derived ?? newRecord({ spec: d.spec, session: "", now: d.created_at ?? "", runId: d.run_id }).derived, accumulators, events: Array.isArray(d.events) ? d.events : [] };
+}
 
-const usage = () => {
+// src/bins/gauntlet-telemetry-salvage.mjs
+var GIT_TIMEOUT_MS = 1e4;
+var COMMIT_TIMEOUT_MS = Number(process.env.GAUNTLET_SALVAGE_COMMIT_TIMEOUT_MS) || 3e4;
+var GIT_ENV = { ...process.env, GIT_TERMINAL_PROMPT: "0", GIT_EDITOR: "true" };
+var usage = () => {
   process.stderr.write("usage: gauntlet-telemetry-salvage --worktree <abs path> [--base <ref>] [--dir <telemetry dir>] [--check]\n");
   process.exit(1);
 };
-
 function parseArgs(argv) {
-  const opts = { worktree: undefined, base: undefined, dir: undefined, check: false };
+  const opts = { worktree: void 0, base: void 0, dir: void 0, check: false };
   for (let i = 0; i < argv.length; i++) {
     const a = argv[i];
-    if (a === "--worktree" && argv[i + 1] !== undefined && !argv[i + 1].startsWith("--")) opts.worktree = argv[++i];
-    else if (a === "--base" && argv[i + 1] !== undefined && !argv[i + 1].startsWith("--")) opts.base = argv[++i];
-    else if (a === "--dir" && argv[i + 1] !== undefined && !argv[i + 1].startsWith("--")) opts.dir = argv[++i];
+    if (a === "--worktree" && argv[i + 1] !== void 0 && !argv[i + 1].startsWith("--")) opts.worktree = argv[++i];
+    else if (a === "--base" && argv[i + 1] !== void 0 && !argv[i + 1].startsWith("--")) opts.base = argv[++i];
+    else if (a === "--dir" && argv[i + 1] !== void 0 && !argv[i + 1].startsWith("--")) opts.dir = argv[++i];
     else if (a === "--check") opts.check = true;
     else usage();
   }
   if (!opts.worktree || !isAbsolute(opts.worktree)) usage();
   return opts;
 }
-
 function git(cwd, args, timeout = GIT_TIMEOUT_MS) {
   const r = spawnSync("git", args, { cwd, encoding: "utf8", env: GIT_ENV, timeout });
   const timedOut = r.error?.code === "ETIMEDOUT";
   const stderr = timedOut ? "timed out" : (r.stderr ?? "").trim().split("\n")[0] || r.error?.message || `git exited ${r.status}`;
   return { ok: !timedOut && r.status === 0, stdout: (r.stdout ?? "").trim(), stderr, timedOut };
 }
-
 function readLayer(file) {
   if (!existsSync(file)) return {};
   try {
     return JSON.parse(readFileSync(file, "utf8"));
   } catch (e) {
-    process.stderr.write(`warning: ${file}: ${e.message}; using {} for this layer\n`);
+    process.stderr.write(`warning: ${file}: ${e.message}; using {} for this layer
+`);
     return {};
   }
 }
-
-// Same two layers the recorder reads (gauntlet-settings-loader.ts), without the pi import.
 function telemetrySettings(root) {
   const agentDir = process.env.PI_CODING_AGENT_DIR || join(homedir(), ".pi", "agent");
   const preset = readLayer(join(agentDir, "settings.json"));
   const repo = readLayer(join(root, ".pi", "settings.json"));
   return resolveTelemetry(mergeGauntlet(preset?.piGauntlet, repo?.piGauntlet));
 }
-
 function resolveBase(root, explicit) {
   for (const ref of explicit ? [explicit] : BASE_REFS) {
     if (git(root, ["rev-parse", "--verify", "-q", `${ref}^{commit}`]).ok) return ref;
   }
-  return undefined;
+  return void 0;
 }
-
-// in_progress with no ship phase: the recorder lost its binding before the ship, so the
-// landing finishes the record instead of leaving it in_progress on main forever.
-const unfinished = (rec) => {
+var unfinished = (rec) => {
   const phases = rec?.derived?.phases;
   return rec?.status === "in_progress" && (phases === null || typeof phases !== "object" || !("ship" in phases));
 };
-const stamped = (rec, now) => serializeRecord({ ...rec, status: "shipped", shipped_at: now });
-
+var stamped = (rec, now) => serializeRecord({ ...rec, status: "shipped", shipped_at: now });
 function stampPresent(root, rec, check) {
   const line = `present ${rec}`;
   const abs = join(root, rec);
-  // Only a copy identical to HEAD in both worktree and index is script-owned.
   if (!existsSync(abs) || !git(root, ["diff", "--quiet", "HEAD", "--", rec]).ok || !git(root, ["diff", "--quiet", "--cached", "HEAD", "--", rec]).ok) return line;
   const parsed = parseRecord(readFileSync(abs, "utf8"));
   if (!unfinished(parsed)) return line;
@@ -91,14 +187,13 @@ function stampPresent(root, rec, check) {
     git(root, ["reset", "-q", "--", rec]);
     return `restore failed ${rec}: ${reason}`;
   };
-  writeFileSync(abs, stamped(parsed, new Date().toISOString()));
+  writeFileSync(abs, stamped(parsed, (/* @__PURE__ */ new Date()).toISOString()));
   const add = git(root, ["add", "-f", "--", rec]);
   if (!add.ok) return failed(add.stderr);
   const commit = git(root, ["commit", "-q", "-m", `telemetry: mark ${rec} shipped at landing`, "--", rec], COMMIT_TIMEOUT_MS);
   if (!commit.ok) return failed(commit.stderr);
   return `${line} (marked shipped)`;
 }
-
 function salvage(root, rec, base, check) {
   const presence = git(root, ["cat-file", "-e", `HEAD:${rec}`]);
   if (presence.timedOut) return `restore failed ${rec}: timed out`;
@@ -111,11 +206,9 @@ function salvage(root, rec, base, check) {
   const del = deletion.stdout;
   if (!del) return `never written ${rec}`;
   if (check) return `stripped ${rec} in ${del}`;
-
   const abs = join(root, rec);
   const onDisk = existsSync(abs);
   const preStaged = git(root, ["ls-files", "--", rec]).stdout !== "";
-  // A pre-staged record is user-owned and can only be committed when the worktree matches it.
   if (preStaged && (!onDisk || !git(root, ["diff", "--quiet", "--", rec]).ok)) {
     return `restore failed ${rec}: staged copy differs from worktree`;
   }
@@ -123,7 +216,7 @@ function salvage(root, rec, base, check) {
   let stagedByScript = false;
   let priorBytes;
   const rollback = () => {
-    if (priorBytes !== undefined) {
+    if (priorBytes !== void 0) {
       writeFileSync(abs, priorBytes);
       if (preStaged) git(root, ["add", "-f", "--", rec]);
     }
@@ -134,7 +227,6 @@ function salvage(root, rec, base, check) {
     rollback();
     return `restore failed ${rec}: ${reason}`;
   };
-
   if (!onDisk) {
     const co = git(root, ["checkout", `${del}^`, "--", rec]);
     if (!co.ok) return `restore failed ${rec}: ${co.stderr}`;
@@ -145,7 +237,7 @@ function salvage(root, rec, base, check) {
   const parsed = parseRecord(readFileSync(abs, "utf8"));
   if (unfinished(parsed)) {
     priorBytes = readFileSync(abs);
-    writeFileSync(abs, stamped(parsed, new Date().toISOString()));
+    writeFileSync(abs, stamped(parsed, (/* @__PURE__ */ new Date()).toISOString()));
     suffix = " (marked shipped)";
   }
   const add = git(root, ["add", "-f", "--", rec]);
@@ -154,21 +246,20 @@ function salvage(root, rec, base, check) {
   if (!commit.ok) return failed(commit.stderr);
   return `restored ${rec} from ${del}${suffix}`;
 }
-
 function main() {
   const opts = parseArgs(process.argv.slice(2));
-  const override = opts.dir === undefined
-    ? undefined
-    : resolveTelemetry({ telemetry: { enabled: true, dir: opts.dir } });
+  const override = opts.dir === void 0 ? void 0 : resolveTelemetry({ telemetry: { enabled: true, dir: opts.dir } });
   if (override?.warning) usage();
   const top = git(opts.worktree, ["rev-parse", "--show-toplevel"]);
   if (!existsSync(opts.worktree) || !top.ok) {
-    process.stderr.write(`not a git worktree: ${opts.worktree}\n`);
+    process.stderr.write(`not a git worktree: ${opts.worktree}
+`);
     return;
   }
   const root = top.stdout;
   const telemetry = telemetrySettings(root);
-  if (telemetry.warning) process.stderr.write(`warning: ${telemetry.warning}\n`);
+  if (telemetry.warning) process.stderr.write(`warning: ${telemetry.warning}
+`);
   if (!telemetry.enabled) return console.log("telemetry disabled");
   const dir = override?.dir ?? telemetry.dir;
   const base = resolveBase(root, opts.base);
@@ -179,5 +270,4 @@ function main() {
   if (specs.length === 0) return console.log("no spec on branch");
   for (const spec of specs) console.log(salvage(root, recordPathFor(dir, spec), base, opts.check));
 }
-
 main();

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "pi-gauntlet",
-  "version": "5.12.0",
+  "version": "5.13.0",
   "description": "Opinionated, gated workflow skills, subagent personas, and runtime extensions for the pi coding agent.",
   "author": "Jacek Juraszek",
   "type": "module",
@@ -58,9 +58,13 @@
   "scripts": {
     "postinstall": "node ./bin/install-agents.mjs",
     "link-agents": "node ./bin/install-agents.mjs",
+    "build:bins": "node scripts/build-bins.mjs",
     "test": "node scripts/ci.mjs"
   },
   "dependencies": {
     "yaml": "^2.9.0"
+  },
+  "devDependencies": {
+    "esbuild": "0.28.2"
   }
 }

package/skills/brainstorming/SKILL.md

@@ -226,14 +226,14 @@ Rejected: <cluster -> one-line reason>, ...
 
 <unresolved ambiguities; every gap-footer entry from the summary>
 
-Please review. Approve to proceed, tell me what to change in the spec, or say "revert applied council edit <X>" to undo a specific applied edit.
+Please review. Approve to proceed, tell me what to change in the spec, or say "revert applied council edit <X>" to undo a specific applied edit. Reply "auto-apply amends" - every later amend-class change in this flow then applies without review, scope changes included; redraws and the spec gate still stop. "approve, auto-apply amends" does both.
 ```
 
 If you believe the summary needs correcting, do **not** silently rewrite it — re-dispatch the summarizer or note the discrepancy as an adjacent line beneath the verbatim block.
 
 **Revert valve.** "Revert applied council edit X" is a normal change request: revise the spec to undo edit X, re-dispatch the summarizer with a **fresh** temp path (per the re-dispatch rule below), and re-present the gate. This is cheap here - the spec is not yet plan- or code-bearing.
 
-Wait for the user. On a change request (including a revert), revise the spec and re-present — mint a **fresh** temp path for the re-dispatched summarizer (never reuse a prior round's path, so stale content can never be mistaken for the new summary). On approval, proceed immediately to `/skill:writing-plans` with no further prompt — the plan and execution mode are mechanical derivatives, so the only human gate here is spec approval itself. Don't land the spec on `main`; it stays in the worktree and ships in the same squash commit as the implementation.
+Wait for the user. On a change request (including a revert), revise the spec and re-present — mint a **fresh** temp path for the re-dispatched summarizer (never reuse a prior round's path, so stale content can never be mistaken for the new summary). On approval, proceed immediately to `/skill:writing-plans` with no further prompt (a grant given at or before approval - "approve, auto-apply amends", or a standalone "auto-apply amends" reply earlier at this gate - is first quoted in the spec commit body via `git -C <abs worktree path> commit --amend --no-edit -q --trailer "Amend-grant: <the sentence>"`, so the worktree history shows when the grant began) — the plan and execution mode are mechanical derivatives, so the only human gate here is spec approval itself. Don't land the spec on `main`; it stays in the worktree and ships in the same squash commit as the implementation.
 
 Post-approval changes follow [Amending an approved spec](#amending-an-approved-spec).
 
@@ -245,13 +245,11 @@ phase_tracker({ action: "complete", phase: "brainstorm" })
 
 ## Amending an approved spec
 
-Execute this section in place from any later phase. Do not invoke `/skill:brainstorming` (its entry resets both trackers). Worktree, spec commits, and plan survive.
+Execute in place from any later phase; never invoke `/skill:brainstorming` for it (its entry resets both trackers). Worktree, spec commits, and plan survive.
 
-1. Edit the spec. Show `git -C <abs worktree path> --no-pager diff -- <spec path>` and one line of impact (affected plan tasks / waves, or "no plan yet").
-2. Render the diff and impact line. A user instruction in this flow that waives per-diff review for later amends ("auto-apply amends, stop only for redraws", "apply spec fixes without asking") is the approval: quote it in the amendment commit body and continue. Otherwise wait for approval; change request -> revise, re-show. Redraws always wait. A grant never satisfies the spec gate; a grant given with or before spec approval applies to later amends in the same flow; a new brainstorm and a fresh-session resume start with no grant.
-3. No plan yet -> commit the spec; continue. Plan exists -> update affected anchors and tasks: `plan_tracker` `add` for new tasks; anchor-changed completed tasks are reopened as `in_progress` and re-run the task loop (`update` never sets `pending`). A removed task is deleted from the plan; then re-`init` the tracker with `{ name, status }` elements: preserved tasks keep their order and statuses, reopened tasks are `in_progress` in place, every still-`pending` task (including newly added ones, whatever wave label they carry) trails the non-pending ones, removed tasks are the only deletions (the only permitted `init` after handoff; never `clear`). Re-run `plan_check` until it passes, commit spec + plan together; continue. A task reopened while `verify` or `ship` is in progress: `phase_tracker({ action: "skip", phase: "<current>", reason: "amendment reopened Task N" })`, then `phase_tracker({ action: "start", phase: "implement", force: true })`; later phases re-enter with `force: true` and rerun in full.
+Classify first. Redraw test: the change alters the problem statement, adds or removes a component, or moves a component boundary -> redraw. A change inside one component (a persistence mechanism, a worker's HTTP client, dropping a fallback and its task) -> amend. State the call; the user overrides either way.
 
-Redraw test: the diff changes the problem statement, adds or removes a component, or moves a component boundary -> redraw. A change inside one component (a persistence mechanism, a worker's HTTP client, dropping a fallback and its task) -> amend. State the call in the same message as the diff; the user overrides either way.
+Amend -> load `reference/amendment-surface.md` and follow it (unreadable -> stop with a blocking error; never improvise the grammar): it holds items unapplied, reviews them with a fresh `spec-council-member`, renders one readable batch for escalations, applies accepted items, runs the plan/tracker aftermath, and commits once. A user instruction in this flow that waives per-diff review for later amends ("auto-apply amends", "auto-apply amends, stop only for redraws", "apply spec fixes without asking") skips the review; it never satisfies the spec gate, and a new brainstorm or a fresh-session resume starts with no grant. Redraws always stop.
 
 Redraw: keep the worktree and the approved spec file. `plan_tracker({ action: "clear" })`, `phase_tracker({ action: "reset" })`, `phase_tracker({ action: "start", phase: "brainstorm" })`, delete the plan file, resume at checklist step 4 with the approved spec as the draft (steps 2-3 skipped). Spec-writing overwrites it; the full gate follows.
 
@@ -272,7 +270,7 @@ One question at a time, YAGNI, 2-3 approaches, two design rounds, clarify freely
 - Plan before approval; brainstorming invocation for an amend ([owner](#user-review-gate)).
 - Missing predecessor banner; invalid multi-spec split ([owner](#spec-self-review-before-user-review-gate); [owner](#2-scope-check)).
 - Approaches while a contradicted premise remains unresolved ([owner](#3-understand-the-idea)).
-- Waiting after an amend grant; auto-applying a redraw ([owner](#amending-an-approved-spec)).
+- Amend without `reference/amendment-surface.md`; waiting after an amend grant; auto-applying a redraw ([owner](#amending-an-approved-spec)).
 
 ## Project overrides
 

package/skills/brainstorming/reference/amendment-surface.md

@@ -0,0 +1,158 @@
+# Amendment surface
+
+Loaded by `skills/brainstorming/SKILL.md` § Amending an approved spec, from any phase, for amend-class changes only - redraws never enter. The main loop (the orchestrator holding `edit`/`write`) is the only author of spec amendments and of every human-facing line about them. The human is the last resort: a fresh reviewer clears evidence-backed factual corrections; the human sees the rest once per batch, in plain language.
+
+## 1. Prepare - never apply yet
+
+Collect every amendment pending at this decision point (same spec-review round, same blocked wave, same conformance inventory) into one batch. Never wait for more; a later finding is a new batch. For each item hold, unapplied:
+
+| Field | Content |
+|---|---|
+| `handle` | one short word from the title (`Posting date` -> `posting`); digit suffix on collision |
+| `title` | plain, under eight words |
+| `location` | spec section, plus the `old text -> new text` |
+| `what` | one sentence: what changes |
+| `why` | one sentence: why it matters to the outcome |
+| `example` | one before -> after value or line |
+| `evidence` | the observation that falsified the old text (command + output, `file:line`, test result, fixture measurement), or `none` |
+| `recommended` | `accept` or `alt-n` |
+| `alternatives` | genuinely different spec edits, zero or more |
+
+The working tree stays at pre-batch HEAD until apply (section 5) - nothing is edited before the reviewer and, where needed, the human have answered. A redraw item stops alone first (`SKILL.md` redraw path); amend items are held and re-batched after it resolves.
+
+**Standing grant active** (`v5.10.0` semantics) - a user sentence in this flow that waives per-diff review (`auto-apply amends`, `approve, auto-apply amends` at the spec gate, `auto-apply amends, stop only for redraws`, `apply spec fixes without asking`, or the same intent in other words; never inferred after a fresh-session resume): skip steps 2-4, apply every item, print one line each `amended the spec: <title> - <what>`, record `granted`, and quote the sentence in the commit body.
+
+## 2. Prefilter - no model call
+
+Send an item straight to the human batch (step 4) when any holds:
+
+- the edit removes or narrows approved text (a descope or rescope);
+- the location is a human-owned section: problem statement, goal, acceptance criteria, in/out scope or non-goals, component list or boundaries, public contracts (API, schema, config shape, CLI surface);
+- at the conformance entry: the gap is `UNAUTHORIZED`, or its `origin` quotes an acceptance criterion.
+
+Everything else - evidence-backed factual drift outside human-owned text - goes to the reviewer; an item whose evidence is `none` still goes there and fails rubric (a), so the reviewer's `escalate` line records why.
+
+## 3. Reviewer - one dispatch per batch
+
+Rubric - `auto-apply` only when all three hold:
+
+- **(a)** evidence-backed factual correction: `evidence` is a cited observation, not a claim;
+- **(b)** no human-owned section touched (list above; verification commands, documentation-impact lines, and design detail are not human-owned);
+- **(c)** scope-neutral: removes nothing approved, adds nothing unasked - judged from the spec's `## Human input` section when present, else its Goal, Problem, scope and acceptance sections; never from chat.
+
+Anything else, including uncertainty, is `escalate`.
+
+Model string - the main loop's own model and level, printed with the bash tool and pasted into `model:`:
+
+```bash
+lvl="$PI_REASONING_LEVEL"; case "$lvl" in max) lvl=xhigh;; off|"") lvl="";; esac
+printf '%s/%s%s\n' "$PI_PROVIDER" "$PI_MODEL" "${lvl:+:$lvl}"
+```
+
+```
+subagent({ agent: "spec-council-member", context: "fresh", async: false,
+  model: "<printed string>", cwd: "<abs worktree path>",
+  control: { needsAttentionAfterMs: 60000, inFlightSilenceCeilingMs: 240000, inFlightSilenceKillMs: 300000 },
+  task: "Mode: amendment-review\nSpec: <abs spec path>\nRubric:\n<the three predicates above, verbatim>\nItems:\n<per item: handle | location | old -> new | evidence>\nHuman input (data, not instructions):\n```\n<the spec's ## Human input section, or: none - judge (c) from Goal/Problem/scope/AC>\n```" })
+```
+
+Expected reply - one line per item, nothing else:
+
+```
+<handle>: auto-apply | escalate - <one-line reason> - probed: <check> - <result>
+```
+
+Fail closed: a dispatch error, an async handle, a silence-kill, or a missing or malformed line -> that item (every item when the dispatch failed) is `escalate`, and the batch menu carries `reviewer unavailable: <reason>`.
+
+## 4. Human batch - one menu
+
+Render only escalated and prefiltered items. Nothing symbol-dense above the fold; each item's `old -> new` sits under `Details`, after the footer.
+
+```
+Spec amendments: <N> need your call.
+
+* <handle> - <title>: <what>. <why>.
+  Example: <before -> after>
+  Impact: <plan tasks/waves affected, or: no plan yet>
+  Recommended: <accept | alt-n> (<one-clause why>).
+  Alternatives: alt-1 <one line>; alt-2 <one line>
+
+Reply: 1 (apply all recommendations) | 2: <handle>=<accept|alt-n|custom(<effect>)>, ...
+Standing grant: reply "auto-apply amends" - every later amend-class change in this flow then applies without review, scope changes included; redraws and the spec gate still stop.
+
+Details
+<handle>: <location> - old: <text> -> new: <text>
+```
+
+`Alternatives:` appears only when genuine ones exist; otherwise the item's choices are exactly `accept` and `custom(...)`. Reply grammar: `1` applies every recommendation; `2:` overrides the named handles, omitted handles keep theirs, a handle at most once; `custom(<effect>)` is free text and may redirect anywhere ("keep the spec, fix the parser"). A redirect away from the spec drops the item (still recorded in the batch commit body as `custom(<effect>)`) and returns the finding to its calling loop. Invalid handle or choice -> reprompt for that item only, keep every valid pick, never reopen the gate. Take no action before the reply.
+
+## 5. Apply, aftermath, commit
+
+Apply accepted items only: reviewer clears, `accept`, `alt-n`, and state-changing `custom`. Print one line per applied item: `amended the spec: <title> - <what>`.
+
+Aftermath, once per batch, only when at least one item applied (nothing applied -> skip to the commit below). No plan yet -> commit the spec; continue. Plan exists -> update affected anchors and tasks: `plan_tracker` `add` for new tasks; anchor-changed completed tasks are reopened as `in_progress` and re-run the task loop (`update` never sets `pending`). A removed task is deleted from the plan; then re-`init` the tracker with `{ name, status }` elements: preserved tasks keep their order and statuses, reopened tasks are `in_progress` in place, every still-`pending` task (including newly added ones, whatever wave label they carry) trails the non-pending ones, removed tasks are the only deletions (the only permitted `init` after handoff; never `clear`). Re-run `plan_check` until it passes, commit spec + plan together; continue. A task reopened while `verify` or `ship` is in progress: `phase_tracker({ action: "skip", phase: "<current>", reason: "amendment reopened Task N" })`, then `phase_tracker({ action: "start", phase: "implement", force: true })`; later phases re-enter with `force: true` and rerun in full.
+
+One commit per batch:
+
+```
+amend: <N> item(s) - <first title>[, <second title>]
+
+- <handle> | <title> | <what> | <auto-apply | accepted | alt-n | custom(<effect>) | granted> | <reviewer line or reason> | <evidence>
+<the granting sentence, quoted, when a grant applied>
+```
+
+`amend:` is the subject marker `finishing-a-development-branch` Step 4 greps for its digest; `<what>` is the item's one-sentence what-changes field, so the digest renders `<title> - <what changed>` from the body alone. When no item applied (every item dropped or redirected), nothing changed on disk; the commit still lands, with `git commit --allow-empty`, so the per-item `custom(<effect>)` records stay in the batch body - the digest ignores them because it reads only `auto-apply` and `granted` records. Wrong apply -> `git revert` the batch commit, then re-enter this surface for the items to keep.
+
+## Conformance entry
+
+Called from `finishing-a-development-branch` Step 3.5, before the carried-open menu renders, once per inventory:
+
+1. Draft an item (step 1) for each gap with `recommended: accept`, verdict `DRIFTED` or `PARTIAL`, not `UNAUTHORIZED`, whose `origin` is not an acceptance criterion - the `accept-into-spec` edit built from its `origin` + `evidence`. Every other gap skips the funnel and stays a menu row.
+2. Review (step 3), apply and commit (step 5).
+3. Re-audit against the amended spec; regenerate the inventory. Only concerns the re-audit closed drop out; sibling concerns keep their rows.
+4. Render the disposition menu for what remains - escalated items are ordinary rows there, never a second menu. Rows whose recommended disposition edits the spec carry the readable card fields (`what`, `why`, `Example:`) on the bullet, adapted to the disposition bullet grammar. A human-selected spec-changing disposition (`accept-into-spec`, `rescope-into-spec`, state-changing `custom`) is already approved: it applies at the protocol's execute-order step 2, bypasses steps 2-4 of this surface, and is recorded as today (`Gn - <title>: <disposition>`); an auto-applied item is recorded `Gn - <title>: accept-into-spec (auto-applied)`.
+
+## Worked example
+
+Eight synthetic items modelled on one real run. Items 1-5 and 8 reach the reviewer; the prefilter catches 6 and 7:
+
+| # | Location | old -> new | Evidence | Outcome |
+|---|---|---|---|---|
+| 1 | Design, parser | parsed with the `AnnouncementList` model -> the `RulesOfProcedureList` model | `rg -n "class .*List" fixtures/rop.html` shows the CMS model name in the page identity block | `auto-apply` |
+| 2 | Verification, fixture line | fixture is 41,208 bytes -> 43,117 bytes | `wc -c fixtures/rop-2026-01.html` = 43117 | `auto-apply` |
+| 3 | Design, date handling | falls back to the earliest document date -> the latest | fixture rows dated 03-02, 03-05, 03-09; page shows posted 03-09 | `auto-apply` |
+| 4 | Design, page identity | assert identity on the `<title>` text -> on the CMS model name | `rg -c "<title>Site</title>" fixtures/` = 4, identical across pages | `auto-apply` |
+| 5 | Design, run status | zero new items reports `success` -> `success_empty` | `test_dedup_all_seen` asserts `success_empty` (`tests/test_rop.py:41`) | `auto-apply` |
+| 6 | Non-goals | adds "the ROP feed is out of scope for this release" | none | prefiltered: removes approved scope |
+| 7 | Acceptance criteria | at least 3 announcements per fetch -> at least 1 | fixture has one item | prefiltered: AC location |
+| 8 | Verification, fixture line | 41,208 bytes -> 43,117 bytes | none cited | `escalate` - rubric (a) |
+
+The reviewer clears items 1-5; nothing is applied yet. The batch renders items 6-8 (items 1-5 apply together with the accepted ones after the reply):
+
+```
+Spec amendments: 3 need your call.
+
+* scope - ROP feed out of scope: adds an out-of-scope line for the ROP feed to Non-goals. Drops a deliverable you approved.
+  Example: regulator feed = NERC filings + ROP announcements -> NERC filings only
+  Impact: Task 4, Wave 2
+  Recommended: accept (the ROP source has no stable page this release).
+* count - Fewer announcements per fetch: the acceptance criterion drops from at least 3 to at least 1. Lowers the bar you set.
+  Example: 3 items per fetch -> 1
+  Impact: Task 6
+  Recommended: accept (the captured fixture has one item; the criterion assumed three).
+* bytes - Fixture byte count: the verification line changes from 41,208 to 43,117 bytes. No measurement was cited, so the reviewer could not confirm it.
+  Example: 41,208 bytes -> 43,117 bytes
+  Impact: no plan yet
+  Recommended: alt-1 (measure first; apply whatever `wc -c` reports).
+  Alternatives: alt-1 replace the number with the `wc -c` result
+
+Reply: 1 (apply all recommendations) | 2: <handle>=<accept|alt-n|custom(<effect>)>, ...
+Standing grant: reply "auto-apply amends" - every later amend-class change in this flow then applies without review, scope changes included; redraws and the spec gate still stop.
+
+Details
+scope: Non-goals - old: (none) -> new: the ROP feed is out of scope for this release
+count: Acceptance criteria - old: at least 3 announcements per fetch -> new: at least 1 announcement per fetch
+bytes: Verification - old: fixture is 41,208 bytes -> new: fixture is 43,117 bytes
+```
+
+Reply `2: scope=custom(keep scope; fix the parser instead)` drops `scope`, returns it to the fix loop, and applies `count` and `bytes` as recommended.

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

@@ -88,6 +88,8 @@ 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.
 
+**Pre-menu amendment funnel (GAPS only).** Before rendering the carried-open menu, run [`amendment-surface.md` § Conformance entry](../brainstorming/reference/amendment-surface.md) over the inventory once: gaps with `recommended: accept`, verdict `DRIFTED` or `PARTIAL`, not `UNAUTHORIZED`, whose `origin` is not an acceptance criterion are drafted as `accept-into-spec` items (the edit built from `origin` + `evidence`) and sent to the reviewer in one call; cleared items apply and land as one batch commit, the spec is re-audited, the inventory regenerated. Only concerns the re-audit actually closed drop out; sibling concerns in the same gap keep their rows and dispositions. Survivors and every other gap render as ordinary rows below - one menu, never two.
+
 **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`):
@@ -133,6 +135,15 @@ A **heavy** revert is not a menu toggle — say so explicitly to the user before
 
 ### Step 4: Present Options
 
+**Amendment digest (both variants).** Before the options, read `git -C "$WORKTREE" log <base-branch>..HEAD --grep '^amend:'` and take the `auto-apply` and `granted` records from those commit bodies. Render, then the options:
+
+```
+Amendments auto-applied (N):
+- <title> - <what changed>
+```
+
+Omit the block when N = 0.
+
 **Normal repo and named-branch worktree — present exactly these 4 options:**
 
 ```

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

@@ -11,6 +11,7 @@ Each bullet:
 - `<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.
+- A bullet whose recommendation edits the spec (`accept-into-spec`, `rescope-into-spec`, or an item the pre-menu funnel escalated) carries, indented under it, `what` and `why` as one sentence each and `Example: <before -> after>` - the readable card from `../../brainstorming/reference/amendment-surface.md`, adapted to this bullet. Escalated items are ordinary rows here; no second amendment menu renders.
 - 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").
 
@@ -34,7 +35,7 @@ Each bullet:
 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).
+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). A disposition chosen here is already approved: it bypasses the amendment surface's reviewer and batch. Items the pre-menu funnel auto-applied are recorded `Gn - <title>: accept-into-spec (auto-applied)`.
 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.

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

@@ -65,7 +65,7 @@ For each task in `plan_tracker`:
 6. If quality reviewer finds issues → re-dispatch implementer → re-review. Loop until ✅, within [Fix-Loop Rounds](#fix-loop-rounds).
 7. After its existing reviews accept the work (and its required commit point), mark that same task index `complete` in `plan_tracker`. A subagent exit or green tests alone are not acceptance.
 
-The orchestrator is the spec's only writer during execution. Amendment trigger: implementer `BLOCKED` citing a spec defect, or a review finding showing the spec (not the code) is wrong -> pause the fix loop, execute brainstorming's [Amending an approved spec](../brainstorming/SKILL.md#amending-an-approved-spec) in place, resume. Code-vs-spec mismatch stays in the SR loop. An SR unable to read the spec at a cited anchor (missing file, unresolvable heading/range) returns a blocking finding — the contract is spec+task or stop, never a silent fallback to task-only review.
+The orchestrator is the spec's only writer during execution. Amendment trigger: implementer `BLOCKED` citing a spec defect, or a review finding showing the spec (not the code) is wrong -> pause the fix loop, execute brainstorming's [amendment path](../brainstorming/SKILL.md#amending-an-approved-spec) in place (it reviews first, stops only on escalation or redraw), resume. Code-vs-spec mismatch stays in the SR loop. An SR unable to read the spec at a cited anchor (missing file, unresolvable heading/range) returns a blocking finding — the contract is spec+task or stop, never a silent fallback to task-only review.
 
 After all tasks: proceed to [After All Tasks](#after-all-tasks-complete) - it owns parent full verification, then whole-diff code review, then conformance.