thurview 0.6.0 → 0.8.0

package/package.json

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

@@ -1,12 +1,24 @@
 ---
 name: thurview
-description: Author and publish a thurview review - a guided, evidence-anchored explanation of a branch, pull request or commit range that the reader opens in the browser, annotates, asks questions about, and approves or sends back. Use when the user asks to review a branch or PR, to explain or walk through a change, "review my branch against main", to explain how a codebase or subsystem works, or invokes /thurview. Not for a pass/fail bug hunt.
+description: Author and publish a thurview document - a guided, evidence-anchored explanation the reader opens in the browser, annotates, asks questions about, and approves or sends back. Two kinds: a review of a branch, pull request or commit range, and a code explainer of a whole codebase or one subsystem at a pinned commit. Use when the user asks to review a branch or PR, to explain or walk through a change, "review my branch against main", to explain how a codebase or subsystem works or where its design problems might be, or invokes /thurview. Not for a pass/fail bug hunt.
 user-invocable: true
-argument-hint: "[<pr-number|pr-url> | --base <ref> --head <ref> | <architecture topic>]"
+argument-hint: "[<pr-number|pr-url> | --base <ref> --head <ref> | explain [<path>]]"
 ---
 
 # thurview
 
+There are two kinds of document, and the first decision is which one the
+request asks for.
+
+- A **review** explains a CHANGE: a branch, a pull request, a commit range. It
+  has a diff, commits and an interface delta, and the reader approves it or
+  sends it back. Everything below describes it.
+- A **code explainer** explains a CODEBASE, or one subsystem, at a single
+  pinned commit, so the reader can see the architecture well enough to spot
+  design problems themselves. It has no diff and nothing to approve, and it
+  states what it did not examine. Read
+  [Code explainer](references/code-explainer.md) and follow that instead.
+
 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.
 thurview validates those anchors, seals a revision, and serves it in the
@@ -41,9 +53,11 @@ directory; `thurview <command> --help` shows flags and examples.
 
 $ARGUMENTS
 
-Empty: the current branch against its up-to-date trunk. A PR number or URL:
-that pull request. `--base`/`--head`: that range. Anything else: an
-architecture review of that topic in the current repository.
+Empty: a review of the current branch against its up-to-date trunk. A PR
+number or URL: that pull request. `--base`/`--head`: that range. `explain`, or
+a request to explain the codebase, a subsystem or its architecture rather than
+a change: a code explainer, per
+[Code explainer](references/code-explainer.md).
 
 ## Before authoring
 
@@ -60,7 +74,8 @@ Read [Components](references/components.md) before you edit `data.yaml` or add
 a fenced component. Read [Lifecycle](references/lifecycle.md) for statuses,
 storage and thread rules. Read [Software map](references/software-map.md)
 before you author `map.yaml`. Read [Theme](references/theme.md) before you
-write `theme.yaml`.
+write `theme.yaml`. Read [Code explainer](references/code-explainer.md) when
+the request is a codebase rather than a change.
 
 ## Workflow
 
@@ -150,11 +165,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 +248,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.
@@ -273,12 +296,17 @@ Then publish again (step 7), tell the user what changed since the previous
 revision in a line or two, and wait again (step 9). A republish requires zero
 open submitted comment threads; questions do not block.
 
-## Architecture reviews
+## Explaining a codebase rather than a change
+
+Do not pin the same commit as base and head to fake it. That leaves a review
+whose Files, Commits and interface-delta surfaces all describe a change that
+does not exist, which is a claim, not a gap.
 
-Pin the same commit as base and head: `thurview scaffold --base HEAD --head
-HEAD`. Choose sections that describe the system (data flows, state, storage,
-module boundaries) and skip diff-specific ones. Scope to one subsystem. All
-other steps are the same; the Files tab shows any file at head on request.
+Run `thurview explain [<path>]` instead and follow
+[Code explainer](references/code-explainer.md). It is the same loop - pin,
+author, publish, wait, answer - over a document kind whose unit is a codebase:
+no diff, no commits, no interface delta, and a Coverage tab stating what the
+document reached and what it did not.
 
 ## Completion criteria
 

