refactor!: reframe guide file fields as orientation + flag (#18)

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

Author: ymansurozer

README.md

@@ -56,7 +56,7 @@ I'm not saying this is *the* review surface. I built it in a week and I'm still
 - **Per-line comment threads.** Comment on any line. Ask a question and your agent answers live in the thread; leave a change request and it rides to the handoff.
 - **Per-change accept/reject.** Accept or reject individual changes, or sign off a whole file.
 - **A tight handoff loop.** Hit **Send to Agent** and your agent gets a structured review. It makes the edits, re-diffs into the same tab, and replies in place.
-- **Guided review.** Your agent can attach a guide: an overview, the files in a sensible order, a per-file summary and category, and the risky ones flagged.
+- **Guided review.** Your agent can attach a guide: an overview, the files in a sensible order, a per-file orientation (the lens to read it with) and category, and the risky ones flagged.
 - **Four review modes.** The working tree, the staged diff, a single file (tracked or not, like a plan, PRD, or issue), or a branch against its merge-base.
 - **Keyboard-first.** Intuitive navigation: move by file, line, or change, and accept, reject, comment, or approve without touching the mouse.
 - **Open in editor.** Configure a repo-scoped editor command and jump from the review desk to the current file and line.

src/cli.ts

@@ -268,7 +268,7 @@ function loadGuideArg(value: string | boolean | undefined) {
     return null;
   }
   const SCHEMA =
-    "Expected JSON: { overview, prDescription?, files: [{ path, order, category, summary, critical?, why? }] }.";
+    "Expected JSON: { overview, prDescription?, files: [{ path, order, category, orientation, flag? }] }.";
   let parsed: unknown;
   try {
     parsed = JSON.parse(readFileSync(value, "utf8"));

src/guide.test.ts

@@ -13,11 +13,10 @@ const validInput = () => ({
       path: "src/middleware/rateLimit.ts",
       order: 2,
       category: "Core",
-      summary: "The limiter.",
-      critical: true,
-      why: "reject path",
+      orientation: "The limiter.",
+      flag: "reject path",
     },
-    { path: "src/config/limits.ts", order: 1, category: "Config", summary: "Constants." },
+    { path: "src/config/limits.ts", order: 1, category: "Config", orientation: "Constants." },
   ],
 });
 
@@ -32,30 +31,29 @@ test("validateGuide accepts a well-formed guide and sorts files by order", () =>
     r.guide.files.map((f) => f.path),
     ["src/config/limits.ts", "src/middleware/rateLimit.ts"],
   );
-  assert.equal(r.guide.files[1]!.critical, true);
-  assert.equal(r.guide.files[1]!.why, "reject path");
+  assert.equal(r.guide.files[1]!.flag, "reject path");
 });
 
 test("validateGuide defaults missing order (by position) and category", () => {
-  const r = validateGuide({ overview: "x", files: [{ path: "a.ts", summary: "s" }] });
+  const r = validateGuide({ overview: "x", files: [{ path: "a.ts", orientation: "s" }] });
   assert.ok(r.ok);
   if (!r.ok) return;
   assert.equal(r.guide.files[0]!.order, 0);
   assert.equal(r.guide.files[0]!.category, "Changes");
-  assert.equal(r.guide.files[0]!.critical, undefined);
+  assert.equal(r.guide.files[0]!.flag, undefined);
 });
 
 test("validateGuide rejects malformed input", () => {
   const cases: unknown[] = [
     null,
     "nope",
-    { files: [{ path: "a", summary: "s" }] }, // missing overview
-    { overview: "  ", files: [{ path: "a", summary: "s" }] }, // blank overview
+    { files: [{ path: "a", orientation: "s" }] }, // missing overview
+    { overview: "  ", files: [{ path: "a", orientation: "s" }] }, // blank overview
     { overview: "x" }, // missing files
     { overview: "x", files: "no" }, // files not array
     { overview: "x", files: [] }, // empty files
-    { overview: "x", files: [{ summary: "s" }] }, // entry missing path
-    { overview: "x", files: [{ path: "a" }] }, // entry missing summary
+    { overview: "x", files: [{ orientation: "s" }] }, // entry missing path
+    { overview: "x", files: [{ path: "a" }] }, // entry missing orientation
   ];
   for (const input of cases) assert.equal(validateGuide(input).ok, false, JSON.stringify(input));
 });
