revspec 0.6.0 → 0.7.1

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,20 +27,7 @@ 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** — ` ``` ` 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
 
@@ -52,7 +39,7 @@ Revspec renders markdown in-place (toggle with `m`):
 | `gg` / `G` | Go to top / bottom |
 | `Ctrl+D/U` | Half page down/up |
 | `zz` | Center cursor line in viewport |
-| `/` | Search (smartcase: lowercase = case-insensitive, any uppercase = case-sensitive) |
+| `/` | Search (smartcase) |
 | `n/N` | Next/prev search match |
 | `Esc` | Clear search highlights |
 | `]t/[t` | Next/prev thread |
@@ -66,68 +53,88 @@ Revspec renders markdown in-place (toggle with `m`):
 | `r` | Resolve thread (toggle) |
 | `R` | Resolve all pending |
 | `dd` | Delete thread (with confirm) |
-| `T` | List threads |
-| `a` | Approve spec |
+| `t` | List threads |
+| `S` | Submit for rewrite (AI updates spec, TUI reloads) |
+| `A` | Approve spec (finalize and exit) |
 
 **Commands**
 
 | Key | Action |
 |-----|--------|
-| `:w` | Merge changes to review JSON |
-| `:wq` / `:qw` | Merge and quit |
-| `:q` | Quit (blocks if unsaved) |
-| `:q!` | Quit without merging |
-| `:{N}` | Jump to line N (e.g. `:42`) |
-| `Ctrl+C` | Quit without merging |
+| `: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, `gg/G` top/bottom, `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
@@ -143,46 +150,31 @@ Then use `/revspec` in Claude Code after generating a spec.
 ## Testing
 
 ```bash
-bun test                    # Run all tests (~70s)
-bun test test/e2e           # E2E snapshot tests only (~66s)
-bun test --update-snapshots # Regenerate snapshots after UI changes
+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 screen output, and compare against saved snapshots. Covers: navigation, search, overlays (help, comment, thread list, confirm), thread creation/resolve/delete, command mode, and context-sensitive hints.
+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,10 +1,24 @@
 {
   "name": "revspec",
-  "version": "0.6.0",
+  "version": "0.7.1",
+  "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/unit test/integration",

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)) {