fix: show untracked files in working-tree review (#16)

Co-authored-by: Claude Opus 4.8 (1M context) <noreply@anthropic.com>

Author: ymansurozer

skills/galley/SKILL.md

@@ -168,6 +168,8 @@ If your harness can't hold a `galley await` long-poll open or background the des
 
 Optionally attach a **guided review** so the desk presents the changeset as a guided flow: an overview page, then the files in the order you choose, each with a summary and category, and the critical ones flagged. The prose fields (overview, summaries, why) render as markdown — use inline code for identifiers and lists for multi-point guidance. You generate the guide from the diff and attach it at start with `galley … --guide <file>`. Galley validates and renders it and runs no model; with no guide the desk works exactly the same.
 
+Write the guide file **outside the repo working tree** — a temp path (e.g. from `mktemp`) or a gitignored directory. Working-tree review mode surfaces untracked files, so a guide left in the repo would appear in the review as a stray addition (and risks being committed by accident).
+
 Run **`galley guide-spec`** for the authoritative schema, field meanings, and validation rules.
 
 The guide is attached at **start** and survives `reload` and restarts. It is stamped against the diff it was generated for; once a `reload` advances the diff past that point, the desk flags it stale. To refresh it, regenerate the guide from the new diff and swap it into the **live** desk — `galley reload --guide <new.json>`, or simply re-run the start command with the new `--guide` (a live desk is reused: same tab, guide swapped, diff reloaded). Never start a second desk for a fresh guide.

skills/galley/agents-snippet.md

@@ -12,7 +12,7 @@ When the user should review a plan, a PR, or code changes you've made, hand it t
 - **A markdown plan / single artifact** → `galley file <path> &`.
 - **A branch / PR** → `galley pr <ref> &`.
 
-Optionally attach an AI **guided review** so the human gets an overview + a logical, annotated file order: add `--guide guide.json` to the start command (see the skill for the JSON schema).
+Optionally attach an AI **guided review** so the human gets an overview + a logical, annotated file order: add `--guide <file>` to the start command (see the skill for the JSON schema). Write the guide file **outside the repo working tree** (a temp path or gitignored dir) — working-tree review surfaces untracked files, so a guide left in the repo shows up as a stray addition.
 
 Then loop: `galley await --session <task-id>` blocks for the next event and prints a tagged JSON envelope.
 - `{"kind":"question",…}` → answer **now** with `galley comment --path … --line … --side … --body "…"` at the question's location. While gathering the answer (or acting on a review), post brief `galley status --session <task-id> --body "Reading X…"` lines — they show live next to the reviewer's waiting indicator so they're not staring at a static spinner.

src/diffsource.test.ts

@@ -1,9 +1,10 @@
-import { test, before, after } from "node:test";
 import assert from "node:assert/strict";
 import { execFileSync } from "node:child_process";
 import { mkdtempSync, writeFileSync, rmSync } from "node:fs";
 import { tmpdir } from "node:os";
 import path from "node:path";
+import { test, before, after } from "node:test";
+
 import { buildDiffSource } from "./state.js";
 
 let root: string;
@@ -99,3 +100,41 @@ test("file mode: staged content is the old-side baseline, not HEAD", async () =>
   git(["restore", "--staged", "a.txt"]);
   git(["checkout", "--", "a.txt"]);
 });
