thurview 0.5.0 → 0.6.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "thurview",
-  "version": "0.5.0",
+  "version": "0.6.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
@@ -176,6 +185,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,6 +223,7 @@ 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
 - that you are now waiting for their questions and their decision

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