thurview 0.8.2 → 0.9.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "thurview",
-  "version": "0.8.2",
+  "version": "0.9.0",
   "description": "Guided, evidence-anchored reviews of agent-written code. A coding agent authors the review; you read, ask, comment and decide in the browser.",
   "license": "MIT",
   "type": "module",

package/skills/forge-review/SKILL.md

@@ -0,0 +1,276 @@
+---
+name: forge-review
+description: Review a pull or merge request and post the review back to the forge - inline comments anchored to lines, a summary, a verdict, and a re-review that answers the previous pass point by point. Use when the user asks to review a PR or MR and post the comments, to re-review after a push, to approve or request changes on a pull or merge request, or invokes /forge-review. Built on thurview for the evidence, with the forge as the destination.
+user-invocable: true
+argument-hint: "[<number|url>] [--forge github|gitlab]"
+---
+
+# forge-review
+
+thurview authors the evidence; the forge is where the review lands. This skill
+is the bridge between them, and it is the only one that posts.
+
+```mermaid
+flowchart LR
+  A[forge status: what CI really did] --> B[forge prior: the previous pass]
+  B --> C[scaffold + graph: the evidence]
+  C --> D[publish: the reader approves the review before it is posted]
+  D --> E[forge submit: comments, summary, verdict]
+  E --> F[forge reply --resolve: only what is verified]
+  F -->|author pushes| A
+```
+
+Run the CLI as `thurview`, or `npx -y thurview` when it is not on PATH. Every
+command prints TOON on stdout, errors are structured on stdout too, exit code
+2 is a usage error. If a command answers `unknown command` or `unknown flag`
+for something below, the installed CLI is older than this skill: run
+`thurview update` and retry once.
+
+## Request
+
+$ARGUMENTS
+
+A number or URL names the change request. Empty means the change request open
+from the current branch - `thurview forge status` with no `--change` finds it
+through the active review's binding, and when there is none, ask which one
+rather than guessing.
+
+## The word
+
+GitHub calls it a pull request, GitLab a merge request. Everything here calls
+it a **change request** and the CLI takes `--change <number|url>` on either
+forge. Use the forge's own word only when you are writing to the author on
+that forge.
+
+Forge coverage, and what a third forge would need, is in
+[Forges](references/forges.md). Read it when a call fails or the forge is not
+github.com.
+
+## What this never does
+
+Never merge, never close, never push to the branch under review. You usually
+cannot push to a fork at all, so **every finding is a comment**. Merging is
+the maintainer's decision and the CLI has no command for it.
+
+## Before you start
+
+Read `~/.agent-rules/VOICE.md` **on every run**. Every comment, reply and
+summary is published on the operator's account, and that file is the spec for
+how they read - the sign-off line and its exact wording, the length budget per
+comment, severity prefixes, and when to ask instead of assert. It changes; do
+not work from memory of it, and do not copy it in here.
+
+Two consequences of it shape everything below, so they are worth saying once:
+a comment is a few lines and no more, and it ends with the sign-off as a plain
+last line. A finding that will not fit is **two comments**, or one comment
+carrying the claim and one suggestion with the evidence behind a permalink -
+never a wall of prose on a line of someone's diff.
+
+## Workflow
+
+### 1. Ask the forge what it knows, before forming any opinion
+
+```sh
+thurview forge status --change <ref>
+```
+
+Record `change.head`. That commit is what this pass reviews, and a later pass
+diffs against it to find what moved. Note `change.fromFork` and
+`change.author`: a change request from outside the organisation is the case
+every rule here was learned on.
+
+### 2. Establish what CI actually ran
+
+`ci.verdict` is one sentence you can quote. `ci.trustworthy` is the only field
+that means "the tests really passed here".
+
+Two failures this answers, both of which shipped real bugs:
+
+- **A fork change request has almost no CI.** `ci.baselineRan` is what the
+  target branch's own tip runs. One check here against twenty there means the
+  pipeline is not a gate on this change - the review is.
+- **A green tick can mean "never ran".** `passed`, `failed`, `cancelled`,
+  `skipped` and `running` are counted separately because a cancelled job
+  asserted nothing while showing no failure. A title-gate failure that
+  cancels the test matrix leaves exactly that shape.
+
+When `ci.trustworthy` is false, **say so in the summary comment in your own
+words, with the counts**. An unstated gap is one the maintainer will assume
+you checked.
+
+### 3. Read the previous pass back, point by point
+
+```sh
+thurview forge prior --change <ref>          # add --mine for this account's threads
+```
+
+`summary.passes` of 0 means this is a first pass; skip to step 4.
+
+Otherwise this is a **re-review, and answering the prior pass is the most
+important thing you will do here**. A point raised and then silently dropped
+teaches the author that review is noise.
+
+Go through every open thread and give it exactly one of three words:
+
+| Word                | What you do                                                     |
+| ------------------- | --------------------------------------------------------------- |
+| addressed           | Verify it at the current head, then reply and resolve (step 8)  |
+| partially addressed | Reply saying which part is done and which is not; leave it open |
+| untouched           | Reply asking for it again, or say why you are dropping it       |
+
+`threads[].atHead` is false when the thread was written against an older
+commit, and `outdated` when the code under it moved. Neither means the point
+was fixed - only reading the code at the current head means that.
+
+### 4. Diff only what moved
+
+On a re-review, read the new work rather than the whole change again:
+
+```sh
+git range-diff <base>...<previous head> <base>...<current head>
+```
+
+The previous head is the one you recorded last pass, or `review.pinnedHead`
+from `forge status`. Read the full diff only on a first pass.
+
+### 5. Get the evidence from thurview
+
+```sh
+thurview scaffold --pr <ref>                 # pins base and head from the forge
+thurview graph interfaces --review <id>      # what the change moved in the visible surface
+thurview graph impact --review <id>          # what it reaches that the diff does not show
+thurview graph callers <symbol> --review <id>
+thurview graph tests-for <symbol> --review <id>
+```
+
+The thurview skill owns these in full - `thurview skill` prints the path to
+its SKILL.md, and its references sit beside it. Read them when you author the
+document in step 6; do not re-derive structure from hunks.
+
+Read every line you are about to comment on **at the pinned head**, with
+`git show <head>:<path>`, never from the working tree.
+
+### 6. Decide who reads the review before the forge does
+
+Default: **a human approves the pass before it is posted.** Author the
+thurview document as the thurview skill describes, publish it, and wait:
+
+```sh
+thurview publish --review <id> --open
+thurview wait --review <id> --timeout <seconds>
+```
+
+The reader sees every finding against its anchored code and approves or sends
+it back; `wait.reason` of `accepted` is your signal to post. This is the whole
+reason to go through thurview rather than straight to `gh`: comments land on
+the operator's account, on a contributor's work, and are read as the
+maintainer's word.
+
+Post without that gate only when the user asked for an unattended run. Say in
+the handover which of the two happened.
+
+**Never put the thurview URL in a forge comment.** That server is local to
+this machine; the author cannot open it, and the link leaks a path. Evidence
+that must travel goes in a permalink - `status.permalink` shows the shape for
+this forge, with the pinned head already in it.
+
+### 7. Write the pass
+
+One JSON file, which is also what a human can read before it is posted:
+
+```json
+{
+  "verdict": "request-changes",
+  "body": "<the summary, in VOICE.md's shape, ending with the sign-off>",
+  "comments": [
+    {
+      "path": "src/clip.rs",
+      "line": 44,
+      "startLine": 40,
+      "side": "head",
+      "body": "<one point, ending with the sign-off>"
+    }
+  ]
+}
+```
+
+`line` is the LAST line of the range and `startLine` the first. `side` is
+`head` unless you are commenting on a line the change deleted. Both forges
+refuse a comment on a line the diff does not touch, so anchor inside a hunk.
+
+Per comment: one point, stated as a problem then a concrete suggestion,
+within VOICE.md's length budget, sign-off last. **A finding you cannot
+reproduce is a question, not an assertion** - give the mechanism and the
+evidence, say what you could not reproduce, and ask the author to confirm.
+That is the correct form, not a weaker one.
+
+The summary body carries what has no line: what CI did and did not establish
+(step 2), the security result (step 5 of
+[Security surfaces](references/security-surfaces.md)), and who does what next.
+
+Check it before it goes anywhere:
+
+```sh
+thurview forge submit --change <ref> --file pass.json --dry-run
+```
+
+`warnings` names every comment past the line budget. Split those, do not
+shorten by deleting the suggestion.
+
+### 8. Submit
+
+```sh
+thurview forge submit --change <ref> --file pass.json
+```
+
+`verdict` is `comment`, `request-changes` or `approve`.
+
+**Approving is a state change with consequences, and you say them out loud
+before you do it.** It dismisses a standing request for changes, which is what
+makes the change request mergeable, and where auto-merge is armed it merges
+the code with no further human read. The CLI refuses an approve without
+`--confirm` for that reason; the flag is not a formality, it is the point at
+which you have told the user.
+
+Record `submitted.head`. That is the commit the next pass diffs against.
+
+### 9. Resolve only what you verified
+
+```sh
+thurview forge reply <threadId> --change <ref> --body "<answer>" --resolve --at <head>
+```
+
+`--at` must be the current head, and the CLI refuses any other. Resolving a
+thread tells the author a point was accepted; doing it without reading the
+code at that head is worse than leaving it open. A thread deferred by
+agreement may be resolved only when the agreement is written in the thread.
+
+Reply without `--resolve` for a point that is partially addressed.
+
+### 10. Hand over
+
+Tell the user, in a few lines:
+
+- the change request, its head, and the verdict you posted
+- what CI established, in one clause, when `ci.trustworthy` was false
+- how many comments, and how many prior threads you resolved
+- whether a human approved the pass first, or it was unattended
+- what you are waiting for now - the author's push, or the maintainer's merge
+
+## Re-review after a push
+
+Start at step 1 again. The head will have moved; `forge status` says so and
+`review.pinnedHead` holds what you reviewed last. Re-pin with
+`thurview scaffold --update --review <id>`, range-diff from the old head, and
+answer the prior pass before reading anything new.
+
+## Completion criteria
+
+Report completion only when all of these hold:
+
+- `forge status` was read and its CI verdict is reflected in the summary.
+- Every prior thread is marked addressed, partially addressed or untouched.
+- Security is stated explicitly, findings or none.
+- The pass is posted, with a verdict, and its head is recorded.
+- Every thread you resolved was verified at the current head.
+- Nothing was merged, closed or pushed.

