feat(diff): add vouch diff for claim/page revisions#86
Conversation
read-only `vouch diff <old> <new>` that shows what changed between two claim or two page revisions: field-level changes plus a line-diff of the long text/body. auto-detects kind, hides churning metadata.
new read-only `vouch diff <old> <new>` compares two claims or two pages by id and shows what changed: scalar/list fields as old → new, plus a line-diff of the long text/body. auto-detects kind, hides churning metadata (timestamps, approved_by), supports --json. closes a roadmap 0.1 item.
|
Important Review skippedAuto reviews are disabled on base/target branches other than the default branch. Please check the settings in the CodeRabbit UI or the ⚙️ Run configurationConfiguration used: defaults Review profile: CHILL Plan: Pro Plus Run ID: You can disable this status message by setting the Use the checkbox below for a quick retry:
📝 WalkthroughWalkthroughThis PR introduces a read-only Changesvouch diff feature
Estimated code review effort🎯 3 (Moderate) | ⏱️ ~20 minutes Poem
🚥 Pre-merge checks | ✅ 4 | ❌ 1❌ Failed checks (1 warning)
✅ Passed checks (4 passed)
✏️ Tip: You can configure your own custom pre-merge checks in the settings. ✨ Finishing Touches🧪 Generate unit tests (beta)
Comment |
mypy inferred old/new as Claim from the first branch, so the page branch's reassignment tripped an incompatible-assignment error in CI. annotate the union up front.
![coderabbitai[bot]](https://avatars.githubusercontent.com/in/347564?s=60&v=4){kind=small}
There was a problem hiding this comment.
Actionable comments posted: 1
🤖 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 `@docs/superpowers/specs/2026-05-25-vouch-diff-design.md`:
- Around line 63-73: The fenced code block showing the diff (the triple-backtick
block containing "diff claim <old> → <new>" and the lines starting with status:,
confidence:, evidence:, text:, --- a, +++ b, etc.) is missing a language tag and
triggers markdownlint MD040; update the opening fence from ``` to ```text (or
another appropriate language like diff) so the block becomes ```text diff claim
<old> → <new> ... to satisfy MD040 and preserve the displayed content.
🪄 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: ce03b50c-fa94-403c-8915-d15bd467d0e6
📒 Files selected for processing (5)
CHANGELOG.mddocs/superpowers/specs/2026-05-25-vouch-diff-design.mdsrc/vouch/cli.pysrc/vouch/diff.pytests/test_diff.py
| ``` | ||
| diff claim <old> → <new> | ||
| status: working → stable | ||
| confidence: 0.7 → 0.9 | ||
| evidence: ['s1'] → ['s1', 's2'] | ||
| text: | ||
| --- a | ||
| +++ b | ||
| -old wording | ||
| +new wording | ||
| ``` |
There was a problem hiding this comment.
Add a language tag to the fenced code block.
Line 63 starts a fenced block without a language, which triggers markdownlint MD040.
🧩 Suggested fix
-```
+```text
diff claim <old> → <new>
status: working → stable
confidence: 0.7 → 0.9
evidence: ['s1'] → ['s1', 's2']
text:
--- a
+++ b
-old wording
+new wording</details>
<details>
<summary>🧰 Tools</summary>
<details>
<summary>🪛 markdownlint-cli2 (0.22.1)</summary>
[warning] 63-63: Fenced code blocks should have a language specified
(MD040, fenced-code-language)
</details>
</details>
<details>
<summary>🤖 Prompt for AI Agents</summary>
Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.
In @docs/superpowers/specs/2026-05-25-vouch-diff-design.md around lines 63 - 73,
The fenced code block showing the diff (the triple-backtick block containing
"diff claim → " and the lines starting with status:, confidence:,
evidence:, text:, --- a, +++ b, etc.) is missing a language tag and triggers
markdownlint MD040; update the opening fence from totext (or another
appropriate language like diff) so the block becomes ```text diff claim →
... to satisfy MD040 and preserve the displayed content.
</details>
<!-- fingerprinting:phantom:poseidon:hawk -->
<!-- This is an auto-generated comment by CodeRabbit -->
1 participant
Problem
When a claim is superseded or a page is revised, there's no way to see what
changed between the old and new artifact — you have to
showboth and compareby eye. ROADMAP 0.1 lists
vouch diff <id-old> <id-new>for exactly this.What this adds
A read-only
vouch diff <id-old> <id-new>that compares two claim revisions ortwo page revisions:
mismatched kinds or unknown ids raise a clean error (no
--kindflag).field: old → newandhides always-churning metadata (
created_at,updated_at,approved_by).claim.text/page.bodyrender as adifflibunified diff.--jsonfor machine output;no differenceswhen nothing changed.Example:
New module
src/vouch/diff.py(diff_artifacts,DiffError,FieldChange,ArtifactDiff); CLI command insrc/vouch/cli.py.DiffErrorsubclassesValueErrorso the existing_cli_errors()renders it as a cleanError:line.CLI-only — the
kb.*capability surface is unchanged.Tests
10 new tests (
tests/test_diff.py), written test-first:diff_artifacts: scalar field changes; text line-diff; identical → empty;page title/body; unknown id →
DiffError; claim-vs-page →DiffError.--jsonemits a dict; identical →no differences; unknown id → cleanError:(no traceback).ruffclean. Full suite green except one pre-existing, unrelated failure onmain(test_crystallize_cli_partial_failures_shows_warning).Design spec:
docs/superpowers/specs/2026-05-25-vouch-diff-design.md.Summary by CodeRabbit
New Features
vouch diff <id-old> <id-new>CLI command to compare two artifact revisions side-by-side, displaying field-level changes and unified text diffs with automatic artifact-kind detection; includes--jsonoutput for programmatic access.Documentation
Tests