docs: use exact ranges for last-commit reviews

.claude-plugin/skills/revdiff/references/usage.md

@@ -11,7 +11,7 @@ revdiff              # review uncommitted changes
 revdiff main         # review changes against a branch
 revdiff --staged     # review staged changes
 revdiff --untracked  # show untracked files in the tree
-revdiff HEAD~1       # review last commit
+revdiff HEAD~1 HEAD  # review last commit
 revdiff main feature # diff between two refs
 revdiff main..feature  # same as above, git dot-dot syntax
 revdiff main...feature # changes since feature diverged from main

README.md

@@ -129,17 +129,17 @@ Priority: agterm → tmux → Zellij → herdr → kitty → wezterm/Kaku → cm
 
 ```
 /revdiff                  -- smart detection: uncommitted, last commit, or branch diff
-/revdiff HEAD~1           -- review last commit
+/revdiff HEAD~1 HEAD      -- review last commit
 /revdiff main             -- review current branch against main
 /revdiff --staged         -- review staged changes only
-/revdiff HEAD~3           -- review last 3 commits
+/revdiff HEAD~3 HEAD      -- review last 3 commits
 ```
 
 **Use with free text** (no slash command needed):
 
 ```
 "review diff"                     -- smart detection, same as /revdiff
-"review diff HEAD~1"              -- last commit
+"review diff HEAD~1 HEAD"         -- last commit
 "review diff against main"        -- branch diff
 "review changes from last 2 days" -- Claude resolves the ref automatically
 "revdiff for staged changes"      -- staged only
@@ -219,7 +219,7 @@ Useful args:
 
 ```text
 /revdiff                         -- detect uncommitted, staged, or branch changes, then open revdiff
-/revdiff HEAD~1                  -- review last commit
+/revdiff HEAD~1 HEAD             -- review last commit
 /revdiff main                    -- review against main
 /revdiff --staged                -- review staged changes
 /revdiff --untracked             -- include untracked files in working-tree review
@@ -327,7 +327,7 @@ The setup script copies files to `~/.config/opencode/` and registers the plan-re
 
 ```text
 /revdiff                         -- review git diff with revdiff TUI
-/revdiff HEAD~3                  -- review last 3 commits
+/revdiff HEAD~3 HEAD             -- review last 3 commits
 ```
 
 The plan-review plugin automatically launches revdiff when the assistant exits plan mode, letting you annotate before approval.
@@ -358,6 +358,7 @@ revdiff [OPTIONS] [base] [against]
 Positional arguments support several forms:
 - `revdiff` — uncommitted changes
 - `revdiff HEAD~3` — diff a single ref against the working tree
+- `revdiff HEAD~1 HEAD` — review exactly the last commit
 - `revdiff main feature` — diff between two refs
 - `revdiff main..feature` — same as above, using git's dot-dot syntax
 - `revdiff main...feature` — changes since `feature` diverged from `main`
@@ -554,7 +555,7 @@ revdiff main
 revdiff --staged
 
 # review last commit
-revdiff HEAD~1
+revdiff HEAD~1 HEAD
 
 # diff between two refs
 revdiff main feature

docs/backlog/jj-head-caret-refs-silently-mistranslated.md

@@ -0,0 +1,22 @@
+# jj mistranslates `HEAD^!` and approximates `HEAD^N`
+
+`(*Jj).translateRef` in `app/diff/jj.go` has a broad `strings.HasPrefix(ref, "HEAD^")` branch that
+swallows two different inputs and answers both with `parents(@-)`:
+
+- `HEAD^!` is git revision-set syntax jj does not support. It becomes `parents(@-)`, and
+  `diffRangeFlags` then builds `--from parents(@-) --to @`, so the user gets a grandparent-to-working-copy
+  diff that looks plausible and carries no error, while git rejects `HEAD^!..HEAD` for the commit log
+  and hg emits the invalid revset `p!(.)`, so jj is the only backend that fails silently here.
+- `HEAD^N` for N greater than 1 means the Nth parent. The branch's own comment admits jj cannot single
+  out an individual parent in one revset step and calls `parents(@-)` a best-effort approximation.
+
+Found while investigating #335 (closed as not planned); not part of that issue and not caused by it.
+hg's equivalent needs no change: its `pN(.)` mapping is correct.
+
+Not pre-deciding the fix. Two options, and they can differ per input: fail closed on a malformed
+suffix so the user sees a rejection instead of wrong data, or implement exact Nth-parent selection if
+jj can express it. Rejecting `HEAD^N` is a behavior change beyond a bug fix, so it needs a decision.
+
+A regression must assert at the public operation, e.g. `ChangedFiles("HEAD^!", false)` returning an
+error against a real jj repo. Asserting that `translateRef` returns the raw string does not prove the
+user ever sees the rejection.