package/skills/forge-review/references/forges.md

@@ -0,0 +1,58 @@
+# Forges
+
+`thurview forge` speaks to GitHub through `gh` and to GitLab through `glab`.
+Both are driven through `gh api` and `glab api` rather than their porcelain,
+because the REST and GraphQL payloads are a contract and the porcelain is not.
+
+Which adapter owns a host is decided by name for `github.com` and
+`gitlab.com`, and read off the machine for everything else - a host is owned
+when `gh auth status --hostname <host>` or `glab auth status --hostname
+<host>` succeeds, which is where the answer for a self-hosted instance already
+lives. `GH_HOST` and `GITLAB_HOST` are honoured. A host no adapter claims is
+**refused**, not guessed at; pass `--forge github|gitlab` to name it.
+
+## What differs, and what the CLI does about it
+
+| Behaviour              | GitHub                                    | GitLab                                                                                      |
+| ---------------------- | ----------------------------------------- | ------------------------------------------------------------------------------------------- |
+| The noun               | pull request                              | merge request                                                                               |
+| A pass                 | one atomic review                         | N discussions plus one note; no atomic form exists                                          |
+| Requesting changes     | `CHANGES_REQUESTED`, which blocks a merge | no such state; the account's approval is removed and the summary says it                    |
+| A comment's anchor     | a line range, `start_line` to `line`      | one line; a range is anchored at its last line and `notes` says so                          |
+| Thread identity        | a GraphQL node id                         | a discussion id                                                                             |
+| Resolving              | `resolveReviewThread`                     | `PUT .../discussions/<id>?resolved=true`                                                    |
+| Staleness of a thread  | `isOutdated` from the forge               | not reported; compare `threads[].atHead` against the current head instead                   |
+| CI                     | check runs plus commit statuses           | the latest pipeline's jobs, read from the pipeline's own project so a fork's jobs are found |
+| Fetching a head        | `refs/pull/<n>/head`                      | `refs/merge-requests/<n>/head`                                                              |
+| A line range permalink | `#L10-L20`                                | `#L10-20`                                                                                   |
+
+Consequences worth knowing before you post:
+
+- On GitLab a pass that fails half way through has already posted the
+  comments it got to. The inline comments go first and the summary last, so a
+  partial pass is still one the author can read, but check `submitted.comments`
+  against what you sent.
+- `request-changes` on GitLab does not block a merge. If blocking matters,
+  say so in the summary and leave it to the maintainer.
+- A multi-line finding on GitLab loses its range. Put the range in the
+  comment's own permalink.
+
+## What has been exercised
+
+The GitHub adapter is driven by tests and against github.com. The GitLab
+adapter is driven by the same tests - the calls it makes and the answers it
+parses are asserted - but has not been run against a live GitLab instance. If
+you are the first to point it at one, expect the friction to be in `glab api`'s
+own flags rather than in the endpoints, and report what differed.
+
+## Adding a forge
+
+Implement `Forge` in `src/forge/types.ts` and register it in `BUILTIN` in
+`src/forge/index.ts`. The interface is the whole contract - `get`, `fetchRef`,
+`checks`, `baseline`, `prior`, `submit`, `reply`, `permalink`, plus `owns` and
+`whoami`. There is deliberately no `merge`, `close` or `push`.
+
+Then drive it from `test/forge.test.ts`. The tests put a fake CLI on PATH
+under the adapter's own binary name and answer from a fixture table, so an
+adapter is proved by the calls it makes and the answers it parses rather than
+by being asserted to exist.

