refactor: make galley spec the single source of truth for the agent contract

The agent-facing contract (review modes, the await/comment/reload loop,
await exit semantics, ReviewResult, how to act on a review, the
guided-review schema) was hand-duplicated across SKILL.md, the AGENTS.md
snippet, and partially in guide-spec — and CLAUDE.md warned to update
SKILL.md on every contract change. The skill and snippet drift from the
installed binary's real behavior.

Consolidate the full contract into a CLI-printed spec so the binary and
its instructions ship together and can't diverge:

- Rename src/guidespec.ts -> src/spec.ts; the SPEC export now holds the
  full contract, with the guided-review JSON schema folded in as a
  section.
- Add `galley spec`; remove `galley guide-spec` entirely (clean break).
  Repoint the server error `docs` field and the inline schema pointer to
  `galley spec`.
- Shrink SKILL.md and the AGENTS.md snippet to bootstrap only (what
  Galley is, when to use it, install, the 3 start commands) plus a
  once-per-session "run `galley spec` and follow it" pointer.
- Redirect CLAUDE.md's maintenance rule and README's pointer at
  src/spec.ts / `galley spec`.
- Add src/spec.test.ts guarding that SPEC carries every consolidated
  section and has no dangling skill/guide-spec references.

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

Author: ymansurozer

CLAUDE.md

@@ -46,7 +46,7 @@ The two worlds do not import each other. `src/types.ts` (backend) and `src/ui/ty
 - `contentHash`/`reviewedHash` pairs detect staleness: if the agent rewrites a block (or a file) after it was decided/approved, the decision/approval resets to pending on reload. The same pattern invalidates comment anchors (`anchorText` → re-anchoring → `unanchored`) and guides (`baseDiffHash`).
 - Desks are idempotent per repo+session: `stablePort` hashes repo+session to a port in 41000–50999 so a restarted desk binds the same origin and an open tab self-heals; a desk lock file is trusted only if the server actually answers (`deskAlive`).
 
-**Agent contract:** plain JSON on stdout. `galley await` long-polls and prints one tagged event — `{"kind":"question",…}` (answer now via `galley comment`) or `{"kind":"review","result":{…ReviewResult…}}` (the reviewer hit Send). The contract is documented for consuming agents in `skills/galley/SKILL.md` (and the short form in `skills/galley/agents-snippet.md`); the server's error responses point there too. **If you change the CLI flags, events, or ReviewResult shape, update SKILL.md in the same change.** `scripts/smoke.mjs` exercises this contract end-to-end and is the regression net for it.
+**Agent contract:** plain JSON on stdout. `galley await` long-polls and prints one tagged event — `{"kind":"question",…}` (answer now via `galley comment`) or `{"kind":"review","result":{…ReviewResult…}}` (the reviewer hit Send). The contract is the single source of truth in `src/spec.ts` (printed by `galley spec`); the skill (`skills/galley/SKILL.md`) and the AGENTS.md snippet (`skills/galley/agents-snippet.md`) are bootstrap-only and point consuming agents at `galley spec`, and the server's error responses do too. **If you change the CLI flags, events, or ReviewResult shape, update `src/spec.ts` in the same change.** `scripts/smoke.mjs` and `src/spec.test.ts` exercise this contract and are the regression net for it.
 
 **UI:** an Alpine.js app with a global store (`src/ui/store.ts`); `poll.ts` polls `/api/state`, `render.ts` renders the diff via `@pierre/diffs` (which renumbers lines per render — display anchors are derived, raw file lines stay canonical), `keys.ts` holds the keyboard-first command map, and `guide.ts`/`tree.ts`/`decisions.ts` etc. are feature modules.
 

README.md

@@ -48,7 +48,7 @@ I'm not saying this is *the* review surface. I built it in a week and I'm still
    galley pr feature-branch     # review a branch's commits vs its merge-base
    ```
 
-   Galley opens in your browser and stays open. You review and click **Send to Agent**; the agent attaches, acts on each send, and replies in the same tab. More flags (`--repo`, `--path`, `--port`, `--no-open`, `--guide`, …) are documented in the skill.
+   Galley opens in your browser and stays open. You review and click **Send to Agent**; the agent attaches, acts on each send, and replies in the same tab. The full agent contract — modes, the event loop, all flags (`--repo`, `--path`, `--port`, `--no-open`, `--guide`, …), `ReviewResult`, and the guided-review schema — is printed by **`galley spec`** (always current with your installed version); the skill is a thin pointer to it.
 
 ## Features
 

