thurview 0.5.1 → 0.7.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "thurview",
-  "version": "0.5.1",
+  "version": "0.7.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/thurview/SKILL.md

@@ -113,6 +113,7 @@ definitions-and-references query each grammar ships, so ask it rather than
 re-deriving structure from hunks:
 
 ```sh
+thurview graph interfaces --review <id>         # what the change added to, changed in or removed from the visible surface
 thurview graph impact --review <id>             # symbols touched, edges added and removed, what reaches them, what tests cover them
 thurview graph callers <symbol> --review <id>   # used, or speculative? (--graph base for the old side)
 thurview graph tests-for <symbol> --review <id>
@@ -128,11 +129,19 @@ plain `truncated` for callers and tests-for, which look at one), the repo has
 more supported files than the graph could parse, and that answer is a partial
 view: say so rather than treating an empty result as "nothing there".
 
-Spend the review on what those answer: what the change reaches that the diff
-does not show, which boundaries it crosses, what now depends on what, what it
-left untested. Then compare the stated intent (commit messages, PR
-description, the user's own words) with what the code does. The gap is the
-most valuable finding.
+Read `graph interfaces` first: it is the reader's own first question, and its
+`verdict` is what the browser shows above your document. A `removed` entry is
+the most review-worthy thing the change can contain; `No interface moved`
+means the change is internal, and the document should say why the refactor was
+worth making rather than dress it up as a feature. Do not repeat the entries
+in prose - the panel already lists them. Explain the ones that need it,
+in `data.yaml` (see below).
+
+Spend the rest of the review on what the other queries answer: what the change
+reaches that the diff does not show, which boundaries it crosses, what now
+depends on what, what it left untested. Then compare the stated intent (commit
+messages, PR description, the user's own words) with what the code does. The
+gap is the most valuable finding.
 
 Do not spend the review on naming, formatting, import order, or missing
 defensive checks. Linters, type checkers and `/code-review` catch those, and a
@@ -141,11 +150,18 @@ reader who wanted them would have run those instead.
 Read every range you anchor from the pinned commit, not the working tree:
 `git show <head>:<path>` or `git show <base>:<path>`.
 
-### 4. Start the map
+### 4. Decide on the map, then start it
+
+The Map tab answers where the change landed in the system and what sits next
+to it. A change that lands in one place does not raise that question: leave
+`nodes: []`, say why in the handover, and go to step 5. A change that crosses a
+boundary, adds or removes a part, or reaches code the diff does not show, does:
+map it. [Software map](references/software-map.md) makes that call in full, and
+a map that earns nothing is worse for the reader than none.
 
-Dispatch one sub-agent to write `map.yaml` per
-[Software map](references/software-map.md) now, so it works while you write
-the document, with this prompt filled in:
+When it earns its place, dispatch one sub-agent to write `map.yaml` per that
+reference now, so it works while you write the document, with this prompt
+filled in:
 
 ```text
 Use the thurview skill's software-map reference (`thurview skill` prints the
@@ -176,6 +192,13 @@ Edit `review.md` and `data.yaml` in the review directory following
 Default to anchor links for evidence; use an inline peek only when the reader
 must see the code to follow the main claim.
 
+In `data.yaml`, add an `interfaces` entry for each interface change a
+consumer would not understand from its declaration alone, and for the ones
+the graph cannot see - a CLI flag, an HTTP route, a config key, a file
+format. See [Components](references/components.md) for the shape and
+[Document authoring](references/document-authoring.md) for what earns an
+entry. Never write one for a capability the change did not deliver.
+
 ### 6. Theme the review after the project
 
 Read [Theme](references/theme.md). Decide the look in its order: what the
@@ -207,8 +230,10 @@ Tell the user, in a few lines and nothing more:
 - the `url`
 - what the review covers, in one sentence, and where to start: the Review tab
   as a rule; the Files tab when the change is small and the diff is the story
+- the interface delta `verdict`, in its own words
 - 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
 
 The page explains its own controls; do not describe them.

package/skills/thurview/references/components.md