package/skills/forge-review/references/security-surfaces.md

@@ -0,0 +1,54 @@
+# Security surfaces
+
+A generic security pass produces generic findings. The checklist has to come
+from what the change actually touches, so derive it from the diff and say what
+you derived it from.
+
+## How to derive it
+
+1. List the surfaces the diff crosses. A surface is a place where the change
+   meets something it does not control - input it did not produce, a file
+   system, another process, a network peer, a platform API, a log.
+2. For each surface, take its questions from the table below.
+3. Ask each question against the code at the pinned head, not against the
+   hunk. A missing cleanup path is invisible in a diff that only adds lines.
+4. Anchor every finding to the line that answers it.
+5. **State the result explicitly, findings or none.** "No security findings"
+   is a result; an absent section is not one, and the maintainer cannot tell
+   the two apart.
+
+## Surfaces and their questions
+
+| The change touches         | Ask                                                                                                                                          |
+| -------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------- |
+| Text that reaches a model  | Prompt injection - whose text is it, what can it make the agent do, what is quoted versus interpreted                                        |
+| Temporary files            | Predictable name, permissions at creation, symlink races, TOCTOU between check and use, cleanup on every error path as well as the happy one |
+| Attacker-controlled names  | Path traversal, absolute paths, shell metacharacters, leading dashes read as flags, Unicode that normalises to something else                |
+| Reading untrusted bytes    | Unbounded reads, allocation from a length the input chose, decompression ratios, what happens at the size limit rather than below it         |
+| Running another process    | Argument construction, quoting per platform, whether a shell is involved at all, what the environment carries, working directory             |
+| Process or PTY lifetime    | Orphans on error, exit status that can be forged or lost, signals, what happens when the child outlives the parent                           |
+| Logs and telemetry         | What reaches a log that should not - secrets, tokens, file contents, personal data - and whether log lines can be forged by input            |
+| Platform branches          | Each branch checked separately; a guard that holds on Linux and not on Windows is the common shape                                           |
+| Authentication or identity | What is trusted, what is verified, what a caller can assert about itself                                                                     |
+| Serialised data            | Deserialisation of attacker-controlled shapes, schema validation before use, defaults that silently accept                                   |
+
+## Two worked examples
+
+**A clipboard copy through a temporary file.** Surfaces: text that reaches a
+model, temporary files, attacker-controlled names, unbounded reads, running
+another process, platform branches, logs. Which yields, concretely - is the
+temp file name predictable; what mode is it created with; is there a window
+between creating and writing it; is it removed when the copy fails and not
+only when it succeeds; can the copied text be read back by another user; does
+the platform helper get its argument as an argument or through a shell; does
+the content reach a log.
+
+**A window lifecycle change that spawns a process.** Surfaces: running another
+process, process lifetime, attacker-controlled names, platform branches.
+Which yields - how the command line is built and escaped on each platform;
+whether a window name is interpolated into it; whether the child is reaped;
+whether its exit status can be forged by something the child does not control;
+what the code does when the platform branch it was not written for runs.
+
+The pattern in both: the surfaces come from the diff, the questions come from
+the surfaces, and the answers come from the code at head.

