pi-gauntlet 5.18.4 → 5.18.6

package/CHANGELOG.md

@@ -1,5 +1,15 @@
 # Changelog
 
+## v5.18.6 - 2026-09-24
+
+### Changed
+
+- `gauntlet-spec-index` prints the recorded modified-file paths that still exist in the repository in its `files` column, `;`-separated, with `missing` marking a telemetry record that has no list; the brainstorming scout renders them as a `Predecessor anchors` section for named predecessors. (#52)
+
+## v5.18.5 - 2026-09-23
+
+- The TDD RED step directs authors to reuse existing setup helpers and consolidate near-identical cases into parametrized or table-driven examples. (#49)
+
 ## v5.18.4 - 2026-09-23
 
 ### Changed

package/README.md

@@ -134,7 +134,7 @@ Pin an exact release with `npm:pi-gauntlet@X.Y.Z`. See [doc/install-internals.md
 
 ## Spec search index
 
-`gauntlet-spec-index` provides lexical search across `doc/specs/*.md` at the repository root and one service level down. From a repository worktree, run `node <pi-gauntlet-package>/bin/gauntlet-spec-index.mjs --query "<text>" [--limit N]`; it requires Node >=24.15.0, refreshes its FTS5 index on every query, and prints tab-separated `score`, `path`, `service`, `title`, `status`, `shipped_at`, `files`, and `snippet` columns. The per-worktree cache lives at `.pi/gauntlet/index.sqlite`, and its first creation adds `/.pi/gauntlet/index.sqlite*` to Git's `info/exclude` so the database and SQLite sidecars stay out of `git status`.
+`gauntlet-spec-index` provides lexical search across `doc/specs/*.md` at the repository root and one service level down. From a repository worktree, run `node <pi-gauntlet-package>/bin/gauntlet-spec-index.mjs --query "<text>" [--limit N]`; it requires Node >=24.15.0, refreshes its FTS5 index on every query, and prints tab-separated `score`, `path`, `service`, `title`, `status`, `shipped_at`, `files`, and `snippet` columns. The `files` column is a `;`-separated list of repo-relative paths the spec's shipped change modified and that still exist in the repository, the literal `missing` when the spec's telemetry record has no `derived.modified_files` list, or blank when there is no readable record or no recorded path remains. The per-worktree cache lives at `.pi/gauntlet/index.sqlite`, and its first creation adds `/.pi/gauntlet/index.sqlite*` to Git's `info/exclude` so the database and SQLite sidecars stay out of `git status`.
 
 ## Performance digest
 

package/bin/gauntlet-spec-index.mjs

@@ -176,7 +176,7 @@ const toMatch = (query) =>
   query.split(/\s+/).filter((t) => t.length >= 2).map((t) => `"${t.replaceAll('"', '""')}"`).join(" OR ");
 
 function telemetry(root, specPath) {
-  const blank = { status: null, shipped_at: null, files: null };
+  const blank = { status: null, shipped_at: null, files: "" };
   const p = join(root, ".pi/gauntlet/telemetry", specPath.replace(/\.md$/, ".yaml"));
   if (!existsSync(p)) return blank;
   let rec;
@@ -186,12 +186,17 @@ function telemetry(root, specPath) {
     process.stderr.write(`gauntlet-spec-index: warning: unreadable telemetry ${p}\n`);
     return blank;
   }
-  if (!rec || typeof rec !== "object") return blank;
+  if (!rec || typeof rec !== "object" || Array.isArray(rec)) return blank;
   const mf = rec.derived?.modified_files;
-  return { status: rec.status ?? null, shipped_at: rec.shipped_at ?? null, files: Array.isArray(mf) ? mf.length : null };
+  const files = Array.isArray(mf)
+    ? mf.filter((f) => typeof f === "string" && existsSync(join(root, f))).join(";")
+    : "missing";
+  return { status: rec.status ?? null, shipped_at: rec.shipped_at ?? null, files };
 }
 
 const cell = (v) => (v === null || v === undefined ? "" : String(v).replace(/\s+/g, " ").trim());
+// Paths keep their spaces; only column and row delimiters are neutralised.
+const filesCell = (v) => v.replace(/[\t\r\n]+/g, " ");
 
 async function main() {
   if (!nodeOk()) die(`gauntlet-spec-index needs Node >=24.15.0 (found ${process.versions.node})`);
@@ -211,7 +216,7 @@ async function main() {
   const out = [HEADER.join("\t")];
   for (const r of rows) {
     const t = telemetry(root, r.path);
-    out.push([r.score.toFixed(3), r.path, r.service, r.title, t.status, t.shipped_at, t.files, r.snippet].map(cell).join("\t"));
+    out.push([...[r.score.toFixed(3), r.path, r.service, r.title, t.status, t.shipped_at].map(cell), filesCell(t.files), cell(r.snippet)].join("\t"));
   }
   process.stdout.write(out.join("\n") + "\n");
   db.close();

package/bin/gauntlet-spec-index.test.mjs

@@ -112,13 +112,17 @@ test("6: telemetry join is output-only and tolerant", (t) => {
   t.after(() => rmSync(root, { recursive: true, force: true }));
   run(root, ["--query", "zephyr"]);
   const filesBefore = withDb(root, (database) => JSON.stringify(database.prepare("SELECT * FROM files ORDER BY path").all()));
+  write(root, "x", "x\n");
+  write(root, "y", "y\n");
   write(root, ".pi/gauntlet/telemetry/doc/specs/a.yaml", "status: shipped\nshipped_at: 2026-09-17T10:00:00Z\nderived:\n  modified_files:\n    - x\n    - y\n");
   let r = run(root, ["--query", "zephyr"]);
-  assert.deepEqual(r.rows[0].slice(4, 7), ["shipped", "2026-09-17T10:00:00Z", "2"]);
+  assert.deepEqual(r.rows[0].slice(4, 7), ["shipped", "2026-09-17T10:00:00Z", "x;y"]);
+  assert.equal(r.rows[0].length, 8);
+  assert.equal(r.rows[1][6], "");
   assert.equal(withDb(root, (database) => JSON.stringify(database.prepare("SELECT * FROM files ORDER BY path").all())), filesBefore);
   write(root, ".pi/gauntlet/telemetry/doc/specs/a.yaml", "status: in_progress\nshipped_at: 2026-09-18T10:00:00Z\n");
   r = run(root, ["--query", "zephyr"]);
-  assert.deepEqual(r.rows[0].slice(4, 7), ["in_progress", "2026-09-18T10:00:00Z", ""]);
+  assert.deepEqual(r.rows[0].slice(4, 7), ["in_progress", "2026-09-18T10:00:00Z", "missing"]);
   write(root, ".pi/gauntlet/telemetry/doc/specs/a.yaml", "status: [unclosed\n");
   r = run(root, ["--query", "zephyr"]);
   assert.equal(r.status, 0);
@@ -126,6 +130,51 @@ test("6: telemetry join is output-only and tolerant", (t) => {
   assert.match(r.stderr, /a\.yaml/);
 });
 
+test("6b: files cell is the AC fixture - present paths kept, gone paths dropped, no list is missing", (t) => {
+  const root = mkdtempSync(join(tmpdir(), "gsi-"));
+  t.after(() => rmSync(root, { recursive: true, force: true }));
+  spawnSync("git", ["init", "-q"], { cwd: root });
+  write(root, "doc/specs/a.md", "# Alpha quokka\n\n**Goal:** quokka.\n");
+  write(root, "doc/specs/b.md", "# Beta quokka\n\n**Goal:** quokka too.\n");
+  write(root, "src/x.ts", "export {};\n");
+  write(root, ".pi/gauntlet/telemetry/doc/specs/a.yaml", "status: shipped\nderived:\n  modified_files:\n    - src/x.ts\n    - src/gone.ts\n");
+  write(root, ".pi/gauntlet/telemetry/doc/specs/b.yaml", "status: shipped\n");
+  spawnSync("git", ["add", "-A"], { cwd: root });
+  spawnSync("git", ["-c", "user.name=t", "-c", "user.email=t@t", "commit", "-q", "-m", "fixture"], { cwd: root });
+  const r = run(root, ["--query", "quokka"]);
+  assert.equal(r.status, 0, r.stderr);
+  const cells = Object.fromEntries(r.rows.map((row) => [row[1], row[6]]));
+  assert.equal(cells["doc/specs/a.md"], "src/x.ts");
+  assert.equal(cells["doc/specs/b.md"], "missing");
+  for (const row of r.rows) assert.equal(row.length, 8);
+});
+
+test("6c: files cell edge cases - order, spaces kept, all gone, non-array, null record", (t) => {
+  const root = repo();
+  t.after(() => rmSync(root, { recursive: true, force: true }));
+  const yaml = ".pi/gauntlet/telemetry/doc/specs/a.yaml";
+  const files = () => run(root, ["--query", "zephyr"]).rows[0][6];
+  write(root, "b.js", "");
+  write(root, "a.js", "");
+  write(root, "sp  aced.txt", "");
+  write(root, yaml, "status: shipped\nderived:\n  modified_files:\n    - a.js\n    - b.js\n");
+  assert.equal(files(), "a.js;b.js");
+  write(root, "tab\there.js", "");
+  write(root, yaml, 'status: shipped\nderived:\n  modified_files:\n    - a.js\n    - "tab\\there.js"\n');
+  assert.equal(files(), "a.js;tab here.js");
+  assert.equal(run(root, ["--query", "zephyr"]).rows[0].length, 8);
+  write(root, yaml, "status: shipped\nderived:\n  modified_files:\n    - 'sp  aced.txt'\n    - 7\n");
+  assert.equal(files(), "sp  aced.txt");
+  write(root, yaml, "status: shipped\nderived:\n  modified_files:\n    - nope1\n    - nope2\n");
+  assert.equal(files(), "");
+  write(root, yaml, 'status: shipped\nderived:\n  modified_files: "x"\n');
+  assert.equal(files(), "missing");
+  write(root, yaml, "");
+  assert.equal(files(), "");
+  write(root, yaml, "- a\n- b\n");
+  assert.equal(files(), "");
+});
+
 test("7: query sanitising tolerates embedded quotes", (t) => {
   const root = repo();
   t.after(() => rmSync(root, { recursive: true, force: true }));

package/package.json

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

package/skills/brainstorming/gatherer.md

@@ -63,8 +63,23 @@ Scout (always dispatched):
 > handoff. Either way open at
 > most five candidates whose topic matches this request, and name any whose design
 > this request replaces or amends with the section(s) affected - `Predecessor:
-> <path>, <scope>` - or `Predecessor: none`. Judge by topic; shared file paths never
-> decide. End with an
+> <path>, <scope>` - or `Predecessor: none`.
+> Judge by topic; shared file paths never decide.
+> The `files` column of each candidate row is the `;`-separated list of repo-relative
+> paths that predecessor's ship modified and that still exist, or the literal `missing`,
+> or blank; do not recompute it from git or telemetry. After the `Predecessor:` line(s),
+> and only when at least one predecessor is named, render a `Predecessor anchors`
+> section: list every attributed path exactly once, attributed to the first named
+> predecessor in index output order whose cell lists it, with no per-path commentary
+> (bookkeeping paths such as `CHANGELOG.md` are listed like any other); for each named
+> predecessor whose cell is `missing`, write one line
+> `<spec>: modified file list missing for this spec`, where `<spec>` is the path exactly
+> as written in its `Predecessor:` line. A blank cell contributes nothing for that spec;
+> a named predecessor with no index row (reached through a supersession banner, or named
+> from the directory-listing fallback) contributes no path and no `missing` line. When
+> no path and no `missing` line results - including whenever the index was unavailable -
+> omit the section entirely; `Predecessor: none` produces no anchors section. The anchors
+> are a recon hint, never a selection input. End with an
 > "Open questions that matter for the spec"
 > section. Compact handoff, not a dump.
 

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

@@ -60,6 +60,8 @@ Implement fresh from tests. Period.
 
 Write one minimal test showing what should happen.
 
+Before writing setup, look for an existing helper, fixture, or factory. Extend a suitable existing one before creating another. Write near-identical cases for the same behavior as one parametrized or table-driven example.
+
 **Requirements:**
 - One behavior per test
 - Clear name describing behavior (if the name contains "and", split it)