revspec 0.5.0 → 0.7.0

package/README.md

@@ -1,6 +1,6 @@
 # Revspec
 
-A review tool for AI-generated spec documents with real-time AI conversation. Comment on specific lines, get AI replies instantly, resolve discussions, and approve — all without leaving the terminal.
+A review tool for AI-generated spec documents with real-time AI conversation. Comment on specific lines, get AI replies instantly, resolve discussions, submit for rewrites, and approve — all without leaving the terminal.
 
 ## Why
 
@@ -27,92 +27,114 @@ cd revspec && bun install && bun link
 revspec spec.md
 ```
 
-Opens a TUI in line mode with vim-style navigation. Press `c` on any line to open a thread and start commenting.
-
-### Markdown rendering
-
-Revspec renders markdown in-place (toggle with `m`):
-
-- **Headings** — colored and bold, `#`–`######`
-- **Inline** — bold (`**`/`__`), italic (`*`/`_`), bold-italic (`***`), strikethrough (`~~`), `code`, [links](url)
-- **Fenced code blocks** — fence markers dimmed, body in green
-- **Tables** — box-drawing borders, header row bolded, auto-column-widths
-- **Lists** — unordered (`•`), ordered, task lists (`☐`/`☑`)
-- **Blockquotes** — bar gutter, italicized text
-- **Cursor line** highlighting across all elements
-- **Search highlights** — colored match segments
+Opens a TUI with vim-style navigation. Press `c` on any line to open a thread and start commenting.
 
 ### Keybindings
 
+**Navigation**
+
 | Key | Action |
 |-----|--------|
 | `j/k` | Move cursor down/up |
 | `gg` / `G` | Go to top / bottom |
 | `Ctrl+D/U` | Half page down/up |
-| `m` | Toggle markdown / line mode |
-| `c` | Open thread / comment on line |
-| `r` | Resolve thread (toggle) |
-| `R` | Resolve all pending |
-| `dd` | Delete draft comment (double-tap) |
-| `/` | Search |
+| `zz` | Center cursor line in viewport |
+| `/` | Search (smartcase) |
 | `n/N` | Next/prev search match |
+| `Esc` | Clear search highlights |
 | `]t/[t` | Next/prev thread |
 | `]r/[r` | Next/prev unread AI reply |
-| `l` | List threads |
-| `a` | Approve spec |
-| `:w` | Merge changes to review JSON |
-| `:wq` | Merge and quit |
-| `:q` | Quit (only if merged) |
-| `:q!` | Quit without merging |
+
+**Review**
+
+| Key | Action |
+|-----|--------|
+| `c` | Open thread / comment on line |
+| `r` | Resolve thread (toggle) |
+| `R` | Resolve all pending |
+| `dd` | Delete thread (with confirm) |
+| `t` | List threads |
+| `S` | Submit for rewrite (AI updates spec, TUI reloads) |
+| `A` | Approve spec (finalize and exit) |
+
+**Commands**
+
+| Key | Action |
+|-----|--------|
+| `:q` | Quit (warns if unresolved threads) |
+| `:q!` | Force quit |
+| `:{N}` | Jump to line N |
+| `Ctrl+C` | Force quit |
 | `?` | Help |
 
+**Popups**
+
+| Key | Action |
+|-----|--------|
+| `y/Enter` | Confirm / select |
+| `q/Esc` | Cancel / close |
+
 ### Thread popup
 
 The thread popup has two modes:
 
 - **Insert mode** — type your comment, `Tab` sends, `Esc` switches to normal mode
-- **Normal mode** — `j/k` and `Ctrl+D/U` scroll the conversation history, `c` to reply, `r` to resolve, `Esc` to close
+- **Normal mode** — `j/k` and `Ctrl+D/U` scroll the conversation, `gg/G` top/bottom, `c` to reply, `r` to resolve, `q/Esc` to close
+
+### Markdown rendering
+
+Revspec renders markdown in-place:
+
+- **Headings** — colored and bold, `#`–`######`
+- **Inline** — bold, italic, bold-italic, strikethrough, `code`, links
+- **Fenced code blocks** — markers dimmed, body in green
+- **Tables** — box-drawing borders, header row bolded, auto-column-widths
+- **Lists** — unordered, ordered, task lists
+- **Blockquotes** — bar gutter, italicized text
+- **Cursor line** highlighting and **search highlights**
 
 ## Live AI Integration
 