+
+// `git diff` never lists untracked files, so the working review must surface them itself —
+// otherwise a brand-new file the agent created (but never `git add`ed) silently vanishes.
+test("repo mode: untracked file → full additions alongside tracked changes", async () => {
+  write("a.txt", "a\nUNTRACKED-NEIGHBOR\nc\n"); // a tracked change…
+  write("new.ts", "export const x = 1;\n"); // …and a brand-new untracked file
+  const src = await buildDiffSource({ mode: "repo", root });
+  assert.ok(src);
+  const newFile = src!.files.find((f) => f.path === "new.ts");
+  assert.ok(newFile, "untracked file should appear in the working diff");
+  assert.equal(newFile!.oldFile.contents, ""); // nothing to diff against → all additions
+  assert.equal(newFile!.newFile.contents, "export const x = 1;\n");
+  assert.equal(
+    src!.changes.filter((c) => c.path === "new.ts").length,
+    0, // no per-hunk changes — whole-file Approve stages it via `git add`
+  );
+  assert.ok(src!.changes.some((c) => c.path === "a.txt")); // tracked change still present
+  git(["checkout", "--", "a.txt"]);
+  rmSync(path.join(root, "new.ts"));
+});
+
+// Guards the early-return: with every tracked change staged, `git diff` is empty — but an
+// untracked-only working tree must still open a desk, not return null.
+test("repo mode: only untracked files, nothing else changed → non-null", async () => {
+  write("new.ts", "export const y = 2;\n");
+  const src = await buildDiffSource({ mode: "repo", root });
+  assert.ok(src, "untracked-only working tree should still produce a review");
+  assert.equal(src!.files.length, 1);
+  assert.equal(src!.files[0]!.path, "new.ts");
+  rmSync(path.join(root, "new.ts"));
+});
+
+test("repo mode: staged diff ignores untracked files", async () => {
+  write("new.ts", "export const z = 3;\n"); // untracked, never added
+  const src = await buildDiffSource({ mode: "repo", root, staged: true });
+  assert.equal(src, null); // nothing staged, and untracked must not leak into staged mode
+  rmSync(path.join(root, "new.ts"));
+});

src/guidespec.ts

@@ -7,6 +7,10 @@ export const GUIDE_SPEC = `galley guided-review spec
 
 Attach a guide at start:  galley <mode> --guide <file.json>
 
+Write the guide file OUTSIDE the repo working tree (a temp path, e.g. one from \`mktemp\`, or
+a gitignored directory). Working-tree review mode surfaces untracked files, so a guide left in
+the repo would show up in the review as a stray addition — and could get committed by accident.
+
 The file is one JSON object:
 
 {

src/state.ts

@@ -1,6 +1,7 @@
 import crypto from "node:crypto";
 import { promises as fs } from "node:fs";
 import path from "node:path";
+
 import {
   changeBlockContent,
   changeStableKeyFromBlock,
@@ -177,17 +178,34 @@ export async function buildDiffSource(opts: {
   if (opts.staged) args.push("--cached");
   if (opts.path) args.push("--", opts.path);
   const rawDiff = await git(args, root);
-  if (!rawDiff.trim()) return null;
   // Each side must match what the diff was taken against, because the UI re-diffs the
   // old/new contents itself instead of rendering these hunks. Unstaged diffs working
   // tree vs INDEX, so old reads :0 — a HEAD baseline would resurrect already-staged
   // changes as pending diff on every reload. Staged (--cached) diffs index vs HEAD.
-  const { files, changes } = await assembleDiff(
-    rawDiff,
-    (p) => fileAt(root, p, opts.staged ? "HEAD" : ":0"),
-    (p) => (opts.staged ? fileAt(root, p, ":0") : fileAt(root, p)),
-    true,
-  );
+  const { files, changes } = rawDiff.trim()
+    ? await assembleDiff(
+        rawDiff,
+        (p) => fileAt(root, p, opts.staged ? "HEAD" : ":0"),
+        (p) => (opts.staged ? fileAt(root, p, ":0") : fileAt(root, p)),
+        true,
+      )
+    : { files: [], changes: [] };
+  // `git diff` never reports untracked files (a brand-new file has no index/HEAD side to
+  // diff against), so the working review would silently drop any file the agent created but
+  // never `git add`ed. Surface them as full-file additions — same representation as file
+  // mode. They carry no stageable hunks; whole-file Approve stages them via `git add`
+  // (/api/stage), which doesn't rely on rawDiff. Staged mode is unaffected: untracked files
+  // are by definition not in the index.
+  if (!opts.staged) {
+    const lsArgs = ["ls-files", "--others", "--exclude-standard"];
+    if (opts.path) lsArgs.push("--", opts.path);
+    const untracked = (await git(lsArgs, root)).split(/\r?\n/).filter(Boolean);
+    for (const rel of untracked) {
+      const working = await fs.readFile(path.join(root, rel), "utf8").catch(() => "");
+      files.push(fileEntry(rel, "", working));
+    }
+  }
+  if (files.length === 0) return null;
   return { files, changes, rawDiff };
 }