skills/galley/SKILL.md

@@ -1,23 +1,15 @@
 # Galley — AGENTS.md / CLAUDE.md snippet
 
-Paste the block below into your agent's instruction file (`AGENTS.md`, `CLAUDE.md`, `.cursorrules`, …) so the agent always routes plan/PR/change review through Galley. It's deliberately short and points at the skill (`skills/galley/SKILL.md`) for the full contract — modes, the event loop, CLI options, and the `ReviewResult` shape.
+Paste the block below into your agent's instruction file (`AGENTS.md`, `CLAUDE.md`, `.cursorrules`, …) so the agent always routes plan/PR/change review through Galley. It's deliberately short: it points at `galley spec` — printed by the installed binary, always current — for the full contract (modes, the event loop, CLI options, `ReviewResult`, and how to act).
 
 ---
 
 ## Reviewing with Galley
 
-When the user should review a plan, a PR, or code changes you've made, hand it to **Galley** — a living browser review desk.
+When the user should review a plan, a PR, or code changes you've made, hand it to **Galley** — a living browser review desk. Three ways to start (each stays alive across rounds):
 
 - **Changes you made** → `galley --session <task-id> &` (working tree; `--diff staged` for staged only).
 - **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 <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.
-- `{"kind":"review","result":{…}}` → act on `result`: revert **rejected**, make **requestedChanges**, leave **accepted** alone, leave **approvedFiles** (signed off as-is) untouched, don't touch **stagedFiles** unless a change requires it. (Editing an approved file invalidates its approval → it needs re-review next round.)
-
-After editing code, run `galley reload --session <task-id>` so your edits show in the open tab (add `--guide <file>` to swap in a regenerated guide), then `galley await` again for the next round. The desk stays open across rounds and the reviewer keeps **one tab**: starting is idempotent (a live desk is reused, never duplicated) and the port is stable per session, so even after a desk process dies, re-running the start command brings the same tab back to life — never open a second desk for the same session.
-
-Full reference (modes, options, exit semantics, `ReviewResult`): **`skills/galley/SKILL.md`**.
+**For the full contract — the `await`/`comment`/`reload` loop, event shapes, `ReviewResult`, how to act on accepted/rejected/requested changes, the guided-review schema, and all options — run `galley spec` and follow it (once per session before your first review).** `galley spec` ships with the binary, so it never goes stale; this snippet intentionally doesn't duplicate it.

skills/galley/agents-snippet.md

@@ -1,8 +1,12 @@
 #!/usr/bin/env node
-import http from "node:http";
 import { readFileSync, unlinkSync, writeFileSync } from "node:fs";
+import http from "node:http";
 import path from "node:path";
+
 import { getBranch, getGitRoot, gh, git } from "./git.js";