-Revspec supports real-time communication with AI coding tools (Claude Code, opencode, etc.) via two CLI subcommands:
+Revspec communicates with AI coding tools (Claude Code, etc.) via CLI subcommands:
 
 ### `revspec watch <file.md>`
 
-Blocks until the reviewer adds comments, then returns them with spec context:
+Blocks until the reviewer acts, then returns structured output:
 
 ```
 === New Comments ===
-Thread: t1 (line 14)
+Thread: x1a3f (line 14)
   Context:
       12: The system uses polling...
     > 14: it sends a notification via webhook.
       16: resource state.
   [reviewer]: this is unclear
 
-To reply: revspec reply spec.md t1 "<your response>"
+To reply: revspec reply spec.md x1a3f "<your response>"
 When done replying, run: revspec watch spec.md
 ```
 
+Watch exits on three events:
+- **Comment/reply** — returns thread content for AI to respond
+- **Submit (`S`)** — returns resolved thread summaries for AI to rewrite the spec
+- **Approve (`A`)** — spec is finalized
+- **Session end** — reviewer quit the TUI
+
 ### `revspec reply <file.md> <threadId> "<text>"`
 
-Sends an AI reply that appears instantly in the reviewer's TUI:
-
-```bash
-revspec reply spec.md t1 "Good point. I'll clarify the polling vs webhook distinction."
-```
+Sends an AI reply that appears instantly in the reviewer's TUI.
 
 ### The loop
 
 ```
 1. AI generates spec
-2. AI launches: revspec spec.md (in tmux pane or separate terminal)
+2. AI launches: revspec spec.md (in tmux pane)
 3. AI runs: revspec watch spec.md (blocks)
-4. Reviewer comments on lines in the TUI
-5. Watch returns with comments → AI replies → watch again
-6. Reviewer resolves threads → approves
-7. AI reads review JSON, rewrites spec, launches new round
-8. Repeat until clean approval
+4. Reviewer comments → AI replies → watch again
+5. Reviewer resolves threads → presses S (submit)
+6. Watch returns resolved thread summaries → AI rewrites spec
+7. TUI reloads with new spec → reviewer continues reviewing
+8. Repeat 3-7 until A (approve)
 ```
 
 ### Claude Code skill
@@ -125,39 +147,34 @@ Install the `/revspec` skill for Claude Code:
 
 Then use `/revspec` in Claude Code after generating a spec.
 
+## Testing
+
+```bash
+bun run test          # Unit + integration (~3s)
+bun run test:e2e      # E2E snapshot tests (~7s)
+bun run test:all      # Everything
+```
+
+E2E tests use `bun-pty` to spawn revspec in a pseudo-terminal (80x24), send keystrokes, capture plain-text output, and compare snapshots.
+
 ## Protocol
 
-Communication happens through a JSONL file (`spec.review.live.jsonl`) — append-only, both sides write to it. On session end, events are merged into `spec.review.json`.
+Communication happens through a JSONL file (`spec.review.jsonl`) — append-only, both sides write to it. The JSONL is the single source of truth for the review session.
 
 ### Event types
 
 ```jsonl
-{"type":"comment","threadId":"t1","line":14,"author":"reviewer","text":"unclear","ts":1710400000}
-{"type":"reply","threadId":"t1","author":"owner","text":"I'll fix it","ts":1710400005}
-{"type":"resolve","threadId":"t1","author":"reviewer","ts":1710400010}
-{"type":"approve","author":"reviewer","ts":1710400050}
+{"type":"comment","threadId":"x1a3f","line":14,"author":"reviewer","text":"unclear","ts":1710400000}
+{"type":"reply","threadId":"x1a3f","author":"owner","text":"I'll fix it","ts":1710400005}
+{"type":"resolve","threadId":"x1a3f","author":"reviewer","ts":1710400010}
+{"type":"submit","author":"reviewer","ts":1710400050}
+{"type":"approve","author":"reviewer","ts":1710400060}
+{"type":"session-end","author":"reviewer","ts":1710400070}
 ```
 
-### Review JSON
-
-```json
-{
-  "file": "spec.md",
-  "threads": [
-    {
-      "id": "t1",
-      "line": 14,
-      "status": "resolved",
-      "messages": [
-        { "author": "reviewer", "text": "this is unclear", "ts": 1710400000 },
-        { "author": "owner", "text": "I'll restructure this section", "ts": 1710400005 }
-      ]
-    }
-  ]
-}
-```
+The `submit` event acts as a round delimiter — the AI rewrites the spec, and the TUI reloads. Events before a `submit` reference the previous spec version.
 