@@ -32,10 +32,44 @@ stores:
         schema:
           id: { type: text, pk: true }
           body: { type: text }
+
+interfaces:
+  spawnPty:                               # annotate a derived entry
+    symbol: src/pty.ts:spawnPty           # an id from `thurview graph interfaces`
+    capability: Callers get a sized PTY without knowing the fallback.
+  dryRun:                                 # declare one the graph cannot see
+    name: thurview publish --dry-run      # what a consumer types or calls
+    change: added                         # added | changed | removed
+    capability: Validate a review without sealing a revision.
+    anchor: dryRunFlag                    # must hold a line the diff moved
 ```
 
 An anchor without `peek` can label a map node but cannot open code.
 
+## interfaces
+
+The browser shows the interface delta above the document. thurview derives it
+at `publish` from the code graph at both pinned commits - every symbol the
+diff touched that is visible outside its own file, split into added, changed
+and removed - so the list itself is never authored and never goes stale.
+
+Each entry in `interfaces` does one of two things, and never both:
+
+- **`symbol`** annotates a derived entry with `capability`, one sentence in a
+  consumer's terms. `publish` fails when the change did not move that symbol,
+  so an annotation cannot outlive the entry it explains. Take the id verbatim
+  from `thurview graph interfaces`.
+- **`name`** declares an interface the graph cannot see: a CLI subcommand or
+  flag, an HTTP route, an event kind, a config key, a file format. It needs
+  `change` and an `anchor`. `publish` checks the anchor against the pinned
+  diff - a `removed` entry needs a `graph: base` anchor covering a deleted
+  line, `added` and `changed` need a head anchor covering an added line - so a
+  declared interface is evidence, not a claim.
+
+`capability` is what a consumer can now do, or can no longer do. Write
+"`thurview publish` gains `--dry-run`", not "added a boolean to
+PublishOptions".
+
 ## Anchor link
 
 ```markdown

package/skills/thurview/references/document-authoring.md

@@ -40,12 +40,14 @@ Then fewer than five further sections when practical. Pick those that fit:
 
 - requirements
 - design
-- interface change
 - lifecycle or data flow
 - state or storage
 - testing evidence
 - decision log
 