@@ -85,7 +83,7 @@ function state(over: Partial<ReviewState>): ReviewState {
 test("mergeReviewState carries an attached guide across a reload", () => {
   const guide: Guide = {
     overview: "o",
-    files: [{ path: "a.ts", order: 0, category: "Config", summary: "s" }],
+    files: [{ path: "a.ts", order: 0, category: "Config", orientation: "s" }],
   };
   const base = state({ baseDiffHash: "new" }); // freshly rebuilt diff — no guide
   const saved = state({ guide }); // live state with the attached guide

src/guide.ts

@@ -3,10 +3,11 @@ import type { Guide, GuideFile } from "./types.js";
 export type GuideValidation = { ok: true; guide: Guide } | { ok: false; reason: string };
 
 // Validate + normalize an agent-supplied guide. Required: a non-empty `overview` and a
-// non-empty `files` array whose every entry has a `path` and a `summary`. `order` and
-// `category` are optional (default to the entry's position / "Changes"); `critical`/`why`
-// are optional flags. Returns the normalized guide with files sorted by `order`, or a
-// reason the input was rejected. Pure — no IO — so it's the same check on the server and CLI.
+// non-empty `files` array whose every entry has a `path` and an `orientation`. `order` and
+// `category` are optional (default to the entry's position / "Changes"); `flag` is an
+// optional note whose presence raises the file's flag. Returns the normalized guide with
+// files sorted by `order`, or a reason the input was rejected. Pure — no IO — so it's the
+// same check on the server and CLI.
 export function validateGuide(input: unknown): GuideValidation {
   if (!input || typeof input !== "object") return { ok: false, reason: "guide must be an object" };
   const g = input as Record<string, unknown>;
@@ -22,16 +23,15 @@ export function validateGuide(input: unknown): GuideValidation {
     const f = raw as Record<string, unknown>;
     if (typeof f.path !== "string" || !f.path.trim())
       return { ok: false, reason: `guide.files[${i}].path must be a non-empty string` };
-    if (typeof f.summary !== "string" || !f.summary.trim())
-      return { ok: false, reason: `guide.files[${i}].summary must be a non-empty string` };
+    if (typeof f.orientation !== "string" || !f.orientation.trim())
+      return { ok: false, reason: `guide.files[${i}].orientation must be a non-empty string` };
     const file: GuideFile = {
       path: f.path,
       order: typeof f.order === "number" && Number.isFinite(f.order) ? f.order : i,
       category: typeof f.category === "string" && f.category.trim() ? f.category : "Changes",
-      summary: f.summary,
+      orientation: f.orientation,
     };
-    if (f.critical === true) file.critical = true;
-    if (typeof f.why === "string" && f.why.trim()) file.why = f.why;
+    if (typeof f.flag === "string" && f.flag.trim()) file.flag = f.flag;
     files.push(file);
   }
   files.sort((a, b) => a.order - b.order);

src/spec.test.ts

@@ -28,7 +28,7 @@ const ANCHORS = [
   "one-paragraph changeset overview",
   "files (required, non-empty array)",
   "repo-relative; must be a file in the diff",
-  "shown in the file's diff header",
+  "Orientation, not a changelog",
   // the rest of the operational contract
   "reload vs restart",
   "desk.lock",

src/spec.ts

@@ -99,7 +99,7 @@ Then \`galley reload\` to surface your edits, and \`galley await\` for the next
 
 ## Guided review (optional)
 Attach with \`galley <mode> --guide <file>\`: an overview page + files in your order, each with
-summary/category, critical ones flagged. Galley validates+renders it (markdown in prose fields,
+orientation/category, files worth scrutinizing flagged. Galley validates+renders it (markdown in prose fields,
 raw HTML stripped) and runs no model — content and order are yours. Write the guide OUTSIDE the
 working tree (a temp or gitignored path): working mode surfaces untracked files, so an in-repo
 guide shows as a stray addition. The guide is stamped to its diff and survives reload/restart;
@@ -114,14 +114,17 @@ One JSON object:
 - prDescription? — author/PR intent, shown on the overview page.
 - files (required, non-empty array) — one entry per reviewed file:
   - path (required, non-empty) — repo-relative; must be a file in the diff.
-  - summary (required, non-empty) — shown in the file's diff header.
+  - orientation (required, non-empty) — the lens to read this file with: its role, the
+    problem it solves, what to expect before opening it, what's non-obvious or worth
+    scrutinizing. Orientation, not a changelog — the reviewer already sees the diff. Shown
+    in the file's diff header.
   - order? — ascending review order; defaults to array position.
   - category? — group label (default "Changes").
-  - critical? — flags closer review; surfaces \`why\` when true.
-  - why? — shown when critical.
+  - 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.
 Validation: overview a non-empty string, files a non-empty array, every file a non-empty
-path+summary; an unreadable file / invalid JSON / schema violation aborts the launch naming the
-offending field.
+path+orientation; an unreadable file / invalid JSON / schema violation 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

src/types.ts

@@ -105,14 +105,15 @@ export type ReviewMode = "repo" | "file" | "pr";
 
 // A per-file entry in an agent-generated guided review. `order` drives Next/Prev
 // (general → specific); `category` is the stepper grouping (e.g. Config/Core/Wiring,
-// semantic, distinct from the folder); `critical` + `why` drive the flag + "why flagged".
+// semantic, distinct from the folder); `orientation` is the lens to read the file with
+// (role, problem, what to expect — not a changelog); `flag`, when present, raises the
+// flag for closer scrutiny and is its note. (Its presence is the flag — no separate bool.)
 export type GuideFile = {
   path: string;
   order: number;
   category: string;
-  summary: string;
-  critical?: boolean;
-  why?: string;
+  orientation: string;
+  flag?: string;
 };
 
 // The guided review the coding agent attaches (the desk renders it, runs no model).
@@ -162,7 +163,7 @@ export type ReviewState = {
   decisionFiles?: string[];
   // Explicit accept/reject records — the source of truth for decisions.
   decisions?: Decision[];
-  // Agent-generated guided review (overview + per-file summaries/order/category).
+  // Agent-generated guided review (overview + per-file orientation/order/category).
   // Optional: absent → no guide surfaces render.
   guide?: Guide;
   persistFile?: string;

src/ui/guide.ts

@@ -127,8 +127,8 @@ export function guideStale(): boolean {
   );
 }
 
-// One file row in the Overview list: path (dimmed dir, bright basename) + critical flag +
-// ±counts + a read-only review-state badge on top, the guide's one-line summary beneath.
+// One file row in the Overview list: path (dimmed dir, bright basename) + flag icon +
+// ±counts + a read-only review-state badge on top, the guide's orientation beneath.
 // Read-only by design — decisions stay where the diff is visible; clicking opens the file.
 function overviewFileRow(f: WalkFile): string {
   const badge =
@@ -140,10 +140,10 @@ function overviewFileRow(f: WalkFile): string {
   return `<button class="go-file" data-i="${f.fileIndex}">
     <span class="go-file-top">
       <span class="go-file-path"><span class="fdir">${esc(f.dir)}</span><span class="fname">${esc(f.name)}</span></span>
-      ${f.critical ? `<svg class="ic crit" title="Critical"><use href="#gly-flag"></use></svg>` : ""}
+      ${f.flag ? `<svg class="ic crit" title="${esc(f.flag)}"><use href="#gly-flag"></use></svg>` : ""}
       <span class="go-file-stats">${f.added ? `<i class="add">+${f.added}</i>` : ""}${f.removed ? `<i class="del">−${f.removed}</i>` : ""}${badge}</span>
     </span>
-    ${f.summary ? `<span class="go-file-sum">${renderMarkdownInline(f.summary)}</span>` : ""}
+    ${f.orientation ? `<span class="go-file-sum">${renderMarkdownInline(f.orientation)}</span>` : ""}
   </button>`;
 }
 

src/ui/index.html

@@ -665,22 +665,22 @@
       line-height: 1.55
     }
 
-    .ghdr .ghdr-why {
+    .ghdr .ghdr-flag {
       display: flex;
       align-items: flex-start;
       gap: 6px;
       max-width: 74ch;
       color: var(--amber)
     }
 
-    .ghdr .ghdr-why>.ic {
+    .ghdr .ghdr-flag>.ic {
       width: 12px;
       height: 12px;
       margin-top: 3px;
       fill: currentColor
     }
 
-    .ghdr .ghdr-why .md {
+    .ghdr .ghdr-flag .md {
       margin-top: 0;
       color: var(--amber);
       font-size: var(--text-xs);
@@ -2237,7 +2237,7 @@
       margin-top: 0
     }
 
-    /* Overview file list: the guide's files grouped by category, each row path + summary +
+    /* Overview file list: the guide's files grouped by category, each row path + orientation +
        ±counts + a read-only state badge (decisions stay in the diff; clicking opens it). */
     .guide-overview .go-files-h {
       margin: 0 0 7px
@@ -2560,7 +2560,7 @@
               <svg class="ic st approved" x-show="r.kind==='file' && r.state==='approved'" title="Approved"><use href="#gly-check"></use></svg>
               <svg class="ic st changes" x-show="r.kind==='file' && r.state==='changes-requested'" title="Changes requested"><use href="#gly-circle-alert"></use></svg>
               <span class="nm" x-show="r.kind==='file'" x-text="r.name" :title="r.path"></span>
-              <svg class="ic crit" x-show="r.kind==='file' && r.critical" title="Critical"><use href="#gly-flag"></use></svg>
+              <svg class="ic crit" x-show="r.kind==='file' && r.flag" :title="r.flag"><use href="#gly-flag"></use></svg>
               <span class="status-pack">
                 <svg class="ic badge approved" x-show="r.kind==='cat' && r.complete" title="All files reviewed"><use href="#gly-check"></use></svg>
                 <i class="add" x-show="r.kind==='file' && r.added" x-text="'+'+r.added"></i>

src/ui/render.ts

@@ -387,19 +387,19 @@ async function renderCenter() {
       const guide = document.createElement("div");
       guide.className = "ghdr-guide";
       const chip = document.createElement("span");
-      chip.className = "ghdr-cat" + (entry.critical ? " crit" : "");
+      chip.className = "ghdr-cat" + (entry.flag ? " crit" : "");
       chip.textContent = entry.category;
       guide.appendChild(chip);
       const expl = document.createElement("div");
       expl.className = "ghdr-expl md";
-      expl.innerHTML = renderMarkdown(entry.summary);
+      expl.innerHTML = renderMarkdown(entry.orientation);
       guide.appendChild(expl);
-      // Critical "why" gets its own readable callout within the card.
-      if (entry.critical && entry.why) {
-        const why = document.createElement("div");
-        why.className = "ghdr-why";
-        why.innerHTML = `<svg class="ic"><use href="#gly-flag"></use></svg><div class="md">${renderMarkdown(entry.why)}</div>`;
-        guide.appendChild(why);
+      // A flagged file gets its own readable callout within the card.
+      if (entry.flag) {
+        const flag = document.createElement("div");
+        flag.className = "ghdr-flag";
+        flag.innerHTML = `<svg class="ic"><use href="#gly-flag"></use></svg><div class="md">${renderMarkdown(entry.flag)}</div>`;
+        guide.appendChild(flag);
       }
       wrap.appendChild(guide);
     }