-Thread statuses: `open` (owner's turn), `pending` (reviewer's turn), `resolved`, `outdated`.
+Thread statuses: `open` (awaiting AI reply), `pending` (AI replied, awaiting reviewer), `resolved`, `outdated`.
 
 ## License
 

package/bin/revspec.ts

@@ -1,9 +1,7 @@
 #!/usr/bin/env bun
 import { existsSync } from "fs";
 import { resolve, basename, extname, dirname, join } from "path";
-import { readReviewFile } from "../src/protocol/read";
 import { runTui } from "../src/tui/app";
-import { readEventsFromOffset } from "../src/protocol/live-events";
 
 const args = process.argv.slice(2);
 const subcommand = args[0];
@@ -33,7 +31,7 @@ if (subcommand === "reply") {
 }
 
 if (args.length === 0 || args.includes("--help") || args.includes("-h")) {
-  console.log("Usage: revspec <file.md> [--tui|--nvim|--web]");
+  console.log("Usage: revspec <file.md>");
   process.exit(0);
 }
 
@@ -56,40 +54,8 @@ if (!existsSync(specPath)) {
   process.exit(1);
 }
 
-// 2. Derive review/jsonl paths from spec filename
-//    e.g. spec.md -> spec.review.json, spec.review.live.jsonl
-const specDir = dirname(specPath);
-const specBase = basename(specPath, extname(specPath)); // e.g. "spec"
-const reviewPath = join(specDir, `${specBase}.review.json`);
-const jsonlPath = join(specDir, `${specBase}.review.live.jsonl`);
-const draftPath = join(specDir, `${specBase}.review.draft.json`);
+// 2. Launch TUI
+const pkg = await Bun.file(new URL("../package.json", import.meta.url)).json();
+await runTui(specPath, pkg.version);
 
-// 3. Launch TUI (skip if REVSPEC_SKIP_TUI=1)
-if (process.env.REVSPEC_SKIP_TUI !== "1") {
-  const pkg = await Bun.file(new URL("../package.json", import.meta.url)).json();
-  await runTui(specPath, reviewPath, draftPath, pkg.version);
-}
-
-// 4. After TUI exits, check if approved via JSONL
-if (existsSync(jsonlPath)) {
-  const { events } = readEventsFromOffset(jsonlPath, 0);
-  const wasApproved = events.some(e => e.type === "approve");
-  if (wasApproved && existsSync(reviewPath)) {
-    console.log(`APPROVED: ${reviewPath}`);
-    process.exit(0);
-  }
-}
-
-// 5. Check if review file exists with open/pending threads
-const existingReview = readReviewFile(reviewPath);
-if (existingReview) {
-  const hasOpenOrPending = existingReview.threads.some(
-    (t) => t.status === "open" || t.status === "pending"
-  );
-  if (hasOpenOrPending) {
-    process.stdout.write(`${reviewPath}\n`);
-  }
-}
-
-// Otherwise print nothing
 process.exit(0);

package/package.json

@@ -1,16 +1,33 @@
 {
   "name": "revspec",
-  "version": "0.5.0",
+  "version": "0.7.0",
+  "description": "Terminal-based spec review tool with real-time AI conversation",
   "type": "module",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/icyrainz/revspec.git"
+  },
+  "keywords": ["spec", "review", "tui", "ai", "claude", "vim", "terminal"],
   "bin": {
     "revspec": "./bin/revspec.ts"
   },
