feat: skimmable changes — guide-driven focused reviews

The agent's guide can now mark parts of the diff as skimmable for a
focused review ("ignore pure import churn, show me the real changes"),
replacing the synthetic-branch workaround. GuideFile gains skim/
skimReason (whole file) and skimBlocks (new-side line spans the server
resolves to change blocks and stamps onto ChangeState). Validation
rejects an unresolvable span naming the file and span on attach;
a reload carrying the guide forward silently drops stale spans instead
— a rewritten block deserves fresh attention.

Fully-skimmed files (file-level flag, or every block stamped) leave
the reviewer's flow entirely: they gather under a collapsed
"Skimmed · N files" group at the bottom of the tree, walkthrough, and
Overview, and carry no weight in progress, review-complete, or the
wrap/approve-advance seeks. They are never auto-approved —
approvedFiles still means the reviewer signed off. Opening one is a
deliberate look, so its diff renders expanded; skimmed blocks inside
in-flow files collapse to one-line strips ("N skimmed lines · reason")
that expand on click, in both split and stacked views. Approving a
file accepts pending skimmed blocks exactly like visible ones.

Everything is display-only and derived per render, so a reload that
drops a stamp returns the file to the flow automatically. The contract
documents the fields and their intent: skim lowers attention, flag
raises it — never skim your own risky changes.

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_015jcfPg9g4TTWQksf8vhHps

Author: ymansurozer

scripts/smoke.mjs

