thurview 0.6.0 → 0.7.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "thurview",
-  "version": "0.6.0",
+  "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

@@ -150,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
 
-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:
+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.
+
+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
@@ -226,6 +233,7 @@ Tell the user, in a few lines and nothing more:
 - 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/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