+import { validateGuide } from "./guide.js";
+import { startServer } from "./server.js";
+import { SPEC } from "./spec.js";
 import {
   appendComment,
   buildReviewState,
@@ -17,11 +21,8 @@ import {
   stablePort,
   syncGitState,
 } from "./state.js";
-import { validateGuide } from "./guide.js";
-import { GUIDE_SPEC } from "./guidespec.js";
-import { startServer } from "./server.js";
-import { maybeOfferUpdate } from "./update.js";
 import type { ReviewMode } from "./types.js";
+import { maybeOfferUpdate } from "./update.js";
 
 function parseArgs(argv: string[]) {
   const out: Record<string, string | boolean> = { diff: "working", open: true };
@@ -498,7 +499,7 @@ Usage:
   galley await [--timeout <s>]      Block for the next desk event (question | review)
   galley reload [--guide <file>]    Re-diff the working tree into the open desk
                                     (--guide swaps the attached review guide too)
-  galley guide-spec                 Print the guide JSON schema + authoring rules
+  galley spec                       Print the full agent contract (modes, loop, ReviewResult, guide schema)
 
 Common flags:
   --repo <path>     Repo to review (default: cwd)
@@ -533,8 +534,8 @@ async function main() {
   if (sub === "status") return runStatus(args);
   if (sub === "await") return runAwait(args);
   if (sub === "reload") return runReload(args);
-  if (sub === "guide-spec") {
-    process.stdout.write(GUIDE_SPEC + "\n");
+  if (sub === "spec") {
+    process.stdout.write(SPEC + "\n");
     return;
   }
   if (sub === "file") {
@@ -548,7 +549,7 @@ async function main() {
   if (sub === "pr") return runDesk("pr", positional, args);
   if (sub) {
     console.error(
-      `Unknown command "${sub}". Use: galley | galley file <path> | galley pr <ref|number|url> | comment | status | await | reload | guide-spec.`,
+      `Unknown command "${sub}". Use: galley | galley file <path> | galley pr <ref|number|url> | comment | status | await | reload | spec.`,
     );
     process.exitCode = 1;
     return;

src/cli.ts

@@ -1,11 +1,14 @@
-import crypto from "node:crypto";
 import { execFile } from "node:child_process";
+import crypto from "node:crypto";
 import { promises as fs } from "node:fs";
 import http from "node:http";
 import path from "node:path";
 import { fileURLToPath } from "node:url";
 import { promisify } from "node:util";
+
+import { resolveEditorCommand } from "./editor.js";
 import { git, listProjectTree, patchForChange } from "./git.js";
+import { validateGuide } from "./guide.js";
 import {
   anchorTextFor,
   buildReviewResult,
@@ -19,13 +22,11 @@ import {
   syncGitState,
   writeGlobalSettings,
 } from "./state.js";
-import { validateGuide } from "./guide.js";
-import { resolveEditorCommand } from "./editor.js";
 import type { AgentActivity, AwaitEvent, DeskStatus, ReviewState } from "./types.js";
 
 const execFileAsync = promisify(execFile);
 const __dirname = path.dirname(fileURLToPath(import.meta.url));
-const DOCS = "skills/galley/SKILL.md";
+const DOCS = "Run `galley spec` for the full agent contract.";
 
 export type ServerOptions = {
   state: ReviewState;
@@ -379,7 +380,7 @@ export async function startServer(options: ServerOptions): Promise<ServerHandle>
               422,
               "INVALID_GUIDE",
               `Invalid guide: ${result.reason}.`,
-              "Run `galley guide-spec` for the schema.",
+              "Run `galley spec` for the guided-review schema.",
             );
           validatedGuide = result.guide;
         }

src/guidespec.ts

@@ -0,0 +1,54 @@
+import assert from "node:assert/strict";
+import { test } from "node:test";
+
+import { SPEC } from "./spec.js";
+
+// The SPEC string is the single source of truth for the agent contract (printed by
+// `galley spec`). These anchors guard that consolidating the skill/snippet into it didn't
+// silently hollow out a section — if you intentionally rename a section, update the anchor.
+const ANCHORS = [
+  // modes
+  "Review modes",
+  "repo (default)",
+  "galley file <path>",
+  "galley pr <ref>",
+  // the loop + events
+  "galley await",
+  "galley comment",
+  "galley reload",
+  "galley status",
+  '"kind":"question"',
+  '"kind":"review"',
+  // result + acting
+  "ReviewResult",
+  "approvedFiles",
+  "How to act on a review",
+  // guided review schema (folded in from the old guide-spec)
+  "Guide JSON schema",
+  '"overview"',
+  '"files"',
+  '"path"',
+  '"summary"',
+  // the rest of the operational contract
+  "reload vs restart",
+  "desk.lock",
+  "Settings",
+  "PATCH_CONFLICT",
+];
+
+test("SPEC carries every consolidated section", () => {
+  for (const anchor of ANCHORS) {
+    assert.ok(SPEC.includes(anchor), `galley spec is missing the "${anchor}" anchor`);
+  }
+});
+
+test("SPEC has no dangling references to the old skill/command", () => {
+  assert.ok(
+    !SPEC.includes("guide-spec"),
+    "SPEC should not reference the removed guide-spec command",
+  );
+  assert.ok(
+    !SPEC.includes("SKILL.md"),
+    "SPEC must be self-contained — no 'see the skill' pointers",
+  );
+});