+There is no interface-change section: the browser derives the interface delta
+and shows it above your document. See [Interface delta](#interface-delta).
+
 Add implementation detail only where it lets the reader check an important
 claim. In the decision log, keep the user's requirements in the user's words
 and add the implementation decisions that shaped the result.
@@ -61,6 +63,37 @@ Collapse optional detail with `{collapsed}` at the end of an H2:
 
 Progressive disclosure: every `##` heading is a section the reader can fold.
 
+## Interface delta
+
+The reader's first question is what the change lets them do that they could
+not before, and what it cost. thurview answers it from the code graph rather
+than from your prose: every symbol the diff touched that is visible outside
+its own file, as added, changed or removed, above your document. Read it with
+`thurview graph interfaces` before you write, and let it shape the document:
+
+- **A removed entry is the change's most review-worthy fact.** Say what
+  depended on it (`thurview graph callers <name> --graph base`) and what
+  replaces it. Never let a removal read as a rearrangement.
+- **`No interface moved` is a finding, not an empty result.** The change is
+  internal. Write about why it was worth making - the bug it fixes, the
+  duplication it folds - and do not dress it up as a capability.
+- **Do not restate the entries in prose.** The panel lists them, with the
+  declaration and a link into the file. Your sentences are for what it cannot
+  derive: why the surface has this shape, what a consumer does with it, what
+  a removal breaks.
+
+Add an `interfaces` entry in `data.yaml` (see [Components](components.md))
+only when one of these holds:
+
+1. A derived entry's declaration does not tell a consumer what it is for. The
+   `capability` line says what they can now do, in their words.
+2. The change moves an interface the graph cannot see - a CLI subcommand or
+   flag, an HTTP route, an event kind, a config key, a file format. Declare
+   it, with an anchor on the line the diff moved.
+
+Anything else is noise: the entry is already there, or there is nothing to
+add. An interface the change did not deliver is never an entry.
+
 ## Evidence
 
 Every claim about code carries an anchor. An anchor is a named source range

package/skills/thurview/references/software-map.md

@@ -1,8 +1,66 @@
 # Software map
 
-`map.yaml` describes the repository structure at head, and optionally at
-base, as nested nodes. The Map tab lets the reader drill from systems to code
-and shows what the change added, removed or touched.
+## What it is for
+
+The Files tab already answers *which lines changed*. The map answers the one
+question no other tab does: **where the change landed in the system, and what
+sits next to it.** A reader opens it to find out which parts the diff touched,
+what those parts connect to, and therefore what could break that the diff
+never mentions — and where to start reading.
+
+That makes the map a reviewing instrument, not a picture of the architecture.
+The Map tab reads it that way: parts the change touched are drawn before the
+parts it did not, a part carrying changed files says how many, links into a
+changed part are marked as the seams where two sides can fall out of step, and
+the reader is offered one part to start at. A node that answers none of *where
+did the change land*, *what does it sit next to*, *where do I start* does not
+sit there harmlessly — it makes the ones that do harder to find.
+
+Write it, then read it as the reader: does it send someone to the part of the
+change that needs attention faster than scrolling the diff would? If not,
+either cut nodes until it does, or ship no map at all.
+
+## When to ship without a map
+
+`nodes: []` is a real answer, not a gap. A map that adds nothing costs the
+reader a tab they open, learn nothing from, and distrust on the next review.
+An absent one costs nothing.
+
+Ship without a map when:
+
+- The change lands in one place and stays there. The Files tab already says
+  where it is; a map would only restate it with rounded corners.
+- Every part you could name is a file the diff already lists. The map would be
+  the Files tab with fewer details.
+- The repository has no structure worth naming at review scale — a handful of
+  modules with no boundary between them.
+
+Author one when:
+
+- The change crosses a boundary: one part now calls, stores or serves
+  something another part owns.
+- It adds or removes a part, so the shape of the system is different after it.
+- What the change touches is used by code the diff does not show, and the
+  reader has to know what that is before judging it.
+- The review is an architecture review. There the map is the subject, not the
+  orientation for one.
+
+When you skip it, say so in the handover, with the reason, in one line. Silence
+reads as an oversight.
+
+## What to model
+
+Model the people, systems, containers, components and code elements a reader
+must hold in mind to judge **this** change. Do not model incidental
+implementation detail, and do not aim for completeness: an exhaustive map and
+no map cost the reader about the same. For a large repository, keep the top
+level small and put detail one level down, so the first screen is a short list
+of places the change could be.
+
+## Schema
+
+`map.yaml` describes the repository structure at head, and optionally at base,
+as nested nodes.
 
 ```yaml
 nodes:
@@ -25,17 +83,20 @@ Rules:
   `app.cli`). Identity is the id; keep ids stable between base and head.
 - `kind`: `person`, `system`, `container`, `component`, `code`.
 - `files`: globs relative to the repository root (`*`, `**`, `?`). They link
-  the node to changed files in the Files tab. A glob matching nothing at the
-  pinned commit is a warning.
-- `anchor`: an anchor id from `data.yaml` that opens representative code.
+  the node to changed files in the Files tab, and they are what makes a node
+  say how much of the change it holds. A glob matching nothing at the pinned
+  commit is a warning.
+- `anchor`: an anchor id from `data.yaml` that opens representative code. Give
+  one to every node the change touched; it is the shortest path from the map
+  to the code.
 - Edges reference node ids. Labels are short verbs.
 
-Model the important people, systems, containers, components and code
-elements. Do not model incidental implementation detail. For a large
-repository, keep the top level small and put detail one level down.
+## Base and head
 
 Work base first, then apply only the structural changes of the diff to get
-head. Without `base`, nodes touched by the diff show as changed and nothing
+head. That is what lets the tab say *added*, *removed* and *changed* rather
+than *touched*, and those three words are most of what a reader takes from the
+map. Without `base`, nodes touched by the diff show as changed and nothing
 shows as added or removed.
 
 `thurview publish` validates the map with the document; map errors block