thurview 0.8.3 → 0.10.0

package/README.md

@@ -73,6 +73,7 @@ reads the Agent Skills format:
 
 ```sh
 npx skills add Thurbeen/thurview --skill thurview
+npx skills add Thurbeen/thurview --skill review-fix     # optional, see below
 ```
 
 That form tracks this repository's default branch: `skills update` takes
@@ -89,8 +90,8 @@ that matches the command you have installed. Use that when you want the two to
 move together.
 
 The skill drives the `thurview` command, which needs Node 22 or later and
-git (`gh` for pull requests). Install it, or let the skill reach it through
-`npx`:
+git (`gh` for pull requests, `glab` for merge requests). Install it, or let
+the skill reach it through `npx`:
 
 ```sh
 npm install -g thurview     # or: pnpm add -g thurview
@@ -168,19 +169,20 @@ bar.
 
 ## CLI
 
-| Command                                                               | Purpose                                                          |
-| --------------------------------------------------------------------- | ---------------------------------------------------------------- |
-| `thurview scaffold [--pr N \| --base R --head R]`                     | Create a review pinned to exact commits (`--update` re-pins)     |
-| `thurview explain [<path>] [--commit R]`                              | Create a code explainer of a codebase or subsystem at one commit |
-| `thurview info [--all]`                                               | Reviews bound to this worktree                                   |
-| `thurview publish --review ID [--view T] [--open]`                    | Validate the document and map, seal a revision                   |
-| `thurview open --review ID [--view T]`                                | Start the server if needed and open the browser                  |
-| `thurview wait --review ID [--timeout S]`                             | Block until the reader needs the agent                           |
-| `thurview threads list\|get\|reply\|resolve`                          | Read and answer threads                                          |
-| `thurview graph interfaces\|impact\|callers\|tests-for\|architecture` | Ask the code graph at the pinned commits                         |
-| `thurview serve` / `thurview stop`                                    | Run the server in the foreground / stop the background one       |
-| `thurview setup hooks\|skill\|status`                                 | Session hooks, agent skill, install state                        |
-| `thurview update`                                                     | Self-update from npm                                             |
+| Command                                                               | Purpose                                                           |
+| --------------------------------------------------------------------- | ----------------------------------------------------------------- |
+| `thurview scaffold [--pr N \| --base R --head R]`                     | Create a review pinned to exact commits (`--update` re-pins)      |
+| `thurview explain [<path>] [--commit R]`                              | Create a code explainer of a codebase or subsystem at one commit  |
+| `thurview info [--all]`                                               | Reviews bound to this worktree                                    |
+| `thurview publish --review ID [--view T] [--open]`                    | Validate the document and map, seal a revision                    |
+| `thurview open --review ID [--view T]`                                | Start the server if needed and open the browser                   |
+| `thurview wait --review ID [--timeout S]`                             | Block until the reader needs the agent                            |
+| `thurview threads list\|get\|reply\|resolve`                          | Read and answer threads                                           |
+| `thurview graph interfaces\|impact\|callers\|tests-for\|architecture` | Ask the code graph at a review's pins, or at `--base`/`--head`    |
+| `thurview forge status\|prior\|submit\|reply`                         | Read a change request through its forge, and post the review back |
+| `thurview serve` / `thurview stop`                                    | Run the server in the foreground / stop the background one        |
+| `thurview setup hooks\|skill\|status`                                 | Session hooks, agent skill, install state                         |
+| `thurview update`                                                     | Self-update from npm                                              |
 
 thurview is an [AXI](https://axi.md): built for agents that drive it through a
 shell. Output is [TOON](https://toonformat.dev) on stdout, errors are
@@ -192,6 +194,53 @@ arguments shows live state for the current directory instead of a manual.
 `thurview <command> --help` is the fallback. Progress and diagnostics go to
 stderr.
 
+## Review and fix
+
+The `review-fix` skill reviews a branch, a commit range or a pull or merge
+request, fixes what it is sure of and reports the rest, with no browser and no
+approval step. For each changed symbol it asks the code graph who calls it and
+which tests reach it, so a finding can name a caller the diff never shows.
+Fixes that pass the repository's own tests and lint land as one local commit;
+nothing is pushed unless you ask.
+
+```sh
+thurview graph impact --head HEAD                 # changed symbols, the callers they left alone, the tests
+thurview graph callers discount --head HEAD       # every call site of one symbol
+```
+
+`--base` and `--head` ask about two commits directly; `--head` alone diffs
+from where it forked from trunk. Each caller in `impact.reach` carries the line
+of its call and whether any test reaches it.
+
+With `--post`, the skill posts the findings it did not fix as inline comments
+on the change request, through `thurview forge`:
+
+```sh
+thurview forge status --change 123    # what CI actually did, and whether it is a gate at all
+thurview forge prior  --change 123    # the previous pass, thread by thread
+thurview forge submit --change 123 --file pass.json --dry-run
+thurview forge reply <threadId> --change 123 --body "<answer>" --resolve --at <head>
+```
+
+`status` counts passed, failed, cancelled, skipped and running checks
+separately, and compares them against what the target branch's own tip runs -
+a change request from a fork typically runs a fraction of them, and a
+cancelled job shows no failure while asserting nothing. `ci.trustworthy` is
+the only field that means the tests really passed.
+
+`submit` takes one JSON file so a human can read the pass before it is posted,
+refuses an `approve` without `--confirm`, and warns about comments too long to
+be read. `reply --resolve` takes `--at <sha>` and refuses any commit but the
+current head, so a thread is never closed against code nobody looked at. There
+is no merge, close or push command, deliberately.
+
+GitHub goes through `gh`, GitLab through `glab`; hosts other than github.com
+and gitlab.com are matched against what those CLIs are authenticated for, and
+an unmatched host is refused rather than guessed. The differences that survive
+the seam - GitLab has no changes-requested state, no atomic review and no
+multi-line comment anchor - are listed in
+[skills/review-fix/references/forges.md](skills/review-fix/references/forges.md).
+
 ## Authoring format
 
 The agent writes three files in `~/.thurview/reviews/<id>/`: