feat: add guided proposal review CLI

[jsdevninja]

What changed

Added vouch review, a guided CLI queue for walking through pending proposals one at a time. It supports approve, reject, skip, quit, --limit, --type, and --dry-run, and documents the new command in README.md and CHANGELOG.md.

Closes #83

Why

Reviewing multiple proposals currently requires manually switching between vouch pending, vouch show <id>, vouch approve <id>, and vouch reject <id>. This makes the core review-gate workflow faster and easier while still using the existing approval and rejection paths.

What might break

This is an additive CLI-only change. No .vouch/ files move, no persisted field shapes change, and no kb.* methods behave differently. Existing .vouch/ directories should continue working unchanged.

VEP

No VEP needed. This does not change the object model, kb.* method surface, on-disk layout, bundle format, audit-log shape, default config semantics, or add a transport.

Tests

• make check passes locally (lint + mypy + pytest)
• New / changed behaviour has a test
• CHANGELOG.md updated under ## [Unreleased]

Summary by CodeRabbit

• New Features

  • Added vouch review — interactive queue to approve/reject/skip/quit proposals with --limit, --type, and --dry-run.
  • Added vouch diff <id-old> <id-new> — read-only artifact diffs with per-field summaries, unified text/line diffs, and --json output.

• Tests

  • Added end-to-end and unit tests covering review and diff behaviors, dry-run, error cases, and CLI output.

• Documentation

  • Updated README and changelog; added design spec for the diff command.

[coderabbitai]

Caution

Review failed

Failed to post review comments

📝 Walkthrough

Walkthrough

Adds a read-only artifact diff feature (field-level changes + unified text diff, human/JSON CLI) and a new interactive CLI command vouch review to walk pending proposals with approve/reject/skip/quit and dry-run support; both include tests and docs.

Changes

vouch diff

Layer / File(s)	Summary
Design, spec, and changelog docs/superpowers/specs/2026-05-25-vouch-diff-design.md, CHANGELOG.md	Spec and changelog describe artifact kind resolution, field sets to diff, unified text diff for long fields, CLI contract, error handling, and TDD scenarios.
Diff implementation and CLI src/vouch/diff.py, src/vouch/cli.py	Adds DiffError, FieldChange, ArtifactDiff, kind detection, normalization, unified line-diff, diff_artifacts(store, old, new), and vouch diff CLI that emits JSON or a human-readable field+text diff.
Tests and CLI integration tests/test_diff.py	Filesystem-backed store fixture and tests cover claim/page diffs, identical/no-diff cases, mismatched/unknown ids, and CLI end-to-end checks including --json and clean error messages.

Interactive Proposal Review Command

Layer / File(s)	Summary
Docs and imports CHANGELOG.md, README.md, src/vouch/cli.py	CHANGELOG and README document the vouch review command; cli imports Proposal and ProposalKind needed for filtering/formatting.
Interactive review command and helpers src/vouch/cli.py	Adds formatting helpers and review() which lists pending proposals (optional --type, --limit), prompts for approve/reject/skip/quit, enforces rejection reason, supports --dry-run (no mutations), and prints a completion summary.
Review command test coverage tests/test_cli.py	Tests exercise approval, rejection with reason, skip+quit leaving proposals pending, and dry-run approve/reject verifying messaging and no store mutations.

Estimated code review effort

🎯 4 (Complex) | ⏱️ ~45 minutes

Possibly related PRs

• vouchdev/vouch#86: Overlaps with the added vouch diff implementation, tests, and documentation.

Poem

🐰
In burrows of bytes I quietly comb,
Two new paths help reviewers roam,
Diff shows the changes, line by line,
Review hops proposals—approve or decline,
Dry-run first, then let the ledger home.

🚥 Pre-merge checks | ✅ 4 | ❌ 1

❌ Failed checks (1 warning)

Check name	Status	Explanation	Resolution
Docstring Coverage	⚠️ Warning	Docstring coverage is 33.33% which is insufficient. The required threshold is 80.00%.	Write docstrings for the functions missing them to satisfy the coverage threshold.

✅ Passed checks (4 passed)

Check name	Status	Explanation
Description Check	✅ Passed	Check skipped - CodeRabbit’s high-level summary is enabled.
Title check	✅ Passed	The title 'feat: add guided proposal review CLI' directly and concisely describes the main change: a new CLI command for guided proposal review.
Linked Issues check	✅ Passed	The PR fully implements the requirements from issue #83: adds a vouch review CLI command with guided queue navigation (approve, reject, skip, quit), supports filtering and limiting, includes documentation, and reuses existing approval/rejection paths.
Out of Scope Changes check	✅ Passed	All changes are scoped to the guided proposal review feature: new review and diff CLI commands, supporting utility code, documentation, and tests. The diff command is a closely related utility that enhances the review workflow by allowing field-level comparisons.

_{✏️ Tip: You can configure your own custom pre-merge checks in the settings.}

✨ Finishing Touches

🧪 Generate unit tests (beta)

• Create PR with unit tests

---

_{Comment @coderabbitai help to get the list of available commands and usage tips.}

[jsdevninja]

@plind-junior would you please review this feature?

[coderabbitai]

Actionable comments posted: 2

🤖 Prompt for all review comments with AI agents

Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

Inline comments:
In `@README.md`:
- Line 145: The README CLI synopsis for the "vouch review" command omits the
supported --dry-run flag; update the synopsis line "vouch review [--limit N]
[--type KIND]" to include "[--dry-run]" (e.g., "vouch review [--limit N] [--type
KIND] [--dry-run]") and ensure any nearby CLI option list or examples mention
and briefly describe the --dry-run behavior so the documented surface matches
the implemented flag.

In `@tests/test_cli.py`:
- Around line 171-172: The test asserts the wrong exception type: update the
pytest.raises in tests/test_cli.py around the get_claim call so it expects the
actual exception raised by KBStore.get_claim—ArtifactNotFoundError—instead of
KeyError; ensure the test imports ArtifactNotFoundError (or references it from
its module) and replace pytest.raises(KeyError) with
pytest.raises(ArtifactNotFoundError) for the "review-dry-run" claim check.

🪄 Autofix (Beta)

Fix all unresolved CodeRabbit comments on this PR:

• Push a commit to this branch (recommended)
• Create a new PR with the fixes

---

ℹ️ Review info

⚙️ Run configuration

Configuration used: defaults

Review profile: CHILL

Plan: Pro Plus

Run ID: d8eb8a15-1ed5-455f-82c4-c795bbe43376

📥 Commits

Reviewing files that changed from the base of the PR and between dd83000 and dff95c7.

📒 Files selected for processing (4)

• CHANGELOG.md
• README.md
• src/vouch/cli.py
• tests/test_cli.py

[plind-junior]

@jsdevninja Would you attach the screenshot?

[jsdevninja]

[plind-junior]

@jsdevninja Plz create the PR against the test branch

[jsdevninja]

@plind-junior I updated PR to against the test branch.