+  "files": [
+    "bin/",
+    "src/",
+    "skills/",
+    "README.md",
+    "LICENSE"
+  ],
   "scripts": {
     "start": "bun run bin/revspec.ts",
-    "test": "bun test"
+    "test": "bun test test/unit test/integration",
+    "test:e2e": "bun test test/e2e",
+    "test:all": "bun test"
   },
   "devDependencies": {
-    "@types/bun": "latest"
+    "@types/bun": "latest",
+    "bun-pty": "^0.4.8"
   },
   "peerDependencies": {
     "typescript": "^5"

package/skills/revspec/SKILL.md

@@ -38,7 +38,8 @@ echo $TMUX
 
 **If tmux is available:**
 ```bash
-tmux split-window -v "revspec <spec-file>"
+# Split from Claude Code's own pane (not the user's active window)
+tmux split-window -t "$TMUX_PANE" -v "revspec <spec-file>"
 ```
 
 **If no tmux:**
@@ -55,57 +56,64 @@ revspec watch <spec-file>
 This blocks until the reviewer adds comments. When it returns, you'll see output like:
 
 ```
---- New threads ---
-
-[t1] line 14 (new):
+=== New Comments ===
+Thread: x1a3f (line 14)
   Context:
-    12: The system uses polling...
-   >14: it sends a notification via webhook.
-    16: resource state.
-  Comment: "this is unclear"
+      12: The system uses polling...
+    > 14: it sends a notification via webhook.
+      16: resource state.
+  [reviewer]: this is unclear
+  To reply: revspec reply spec.md x1a3f "<your reply>"
 
-To reply: revspec reply spec.md <threadId> "<your response>"
 When done replying, run: revspec watch spec.md
 ```
 
 **For each comment:** Read the context, understand the concern, and reply thoughtfully:
 
 ```bash
-revspec reply <spec-file> t1 "Good point. I'll clarify — it uses polling to detect changes, then sends a webhook notification to downstream services."
+revspec reply <spec-file> x1a3f "Good point. I'll clarify — it uses polling to detect changes, then sends a webhook notification to downstream services."
 ```
 
 After replying to all comments, run `revspec watch` again to wait for the next batch.
 
-**If watch returns "Session ended. Reviewer exited revspec."** — the reviewer closed the TUI. Check the review JSON for resolved threads that require spec changes (see Step 4). If no resolved threads, stop and wait — the user can invoke `/revspec` again later to resume.
+**If watch returns "Session ended. Reviewer exited revspec."** — the reviewer closed the TUI. Stop and wait — the user can invoke `/revspec` again later.
 
 **Important:** Your replies should be substantive — address the concern, explain your reasoning, or acknowledge the change you'll make. Don't just say "noted" or "will fix."
 
-## Step 4: Handle Session End or Approval
+## Step 4: Handle Submit, Session End, or Approval
 
-The watch loop ends in one of two ways:
+The watch loop ends in one of three ways:
 
-### Session ended (reviewer exited with `:q`)
+### Submit (reviewer pressed `S`)
+
+Watch returns resolved thread summaries:
+
+```
+=== Submit: Rewrite Requested ===
 
-Read the review JSON and check for **resolved threads**. Resolved = the reviewer acknowledged your reply and wants you to make that change.
+Resolved threads:
+  x1a3f (line 14): "this is unclear"
+    → AI: "I'll clarify the polling vs webhook distinction."
 
-**If resolved threads with actionable feedback exist:**
-1. Rewrite the spec incorporating the feedback from resolved threads
-2. Commit the updated spec
-3. Append a round marker to the JSONL:
-   ```bash
-   echo '{"type":"round","author":"owner","round":2,"ts":'$(date +%s000)'}' >> <spec-file>.review.live.jsonl
-   ```
-4. Launch a new revspec session (go back to Step 2) so the reviewer can verify the changes
+Rewrite the spec incorporating the above, then run: revspec watch spec.md
+```
+
+1. Read the current spec and compare against the resolved threads
+2. If changes are needed: rewrite the spec and save — this triggers the TUI to reload automatically
+3. If the spec already reflects the feedback (e.g., crash recovery): skip rewrite
+4. Run `revspec watch` again — the reviewer is still in the TUI and will see the new content
+
+**Important:** Watch may re-output the submit summary on crash recovery. Always verify whether the spec already incorporates the feedback before rewriting.
+
+### Session ended (reviewer exited with `:q`)
 
-**If no resolved threads (or only open/pending threads):**
-The reviewer left without resolving anything — stop and wait. The user can invoke `/revspec` again later.
+The reviewer closed the TUI. Stop and wait — the user can invoke `/revspec` again later.
 
-### Approved (reviewer pressed `a`)
+### Approved (reviewer pressed `A`)
 
 Watch returns:
 ```
 Review approved.
-Review file: <path-to-review.json>
 ```
 
 The spec is finalized. Report: "Spec approved and finalized at `<spec-file>`. Ready to proceed with implementation."
@@ -115,7 +123,6 @@ The spec is finalized. Report: "Spec approved and finalized at `<spec-file>`. Re
 - **Open** — under discussion, AI replied, reviewer hasn't responded yet
 - **Pending** — owner replied, waiting for reviewer to read
 - **Resolved** — reviewer acknowledged the plan, AI should make the change
-- **Approve** — spec is final, proceed to implementation
 
 ## Loop Summary
 
@@ -123,9 +130,9 @@ The spec is finalized. Report: "Spec approved and finalized at `<spec-file>`. Re
 1. Launch revspec on spec file
 2. Watch for comments
 3. Reply to each comment
-4. Watch again (repeat 2-3 until session-end or approval)
-5. On session-end: check for resolved threads
-6. If resolved threads need spec changes: rewrite spec, launch new round (go to 1)
+4. Watch again (repeat 2-3 until submit/session-end/approval)
+5. On submit: verify and rewrite spec if needed (triggers TUI reload), go to step 2
+6. On session-end: stop, user will invoke /revspec again if needed
 7. On approval: spec is finalized, done
 ```
 

package/src/cli/reply.ts

@@ -26,7 +26,7 @@ export function runReply(
   // Derive JSONL path
   const dir = dirname(specPath);
   const base = basename(specPath, ".md");
-  const jsonlPath = `${dir}/${base}.review.live.jsonl`;
+  const jsonlPath = `${dir}/${base}.review.jsonl`;
 
   // Validate JSONL exists
   if (!existsSync(jsonlPath)) {

package/src/cli/watch.ts

@@ -19,9 +19,9 @@ export async function runWatch(specFile: string): Promise<void> {
   // Derive paths
   const dir = dirname(specPath);
   const base = basename(specPath, ".md");
-  const jsonlPath = join(dir, `${base}.review.live.jsonl`);
-  const offsetPath = join(dir, `${base}.review.live.offset`);
-  const lockPath = join(dir, `${base}.review.live.lock`);
+  const jsonlPath = join(dir, `${base}.review.jsonl`);
+  const offsetPath = join(dir, `${base}.review.offset`);
+  const lockPath = join(dir, `${base}.review.lock`);
   const reviewPath = join(dir, `${base}.review.json`);
 
   // Handle lock file
@@ -73,7 +73,7 @@ export async function runWatch(specFile: string): Promise<void> {
       offset
     );
     if (result.approved) {
-      console.log(`Review approved.\nReview file: ${reviewPath}`);
+      console.log("Review approved.");
       cleanupFiles(lockPath, offsetPath);
     } else if (result.output) {
       process.stdout.write(result.output);
@@ -99,7 +99,7 @@ export async function runWatch(specFile: string): Promise<void> {
       );
 
       if (result.approved) {
-        console.log(`Review approved.\nReview file: ${reviewPath}`);
+        console.log("Review approved.");
         cleanupFiles(lockPath, offsetPath);
         process.exit(0);
       }
@@ -135,7 +135,7 @@ export async function runWatch(specFile: string): Promise<void> {
 
   // Also watch the directory for the JSONL file to appear
   const dirWatcher = fsWatch(dir, (eventType, filename) => {
-    if (filename && filename.endsWith(".live.jsonl")) {
+    if (filename && filename.endsWith(".jsonl")) {
       setupWatcher();
     }
   });
@@ -180,7 +180,24 @@ function processNewEvents(
 
   const { events, newOffset } = readEventsFromOffset(jsonlPath, offset);
 
+  // Recovery: detect pending unprocessed submit
   if (events.length === 0) {
+    const { events: allEvents } = readEventsFromOffset(jsonlPath, 0);
+    const lastSubmitIdx = allEvents.findLastIndex(e => e.type === "submit");
+    if (lastSubmitIdx >= 0) {
+      const afterSubmit = allEvents.slice(lastSubmitIdx + 1);
+      const hasNewActivity = afterSubmit.some(e =>
+        e.type === "comment" || e.type === "reply" ||
+        e.type === "approve" || e.type === "session-end"
+      );
+      if (!hasNewActivity) {
+        const roundStart = findCurrentRoundStartIndex(allEvents);
+        const currentRoundThreads = replayEventsToThreads(allEvents.slice(roundStart));
+        const resolved = currentRoundThreads.filter(t => t.status === "resolved");
+        const output = formatSubmitOutput(resolved, specPath);
+        return { approved: false, output, newOffset: offset };
+      }
+    }
     return { approved: false, output: "", newOffset: offset };
   }
 
@@ -193,6 +210,17 @@ function processNewEvents(
     return { approved: true, output: "", newOffset };
   }
 
+  // Check for submit event — priority over session-end
+  const hasSubmit = events.some((e) => e.type === "submit");
+  if (hasSubmit) {
+    const { events: allEvents } = readEventsFromOffset(jsonlPath, 0);
+    const roundStart = findCurrentRoundStartIndex(allEvents);
+    const currentRoundThreads = replayEventsToThreads(allEvents.slice(roundStart));
+    const resolved = currentRoundThreads.filter(t => t.status === "resolved");
+    const output = formatSubmitOutput(resolved, specPath);
+    return { approved: false, output, newOffset };
+  }
+
   // Check for session-end — TUI exited, break the loop
   const hasSessionEnd = events.some((e) => e.type === "session-end");
   if (hasSessionEnd) {
@@ -233,8 +261,6 @@ function formatWatchOutput(
   // Group events by type
   const newCommentThreadIds: string[] = [];
   const replyThreadIds: string[] = [];
-  const resolvedThreadIds: string[] = [];
-  const deletedThreadIds: string[] = [];
 
   const seen = new Set<string>();
 
@@ -249,14 +275,6 @@ function formatWatchOutput(
       if (!replyThreadIds.includes(tid)) {
         replyThreadIds.push(tid);
       }
-    } else if (event.type === "resolve") {
-      if (!resolvedThreadIds.includes(tid)) {
-        resolvedThreadIds.push(tid);
-      }
-    } else if (event.type === "delete") {
-      if (!deletedThreadIds.includes(tid)) {
-        deletedThreadIds.push(tid);
-      }
     }
   }
 
@@ -315,31 +333,6 @@ function formatWatchOutput(
     }
   }
 
-  // Resolved threads
-  if (resolvedThreadIds.length > 0) {
-    lines.push("=== Resolved ===");
-    for (const tid of resolvedThreadIds) {
-      const thread = threadsById.get(tid);
-      if (!thread) continue;
-      lines.push(`Thread: ${tid} (line ${thread.line}) — resolved`);
-      lines.push("");
-    }
-  }
-
-  // Deleted threads
-  if (deletedThreadIds.length > 0) {
-    lines.push("=== Deleted ===");
-    for (const tid of deletedThreadIds) {
-      const thread = threadsById.get(tid);
-      if (thread) {
-        lines.push(`Thread: ${tid} (line ${thread.line}) — deleted`);
-      } else {
-        lines.push(`Thread: ${tid} — deleted`);
-      }
-      lines.push("");
-    }
-  }
-
   // Add footer instruction
   const hasActionable = newCommentThreadIds.length > 0 || replyThreadIds.length > 0;
   if (hasActionable) {
@@ -368,6 +361,41 @@ function getContext(
   return result;
 }
 
+function findCurrentRoundStartIndex(events: LiveEvent[]): number {
+  let count = 0;
+  for (let i = events.length - 1; i >= 0; i--) {
+    if (events[i].type === "submit") {
+      count++;
+      if (count === 2) return i + 1;
+    }
+  }
+  return 0;
+}
+
+function formatSubmitOutput(
+  resolvedThreads: Thread[],
+  specPath: string
+): string {
+  const lines: string[] = [];
+  lines.push("=== Submit: Rewrite Requested ===");
+  lines.push("");
+  if (resolvedThreads.length > 0) {
+    lines.push("Resolved threads:");
+    for (const t of resolvedThreads) {
+      const reviewerMsgs = t.messages.filter(m => m.author === "reviewer");
+      const ownerMsgs = t.messages.filter(m => m.author === "owner");
+      lines.push(`  ${t.id} (line ${t.line}): "${reviewerMsgs.map(m => m.text).join("; ")}"`);
+      if (ownerMsgs.length > 0) {
+        lines.push(`    → AI: "${ownerMsgs.map(m => m.text).join("; ")}"`);
+      }
+    }
+    lines.push("");
+  }
+  lines.push(`Rewrite the spec incorporating the above, then run: revspec watch ${basename(specPath)}`);
+  lines.push("");
+  return lines.join("\n");
+}
+
 function cleanupFiles(lockPath: string, offsetPath: string): void {
   if (existsSync(lockPath)) unlinkSync(lockPath);
   if (existsSync(offsetPath)) unlinkSync(offsetPath);