package/skills/thurview/SKILL.md

@@ -19,6 +19,10 @@ request asks for.
   states what it did not examine. Read
   [Code explainer](references/code-explainer.md) and follow that instead.
 
+Posting a review back to a forge - inline comments on a pull or merge request,
+a verdict, a re-review that answers the previous one - is the `forge-review`
+skill, not this one. This skill's document is read in the browser.
+
 The agent studies the change and writes a short document in which every claim
 about code is anchored to an exact file and line range at a pinned commit.
 thurview validates those anchors, seals a revision, and serves it in the
@@ -86,7 +90,7 @@ request:
 
 ```sh
 thurview scaffold                          # current branch vs its trunk fork point
-thurview scaffold --pr 123                 # pull request (needs gh)
+thurview scaffold --pr 123                 # pull or merge request (needs gh or glab)
 thurview scaffold --base <ref> --head <ref>
 ```
 
@@ -249,7 +253,9 @@ Tell the user, in a few lines and nothing more:
 - which theme source you used: the user's request, the project's design
   system (name the files), or the default skin
 - when the review has no map, why not, in one clause
-- that you are now waiting for their questions and their decision
+- that you are now waiting for their questions and their decision, and that
+  a question asked after you stop waiting is queued rather than lost - the
+  page tells them which of the two it is
 
 The page explains its own controls; do not describe them.
 