package/skills/thurview/references/code-explainer.md

@@ -0,0 +1,166 @@
+# Code explainer
+
+A **review** explains a change. An **explainer** explains a codebase, or one
+subsystem of it, at a single pinned commit, so the reader can see the
+architecture well enough to spot design problems themselves.
+
+Same engine, different unit. It shares anchors, peeks, the map, threads,
+revisions and the publish → wait → answer loop. It has no diff, no commits and
+no interface delta, because those are claims about a change and there is no
+change. Where a review shows the interface delta, an explainer shows
+**coverage**: what it examined at that commit, and what it did not.
+
+| Tab           | Review                             | Explainer                                     |
+| ------------- | ---------------------------------- | --------------------------------------------- |
+| Review        | the walkthrough, with the delta    | **Explainer**: the document, with coverage     |
+| Files         | split diff of the changed files    | absent                                         |
+| Commits       | base..head                         | absent                                         |
+| Map           | parts, marked added/changed/removed | parts at the pinned commit                    |
+| Coverage      | absent                             | **what the document reached, and what it did not** |
+| Threads       | ask, comment, decide               | same, and the decision reads *Done reading* / *Send it back* |
+
+## When to write one
+
+Write an explainer when the request is about the code as it stands: "explain
+this codebase", "how does the server work", "walk me through `src/graph`",
+"I want to see the architecture". Write a review when the request is about a
+change: a branch, a pull request, a range.
+
+If the request is a change, do not reach for an explainer because the change is
+large. A large change is still a change.
+
+## The document kind, in one command
+
+```sh
+thurview explain                 # the whole repository at HEAD
+thurview explain src/server      # one subsystem
+thurview explain --commit v1.2.0 # a released commit rather than HEAD
+```
+
+The positional argument is a path or a glob; a bare path means that directory
+and everything under it. It is the **scope**, and everything else obeys it:
+`graph architecture` reports the clusters inside it, and coverage accounts for
+every file inside it. A scope that matches no file at that commit is refused.
+
+Record `explainer.id`, `explainer.dir`, `explainer.commit`, `explainer.scope`
+and `scale.filesInScope` from the output. Everywhere else the id is passed as
+`--review <id>`; that flag names a document, whichever kind it is.
+
+## Keeping it short without lying about it
+
+A review is bounded by its diff. A codebase is not, and this is the hard part:
+evidence-anchored prose over a whole repository either runs unreadably long or
+quietly leaves most of the system out. Prose that leaves things out silently is
+misleading about architecture, which is the one thing an explainer must not be.
+
+So work in three layers, and let each carry what it is good at.
+
+1. **System — the map carries breadth.** Author `map.yaml` first, seeded from
+   `thurview graph architecture --review <id>`: communities become nodes, their
+   files become the node's `files` globs, and the edges between communities
+   become edges. Every part of the scope should appear here, including the parts
+   the prose will not reach. See [Software map](software-map.md) for the shape.
+2. **Subsystem — the prose carries depth.** Pick the parts that carry the most
+   structure and the most traffic, and explain those. Three to six sections.
+   Everything else stays on the map.
+3. **File and symbol — anchors carry the proof.** Every claim gets an anchor.
+   The reader opens code where they want it and nowhere else.
+
+**Select by structure, not by taste, and say what you selected on.** The graph
+gives you the basis: cluster size in files and symbols, the hub symbols of each
+cluster (most referenced), and the reference counts on the edges between
+clusters. Say in the document which parts you took and why they were the ones -
+"the two clusters with the most traffic between them" is a reason a reader can
+check. "The interesting bits" is not.
+
+## Coverage is derived, not claimed
+
+`thurview publish` accounts for every file in scope at the pinned commit and
+puts one of three states on it:
+
+- **explained** - an anchor in the document points into the file.
+- **placed** - a map node's `files` globs match it, and no anchor does. The
+  reader is told where it sits, not what it does.
+- **not examined** - neither.
+
+The counts go above the document and onto the Coverage tab, and `publish`
+prints them with the files it did not examine. You cannot forget to state
+coverage, and you cannot overstate it: to move a file out of *not examined* you
+have to actually anchor it or actually place it on the map.
+
+Two consequences worth planning for:
+
+- **An explainer without a map counts everything the prose does not anchor as
+  not examined.** `publish` warns when there is no map. That is a true
+  statement, and usually not the one you want to make: author the map.
+- **A broad glob is visible.** The Coverage tab lists each map node with the
+  globs it owns and how many files they match, so `**/*` on one node inflates
+  nothing quietly.
+
+Coverage also states what the code graph could not read: files in languages it
+does not parse (`thurview graph` covers TypeScript, JavaScript, Python, Go,
+Rust and Java), and whether its file list was capped. Those files are absent
+from the structure, not empty. If a large part of the scope is outside the
+graph, say so in the document rather than letting the map imply the system is
+smaller than it is.
+
+## Surface structure; do not grade it
+
+thurview's thesis holds here: *it does not review the code for you; it helps
+you understand it fast enough to review it yourself.* An explainer exists so
+the reader can **detect** design problems. That is only consistent with the
+thesis if you surface structure and leave the conclusion to them.
+
+The test: **every fact in an explainer is a count, or a list of named things,
+at the pinned commit, that the reader could re-derive with `thurview graph`.**
+
+Observation - write these:
+
+- "`src/server` is referenced from four other parts; it references one."
+- "`Store` is defined in `src/db.ts` and `src/cache.ts`."
+- "The API layer reaches the database layer in 14 places and the model layer in
+  2; the model layer reaches the API layer in 6."
+- "Nothing in the scope references `legacy/` at this commit."
+- "No test file reaches this cluster." (a count of zero, stated as one)
+
+Judgement - never write these:
+
+- "This violates separation of concerns."
+- "The god object here should be split."
+- severities, scores, "issues found", "critical", "smell", a ranked list of
+  problems, or a recommendation section.
+
+The difference is not tone. "A module with 14 inbound dependencies" is
+something the reader acts on; "an over-coupled module" is a verdict they cannot
+check. When you are unsure, write the count and stop. If a structure genuinely
+worries you, the honest move is a question in the document - "the two stores
+both define `Session`; whether that is one concept or two is not visible from
+the code" - not a finding.
+
+## Workflow
+
+1. `thurview explain [<scope>]`. Note the id, the commit and the scope.
+2. `thurview graph architecture --review <id>`. This is the structure at the
+   pinned commit; do not re-derive it by reading directories.
+   `thurview graph callers <name>` and `tests-for <name>` answer the follow-ups.
+   `graph interfaces` and `graph impact` compare two commits and are refused.
+3. Author `map.yaml` from the architecture output, covering the whole scope.
+   Dispatch a sub-agent for it if you have one, exactly as a review does.
+4. Author `review.md` and `data.yaml` per [Document authoring](document-authoring.md),
+   minus the interface-delta section: an explainer has none, and declaring
+   `interfaces` in `data.yaml` is an error. So is `graph: base` on an anchor -
+   there is one commit.
+5. `theme.yaml` as usual - see [Theme](theme.md).
+6. `thurview publish --review <id>`. Read `coverage` and `notExamined`. If the
+   split is not the one you meant, anchor or place more and publish again.
+7. `thurview open --review <id>`, then `thurview wait --review <id>`. The loop,
+   the statuses and the thread rules are identical to a review; see
+   [Lifecycle](lifecycle.md).
+
+## Hand over
+
+In a few lines: the url, the scope and the commit, the coverage line in its own
+words (including how many files were not examined), which parts you chose to
+explain and on what basis, and that you are waiting for their questions. Do not
+list the design problems you think you saw. The document is built so the reader
+finds 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