plugins/codex/README.md

@@ -56,7 +56,7 @@ Interactive diff review with inline annotations.
 
 ```text
 /revdiff              — auto-detect ref (uncommitted, staged, branch vs master, or last commit)
-/revdiff HEAD~3       — review last 3 commits
+/revdiff HEAD~3 HEAD  — review last 3 commits
 /revdiff main feature — two-ref diff
 /revdiff all files    — browse all tracked files
 /revdiff path/to/file — review a single file

plugins/codex/skills/revdiff/references/usage.md

@@ -11,7 +11,7 @@ revdiff              # review uncommitted changes
 revdiff main         # review changes against a branch
 revdiff --staged     # review staged changes
 revdiff --untracked  # show untracked files in the tree
-revdiff HEAD~1       # review last commit
+revdiff HEAD~1 HEAD  # review last commit
 revdiff main feature # diff between two refs
 revdiff main..feature  # same as above, git dot-dot syntax
 revdiff main...feature # changes since feature diverged from main

plugins/pi/README.md

@@ -38,7 +38,7 @@ Useful args:
 
 ```text
 /revdiff                         -- detect uncommitted, staged, or branch changes, then open revdiff
-/revdiff HEAD~1                  -- review last commit
+/revdiff HEAD~1 HEAD             -- review last commit
 /revdiff main                    -- review against main
 /revdiff --staged                -- review staged changes
 /revdiff --untracked             -- include untracked files in working-tree review

plugins/pi/skills/revdiff/SKILL.md

@@ -18,7 +18,7 @@ Reference resolution rules:
 
 - Accept natural language. Resolve the user's requested target to concrete revdiff args before launching.
 - If the request identifies another working directory (for example `in ~/source/repo`), use that directory for any git/ref/path resolution, omit that directory phrase from the revdiff args, and pass the directory as the `revdiff_review` tool's `cwd` parameter.
-- For commit-count requests, use the matching git rev: `prev commit`, `previous commit`, `last commit` → `HEAD~1`; `head-3`, `head 3`, `HEAD~3`, `previous 3 commits`, `last 3 commits` → `HEAD~3`.
+- For natural-language commit-count requests, use two refs: `prev commit`, `previous commit`, `last commit` → `HEAD~1 HEAD`; `head-3`, `head 3`, `previous 3 commits`, `last 3 commits` → `HEAD~3 HEAD`.
 - For tag requests, resolve the actual tag first. `last tag` or `latest tag` → run `git describe --tags --abbrev=0`, then pass that tag as `args`.
 - For date requests, resolve the commit first. Examples: `2 weeks ago`, `yesterday`, `last Friday` → run `git rev-list -1 --before=<phrase> HEAD`, then pass the resulting commit hash as `args`.
 - For file targets, use `args: "--only <path>"`.
