@invariant.guru/cli 0.6.0 → 0.6.2

package/README.md

@@ -161,10 +161,36 @@ When the session is done, stamp it:
 invariant plan:complete <session-id> --summary "Booking command + tests"
 ```
 
-### 6. `invariant ui` — see and manage your sessions
+### 6. `invariant review` — have the diff read by someone who did not write it
+
+Composes a *review session*: a second session whose job is to review the branch
+and write the result into `doc/review/<branch>.xml`.
+
+```bash
+invariant review --session <session-id>   # review the work that session produced
+invariant review --base origin/develop    # diff against something else
+```
+
+Paste its execute line into a **new** agent conversation. That is the point: a
+fresh one has not seen the plan, so it reads the diff as evidence rather than as
+confirmation. It reviews exactly `git diff --cached $(git merge-base <base> HEAD)`
+— every commit on the branch plus whatever is staged, and nothing that is only in
+your working tree.
+
+You then rule on each comment (in the UI, or with `invariant review show`), and:
+
+```bash
+invariant review plan-changes <branch>
+```
+
+writes the comments you accepted into that same session's `## Plan` and moves it
+to `planned`. Executing it implements them. Nothing is ever committed or pushed —
+you stage and commit when you are happy.
+
+### 7. `invariant ui` — see and manage your sessions
 
 Opens a local dashboard for this project's sessions: a board grouped by status,
-rendered markdown, a rich editor, and a command palette.
+rendered markdown, a rich editor, review triage, and a command palette.
 
 ```bash
 invariant ui              # start on 4200 (or the next free port) and open a browser
@@ -184,6 +210,7 @@ invariant add nest-clean-architecture   # activate the whole module
 invariant sync
 invariant plan "add the cargo booking command"
 invariant ui                            # follow it through to done
+invariant review                        # then have the diff reviewed
 ```
 
 ---
@@ -415,6 +442,47 @@ invariant plan:complete session-uuid -n "Follow-up: rate limiting" -d 2026-08-19
 | `-n, --note <note>` | Extra note line (repeatable) |
 | `-d, --date <date>` | Completion date (`YYYY-MM-DD`), defaults to today |
 
+### `invariant review [options]`
+
+Compose a review session for the current branch. The session reviews the diff,
+waits for you to rule on every comment, and then implements the ones you
+accepted — one file, one conversation.
+
+```bash
+invariant review                               # review the current branch
+invariant review --session <session-id>        # link it to the work under review
+invariant review --base origin/develop         # diff against another ref
+invariant review list                          # every review document
+invariant review show <branch> --open          # what still needs a decision
+invariant review plan-changes <branch>         # accepted comments → the session's Plan
+```
+
+| Subcommand | Description |
+|--------|-------------|
+| *(none)* | Compose a review session for the current branch |
+| `list` | Every review document in the project (`--json`) |
+| `show <review>` | Print a review's comments (`--staged`, `--open`, `--json`) |
+| `plan-changes <review>` | Write the accepted comments into the session's `## Plan` |
+
+| Option | Description |
+|--------|-------------|
+| `-s, --session <session>` | The plan session whose work is under review |
+| `-b, --base <ref>` | Ref to diff against (default: `origin/main`, then `origin/master`, `main`, `master`) |
+
+Reviews land in `doc/review/<branch>.xml`, one file per branch, appended to on
+each pass. **`plan-changes` refuses while any comment is still undecided** —
+partial triage silently drops the comments nobody looked at, so it is not
+allowed. Nothing here touches the index or a remote: the git commands this tool
+may run are allowlisted to read-only ones.
+
+Configure it under `review` in `invariant.json`:
+
+```jsonc
+{ "review": { "directory": "doc/review", "baseBranch": "origin/main", "editor": "vscode" } }
+```
+
+See [docs/spec-review.md](docs/spec-review.md) for the document format.
+
 ### `invariant ui [port]`
 
 Start (or attach to) the local session UI for the current project, then open a
@@ -447,13 +515,15 @@ per-instance token kept in `~/.invariant/ui.json` (mode 0600). What it can read
 and write is limited to the directory it was started in.
 
 In the UI: `⌘K` opens the command palette, `⇧⌘V` toggles rendered preview and
-editing, `N` starts a session, `?` lists every shortcut.
+editing, `N` starts a session, `?` lists every shortcut. On a review session,
+`j`/`k` move between comments and `s` / `d` / `e` stage, discard, or edit one.
 
 To work on the UI itself: start a daemon (`invariant ui --no-open`), then run
 `yarn dev:ui` for Vite with hot reload against it — `INVARIANT_UI_PORT=<port>`
 when the daemon landed on something other than 4200.
 
-See [docs/spec-ui.md](docs/spec-ui.md) for the header contract and the HTTP API.
+See [docs/spec-ui.md](docs/spec-ui.md) for the header contract and the HTTP API,
+and [docs/spec-review.md](docs/spec-review.md) for reviews.
 
 ### `invariant scan`