@invariant.guru/cli 0.5.6 → 0.6.1

package/README.md

@@ -151,12 +151,56 @@ invariant plan "implement the cargo booking command" --context nest-clean-archit
 invariant plan "implement the cargo booking command" --full
 ```
 
+Every session file starts with a `<session-meta>` header carrying its title and
+status (`draft` → `planned` → `in-progress` → `executed`). The agent updates it
+as the work progresses; the UI reads it.
+
 When the session is done, stamp it:
 
 ```bash
 invariant plan:complete <session-id> --summary "Booking command + tests"
 ```
 
+### 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>.md`.
+
+```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, review triage, and a command palette.
+
+```bash
+invariant ui              # start on 4200 (or the next free port) and open a browser
+invariant ui status       # every running instance on this machine
+invariant ui stop         # stop this project's instance
+```
+
+Each directory gets its own instance on its own port, so several repositories can
+be open at once without ever mixing sessions.
+
 ### Full walkthrough
 
 ```bash
@@ -165,6 +209,8 @@ invariant install github:invariant-guru/inv-nest-clean-architecture
 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
 ```
 
 ---
@@ -381,7 +427,9 @@ invariant plan "implement user authentication" --context nest-clean-architecture
 
 ### `invariant plan:complete <session>`
 
-Stamp a completion header at the top of a finished session file.
+Mark a session finished: sets `<status>` to `executed` and stamps `<summary>` and
+`<completed>` in the session's `<session-meta>` header. Notes are appended to the
+body as a **Completion notes** section.
 
 ```bash
 invariant plan:complete session-uuid --summary "Auth command + e2e tests"
@@ -394,6 +442,89 @@ 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>.md`, 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
+browser. One instance per directory; the default port is 4200 and the next free
+port is used when it is taken.
+
+```bash
+invariant ui                    # start and open a browser
+invariant ui 4300               # ask for a specific port (fails if it is busy)
+invariant ui --no-open          # start without opening a browser
+invariant ui status --json      # machine-readable status of every instance
+invariant ui stop --all         # stop every instance on this machine
+invariant ui migrate-headers    # add <session-meta> headers to legacy sessions
+```
+
+| Subcommand | Description |
+|--------|-------------|
+| *(none)* / `start [port]` | Start or attach, then open a browser |
+| `stop` | Stop this project's instance (`--all` for every instance) |
+| `status` | Every instance, liveness-checked (`--json`) |
+| `migrate-headers` | Give legacy session files a canonical `<session-meta>` header |
+
+| Option | Description |
+|--------|-------------|
+| `-p, --port <port>` | Port to listen on (default 4200) |
+| `--no-open` | Do not open a browser window |
+
+The server binds `127.0.0.1` only, checks `Host` and `Origin`, and requires a
+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. 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,
+and [docs/spec-review.md](docs/spec-review.md) for reviews.
+
 ### `invariant scan`
 
 Scan the codebase with embedded tree-sitter grammars and write a CodeGraph to `.invariant/codegraph/` — a structured inventory of files, languages, and top-level symbols for LLM navigation.
@@ -533,6 +664,7 @@ After `init` + `install` + `sync`:
 │   ├── contexts/            # rendered contexts
 │   ├── instructions/        # rendered instructions
 │   ├── sessions/            # `invariant plan` output
+│   │   └── .archive/        # sessions archived from the UI
 │   └── codegraph/           # `invariant scan` output
 ├── .agents/                 # canonical store — the only physical copy
 │   ├── skills/<name>/SKILL.md