@@ -72,6 +72,7 @@ When annotations arrive from `/revdiff` or `revdiff_review`:
 ```text
 /revdiff
 /revdiff HEAD~1
+/revdiff HEAD~1 HEAD
 /revdiff main
 /revdiff --staged
 /revdiff --untracked

site/docs.html

@@ -135,7 +135,7 @@ <h3>Command inside pi</h3>
         <div class="code-block"><code>/revdiff [args]</code></div>
         <h3>Useful args</h3>
         <div class="code-block"><code>/revdiff                         <span class="code-comment">-- detect uncommitted, staged, or branch changes, then open revdiff</span>
-/revdiff HEAD~1                  <span class="code-comment">-- review last commit</span>
+/revdiff HEAD~1 HEAD             <span class="code-comment">-- review last commit</span>
 /revdiff main                    <span class="code-comment">-- review against main</span>
 /revdiff --staged                <span class="code-comment">-- review staged changes</span>
 /revdiff --untracked             <span class="code-comment">-- include untracked files in working-tree review</span>
@@ -180,6 +180,7 @@ <h2 id="usage">Usage</h2>
         <ul>
             <li><code>revdiff</code> &mdash; uncommitted changes</li>
             <li><code>revdiff HEAD~3</code> &mdash; diff a single ref against the working tree</li>
+            <li><code>revdiff HEAD~1 HEAD</code> &mdash; review exactly the last commit</li>
             <li><code>revdiff main feature</code> &mdash; diff between two refs</li>
             <li><code>revdiff main..feature</code> &mdash; same as above, git dot-dot syntax</li>
             <li><code>revdiff main...feature</code> &mdash; changes since feature diverged from main</li>
@@ -197,7 +198,7 @@ <h2 id="examples">Examples</h2>
 revdiff --staged
 
 <span class="code-comment"># review last commit</span>
-revdiff HEAD~1
+revdiff HEAD~1 HEAD
 
 <span class="code-comment"># diff between two refs</span>
 revdiff main feature
@@ -722,14 +723,14 @@ <h2 id="plugin-terminals">Terminal support</h2>
         <h2 id="plugin-usage">Plugin usage</h2>
         <h3>Slash commands</h3>
         <div class="code-block"><code>/revdiff                  <span class="code-comment">-- smart detection: uncommitted, last commit, or branch diff</span>
-/revdiff HEAD~1           <span class="code-comment">-- review last commit</span>
+/revdiff HEAD~1 HEAD      <span class="code-comment">-- review last commit</span>
 /revdiff main             <span class="code-comment">-- review current branch against main</span>
-/revdiff HEAD~3           <span class="code-comment">-- review last 3 commits</span>
+/revdiff HEAD~3 HEAD      <span class="code-comment">-- review last 3 commits</span>
 /revdiff --staged         <span class="code-comment">-- review staged changes only</span>
 /revdiff all files        <span class="code-comment">-- browse all tracked files</span></code></div>
         <h3>Natural language</h3>
         <div class="code-block"><code>"review diff"                       <span class="code-comment">-- same as /revdiff, smart detection</span>
-"review diff HEAD~1"                <span class="code-comment">-- last commit</span>
+"review diff HEAD~1 HEAD"           <span class="code-comment">-- last commit</span>
 "review diff against main"          <span class="code-comment">-- branch diff</span>
 "review changes from last 2 days"   <span class="code-comment">-- Claude resolves the ref</span>
 "revdiff for staged changes"        <span class="code-comment">-- staged only</span>
@@ -801,7 +802,7 @@ <h2 id="codex-skills">Skills</h2>
         </ul>
         <p>Codex treats exit code <code>10</code> as success-with-annotations and keeps captured output.</p>
         <div class="code-block"><code>/revdiff              <span class="code-comment"># auto-detect ref</span>
-/revdiff HEAD~3       <span class="code-comment"># review last 3 commits</span>
+/revdiff HEAD~3 HEAD  <span class="code-comment"># review last 3 commits</span>
 /revdiff-plan         <span class="code-comment"># review last Codex response</span></code></div>
 
         <h2 id="codex-differences">Differences from Claude Code plugin</h2>
@@ -825,7 +826,7 @@ <h2 id="opencode-usage">Usage</h2>
             <li>Plan-review plugin &mdash; automatically launches revdiff when the assistant exits plan mode, injecting annotations back as user messages</li>
         </ul>
         <div class="code-block"><code>/revdiff              <span class="code-comment"># auto-detect ref</span>
-/revdiff HEAD~3       <span class="code-comment"># review last 3 commits</span>
+/revdiff HEAD~3 HEAD  <span class="code-comment"># review last 3 commits</span>
 /revdiff --staged     <span class="code-comment"># review staged changes</span></code></div>
 
         <!-- output -->

site/index.html

@@ -410,16 +410,16 @@ <h3>Annotate &amp; fix</h3>
         <div class="plugin-examples">
             <h3>Slash commands</h3>
             <div class="code-block"><code>/revdiff                  <span class="code-comment">-- smart detection: uncommitted, last commit, or branch diff</span>
-/revdiff HEAD~1           <span class="code-comment">-- review last commit</span>
+/revdiff HEAD~1 HEAD      <span class="code-comment">-- review last commit</span>
 /revdiff main             <span class="code-comment">-- review current branch against main</span>
-/revdiff HEAD~3           <span class="code-comment">-- review last 3 commits</span>
+/revdiff HEAD~3 HEAD      <span class="code-comment">-- review last 3 commits</span>
 /revdiff --staged         <span class="code-comment">-- review staged changes only</span>
 /revdiff all files        <span class="code-comment">-- browse all tracked files in the project</span></code></div>
         </div>
         <div class="plugin-examples">
             <h3>Natural language</h3>
             <div class="code-block"><code>"review diff"                       <span class="code-comment">-- same as /revdiff, smart detection</span>
-"review diff HEAD~1"                <span class="code-comment">-- last commit</span>
+"review diff HEAD~1 HEAD"           <span class="code-comment">-- last commit</span>
 "review diff against main"          <span class="code-comment">-- branch diff</span>
 "review changes from last 2 days"   <span class="code-comment">-- Claude resolves the ref</span>
 "revdiff for staged changes"        <span class="code-comment">-- staged only</span>