thurview 0.9.0 → 0.10.0

package/skills/review-fix/SKILL.md

@@ -0,0 +1,165 @@
+---
+name: review-fix
+description: Review a change and fix what the review finds - bugs, regressions for callers, missing or broken tests, security issues - with thurview's code graph showing the callers and tests a diff does not. Commits only the fixes that pass the repository's own tests and lint, and reports the rest. Use when the user asks to review and fix a branch, a commit range or a pull or merge request, to find and fix bugs in a change, or invokes /review-fix.
+user-invocable: true
+argument-hint: "[<branch> | <base>..<head> | <PR or MR number or URL>] [--post]"
+---
+
+# review-fix
+
+Review a change, fix what you are sure of, report the rest. The diff shows what
+changed; thurview's code graph shows what depends on it, which is where a
+change breaks code the diff never shows.
+
+```mermaid
+flowchart LR
+  A[Scope: pin base and head] --> B[Graph: who reaches the change]
+  B --> C[Findings]
+  C --> D[Fix, then the repo's tests and lint]
+  D -->|green| E[One fix commit]
+  D -->|red| F[Undo that fix, report why]
+  E --> G[Report]
+  F --> G
+  G -.->|--post| H[Unfixed findings as inline comments]
+```
+
+Run the CLI as `thurview`, or `npx -y thurview` when it is not on PATH. It
+prints TOON, and exit code 2 is a usage error. If it answers `unknown flag` for
+something below, run `thurview update` and retry once.
+
+## Request
+
+$ARGUMENTS
+
+## Never
+
+- Never push, force-push or post unless this request asks for it. `--post`
+  asks to post comments; pushing the fix commit needs its own ask.
+- Never rewrite the branch's history. Fixes are a new commit on top.
+- Never report style. A finding is a bug, a regression for a caller, a missing
+  or broken test, or a security issue.
+
+## 1. Scope
+
+Start from a clean tree (`git status --porcelain` prints nothing), otherwise
+ask: the fixes get committed. Check out the head, then pin both commits with
+one graph call:
+
+| Request            | Check out                                      | Pin with                                                                          |
+| ------------------ | ---------------------------------------------- | --------------------------------------------------------------------------------- |
+| empty              | the current branch                             | `thurview graph impact --head HEAD`                                               |
+| a branch           | `git switch <branch>`                          | `thurview graph impact --head HEAD`                                               |
+| `<base>..<head>`   | the branch at `<head>`                         | `thurview graph impact --base <base> --head HEAD`                                 |
+| a PR or MR ref/URL | `gh pr checkout <n>` or `glab mr checkout <n>` | `thurview graph impact --base $(git merge-base origin/<target> HEAD) --head HEAD` |
+
+With `--head` alone the base is where head forked from trunk. For a change
+request, `thurview forge status --change <ref>` names `<target>` as
+`change.baseBranch`.
+
+The output's `base` and `head` are the pins. Pass `--base <base> --head <head>`
+to every later graph command, as its `help` lines do, so your fix commit does
+not move what you are reviewing.
+
+## 2. Ask the graph
+
+```sh
+thurview graph impact     --base <base> --head <head>  # changed symbols, who reaches them, tests
+thurview graph interfaces --base <base> --head <head>  # exports and signatures that moved
+thurview graph callers <name> --base <base> --head <head>  # every call site; --graph base for before
+thurview graph tests-for <name> --base <base> --head <head>
+```
+
+What to take from them:
+
+- **`impact.reach`** lists code that calls a changed symbol and was not changed
+  itself - what the author may have forgotten. `at` is the line of the call,
+  `via` the changed symbol it reaches. Read each call site against the new
+  behaviour: this is the finding a diff cannot give you.
+- **`reach[].tested: false`**: no test reaches that caller, so nothing catches
+  a break there.
+- **`interfaces`** rows `changed` or `removed`: run `callers` on each, with
+  `--graph base` for a removed one, since head no longer has its callers.
+- **`impact.untested`**: changed symbols no test reaches.
+- **`unresolved`, `truncated`**: references the graph could not resolve and
+  files past its cap. "No callers" is only as true as those allow; say so when
+  a finding rests on it.
+
+Then read the diff (`git diff <base> <head>`) and every call site the rows name.
+
+## 3. Findings
+
+For each one, record:
+
+- `file:line` at `<head>`, now, before a fix moves lines
+- severity: `high` (wrong behaviour on a normal path, data loss, security),
+  `medium` (a likely bug, or a risky path no test reaches), `low` (real but
+  narrow)
+- why, in one line
+- the graph evidence when there is some, e.g.
+  `reach: checkout src/cart.js:5 via discount, tested false`
+
+Security means input crossing a trust boundary: a shell command, query or path
+built from it, a secret reaching a log, an authorization check the change
+skips.
+
+A problem that is just as present at `<base>` is not this change's finding.
+Leave it unfixed and list it after the report's table.
+
+## 4. Fix
+
+Find the repository's own test and lint commands - `CONTRIBUTING.md`,
+`AGENTS.md`, the package manifest's scripts, a `Makefile`, the CI config - and
+run them once before editing. What is already red at head is not yours: note
+it, and judge each fix by not making it worse.
+
+For each finding whose fix is local and whose right behaviour is unambiguous:
+
+1. For a bug, first add or extend a test and run it: it must fail, for the
+   reason the finding gives.
+2. Edit, then run the tests and lint.
+3. Green: keep it. Red: undo only that fix (`git restore <files>`, and delete
+   files it created) and mark the finding unfixed, with the failure as why.
+
+Leave a finding unfixed when it needs a decision the code cannot make, changes
+an interface used outside this repository, or no test can show it.
+
+Once every kept fix passes together, commit them as one. Follow the
+repository's commit convention when it has one; otherwise:
+
+```sh
+git add <files>
+git commit -m "fix: address review findings" -m "<one line per fix: file:line - why>"
+```
+
+## 5. Report
+
+One table - severity, `file:line`, the finding, its graph evidence, and the fix
+commit or why it is unfixed - then the tests and lint after the commit, and
+what the graph could not see. Do not push; offer to.
+
+## 6. Post, with `--post` only
+
+Only on a change request, only the unfixed findings, and before the fix commit
+is pushed, so the lines still match the forge's head. Write `pass.json`:
+
+```json
+{
+  "verdict": "comment",
+  "body": "<what was fixed locally, what is left and why>",
+  "comments": [{ "path": "src/cart.js", "line": 5, "body": "<the problem, then a suggestion>" }]
+}
+```
+
+A comment must sit on a line the change request's diff touches, or the forge
+refuses it; a finding on an untouched caller goes in `body`, with a link in the
+`permalink` shape `forge status` prints. Keep each comment to a few lines, and
+follow the user's own rules for text posted in their name when they keep any.
+Check, then post:
+
+```sh
+thurview forge submit --change <ref> --file pass.json --dry-run
+thurview forge submit --change <ref> --file pass.json
+```
+
+The verdict stays `comment`: approving is the maintainer's call. How GitHub and
+GitLab differ is in [Forges](references/forges.md).

package/skills/thurview/SKILL.md

@@ -19,9 +19,9 @@ 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.
+Reviewing a change and fixing what the review finds - and posting what stays
+unfixed to a pull or merge request - is the `review-fix` 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.

package/skills/forge-review/SKILL.md

@@ -1,276 +0,0 @@
----
-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/security-surfaces.md

@@ -1,54 +0,0 @@
-# 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.