Feat/pending json

[jsdevninja]

What changed

Added --json support to vouch pending, emitting pending proposals as a structured JSON array while keeping the existing human-readable output unchanged. Also added CLI test coverage for empty JSON output, populated JSON output, and the existing text output, plus a CHANGELOG.md entry under ## [Unreleased].

Closes #88

Why

This makes pending proposal queues easier to consume from shell scripts, CI checks, and multi-agent review tooling. The docs already show vouch pending --json for grouping pending proposals by agent, but the CLI did not support that flag yet.

What might break

This should not break existing .vouch/ directories. No files move, no on-disk fields change shape, no bundle format changes, no audit-log shape changes, and no kb.* method behavior changes. The existing vouch pending text output is preserved.

VEP

No VEP needed. This is an additive CLI output flag only and does not change the object model, kb.* method surface, on-disk layout, bundle format, audit-log shape, config.yaml defaults, or transports.

Tests

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

Summary by CodeRabbit

Release Notes

• New Features

  • Added --json output option to vouch pending for structured proposal data
  • New vouch diff command compares two artifact versions with field-level and text changes
  • Enhanced vouch review with --limit, --type filtering and --dry-run options
  • Expanded onboarding guidance for vouch init

• Documentation

  • Updated README with new CLI commands
  • Added design specification for diff feature

[coderabbitai]

Caution

Review failed

Failed to post review comments

📝 Walkthrough

Walkthrough

This PR introduces three new CLI features for the Vouch knowledge base tool: a vouch diff command for comparing artifact revisions, JSON output for the vouch pending command, and an enhanced vouch review interactive queue with filtering and dry-run modes. The changes include new core diff logic, CLI command integration, comprehensive test coverage, and documentation updates.

Changes

CLI Feature Expansion: Artifact Diff, Pending JSON, and Review Enhancements

Layer / File(s)	Summary
Artifact diff specification and implementation docs/superpowers/specs/2026-05-25-vouch-diff-design.md, src/vouch/diff.py, tests/test_diff.py	Design specification and diff.py module implement artifact revision comparison: kind resolution via KBStore, field-level scalar/list change detection with Enum normalization, unified line-diff rendering for long text (claim.text / page.body), and DiffError exception handling. Core diff_artifacts function tested for claim/page diffs, no-op identical artifacts, unknown IDs, and kind mismatch.
Diff CLI command and output src/vouch/cli.py, tests/test_cli.py	vouch diff <old-id> <new-id> [--json] command wired into CLI via diff_artifacts, with JSON serialization via asdict and human-readable field/text change formatting. CLI tests validate --json output structure, "no differences" messaging, changed field/diff rendering, and clean error output for unknown artifacts.
Pending proposals JSON output src/vouch/cli.py, tests/test_cli.py	vouch pending --json extends the pending command to emit proposal objects as a JSON array. Tests verify empty queue returns [] and populated queue serializes proposal shape correctly, alongside human-readable output assertions.
Review command with filtering and dry-run src/vouch/cli.py, tests/test_cli.py	vouch review [--limit N] [--type KIND] [--dry-run] refactors the interactive review loop with proposal preview helpers, approval/rejection prompts, required rejection reason input, and conditional state mutation based on dry-run flag. Tests confirm approval/rejection update proposal status and decision_reason, skip/quit leave proposals pending, and --dry-run produces "Would …" output without persisting state changes.
Documentation updates CHANGELOG.md, README.md	Updates to Unreleased changelog and CLI surface documentation record the new vouch pending --json, vouch diff, and vouch review commands/options.

Estimated code review effort

🎯 3 (Moderate) | ⏱️ ~25 minutes

Possibly related issues

• #88: Requests --json output for the pending command, directly addressed by the pending(as_json: bool) signature update and JSON serialization in this PR.

Possibly related PRs

• vouchdev/vouch#86: Implements the same vouch diff feature with identical src/vouch/diff.py module structure and CLI wiring.
• vouchdev/vouch#84: Implements both the new vouch review guided queue (with --limit, --type, --dry-run) and vouch diff command, overlapping substantially with this PR's scope.

Poem

🐰 A diff for every claim, a queue for every review,
JSON pending proposals, and dry-runs too—
Three features bloomed where once were bare,
The vouch CLI now has flair! ✨

🚥 Pre-merge checks | ✅ 3 | ❌ 2

❌ Failed checks (1 warning, 1 inconclusive)

Check name	Status	Explanation	Resolution
Docstring Coverage	⚠️ Warning	Docstring coverage is 21.21% which is insufficient. The required threshold is 80.00%.	Write docstrings for the functions missing them to satisfy the coverage threshold.
Title check	❓ Inconclusive	The title "Feat/pending json" is vague and generic, using format-style labels rather than describing the actual change. While it references 'pending json', it lacks clarity about what the feature does.	Revise the title to be more descriptive, such as 'Add --json flag to pending command for structured output' to clearly communicate the primary change to reviewers.

✅ Passed checks (3 passed)

Check name	Status	Explanation
Description Check	✅ Passed	Check skipped - CodeRabbit’s high-level summary is enabled.
Linked Issues check	✅ Passed	Check skipped because no linked issues were found for this pull request.
Out of Scope Changes check	✅ Passed	Check skipped because no linked issues were found for this pull request.

_{✏️ 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]

[jsdevninja]

@plind-junior Would you review please?

[plind-junior]

LGTM! Thanks