feat: let coding agents read and act on local review comments

Merged
DA
2mo ago
+2025-223

Summary

Closes #58.

Reviewers can already leave line-anchored local comments in the Stage UI (#68), but nothing exposed them to a coding agent. This PR adds the other half of the loop: a stagereview comments command group that reads and writes the existing comment_thread / comment tables directly (no server required), author attribution so the UI can tell agent replies from the human's notes, a stage-resolve skill that walks an agent through open threads, and light polling so the browser reflects CLI-side changes without a refresh. No new feedback model or export file — it reuses the comment tables from #68.

Changes

  • stagereview comments CLI (packages/cli/src/comments/): list [--status open|resolved|all] [--json], show <id>, reply <id> --body, resolve <id> [--body], reopen <id>, create --file --line [--end-line] [--side] --body. list/create accept the same [refs...], --base, --compare, --ref, --pr selectors as prep/show and resolve the scope through the same code path, so comments list --pr 123 addresses the threads the UI shows for that PR. Thread IDs accept a full UUID or an unambiguous prefix of 6+ characters, with clear errors for no match / ambiguous match.
  • Shared diff-scope options (diff-scope-options.ts): the [refs...]/--base/--compare/--pr/--ref surface is registered once via addDiffScopeOptions and used by prep, show, and comments.
  • LocalCommentThreadStore (runs/local-comment-threads.ts): thread persistence shared by the HTTP routes and the CLI; the routes keep only HTTP concerns (origin checks, promotion locks, status codes).
  • Author attribution: new comment.authorType column (user | agent, as const value set in @stagereview/types/comments) with migration 0008; HTTP routes write user, the CLI writes agent. Exposed on the comment and review wire types and rendered as a small "Agent" badge next to "Local" in the review UI.
  • UI freshness: useReview now sets a refetchInterval (3s for local-only runs, 15s for GitHub-backed runs since those hit the GitHub API on every fetch).
  • Skill + docs: new installable skills/stage-resolve/SKILL.md; short comment-loop sections in skills/stage-chapters/SKILL.md and the README.

Known limitation

The scope key is derived from git state, exactly as show does it. If the working tree was clean when the review was opened (committed scope) and the agent then edits files, a later argument-less comments list resolves to the working-tree scope and won't see the original threads. show/reply/resolve/reopen are addressed by ID and unaffected; the skill tells the agent to list before editing and to work from IDs. A follow-up could let list fall back to the most recent run's scope for the repo.

Testing

  • pnpm typecheck && pnpm lint && pnpm test (773 tests) and pnpm build pass locally; pnpm db:generate reports no pending changes.
  • New Vitest coverage:
    • comments-cli.test.ts: list/show/reply/resolve/reopen/create against a real temp SQLite DB, status filtering, scope isolation, agent attribution, prefix matching (too short / no match / ambiguous), and human-readable formatting.
    • comments-cli-scope.test.ts: scope-key parity with show in a temp git repo (clean branch → committed, dirty tree → working tree, explicit --ref staged and --base/--compare).
    • comments.routes.test.ts: authorType: "user" on threads and replies created through the HTTP routes.
    • migration-comment-author-type.test.ts: migration 0008 backfills existing comments as user.
  • Smoke-tested the built CLI end to end in a scratch repo: list → create → reply by prefix → resolve with body → reopen → show, plus the error paths (short prefix, inverted line range, --pr combined with --base).

Open workspace in Conductor

Summary by cubic

Lets coding agents read and act on local review comments: adds a stagereview comments CLI that reads and writes the existing comment_thread/comment tables directly (no server required), a comment.authorType column so the UI distinguishes agent replies from the human's notes, a stage-resolve skill, and browser polling so CLI-side changes appear without a refresh. Closes #58.

Bug Fixes

  • The working-tree scope key changes once the agent edits files, so an argument-less list may miss threads from a review opened on a clean tree; show/reply/resolve/reopen are ID-based and unaffected, and the skill instructs the agent to list before editing.
  • create, reply, and resolve reject whitespace-only --body values.

Migration

  • Existing comments backfill as authorType: "user" via migration 0008.