@@ -265,9 +271,16 @@ nothing: keep `--timeout` under that limit and run `wait` again on `timeout`.
 When the tool can run a command in the background and wake you when it exits,
 run `wait` that way, so the user has the terminal back while they read.
 
+While `wait` runs the reader's page says an agent is listening, and says the
+opposite within seconds of it returning. Do not loop it to look present: a
+question asked with nobody waiting is queued, not lost, and `thurview`
+reports it as `needsAgent` the next time you run any command in the
+worktree.
+
 `wait.reason` says what happened, with the threads that need you:
 
-- `question`: an "Ask now" thread. Answer each thread in `threads` with
+- `question`: a thread the reader sent to you. Answer each thread in
+  `threads` with
   `thurview threads reply <threadId> --review <id> --body "<answer>"`. Do
   not change the document for a question. Wait again.
 - `awaiting-agent-updates`: the reader submitted with "Request changes".

package/skills/thurview/references/lifecycle.md

@@ -27,7 +27,7 @@ warns when the branch moved past them.
 | `accepted`               | Terminal. Cannot be republished.                         |
 | `closed`                 | Terminal. Ended without approval. Cannot be republished. |
 
-"Ask now" does not change the status. "Submit review" with "Request changes"
+Asking the agent a question does not change the status. "Submit review" with "Request changes"
 sets `awaiting-agent-updates`; with "Approve" sets `accepted`; with "Close"
 sets `closed`.
 