@@ -69,6 +69,48 @@ try {
   assert.ok(state.changes.length >= 1, "desk has a change to review");
   console.log(`✓ desk up — repo mode, ${state.changes.length} change(s)`);
 
+  // guided review with skim (issue 06): attach a guide (OUTSIDE the repo so it isn't a stray
+  // untracked file) whose skimBlocks span resolves to the change block, and a file-level skim.
+  const guideDir = mkdtempSync(path.join(tmpdir(), "galley-smoke-guide-"));
+  const guidePath = path.join(guideDir, "guide.json");
+  writeFileSync(
+    guidePath,
+    JSON.stringify({
+      overview: "Smoke overview.",
+      files: [
+        {
+          path: "a.txt",
+          orientation: "The changed file.",
+          skim: true,
+          skimReason: "smoke",
+          skimBlocks: [{ lines: 2, reason: "line-two churn" }],
+        },
+      ],
+    }),
+  );
+  const reloaded = JSON.parse(cli("reload", "--repo", tmp, "--session", ID, "--guide", guidePath));
+  assert.ok(reloaded.ok, "reload with a skim guide accepted");
+  const guidedState = await getJson("/api/state");
+  assert.equal(guidedState.guide?.files?.[0]?.skim, true, "file-level skim survives to state");
+  assert.ok(
+    guidedState.changes.some((c) => c.skim),
+    "a skimBlocks span stamped a change block",
+  );
+  console.log("✓ reload --guide with skim → accepted, file + block stamped");
+
+  // A skim span that resolves to no change block is rejected (diff-aware validation).
+  const badReload = await post("/api/reload", {
+    guide: {
+      overview: "x",
+      files: [{ path: "a.txt", orientation: "s", skimBlocks: [{ lines: 99 }] }],
+    },
+  });
+  assert.equal(badReload.status, 422, "unresolvable skim span rejected");
+  const badBody = await badReload.json();
+  assert.ok(badBody.error?.includes("a.txt"), "rejection names the offending file");
+  rmSync(guideDir, { recursive: true, force: true });
+  console.log("✓ reload with an unresolvable skim span → 422 naming the entry");
+
   // human asks a question → `galley await` yields a question event
   await post("/api/ask", {
     path: "a.txt",

src/cli.ts

@@ -16,6 +16,7 @@ import {
   mergeReviewState,
   persistReview,
   readDeskLock,
+  resolveSkim,
   reviewDir,
   sanitizeSession,
   stablePort,
@@ -268,7 +269,7 @@ function loadGuideArg(value: string | boolean | undefined) {
     return null;
   }
   const SCHEMA =
-    "Expected JSON: { overview, prDescription?, files: [{ path, order, category, orientation, flag? }] }.";
+    "Expected JSON: { overview, prDescription?, files: [{ path, order, category, orientation, flag?, skim?, skimReason?, skimBlocks? }] }.";
   let parsed: unknown;
   try {
     parsed = JSON.parse(readFileSync(value, "utf8"));
@@ -444,6 +445,19 @@ async function runDesk(
     // Stamp the diff hash the guide was generated against; if a later reload advances the
     // diff past it, the desk flags the guide as possibly stale (slice 05).
     state.guide = { ...guide, baseDiffHash: state.baseDiffHash };
+    // Resolve skim spans against the fresh diff and stamp the collapsed blocks. Strict at
+    // initial attach: an unresolvable span aborts the launch naming the offending field, like
+    // any other invalid-guide input.
+    const skim = resolveSkim(state.rawDiff, state.changes, state.guide, { strict: true });
+    if (!skim.ok) {
+      console.error(`Invalid guide: ${skim.reason}.`);
+      process.exitCode = 1;
+      return;
+    }
+  } else if (state.guide) {
+    // A guide carried forward by the merge (restart without --guide): re-resolve leniently
+    // against the new diff — stale spans drop rather than abort (see resolveSkim).
+    resolveSkim(state.rawDiff, state.changes, state.guide, { strict: false });
   }
   if (mode === "repo") await syncGitState(state);
   await persistReview(state);

src/guide.test.ts

@@ -43,6 +43,48 @@ test("validateGuide defaults missing order (by position) and category", () => {
   assert.equal(r.guide.files[0]!.flag, undefined);
 });
 
+test("validateGuide accepts skim fields and normalizes skimBlocks lines", () => {
+  const r = validateGuide({
+    overview: "o",
+    files: [
+      {
+        path: "a.ts",
+        orientation: "s",
+        skim: true,
+        skimReason: "generated",
+        skimBlocks: [{ lines: 5, reason: "import" }, { lines: [12, 10] }],
+      },
+    ],
+  });
+  assert.ok(r.ok);
+  if (!r.ok) return;
+  const f = r.guide.files[0]!;
+  assert.equal(f.skim, true);
+  assert.equal(f.skimReason, "generated");
+  // a bare number normalizes to [n, n]; a reversed pair is ordered ascending.
+  assert.deepEqual(f.skimBlocks, [{ lines: [5, 5], reason: "import" }, { lines: [10, 12] }]);
+});
+
+test("validateGuide leaves skim fields unset when absent", () => {
+  const r = validateGuide({ overview: "o", files: [{ path: "a.ts", orientation: "s" }] });
+  assert.ok(r.ok);
+  if (!r.ok) return;
+  const f = r.guide.files[0]!;
+  assert.equal(f.skim, undefined);
+  assert.equal(f.skimReason, undefined);
+  assert.equal(f.skimBlocks, undefined);
+});
+
+test("validateGuide rejects malformed skimBlocks", () => {
+  const bad = (skimBlocks: unknown) =>
+    validateGuide({ overview: "o", files: [{ path: "a.ts", orientation: "s", skimBlocks }] }).ok;
+  assert.equal(bad("nope"), false); // not an array
+  assert.equal(bad([null]), false); // entry not an object
+  assert.equal(bad([{ lines: "x" }]), false); // lines not a number/pair
+  assert.equal(bad([{ lines: [1] }]), false); // wrong-length pair
+  assert.equal(bad([{ lines: [1, 2, 3] }]), false); // wrong-length pair
+});
+
 test("validateGuide rejects malformed input", () => {
   const cases: unknown[] = [
     null,

src/guide.ts

@@ -32,6 +32,45 @@ export function validateGuide(input: unknown): GuideValidation {
       orientation: f.orientation,
     };
     if (typeof f.flag === "string" && f.flag.trim()) file.flag = f.flag;
+    // Skim fields (focused review). File-level `skim`/`skimReason` collapse the whole file;
+    // `skimBlocks` are new-side line spans. This is SHAPE validation only — whether a span
+    // actually resolves to a change block is diff-aware and checked later (resolveSkim in
+    // state.ts), because validateGuide is pure (no diff in hand).
+    if (f.skim === true) file.skim = true;
+    if (typeof f.skimReason === "string" && f.skimReason.trim()) file.skimReason = f.skimReason;
+    if (f.skimBlocks !== undefined) {
+      if (!Array.isArray(f.skimBlocks))
+        return { ok: false, reason: `guide.files[${i}].skimBlocks must be an array` };
+      const blocks: NonNullable<GuideFile["skimBlocks"]> = [];
+      for (let j = 0; j < f.skimBlocks.length; j++) {
+        const rawBlock = f.skimBlocks[j] as Record<string, unknown> | null | undefined;
+        if (!rawBlock || typeof rawBlock !== "object")
+          return { ok: false, reason: `guide.files[${i}].skimBlocks[${j}] must be an object` };
+        // `lines` is a [start, end] span or a bare number (a single line, normalized to [n, n]).
+        const raw = rawBlock.lines;
+        let span: [number, number] | null = null;
+        if (typeof raw === "number" && Number.isFinite(raw)) span = [raw, raw];
+        else if (
+          Array.isArray(raw) &&
+          raw.length === 2 &&
+          typeof raw[0] === "number" &&
+          typeof raw[1] === "number" &&
+          Number.isFinite(raw[0]) &&
+          Number.isFinite(raw[1])
+        )
+          span = raw[0] <= raw[1] ? [raw[0], raw[1]] : [raw[1], raw[0]];
+        if (!span)
+          return {
+            ok: false,
+            reason: `guide.files[${i}].skimBlocks[${j}].lines must be a line number or a [start, end] pair`,
+          };
+        const block: { lines: [number, number]; reason?: string } = { lines: span };
+        if (typeof rawBlock.reason === "string" && rawBlock.reason.trim())
+          block.reason = rawBlock.reason;
+        blocks.push(block);
+      }
+      if (blocks.length) file.skimBlocks = blocks;
+    }
     files.push(file);
   }
   files.sort((a, b) => a.order - b.order);

src/server.ts

@@ -20,6 +20,7 @@ import {
   persistReview,
   questionPayload,
   readGlobalSettings,
+  resolveSkim,
   syncGitState,
   writeGlobalSettings,
 } from "./state.js";
@@ -441,10 +442,27 @@ export async function startServer(options: ServerOptions): Promise<ServerHandle>
           await persistReview(state);
           return json(res, 200, { ok: true, empty: true, baseDiffHash: state.baseDiffHash });
         }
-        Object.assign(state, mergeReviewState(base, state));
-        // The merge carries the old guide forward; a provided guide replaces it,
-        // stamped against the just-rebuilt diff so it isn't born stale.
-        if (validatedGuide) state.guide = { ...validatedGuide, baseDiffHash: state.baseDiffHash };
+        // The merge carries the old guide forward; a provided guide replaces it, stamped
+        // against the just-rebuilt diff so it isn't born stale. Resolve skim spans + reject a
+        // bad NEW guide (strict) BEFORE committing the merge onto the live state, so a rejected
+        // reload leaves the desk untouched. A guide carried forward re-resolves leniently —
+        // stale spans drop, they never fail a reload (see resolveSkim's strict/lenient split).
+        const merged = mergeReviewState(base, state);
+        if (validatedGuide) {
+          merged.guide = { ...validatedGuide, baseDiffHash: merged.baseDiffHash };
+          const skim = resolveSkim(merged.rawDiff, merged.changes, merged.guide, { strict: true });
+          if (!skim.ok)
+            return fail(
+              res,
+              422,
+              "INVALID_GUIDE",
+              `Invalid guide: ${skim.reason}.`,
+              "Run `galley spec` for the guided-review schema.",
+            );
+        } else if (merged.guide) {
+          resolveSkim(merged.rawDiff, merged.changes, merged.guide, { strict: false });
+        }
+        Object.assign(state, merged);
         await syncGitState(state);
         await persistReview(state);
         return json(res, 200, { ok: true, empty: false, baseDiffHash: state.baseDiffHash });

src/spec.test.ts

@@ -38,6 +38,14 @@ const ANCHORS = [
   "files (required, non-empty array)",
   "repo-relative; must be a file in the diff",
   "Orientation, not a changelog",
+  // skimmable review (issue 06) — the fields and the "only on request / opposite of flag" rule
+  "skimBlocks?",
+  "new-file-side [start, end] span",
+  "Skim LOWERS attention",
+  "When to skim",
+  // fully-skimmed files leave the flow (issue 07)
+  "drops into a collapsed",
+  "genuinely needs no eyes",
   // the rest of the operational contract
   "reload vs restart",
   "desk.lock",

src/spec.ts

@@ -143,9 +143,27 @@ One JSON object:
     label repeated non-adjacently makes a second section — keep a category's files together.
   - flag? — raises a flag on the file for closer scrutiny; the text is the note (what to
     double-check, what's risky). Omit unless the file genuinely warrants it.
+  - skim? / skimReason? — mark the WHOLE file skimmable: the desk collapses its diff behind a
+    one-click "expand" strip and shows a muted indicator in the tree/walkthrough. skimReason is a
+    short why ("generated", "lockfile churn"). The reviewer can always expand — nothing is hidden.
+  - skimBlocks? — collapse PARTS of the file: an array of { lines, reason? } where lines is a
+    new-file-side [start, end] span (or a single line number) of the diff you read. The server
+    resolves each span to the enclosing change block(s) and collapses them behind an expandable
+    strip. reason is a short label ("import-only"). A span that resolves to no change block aborts
+    the launch (see Validation).
+  When to skim: ONLY when the reviewer asked for a focused review ("ignore the import churn, show
+  me the real changes"). Skim LOWERS attention — it is the opposite of flag, which raises it. Never
+  skim your own risky or non-obvious changes to slip them past review; skim boilerplate the
+  reviewer told you they don't want to see. A file skimmed whole (or every block skimmed) leaves
+  the reviewer's default flow entirely — it drops into a collapsed "Skimmed" group and carries no
+  progress or completion weight — so skim only what genuinely needs no eyes. On reload, skimBlocks
+  re-resolve against the new diff; a span that no longer resolves is dropped (a block you rewrote
+  deserves fresh attention).
 Validation: overview a non-empty string, files a non-empty array, every file a non-empty
-path+orientation; an unreadable file / invalid JSON / schema violation aborts the launch naming
-the offending field.
+path+orientation; skimBlocks (if present) an array of { lines: number | [start, end], reason? };
+an unreadable file / invalid JSON / schema violation — or a skimBlocks span that matches no change
+block in the file (or names a file absent from the diff) — aborts the launch naming the offending
+field.
 
 ## Between rounds — reload vs restart, and the desk lock
 - Don't edit tracked files mid-round: the reviewer wouldn't see the edits and their in-flight