thurview 0.14.0 → 0.16.0

package/README.md

@@ -1,82 +1,123 @@
 # thurview
 
-Guided, evidence-anchored reviews of agent-written code. A coding agent studies
-a branch, pull request or commit range and writes a short document in which
-every claim is anchored to an exact file and line range at a pinned commit. You
-read it in your browser, ask the agent questions, comment on the code, and
-approve or send it back.
+**Your coding agent writes the review; you read it in the browser, anchored to
+the code, and approve it or send it back.**
+
+[![CI](https://github.com/Thurbeen/thurview/actions/workflows/ci.yml/badge.svg)](https://github.com/Thurbeen/thurview/actions/workflows/ci.yml)
+[![npm](https://img.shields.io/npm/v/thurview)](https://www.npmjs.com/package/thurview)
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
+
+![thurview demo: the reader follows an anchor into the code, comments on a line
+range in the diff, reads the agent's answer and requests changes](./media/thurview-demo.gif)
+
+_The reader's half of it; the agent is working off camera._
+
+- **Every claim is anchored to code.** The prose links to an exact file and
+  line range at a pinned commit, and the reader opens that code beside the
+  text — no hunting for what a sentence is about.
+- **You read it in your browser, not in a comment thread.** An argument in the
+  order somebody chose to make it, with the code, the diff between the pinned
+  commits and the system around it one click away — instead of forty remarks
+  in the order they happened to be written.
+- **You ask, and the agent answers in the document.** A question goes to the
+  agent — at once if one is listening, queued if not — and the answer lands
+  in the same thread; a comment waits for your decision. Then you approve the
+  change or send it back with the comments attached.
+- **A code graph answers what the diff cannot.** Who calls the symbol that
+  moved, which tests reach it, where the change landed in the system and what
+  sits next to it. thurview builds the graph itself with tree-sitter from the
+  pinned commits, for TypeScript, JavaScript, Python, Go, Rust, Java and Elixir.
+- **The evidence is checked, not taken on trust.** An anchor whose lines
+  do not exist at the pinned commit, a call stack frame asserting a call the
+  diff does not show, an interface annotation for a symbol the change never
+  moved, a trust boundary crossing that resolves to nothing — publishing
+  rejects each one rather than rendering it.
 
 ## Install
 
-Give your agent the skill, with the [skills](https://github.com/vercel-labs/skills)
-CLI - it works with Claude Code, Codex, Cursor, OpenCode and every agent that
-reads the Agent Skills format:
+One command gives your agent every skill this repository ships, through the
+[skills](https://github.com/vercel-labs/skills) CLI - it works with Claude
+Code, Codex, Cursor, OpenCode and every agent that reads the Agent Skills
+format:
 
 ```sh
 npx skills@latest add https://github.com/Thurbeen/thurview \
-  --skill thurview --agent universal claude-code --global --yes
+  --skill '*' --agent universal claude-code --global --yes
 ```
 
-The skill reaches the `thurview` command through `npx`, so the requirements
-are Node 22 or later and git (`gh` for pull requests, `glab` for merge
-requests). Then, in any repository, ask your agent:
+`--skill '*'` takes all four; quote the star so your shell does not expand it
+against the current directory. The skills reach the `thurview` command through
+`npx`, so the requirements are Node 22 or later and git (`gh` for pull
+requests, `glab` for merge requests). Then, in any repository, ask your agent:
 
 ```text
 Use the thurview skill to review my current branch against up-to-date main
 and open it.
 ```
 
-![thurview demo: the reader follows an anchor into the code, comments on a line
-range in the diff, reads the agent's answer and requests changes](./media/thurview-demo.gif)
-
-The clip is the reader's half, the agent working off camera: following an anchor
-from the prose into the code, opening a call stack frame, commenting on a line
-range of the diff, seeing on the map what the change added, reading in the
-threads panel the answer to a question already asked, and sending the review
-back with changes requested.
+## The four skills
+
+Three kinds of document, and one companion that writes none:
+
+- **`thurview`** - a change that is already written: a branch, a pull request,
+  a commit range. The document carries the diff, the commits and the interface
+  delta, and the reader approves it or sends it back.
+- **`thurview-explain`** - a codebase, or one subsystem of it, at a single
+  pinned commit. No diff and nothing to approve: it surfaces the architecture
+  well enough for the reader to spot design problems, and states what it did
+  not examine.
+- **`thurview-design`** - a change that is not written yet: a design, an
+  architecture proposal, an implementation plan. It anchors on the code as it
+  stands and declares what it would build as proposals, each attached to the
+  code it lands in today.
+- **`thurview-fix`** - no browser and no reader. It reviews, fixes what it is
+  sure of behind the repository's own tests and lint, and reports the rest -
+  optionally as inline comments on the change request.
 
 <details>
-<summary><b>Other ways to install</b> - pin the skill to a release, install the
-command from npm, run from a checkout, session hooks, the thurview-design and
-thurview-fix skills</summary>
+<summary><b>Other ways to install</b> - one skill at a time, pin to a release,
+install the command from npm, run from a checkout, session hooks, and coming
+from an older install</summary>
 
 `--global` installs for your user, so one install covers every repository.
-`universal` puts the one real copy in `~/.agents/skills/thurview`, the directory
-no single agent owns, and every other agent you name gets a symlink to it, such
-as `~/.claude/skills/thurview` → `../../.agents/skills/thurview`, so an update
-lands everywhere at once. Swap `claude-code` for any agent the skills CLI
-supports, but keep `universal` and at least one more: with `--yes` and a single
-target, the CLI copies instead of linking.
-
-That form tracks this repository's default branch: `skills update` takes
-whatever `main` holds, which can be ahead of the released command. To pin the
-skill to a release instead, install it from the tag, which the skill lock
-records and later updates keep:
+`universal` puts the one real copy of each skill under `~/.agents/skills/`,
+the directory no single agent owns, and every other agent you name gets a
+symlink to it - `~/.claude/skills/thurview` →
+`../../.agents/skills/thurview`, and the same for the other three - so an
+update lands everywhere at once. Swap `claude-code` for any agent the skills
+CLI supports, but keep `universal` and at least one more: with `--yes` and a
+single target, the CLI copies instead of linking.
+
+`--skill` also takes names, one or several, when you do not want all four:
+`--skill thurview`, or `--skill thurview thurview-fix`.
+
+The untagged URL above tracks this repository's default branch:
+`skills update` takes whatever `main` holds, which can be ahead of the
+released command. To pin the skills to a release instead, install from the
+tag, which the skill lock records and later updates keep:
 
 ```sh
-npx skills@latest add https://github.com/Thurbeen/thurview/tree/v0.10.0/skills/thurview \
-  --agent universal claude-code --global --yes
+npx skills@latest add https://github.com/Thurbeen/thurview/tree/v0.15.0 \
+  --skill '*' --agent universal claude-code --global --yes
 ```
 
 Releases tag without committing, so nothing moves the tag above: swap in the
 [latest release](https://github.com/Thurbeen/thurview/releases/latest).
 
-The npm package ships the same skill, so `thurview setup skill` links the copy
-that matches the command you have installed. Use that when you want the two to
-move together.
+The npm package ships the same skills, so `thurview setup skill` links the
+copies that match the command you have installed. Use that when you want the
+two to move together.
 
-Install the command itself, rather than leaving the skill to reach it through
+Install the command itself, rather than leaving the skills to reach it through
 `npx` on every run:
 
 ```sh
 npm install -g thurview     # or: pnpm add -g thurview
 ```
 
-The review reasons over a code graph thurview builds itself from the pinned
-commits with tree-sitter, so nothing else needs installing. `thurview graph`
-answers which interfaces the change moved, what it reaches, who calls a
-symbol, what tests cover it and how files cluster, for TypeScript,
-JavaScript, Python, Go, Rust, Java and Elixir.
+Nothing else needs installing: the code graph is built from the pinned commits
+with tree-sitter. `thurview graph` answers which interfaces the change moved,
+what it reaches, who calls a symbol, what tests cover it and how files cluster.
 
 To run from a checkout instead:
 
@@ -89,30 +130,27 @@ npm link                    # puts `thurview` on PATH
 Optional, for ambient context: `thurview setup hooks` installs a
 SessionStart hook for Claude Code, Codex and OpenCode, so every session opens
 with the reviews of its working directory. `thurview setup skill` links the
-skill from this checkout instead of the `skills` CLI copy; use one or the
+skills from this checkout instead of the `skills` CLI copies; use one or the
 other.
 
-Also available: `thurview-design`, which authors the design kind described
-[below](#how-it-works), and `thurview-fix`, the browserless companion skill
-described [below](#review-and-fix).
+**Coming from an older install.** A skill name is an address, so nothing
+renames or splits one in place - the command above adds what is missing, and
+what is stale has to go.
 
-```sh
-npx skills@latest add https://github.com/Thurbeen/thurview \
-  --skill thurview-design --agent universal claude-code --global --yes
-npx skills@latest add https://github.com/Thurbeen/thurview \
-  --skill thurview-fix --agent universal claude-code --global --yes
-```
+`thurview-explain` used to be a second kind inside the `thurview` skill, so an
+install made before the split does not have it. Under the `skills` CLI,
+updating `thurview` adds no second skill; run the install command above, which
+takes all four. Under `thurview setup skill`, update the command first -
+`thurview update`, or pull and rebuild the checkout you linked from - and run
+`thurview setup skill` again: it links every skill the installed command
+carries, so it picks the new one up on its own.
 
-`thurview-fix` was called `review-fix`. A skill name is an address, so nothing
-updates the old one in place: an install made before the rename keeps answering
-to `/review-fix` from a copy that will never change again, and one made with
-`thurview setup skill` leaves a symlink pointing at a directory this repository
-no longer ships. Remove it and add the skill under its new name:
+`thurview-fix` was called `review-fix`, and an install made before the rename
+keeps answering to `/review-fix` from a copy that will never change again.
+Remove it:
 
 ```sh
 npx skills@latest remove --global review-fix
-npx skills@latest add https://github.com/Thurbeen/thurview \
-  --skill thurview-fix --agent universal claude-code --global --yes
 ```
 
 For a `thurview setup skill` install, delete the stale link -
@@ -128,20 +166,14 @@ and serves it in your browser: the walkthrough, live code peeks, the diff,
 commits, and a software map. You ask questions, leave anchored comments, and
 approve or request changes. The agent answers and republishes.
 
-It also explains a codebase. A **code explainer** is the same document over a
-different unit: one pinned commit instead of a range, so a reader can see the
-architecture well enough to spot design problems themselves. It has no diff and
-nothing to approve, it surfaces structure rather than grading it, and it states
-what it did not examine.
-
-And it reads a plan. A **design** is the same document over a change that is
-not written yet: one pinned commit — the code it argues from — anchors on the
-code as it stands, and what it would build declared as proposals, each attached
-to the code it lands in today. An anchor never points at code that does not
-exist; the reader approves the design or sends it back.
+An explainer and a design run the same loop over a different unit. An
+explainer pins one commit instead of a range, so it has no diff and nothing to
+approve. A design pins the commit it argues from: its anchors land on the code
+as it stands, never on code that does not exist yet, and what it would build
+rides beside them as proposals.
 
-It does not review the code for you. It helps you understand it fast enough
-to review it yourself.
+The document does not review the code for you. It helps you understand the
+code fast enough to judge it yourself.
 
 ```mermaid
 flowchart LR
@@ -155,6 +187,16 @@ flowchart LR
 
 ## What the reader sees
 
+The home page is a queue: every review, explainer and design, grouped by
+repository and ordered by whose turn it is - a decision not yet posted to its
+change request first, then documents waiting for your reading, then ones whose
+change request moved past the pin, then ones waiting for the agent, then ones
+not published yet. A row bound to a change request also says whether the pin is
+still the head, what you decided and whether it reached the forge, and whether
+CI is a real gate there, as of the last `forge` command and with that age on
+screen. The browser never calls the forge; explainers and designs carry those
+columns empty.
+
 Prose with every claim anchored to code, opened beside the text:
 
 ![The review document, with a call stack diff, a storage view and an anchored
@@ -317,33 +359,44 @@ The agent writes three files in `~/.thurview/reviews/<id>/`:
   `## Heading {collapsed}` folds a section by default.
 - `data.yaml`: typed inputs: `actors`, `anchors` (file, from, to, graph),
   `stores`, `interfaces` (a capability line per derived entry, plus the
-  interfaces the graph cannot see).
+  interfaces the graph cannot see), and `security`, where a review says where
+  the change lets input cross a trust boundary.
 - `map.yaml`: the software map at head, optionally at base. In an explainer it
   carries the breadth the prose has no room for, and a node's `files` globs are
   what let a file count as placed rather than not examined.
 - `theme.yaml`: the look, derived from the reviewed project's own design
   system (tokens, fonts, shape, code palette). Empty means the default skin.
 
-An explainer writes the same files, minus `interfaces`: there is no change to
-derive a delta from, and `graph: base` on an anchor is an error because there
-is one commit.
+`security` is a review's own dimension, shown to the reader under the interface
+delta rather than left to a section the agent might not write. It is
+`security: none` when the change crosses no trust boundary, or one entry per
+place it does — a sentence and the head anchor the reader opens. Left out, it
+publishes as "not assessed", so a review that has not looked and one that looked
+and found nothing are never the same page. What counts as a trust boundary is
+defined in one place — the `thurview-fix` skill's finding rules — and
+nothing else restates it.
+
+An explainer writes the same files, minus `interfaces` and `security`: there is
+no change to derive a delta from or to carry input across a boundary, and
+`graph: base` on an anchor is an error because there is one commit.
 
 A design writes the same files, and `interfaces` means something else in it:
 each entry is a **proposal** — what the design would add, change or remove,
 with the anchor of the code that proposal lands in, replaces or plugs into
-today. `graph: base` is an error for the same reason as in an explainer, a
-`symbol:` entry is an error because no diff derived one, and a design that
-proposes nothing is refused: that document is an explainer. In its `map.yaml`,
-`base` is the structure as it stands and `nodes` the structure it proposes, so
-a proposed part may own files that do not exist yet while a `base` node may
-not.
+today. `graph: base` and `security` are errors for the same reason as in an
+explainer, a `symbol:` entry is an error because no diff derived one, and a
+design that proposes nothing is refused: that document is an explainer. In its
+`map.yaml`, `base` is the structure as it stands and `nodes` the structure it
+proposes, so a proposed part may own files that do not exist yet while a `base`
+node may not.
 
 `thurview publish` rejects an anchor whose file or lines do not exist at the
 pinned commit, a call stack frame that claims an added or removed call the
 diff does not show, a storage operation on an unknown field, a map edge
 to an unknown node, an interface annotation for a symbol the change did not
-move, a declared interface whose anchor holds no added or deleted line, and an
-explainer that anchors nothing at all, and a design that proposes nothing or
+move, a declared interface whose anchor holds no added or deleted line, a trust
+boundary crossing whose anchor resolves to nothing or reads the base commit, and
+an explainer that anchors nothing at all, and a design that proposes nothing or
 whose proposal names no site in the code as it stands. The full format is in
 [skills/thurview/references](skills/thurview/references).
 

package/dist/cli.js

@@ -21,6 +21,7 @@ import { startServer } from "./server/server.js";
 import { parseFlags, helpFor, str, bool } from "./flags.js";
 import { forgeFor, repoOf, summariseCi, } from "./forge/index.js";
 import { parseSubmission, longComments, buildPass } from "./forge/submission.js";
+import { recordForgeFacts, ciFacts } from "./queue.js";
 import { VERSION } from "./version.js";
 const execFileP = promisify(execFile);
 const HERE = dirname(fileURLToPath(import.meta.url));
@@ -273,6 +274,17 @@ const TEMPLATE_DATA = `# Typed inputs for review.md: actors, anchors and stores.
 #
 # interfaces holds one capability line per interface the change moved. thurview
 # derives the list itself; run \`thurview graph interfaces\` for the ids.
+#
+# security says where this change lets input cross a trust boundary. Leave it
+# out (or write \`security: pending\`) until you have looked and the document says
+# so; then write \`security: none\`, or list what it crosses:
+#
+# security:
+#   - boundary: The --shell flag reaches execFile's argv unquoted.
+#     anchor: spawn
+#
+# What counts as a trust boundary is defined once, in the thurview-fix skill's
+# SKILL.md under "Findings". Read it there rather than deciding again.
 actors: {}
 anchors: {}
 stores: {}
@@ -745,6 +757,7 @@ const commands = {
         let base;
         let head;
         let title = str(p, "title") ?? "";
+        let pinned = null;
         const b = existing?.binding;
         const pr = str(p, "pr");
         if (pr || b?.kind === "pr") {
@@ -768,6 +781,7 @@ const commands = {
             base = await g.mergeBase(worktree, baseRef, head);
             binding = { kind: "pr", name: cr.number, url: cr.url, forge: forge.id };
             title ||= cr.title;
+            pinned = { repo, cr };
         }
         else if (str(p, "base") || str(p, "head") || b?.kind === "range") {
             const [bb, hh] = b?.kind === "range" && !str(p, "base") && !str(p, "head")
@@ -846,6 +860,8 @@ const commands = {
                 await writeReview(review);
             }
         }
+        if (pinned)
+            await recordForgeFacts(review, pinned.repo, pinned.cr);
         const stat = await g.shortStat(worktree, base, head);
         const dir = reviewDir(review.id);
         return {
@@ -1177,7 +1193,10 @@ const commands = {
                     ? { coverage: coverage ? coverage.verdict : "(unavailable)" }
                     : kind === "design"
                         ? { proposes: doc.document.interfaces?.verdict ?? "(unavailable)" }
-                        : { interfaces: doc.document.interfaces?.verdict ?? "(unavailable)" }),
+                        : {
+                            interfaces: doc.document.interfaces?.verdict ?? "(unavailable)",
+                            security: doc.document.security?.verdict ?? "(unavailable)",
+                        }),
                 theme: theme?.name ?? "default",
                 url: url ?? "(server not running)",
             },
@@ -1634,6 +1653,7 @@ const commands = {
             const checks = await ctx.forge.checks(ctx.repo, ctx.cr);
             const baseline = await ctx.forge.baseline(ctx.repo, ctx.cr.baseBranch).catch(() => null);
             const ci = summariseCi(checks, baseline, ctx.cr.baseBranch);
+            await recordForgeFacts(ctx.review, ctx.repo, ctx.cr, { ci: ciFacts(ci) });
             const shown = bool(p, "full") ? checks : checks.filter((c) => c.state !== "passed");
             const hidden = checks.length - shown.length;
             const help = [
@@ -1855,6 +1875,9 @@ const commands = {
                     ],
                 };
             const posted = await ctx.forge.submit(ctx.repo, ctx.cr, submission);
+            await recordForgeFacts(ctx.review, ctx.repo, ctx.cr, {
+                posted: { at: now(), verdict: posted.verdict, head: ctx.cr.head },
+            });
             return {
                 submitted: {
                     forge: ctx.forge.id,