@@ -36,21 +36,62 @@ Dismissal is separate: the reader removes the review from the active list and
 
 ## Threads
 
-Two kinds, chosen by the reader when creating one:
+Two kinds, chosen by the reader when creating one. In the browser these are
+the two buttons on the comment box, one click each:
 
-- `ask` mode (a question): delivered at once. `wait` returns `question`.
-  Answer with `threads reply`. It stays open until the reader resolves it;
-  open questions never block a republish.
-- `review` mode (a comment): held as pending until the reader submits. Then
-  `wait` returns `awaiting-agent-updates` with the submitted threads.
+- `ask` mode (a question, "Send to the agent"): submitted on creation and
+  delivered at once. `wait` returns `question`. Answer with `threads reply`.
+  Open questions never block a republish.
+- `review` mode (a comment, "Add to the review"): held as pending until the
+  reader submits. Then `wait` returns `awaiting-agent-updates` with the
+  submitted threads.
 
 Targets: a document block (with an optional quoted selection), a file line
 on the base or head side, a map node, or the whole review.
 
+### Status, `submitted` and `needsAgent`
+
+Two flags and one derived predicate decide whether a thread reaches you.
+`needsAgent` is the whole queue: `wait` reports it, `threads list --open`
+counts it, and a thread outside it will not be delivered to anyone.
+
+```text
+needsAgent = status is open  AND  submitted  AND  the last message is the reader's
+```
+
+| Transition                     | status               | submitted     |
+| ------------------------------ | -------------------- | ------------- |
+| reader creates an `ask` thread | `open`               | `true`        |
+| reader creates a `review` one  | `open`               | `false`       |
+| reader submits the review      | unchanged            | `true` (all)  |
+| **reader writes in a thread**  | **forced to `open`** | `true` if ask |
+| agent replies                  | unchanged            | unchanged     |
+| `threads resolve` / Resolve    | `resolved`           | unchanged     |
+| Reopen                         | `open`               | unchanged     |
+
+A message from the reader always reopens the thread. It has to: a reply that
+left the thread resolved would sit at `needsAgent: false`, invisible to
+`wait` and to `threads list --open`, and the reader would be writing to
+nobody while the page still offered them a Reply button. Publishing a new
+revision never touches a thread's status.
+
 `publish` after the first revision requires zero open submitted comment
 threads. Resolve a thread only when its requested change is present. Do not
 rewrite or merge threads.
 
+### Presence: what the reader is told
+
+While `thurview wait` runs it writes a heartbeat to
+`${THURVIEW_HOME:-~/.thurview}/agents/<reviewId>.json`, and the browser reads
+it back as one of two sentences: an agent is listening now, or nothing is
+listening and what you send is queued until one checks in. Nothing else
+writes it, so presence is never inferred and never faked. A heartbeat older
+than 15 seconds is a dead `wait`, not an agent.
+
+That is why a question asked while you are away is not lost and does not need
+you to sit in `wait`: it is queued, `thurview` reports it as `needsAgent` the
+next time you run any command in the worktree, and you answer it then.
+
 ```sh
 thurview threads list --review <id> [--open]
 thurview threads get <threadId> --review <id>
@@ -64,6 +105,7 @@ thurview threads resolve <threadId> --review <id>
 ${THURVIEW_HOME:-~/.thurview}/
 ├── THURVIEW.md              user guidance (optional)
 ├── server.json              running server, if any
+├── agents/<id>.json         heartbeat of a running `wait`, removed when it ends
 └── reviews/<id>/
     ├── review.md            you edit
     ├── data.yaml            you edit
@@ -90,3 +132,8 @@ again.
 
 `thurview threads get <id>` truncates bodies over 1500 characters; pass
 `--full` when the hint says so.
+
+While `wait` runs, the reader's page says an agent is listening; when it
+returns, the page says the opposite within seconds. Do not leave `wait`
+running to look present when you are not going to answer, and do not loop it
+to keep a queue drained: the queue survives you, and the reader is told so.