claude-plan-review 0.1.1 → 0.3.0

package/README.md

@@ -8,7 +8,10 @@ When Claude finishes a plan in **plan mode**, a `PreToolUse` hook on the
 `ExitPlanMode` tool intercepts it, opens the plan in your browser, and **blocks**
 until you decide:
 
-- **Approve** → Claude exits plan mode and starts implementing.
+- **Approve** → Claude exits plan mode and starts implementing **immediately** —
+  no need to switch back to the terminal and confirm. (If you leave any comments
+  before approving, they ride along as guidance for Claude to incorporate while
+  implementing — "approve with comments".)
 - **Request changes** → your line + general comments are sent back as the denial
   reason; Claude stays in plan mode and revises, producing a new version.
 
@@ -24,6 +27,9 @@ Git worktrees are scoped separately automatically.
 - 🔀 **Diff** current vs any previous version — **side-by-side or unified** (toggle)
 - ✅ **Approve / request-changes** straight from the UI, fed back to Claude
 - 🗂 Per-worktree scoping; per-project opt-in (only runs where you enable the hook)
+- 📤 **Save a plan to a storage channel** — push the plan markdown to a secret
+  **GitHub Gist** (one gist per project, overwritten on each save; GitHub keeps
+  the gist's revision history). More channels can be added later.
 - ⚡ Tiny, zero-framework UI; Bun server; one dependency (`marked`)
 
 ## Requirements
@@ -32,6 +38,9 @@ Git worktrees are scoped separately automatically.
   tool is plain ESM JavaScript and runs unchanged on both. `init` auto-detects which
   you have (preferring Bun) and writes the matching hook command; override with `--runtime`.
 - Claude Code ≥ 2.1 (verified against 2.1.185)
+- *(Optional, only for saving to a Gist)* the [GitHub CLI](https://cli.github.com)
+  `gh`, logged in (`gh auth login`) with the `gist` scope. The tool reuses your
+  existing `gh` session — it never asks for or stores a token of its own.
 
 ## Setup
 
@@ -54,7 +63,7 @@ any machine — nothing to keep in your repo but the one settings entry.
 ### Option B — from a local clone (for hacking on it)
 
 ```bash
-git clone https://github.com/pavlo-petrychenko/claude-plan-preview-local
+git clone https://github.com/pavlo-petrychenko/claude-plan-review
 cd claude-plan-review
 bun install                                  # or: npm install
 bun  src/cli.js init /path/to/your/project   # …or…
@@ -88,6 +97,7 @@ Use `bun` or `node` interchangeably (or `bunx`/`npx claude-plan-review …` when
 | `… cli.js init [dir] [--local] [--published] [--runtime bun\|node]` | Wire the `ExitPlanMode` hook into a project |
 | `… cli.js serve [port]` | Start the review server manually (default `4607`) |
 | `… cli.js stop` | Stop the running server |
+| `… cli.js channels` | Show storage-channel readiness (is `gh` installed / authed / `gist`-scoped?) |
 
 The server auto-starts on the first plan and stays up, so you can browse history
 anytime at `http://localhost:4607`.
@@ -102,6 +112,28 @@ anytime at `http://localhost:4607`.
 
 > The hook entry sets `timeout: 1800` so Claude Code waits while you review.
 
+## Storage channels (save a plan out of the local store)
+
+Each plan version lives only on your machine by default. A **storage channel**
+lets you push the plan markdown somewhere shareable. Today there's one channel —
+**GitHub Gist** — and the registry is built so more can be added later.
+
+Click **Save to gist** in the header. The first save asks for a description and
+file name and creates a **secret** (unlisted) gist from the version you're
+viewing. There's **one gist per project**: saving any later version overwrites
+that same gist (GitHub keeps the gist's own revision history), and you can rename
+the description/file name on any save. The header then shows a link to the gist
+and which version it currently holds.
+
+Auth is delegated entirely to the GitHub CLI — if you've run `gh auth login`,
+nothing else is needed and **no token is ever stored by this tool**. If `gh`
+isn't installed, isn't logged in, or its token lacks the `gist` scope, the save
+dialog tells you the exact command to fix it (e.g. `gh auth refresh -s gist`).
+Run `claude-plan-review channels` to check readiness from the terminal.
+
+> Note: the Gist API requires a **classic** `gh` token scope (`gist`);
+> fine-grained tokens don't support gists. `gh auth login` handles this for you.
+
 ## How it works
 
 ```
@@ -111,8 +143,10 @@ Claude finishes plan ──> PreToolUse hook (ExitPlanMode)
                           │  ensures the server is up, opens the browser
                           │  BLOCKS, polling for your decision
    browser (you) ─────────┘
-     approve  ──> hook emits {permissionDecision:"allow"}            ──> Claude implements
-     request  ──> hook emits {permissionDecision:"deny", reason:...} ──> Claude revises (new version)
+     approve  ──> hook emits {permissionDecision:"allow", updatedInput, additionalContext?} ──> Claude implements
+                  (updatedInput is what skips the native "Exit plan mode?" prompt;
+                   additionalContext carries any comments as "approve with comments")
+     request  ──> hook emits {permissionDecision:"deny", reason:...}                        ──> Claude revises (new version)
 ```
 
 ## Storage layout

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "claude-plan-review",
-  "version": "0.1.1",
+  "version": "0.3.0",
   "description": "Review, comment on, and approve/reject Claude Code plans in a local GitHub-style web UI — with persistent comments, version history, and diffs.",
   "type": "module",
   "bin": {
@@ -32,13 +32,13 @@
     "hooks",
     "exitplanmode"
   ],
-  "homepage": "https://github.com/pavlo-petrychenko/claude-plan-preview-local#readme",
+  "homepage": "https://github.com/pavlo-petrychenko/claude-plan-review#readme",
   "repository": {
     "type": "git",
-    "url": "git+https://github.com/pavlo-petrychenko/claude-plan-preview-local.git"
+    "url": "git+https://github.com/pavlo-petrychenko/claude-plan-review.git"
   },
   "bugs": {
-    "url": "https://github.com/pavlo-petrychenko/claude-plan-preview-local/issues"
+    "url": "https://github.com/pavlo-petrychenko/claude-plan-review/issues"
   },
   "author": "pavlo.p@mate.academy",
   "license": "MIT"

package/src/channels/gh.js

@@ -0,0 +1,84 @@
+/**
+ * Thin wrapper around the GitHub CLI (`gh`). Runs on Bun or Node ≥18.
+ *
+ * We shell out to `gh` rather than holding our own token: if the user has
+ * already `gh auth login`'d, we store no secrets at all. All request bodies are
+ * piped via STDIN (never argv), so plan content / descriptions can't break
+ * argument parsing.
+ */
+import { spawnSync } from "node:child_process";
+
+function run(args, { input } = {}) {
+  try {
+    const r = spawnSync("gh", args, {
+      input: input ?? undefined,
+      encoding: "utf8",
+      // gh writes `auth status` to stderr; capture both streams.
+    });
+    return {
+      ok: r.status === 0,
+      status: r.status,
+      stdout: r.stdout || "",
+      stderr: r.stderr || "",
+      spawnError: r.error || null,
+    };
+  } catch (e) {
+    return { ok: false, status: null, stdout: "", stderr: "", spawnError: e };
+  }
+}
+
+/** Is `gh` on PATH at all? */
+export function installed() {
+  return run(["--version"]).ok;
+}
+
+/**
+ * Readiness probe: { installed, authed, scopes:[...] }.
+ * `gh auth status` exits non-zero when not logged in; its human output (on
+ * stderr) carries a "Token scopes: 'gist', 'repo', …" line we parse.
+ */
+export function status() {
+  if (!installed()) return { installed: false, authed: false, scopes: [] };
+  const r = run(["auth", "status"]);
+  const text = `${r.stdout}\n${r.stderr}`;
+  const authed = r.ok || /Logged in to/i.test(text);
+  let scopes = [];
+  const m = text.match(/Token scopes:\s*(.+)/i);
+  if (m) {
+    scopes = m[1]
+      .split(",")
+      .map((s) => s.trim().replace(/^['"]|['"]$/g, ""))
+      .filter(Boolean);
+  }
+  return { installed: true, authed, scopes };
+}
+
+/**
+ * Call the GitHub REST API through gh, sending `body` as JSON on stdin.
+ * Returns { ok, data, error, needsGistScope }.
+ */
+export function api(method, path, body) {
+  const args = ["api", "-X", method.toUpperCase(), path];
+  let input;
+  if (body !== undefined) {
+    args.push("--input", "-");
+    input = JSON.stringify(body);
+  }
+  const r = run(args, { input });
+  if (r.ok) {
+    try {
+      return { ok: true, data: JSON.parse(r.stdout || "null") };
+    } catch {
+      return { ok: true, data: null };
+    }
+  }
+  const errText = `${r.stderr}${r.stdout}`.trim();
+  // gh surfaces a "(HTTP 404)"/"(HTTP 403)" + scope hint when the token can't touch gists
+  const needsGistScope =
+    /gist/i.test(errText) && /(scope|HTTP 40[34]|Not Found|requires)/i.test(errText);
+  return {
+    ok: false,
+    error: errText || (r.spawnError ? String(r.spawnError.message || r.spawnError) : "gh failed"),
+    needsGistScope,
+  };
+}

package/src/channels/gist.js

@@ -0,0 +1,97 @@
+/**
+ * GitHub Gist storage channel. Stores the plan markdown (only) in a secret
+ * gist owned by the user's `gh`-authenticated account. One gist per project:
+ * the first save creates it, later saves PATCH the same gist (GitHub keeps the
+ * gist's own revision history automatically).
+ */
+import * as gh from "./gh.js";
+
+export const id = "gist";
+export const label = "GitHub Gist";
+
+const REFRESH_CMD = "gh auth refresh -s gist";
+const LOGIN_CMD = "gh auth login";
+
+/** Readiness for the UI: can we create a gist right now, and if not, how to fix it. */
+export function available() {
+  const s = gh.status();
+  if (!s.installed)
+    return {
+      ready: false,
+      installed: false,
+      authed: false,
+      hasGistScope: false,
+      reason: "GitHub CLI (gh) is not installed.",
+      fixCommand: null,
+      fixUrl: "https://cli.github.com",
+    };
+  if (!s.authed)
+    return {
+      ready: false,
+      installed: true,
+      authed: false,
+      hasGistScope: false,
+      reason: "Not logged in to GitHub.",
+      fixCommand: LOGIN_CMD,
+    };
+  const hasGistScope = s.scopes.includes("gist");
+  return {
+    ready: hasGistScope,
+    installed: true,
+    authed: true,
+    hasGistScope,
+    reason: hasGistScope ? null : "Your gh token is missing the 'gist' scope.",
+    fixCommand: hasGistScope ? null : REFRESH_CMD,
+    scopes: s.scopes,
+  };
+}
+
+function ghError(res) {
+  const e = new Error(
+    res.needsGistScope
+      ? `GitHub rejected the gist write — your gh token likely lacks the 'gist' scope. Run: ${REFRESH_CMD}`
+      : res.error || "gh request failed",
+  );
+  e.fixCommand = res.needsGistScope ? REFRESH_CMD : null;
+  return e;
+}
+
+/** Create a new secret gist. Returns the binding info we persist. */
+export function create({ markdown, description, filename }) {
+  const file = filename || "plan.md";
+  const res = gh.api("POST", "/gists", {
+    description: description || "",
+    public: false,
+    files: { [file]: { content: markdown || "\n" } },
+  });
+  if (!res.ok) throw ghError(res);
+  return {
+    id: res.data.id,
+    htmlUrl: res.data.html_url,
+    filename: file,
+    description: description || "",
+  };
+}
+
+/**
+ * Overwrite an existing gist with new content (and optionally a new
+ * description / filename). `oldFilename` is the name currently in the gist so
+ * we can rename rather than orphan it.
+ */
+export function update({ id: gistId, markdown, description, filename, oldFilename }) {
+  const newName = filename || oldFilename || "plan.md";
+  const fileKey = oldFilename || newName;
+  const filePatch = { content: markdown || "\n" };
+  if (newName !== fileKey) filePatch.filename = newName;
+  const res = gh.api("PATCH", `/gists/${gistId}`, {
+    description: description ?? "",
+    files: { [fileKey]: filePatch },
+  });
+  if (!res.ok) throw ghError(res);
+  return {
+    id: res.data.id,
+    htmlUrl: res.data.html_url,
+    filename: newName,
+    description: res.data.description ?? description ?? "",
+  };
+}

package/src/channels/index.js

@@ -0,0 +1,24 @@
+/**
+ * Storage-channel registry. A channel lets the user push a plan out of the
+ * local store into some shareable location. Gist is the only channel today;
+ * the registry keeps adding more (S3, Drive, …) a matter of dropping in a
+ * module with the same shape.
+ *
+ * Channel contract:
+ *   id, label                         — identity
+ *   available() → { ready, ...flags } — can we use it now, and how to fix it
+ *   create({markdown, description, filename})              → binding info
+ *   update({id, markdown, description, filename, oldFilename}) → binding info
+ */
+import * as gist from "./gist.js";
+
+export const channels = { [gist.id]: gist };
+
+export function getChannel(id) {
+  return channels[id] || null;
+}
+
+/** Readiness of every channel, for the picker / verify UI. */
+export function listChannelStatus() {
+  return Object.values(channels).map((ch) => ({ id: ch.id, label: ch.label, ...ch.available() }));
+}

package/src/cli.js

@@ -102,6 +102,27 @@ async function cmdServe(args) {
   console.log(`Open http://localhost:${port}  (Ctrl+C to stop)`);
 }
 
+async function cmdChannels() {
+  const { listChannelStatus } = await import("./channels/index.js");
+  const list = listChannelStatus();
+  if (!list.length) {
+    console.log("No storage channels registered.");
+    return;
+  }
+  console.log("Storage channels:\n");
+  for (const c of list) {
+    const mark = c.ready ? "✓" : "✗";
+    console.log(`  ${mark} ${c.label} (${c.id})`);
+    if (!c.ready) {
+      if (c.reason) console.log(`      ${c.reason}`);
+      if (c.fixCommand) console.log(`      fix: ${c.fixCommand}`);
+      else if (c.fixUrl) console.log(`      see: ${c.fixUrl}`);
+    } else if (c.scopes) {
+      console.log(`      gh scopes: ${c.scopes.join(", ")}`);
+    }
+  }
+}
+
 function cmdStop() {
   const info = readJSON(SERVER_FILE, null);
   if (!info?.pid) {
@@ -130,6 +151,7 @@ Usage:
                                   --runtime    → force a runtime
   claude-plan-review serve [port] Start the review server (default ${DEFAULT_PORT})
   claude-plan-review stop         Stop the running server
+  claude-plan-review channels     Show storage-channel readiness (e.g. gh / gist)
   claude-plan-review hook         (internal) the PreToolUse hook entry
 `);
 }
@@ -145,6 +167,9 @@ switch (sub) {
   case "stop":
     cmdStop();
     break;
+  case "channels":
+    await cmdChannels();
+    break;
   case "hook":
     await import("./hook.js");
     break;

package/src/hook.js

@@ -23,17 +23,48 @@ const POLL_MS = 700;
 
 const sleep = (ms) => new Promise((r) => setTimeout(r, ms));
 
-function out(decision, reason, sys) {
-  process.stdout.write(
-    JSON.stringify({
-      hookSpecificOutput: {
-        hookEventName: "PreToolUse",
-        permissionDecision: decision,
-        permissionDecisionReason: reason,
-      },
-      systemMessage: sys,
-    }),
-  );
+function emit(payload) {
+  process.stdout.write(JSON.stringify(payload));
+}
+
+/**
+ * Approve and auto-proceed WITHOUT the terminal "Exit plan mode?" keypress.
+ *
+ * ExitPlanMode reports requiresUserInteraction()=true, so a bare allow falls
+ * through to the native prompt. The permission combiner only bypasses the
+ * prompt when the hook ALSO returns `updatedInput` (it treats that as "the hook
+ * already satisfied the user interaction"). So we echo the original tool input
+ * back. `additionalContext`, when present, carries the reviewer's notes into
+ * Claude's context — i.e. "approve with comments".
+ * (Verified against the Claude Code 2.1.185 binary.)
+ */
+function allow(toolInput, notes) {
+  const hookSpecificOutput = {
+    hookEventName: "PreToolUse",
+    permissionDecision: "allow",
+    permissionDecisionReason: notes
+      ? "Approved with comments in the plan-review UI."
+      : "Approved in the plan-review UI.",
+    updatedInput: toolInput, // REQUIRED to skip the native approval prompt
+  };
+  if (notes) hookSpecificOutput.additionalContext = notes;
+  emit({
+    hookSpecificOutput,
+    systemMessage: notes
+      ? "✅ Plan approved with comments via plan-review"
+      : "✅ Plan approved via plan-review",
+  });
+}
+
+function deny(reason) {
+  emit({
+    hookSpecificOutput: {
+      hookEventName: "PreToolUse",
+      permissionDecision: "deny",
+      permissionDecisionReason: reason,
+    },
+    systemMessage: "📝 Changes requested via plan-review",
+  });
 }
 
 function serverPort() {
@@ -92,7 +123,8 @@ async function main() {
 
   if (input.tool_name !== "ExitPlanMode") process.exit(0);
 
-  const plan = input.tool_input?.plan ?? "";
+  const toolInput = input.tool_input ?? {};
+  const plan = toolInput.plan ?? "";
   if (!plan.trim()) process.exit(0);
 
   const { key, version, reviewId } = recordPlan({
@@ -114,15 +146,11 @@ async function main() {
   while (Date.now() < deadline) {
     const review = getReview(reviewId);
     if (review && review.status === "approved") {
-      out("allow", "Approved in the plan-review UI.", "✅ Plan approved via plan-review");
+      allow(toolInput, review.notes);
       process.exit(0);
     }
     if (review && review.status === "rejected") {
-      out(
-        "deny",
-        review.reason || "Changes requested in the plan-review UI.",
-        "📝 Changes requested via plan-review",
-      );
+      deny(review.reason || "Changes requested in the plan-review UI.");
       process.exit(0);
     }
     await sleep(POLL_MS);

package/src/server.js

@@ -9,6 +9,7 @@ import {
   deleteComment,
   getProjectMeta,
   getReview,
+  getStorage,
   getVersion,
   listComments,
   listProjects,
@@ -16,7 +17,9 @@ import {
   listVersions,
   pruneResolvedReviews,
   resolveReview,
+  setStorage,
 } from "./store.js";
+import { getChannel, listChannelStatus } from "./channels/index.js";
 
 const HERE = dirname(fileURLToPath(import.meta.url));
 const UI_DIR = join(HERE, "ui");
@@ -115,6 +118,7 @@ async function handleApi(req, res, seg, url) {
 
   if (a === "health") return sendJSON(res, { ok: true });
   if (a === "version") return sendJSON(res, { version: pkg.version });
+  if (a === "channels" && !b) return sendJSON(res, listChannelStatus());
 
   if (a === "projects" && !b) return sendJSON(res, listProjects());
 
@@ -134,6 +138,11 @@ async function handleApi(req, res, seg, url) {
     });
   }
 
+  // /api/projects/:key/storage  → current channel bindings
+  if (a === "projects" && b && c === "storage" && !d) {
+    return sendJSON(res, getStorage(b));
+  }
+
   // /api/projects/:key/versions/:n ...
   if (a === "projects" && b && c === "versions" && d) {
     const key = b;
@@ -162,6 +171,10 @@ async function handleApi(req, res, seg, url) {
     if (e === "comments" && seg[5] && method === "DELETE") {
       return sendJSON(res, { ok: deleteComment(key, n, seg[5]) });
     }
+    // /api/projects/:key/versions/:n/save  (POST) → push this version to a storage channel
+    if (e === "save" && method === "POST") {
+      return await handleSave(req, res, key, n);
+    }
   }
 
   // /api/reviews ...
@@ -181,6 +194,47 @@ async function handleApi(req, res, seg, url) {
   return sendJSON(res, { error: "unknown endpoint" }, 404);
 }
 
+/** POST /api/projects/:key/versions/:n/save — create or overwrite the channel's store. */
+async function handleSave(req, res, key, n) {
+  const body = JSON.parse((await readBody(req)) || "{}");
+  const channelId = body.channel || "gist";
+  const channel = getChannel(channelId);
+  if (!channel) return sendJSON(res, { error: `unknown channel: ${channelId}` }, 400);
+
+  const v = getVersion(key, n);
+  if (!v) return sendJSON(res, { error: "no such version" }, 404);
+
+  const ready = channel.available();
+  if (!ready.ready) {
+    return sendJSON(
+      res,
+      { error: ready.reason || "channel not ready", fixCommand: ready.fixCommand ?? null },
+      409,
+    );
+  }
+
+  const existing = getStorage(key)[channelId];
+  try {
+    const info = existing?.id
+      ? channel.update({
+          id: existing.id,
+          markdown: v.markdown,
+          description: body.description ?? existing.description ?? "",
+          filename: body.filename ?? existing.filename,
+          oldFilename: existing.filename,
+        })
+      : channel.create({
+          markdown: v.markdown,
+          description: body.description ?? "",
+          filename: body.filename,
+        });
+    const saved = setStorage(key, channelId, { ...info, savedVersion: n });
+    return sendJSON(res, { channel: channelId, savedVersion: n, ...saved });
+  } catch (e) {
+    return sendJSON(res, { error: String(e?.message || e), fixCommand: e?.fixCommand ?? null }, 502);
+  }
+}
+
 // run directly: `node src/server.js [port]` (or bun)
 const invokedDirectly =
   process.argv[1] && realpathSync(process.argv[1]) === realpathSync(fileURLToPath(import.meta.url));

package/src/store.js

@@ -42,6 +42,23 @@ export function getProjectMeta(key) {
   return existsSync(metaPath(key)) ? readJSON(metaPath(key), null) : null;
 }
 
+// ---------- storage-channel bindings ----------
+/** All channel bindings for a project, e.g. { gist: { id, htmlUrl, … } }. */
+export function getStorage(key) {
+  return getProjectMeta(key)?.storage ?? {};
+}
+
+/** Persist (or update) the binding for one channel on a project. */
+export function setStorage(key, channelId, info) {
+  const meta = getProjectMeta(key);
+  if (!meta) return null;
+  meta.storage ??= {};
+  meta.storage[channelId] = { ...meta.storage[channelId], ...info, savedAt: now() };
+  meta.updatedAt = now();
+  writeFileSync(metaPath(key), enc(meta));
+  return meta.storage[channelId];
+}
+
 /**
  * Record a freshly-presented plan. De-dupes by content hash: an identical
  * re-presentation reuses the existing version (and keeps its comments),
@@ -82,6 +99,8 @@ export function recordPlan(opts) {
       updatedAt: now(),
       currentVersion: version,
       latestHash: hash,
+      // carry forward storage-channel bindings — they outlive individual versions
+      storage: meta?.storage ?? {},
     };
   }
   writeFileSync(metaPath(key), enc(meta));
@@ -179,27 +198,50 @@ export function getReview(id) {
   return existsSync(reviewPath(id)) ? readJSON(reviewPath(id), null) : null;
 }
 
-/** Resolve a review; for reject, compile its version's comments into the reason. */
+/**
+ * Resolve a review.
+ *   - reject  → compile the version's comments into `reason` (fed back via deny).
+ *   - approve → if the version has comments, compile them into `notes`
+ *               (delivered to Claude as additionalContext on the allow — "approve with comments").
+ * Returns the review including `commentCount` so callers can reflect it in the UI.
+ */
 export function resolveReview(id, decision) {
   const review = getReview(id);
   if (!review) return null;
   review.status = decision === "approve" ? "approved" : "rejected";
   review.resolvedAt = now();
-  if (decision === "reject") review.reason = compileReason(review.projectKey, review.version);
+  review.commentCount = listComments(review.projectKey, review.version).length;
+  if (decision === "reject") {
+    review.reason = compileComments(review.projectKey, review.version, "reject");
+  } else {
+    const notes = compileComments(review.projectKey, review.version, "approve");
+    if (notes) review.notes = notes;
+  }
   writeFileSync(reviewPath(id), enc(review));
   return review;
 }
 
-function compileReason(key, n) {
+/**
+ * Format a version's comments for the model.
+ *   mode "reject"  → "address these, then re-present" (always returns text, even with no comments).
+ *   mode "approve" → "plan is approved, incorporate these notes" (returns "" when there are none).
+ */
+function compileComments(key, n, mode) {
   const comments = listComments(key, n);
   const lineComments = comments.filter((c) => c.line != null).sort((a, b) => a.line - b.line);
   const general = comments.filter((c) => c.line == null);
+
+  if (mode === "approve" && !lineComments.length && !general.length) return "";
+
   const md = getVersion(key, n)?.markdown ?? "";
   const lines = md.split("\n");
 
   const parts = [
-    "The reviewer requested changes to this plan in the plan-review UI. " +
-      "Address each comment below, then re-present the revised plan with ExitPlanMode.",
+    mode === "approve"
+      ? "The reviewer APPROVED this plan in the plan-review UI and left the notes below. " +
+        "Proceed with implementation, incorporating each note as you go."
+      : "The reviewer requested changes to this plan in the plan-review UI. " +
+        "Address each comment below, then re-present the revised plan with ExitPlanMode.",
   ];
   if (lineComments.length) {
     parts.push("\nLine comments:");
@@ -220,7 +262,7 @@ function compileReason(key, n) {
     parts.push("\nGeneral comments:");
     for (const c of general) parts.push(`- ${c.body}`);
   }
-  if (!lineComments.length && !general.length) {
+  if (mode === "reject" && !lineComments.length && !general.length) {
     parts.push("\n(No specific comments were left — please reconsider and improve the plan.)");
   }
   return parts.join("\n");

package/src/ui/app.js

@@ -6,7 +6,12 @@ const esc = (s) =>
 
 async function api(path, opts) {
   const res = await fetch(path, opts);
-  if (!res.ok) throw new Error((await res.json().catch(() => ({}))).error || res.statusText);
+  if (!res.ok) {
+    const body = await res.json().catch(() => ({}));
+    const err = new Error(body.error || res.statusText);
+    err.fixCommand = body.fixCommand ?? null;
+    throw err;
+  }
   return res.status === 204 ? null : res.json();
 }
 
@@ -23,6 +28,8 @@ const state = {
   diffMode: "split",
   sel: { anchor: null, start: null, end: null }, // source line-range selection
   dragging: false,
+  storage: {}, // channel bindings for the current project, e.g. { gist: {...} }
+  channels: [], // channel readiness (loaded when the save modal opens)
 };
 
 function toast(msg) {
@@ -60,6 +67,7 @@ function showEmpty(msg) {
   $("panel-preview").classList.add("active");
   $("preview").innerHTML = `<div class="empty">${esc(msg)}</div>`;
   $("reviewActions").hidden = true;
+  $("saveActions").hidden = true;
 }
 
 async function loadProjects() {
@@ -80,6 +88,7 @@ async function selectProject(key, wantV) {
   $("projectSel").value = key;
   const { versions } = await api(`/api/projects/${encodeURIComponent(key)}`);
   state.versions = versions;
+  state.storage = await api(`/api/projects/${encodeURIComponent(key)}/storage`).catch(() => ({}));
   if (!versions.length) {
     showEmpty("This project has no plan versions yet.");
     return;
@@ -111,6 +120,7 @@ async function loadVersion(n) {
   renderSource();
   renderGeneral();
   updateCommentCount();
+  refreshSaveUI();
   await refreshReview();
   if (state.tab === "diff") loadDiff();
 }
@@ -349,13 +359,128 @@ async function refreshReview() {
 }
 
 async function resolve(decision) {
-  await api(`/api/reviews/${state.reviewId}/decision`, {
+  const review = await api(`/api/reviews/${state.reviewId}/decision`, {
     method: "POST",
     headers: { "content-type": "application/json" },
     body: JSON.stringify({ decision }),
   });
   await refreshReview();
-  toast(decision === "approve" ? "Plan approved — Claude will proceed." : "Sent back to Claude with your comments.");
+  if (decision === "approve") {
+    const n = review?.commentCount || 0;
+    toast(
+      n
+        ? `Approved with ${n} comment${n === 1 ? "" : "s"} — Claude will proceed and incorporate them.`
+        : "Plan approved — Claude will proceed.",
+    );
+  } else {
+    toast("Sent back to Claude with your comments.");
+  }
+}
+
+// ---------- storage / save ----------
+function projectName() {
+  return state.projects?.find((p) => p.key === state.key)?.name || "plan";
+}
+
+function refreshSaveUI() {
+  const box = $("saveActions");
+  if (!state.version) {
+    box.hidden = true;
+    return;
+  }
+  box.hidden = false;
+  const g = state.storage?.gist;
+  const btn = $("saveBtn");
+  const link = $("savedLink");
+  if (g?.id) {
+    btn.textContent = state.version === g.savedVersion ? "Update gist" : `Save v${state.version} → gist`;
+    link.hidden = false;
+    link.href = g.htmlUrl;
+    link.textContent = `gist · holds v${g.savedVersion}`;
+  } else {
+    btn.textContent = "Save to gist";
+    link.hidden = true;
+  }
+}
+
+function renderChannelStatus(ch) {
+  const box = $("channelStatus");
+  const confirm = $("saveConfirm");
+  if (!ch) {
+    box.className = "channelStatus warn";
+    box.textContent = "Could not read channel status.";
+    confirm.disabled = true;
+    return;
+  }
+  if (ch.ready) {
+    box.className = "channelStatus ok";
+    box.textContent = "✓ GitHub CLI ready — gist scope present.";
+    confirm.disabled = false;
+  } else {
+    box.className = "channelStatus warn";
+    const cmd = ch.fixCommand ? ` Run:  ${ch.fixCommand}` : ch.fixUrl ? ` See ${ch.fixUrl}` : "";
+    box.textContent = `⚠ ${ch.reason || "Channel not ready."}${cmd}`;
+    confirm.disabled = true;
+  }
+}
+
+async function openSaveModal() {
+  const g = state.storage?.gist;
+  $("saveTitle").textContent = g?.id ? "Update gist" : "Save plan to a gist";
+  $("saveDesc").value = g?.description ?? `${projectName()} — plan`;
+  $("saveFilename").value = g?.filename ?? "plan.md";
+  $("saveHint").textContent = g?.id
+    ? `Overwrites your secret gist (currently holds v${g.savedVersion}) with v${state.version}. GitHub keeps the gist's revision history.`
+    : `Creates a secret (unlisted) gist with v${state.version}'s markdown. Only people with the link can see it.`;
+  $("saveModal").hidden = false;
+
+  const sel = $("saveChannel");
+  $("channelStatus").textContent = "Checking GitHub CLI…";
+  $("channelStatus").className = "channelStatus";
+  $("saveConfirm").disabled = true;
+  try {
+    state.channels = await api("/api/channels");
+  } catch {
+    state.channels = [];
+  }
+  sel.innerHTML = state.channels.map((c) => `<option value="${esc(c.id)}">${esc(c.label)}</option>`).join("");
+  const current = state.channels.find((c) => c.id === (sel.value || "gist")) || state.channels[0];
+  if (current) sel.value = current.id;
+  renderChannelStatus(current);
+}
+
+function closeSaveModal() {
+  $("saveModal").hidden = true;
+}
+
+async function doSave() {
+  const channel = $("saveChannel").value || "gist";
+  const description = $("saveDesc").value.trim();
+  const filename = $("saveFilename").value.trim() || "plan.md";
+  const btn = $("saveConfirm");
+  btn.disabled = true;
+  const prev = btn.textContent;
+  btn.textContent = "Saving…";
+  try {
+    const r = await api(
+      `/api/projects/${encodeURIComponent(state.key)}/versions/${state.version}/save`,
+      {
+        method: "POST",
+        headers: { "content-type": "application/json" },
+        body: JSON.stringify({ channel, description, filename }),
+      },
+    );
+    state.storage[channel] = r;
+    closeSaveModal();
+    refreshSaveUI();
+    toast(`Saved v${state.version} to ${channel}.`);
+  } catch (e) {
+    // surface the remediation command if the channel handed one back
+    renderChannelStatus({ ready: false, reason: e.message, fixCommand: e.fixCommand });
+  } finally {
+    btn.textContent = prev;
+    btn.disabled = false;
+  }
 }
 
 // ---------- polling (reflect external resolution) ----------
@@ -469,6 +594,12 @@ function wireUI() {
     $("generalInput").value = "";
   };
 
+  $("saveBtn").onclick = () => openSaveModal();
+  $("saveCancel").onclick = () => closeSaveModal();
+  $("saveConfirm").onclick = () => doSave();
+  $("saveChannel").onchange = () =>
+    renderChannelStatus(state.channels.find((c) => c.id === $("saveChannel").value));
+
   $("approveBtn").onclick = () => resolve("approve");
   $("rejectBtn").onclick = () => ($("rejectModal").hidden = false);
   $("rejectCancel").onclick = () => ($("rejectModal").hidden = true);

package/src/ui/index.html

@@ -25,6 +25,10 @@
         <select id="versionSel"></select>
       </label>
     </div>
+    <div class="saveActions" id="saveActions" hidden>
+      <button class="btn" id="saveBtn">Save to gist</button>
+      <a class="savedlink" id="savedLink" href="#" target="_blank" rel="noopener" hidden></a>
+    </div>
     <div class="reviewActions" id="reviewActions" hidden>
       <span class="pill pending" id="reviewPill">● review pending</span>
       <button class="btn approve" id="approveBtn">Approve plan</button>
@@ -87,6 +91,27 @@
     </div>
   </div>
 
+  <div class="saveModal" id="saveModal" hidden>
+    <div class="box">
+      <h3 id="saveTitle">Save plan to a gist</h3>
+      <div class="channelStatus" id="channelStatus"></div>
+      <label class="field">Storage channel
+        <select id="saveChannel"></select>
+      </label>
+      <label class="field">Gist description
+        <input type="text" id="saveDesc" placeholder="Short description shown in your gist list" />
+      </label>
+      <label class="field">File name
+        <input type="text" id="saveFilename" placeholder="plan.md" />
+      </label>
+      <p class="hint" id="saveHint"></p>
+      <div class="row">
+        <button class="btn" id="saveCancel">Cancel</button>
+        <button class="btn primary" id="saveConfirm">Save</button>
+      </div>
+    </div>
+  </div>
+
   <div class="toast" id="toast" hidden></div>
 </div>
 <script src="/app.js"></script>

package/src/ui/style.css

@@ -173,6 +173,25 @@ textarea {
 .rejectModal textarea { width: 100%; min-height: 80px; }
 .rejectModal .row { display: flex; justify-content: flex-end; gap: 10px; margin-top: 12px; }
 
+/* save-to-channel control + modal */
+.saveActions { display: flex; align-items: center; gap: 8px; }
+.savedlink { font-size: 11px; color: var(--fg-muted); font-family: var(--mono); text-decoration: none; white-space: nowrap; }
+.savedlink:hover { color: var(--accent); text-decoration: underline; }
+
+.saveModal { position: fixed; inset: 0; background: #00000066; display: flex; align-items: center; justify-content: center; z-index: 50; }
+.saveModal .box { background: var(--bg); border: 1px solid var(--border); border-radius: 10px; padding: 20px; width: 480px; max-width: 92vw; }
+.saveModal h3 { margin-top: 0; }
+.saveModal .field { display: flex; flex-direction: column; gap: 4px; font-size: 12px; color: var(--fg-muted); margin-bottom: 12px; }
+.saveModal .field input, .saveModal .field select { font-family: var(--sans); font-size: 13px; padding: 6px 8px; border: 1px solid var(--border); border-radius: 6px; background: var(--bg); color: var(--fg); }
+.saveModal .hint { color: var(--fg-muted); font-size: 12px; margin: 4px 0 0; }
+.saveModal .row { display: flex; justify-content: flex-end; gap: 10px; margin-top: 16px; }
+.saveModal .btn.primary { background: var(--accent); border-color: var(--accent); color: #fff; }
+.saveModal .btn.primary:hover { filter: brightness(1.08); }
+.saveModal .btn:disabled { opacity: .5; cursor: not-allowed; filter: none; }
+.channelStatus { font-size: 12px; padding: 8px 10px; border-radius: 6px; margin-bottom: 14px; white-space: pre-wrap; word-break: break-word; }
+.channelStatus.ok { background: var(--green-bg); color: var(--green); }
+.channelStatus.warn { background: #fff8c5; color: #7d4e00; font-family: var(--mono); }
+
 .toast { position: fixed; bottom: 22px; left: 50%; transform: translateX(-50%); background: var(--fg); color: var(--bg);
   padding: 10px 18px; border-radius: 8px; font-size: 13px; z-index: 60; box-shadow: 0 4px 16px #0004; }