thurview 0.17.0 → 0.17.2

package/package.json

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

@@ -294,8 +294,9 @@ nothing: keep `--timeout` under that limit and run `wait` again on `timeout`.
 When the tool can run a command in the background and wake you when it exits,
 run `wait` that way, so the user has the terminal back while they read.
 
-While `wait` runs the reader's page says an agent is listening, and says the
-opposite within seconds of it returning. Do not loop it to look present: a
+While `wait` runs, and while you answer a `question` it returned, the
+reader's page says an agent is listening; it says the opposite within
+seconds of `wait` returning anything else. Do not loop it to look present: a
 question asked with nobody waiting is queued, not lost, and `thurview`
 reports it as `needsAgent` the next time you run any command in the
 worktree.

package/skills/thurview/references/components.md

@@ -3,6 +3,51 @@
 `data.yaml` holds typed inputs. `review.md` references them by id. Validation
 is strict: an unknown key fails `publish`.
 
+## Choosing a shape
+
+Pick a component by the question the reader is asking. One shape answers one
+question; used for another it is decoration the reader has to decode.
+
+| The reader is asking                                   | Shape                        |
+| ------------------------------------------------------ | ---------------------------- |
+| in what order, and between whom?                       | `sequence`                   |
+| where does the journey go, and where does it branch?   | `flow`                       |
+| how did we get here, and what did the change do to it? | `callstack`                  |
+| what shape is the data, and who reads or writes it?    | `database`                   |
+| what does this code actually say?                      | `peek`, or an anchor link    |
+| what parts is this system in, and what moved?          | `map.yaml`, not a fence      |
+| why this way and not the other way?                    | **none** — prose and anchors |
+
+Only the fences in this file render. A `mermaid`, `plantuml`, `dot` or `d2`
+fence is a publish error rather than a plain code block (see
+[Fences thurview does not render](#fences-thurview-does-not-render)); to quote
+diagram source as code, fence it as `text`.
+
+### A design choice is a comparison
+
+Reach for a diagram of a design and what you draw is the design you picked: the
+happy path, the way it works. That tells the reader what was built and nothing
+about what was rejected or why — which is the question a design document, and a
+review that made a non-obvious call, is there to answer.
+
+The vocabulary compares along two axes and no others:
+
+- **One call path, base against head.** `callstack`, in a review. Every frame
+  it reports as added or removed is checked against the pinned diff, and an
+  explainer and a design have no diff, so there both lists must be the same
+  frames in the same order. `publish` refuses most of what differs; the rest it
+  renders as unchanged, the diff being over the callee anchor alone. Either way
+  only the head list reaches the reader, and nothing contrasts.
+- **Structure, before against after.** `map.yaml`'s `base` beside `nodes` —
+  the system as it stands against the system the change or the design would
+  leave. See [Software map](software-map.md).
+
+**Neither axis is option A against option B.** Both put today against the one
+outcome you shipped or propose, so write the choice instead: a short paragraph
+per option, each anchored to the code it would land in or to the constraint
+that rules it out, and the reason the loser lost. That is the argument. A
+picture of the winner is not.
+
 ## data.yaml
 
 ```yaml

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

@@ -139,17 +139,13 @@ A claim you cannot anchor is a question, not a fact. Write it as one.
 
 ## Diagrams
 
-Use the fenced components for behaviour that prose explains badly:
-
-- `sequence` for temporal behaviour across actors
-- `flow` for a user journey and where it branches
-- `callstack` for call-flow differences between base and head
-- `database` for persisted-state structure and the operations on it
-
-Each message, frame, step and operation carries an anchor, so the reader can
-open the code behind every arrow. `mermaid` and the other general diagram
-languages are a publish error rather than a fifth option: thurview draws only
-what it can anchor. See [Components](components.md).
+Use a fenced component for behaviour that prose explains badly, and pick it by
+the question the reader is asking: [Choosing a shape](components.md#choosing-a-shape)
+holds one row per question, including the ones whose answer is no diagram at
+all. Frames, steps and operations carry an anchor, and a message carries an
+anchor or the code it stands for, so the reader can open what is behind the
+arrow. `mermaid` and the other general diagram languages are a publish error
+rather than another option: thurview draws only what it can anchor.
 
 Add a diagram only when it materially helps. A document with one good
 sequence diagram beats one with four.

package/skills/thurview/references/lifecycle.md

@@ -111,7 +111,9 @@ While `thurview wait` runs it writes a heartbeat to
 it back as one of two sentences: an agent is listening now, or nothing is
 listening and what you send is queued until one checks in. Nothing else
 writes it, so presence is never inferred and never faked. A heartbeat older
-than 15 seconds is a dead `wait`, not an agent.
+than 15 seconds is a dead `wait`, not an agent. When `wait` returns
+`question` it leaves a last heartbeat that holds for ten minutes, since you
+are answering and will wait again; the next `wait` takes over from it.
 
 That is why a question asked while you are away is not lost and does not need
 you to sit in `wait`: it is queued, `thurview` reports it as `needsAgent` the
@@ -130,7 +132,7 @@ thurview threads resolve <threadId> --review <id>
 ${THURVIEW_HOME:-~/.thurview}/
 ├── THURVIEW.md              user guidance (optional)
 ├── server.json              running server, if any
-├── agents/<id>.json         heartbeat of a running `wait`, removed when it ends
+├── agents/<id>.json         heartbeat of a running `wait`, or of an agent answering what it returned
 ├── forge/<id>.json          what the forge last said of the change request: head, state, CI, last pass posted
 ├── passes/<id>.json         the submission `forge pass` wrote, for `forge submit`
 └── reviews/<id>/
@@ -180,7 +182,8 @@ again.
 `thurview threads get <id>` truncates bodies over 1500 characters; pass
 `--full` when the hint says so.
 
-While `wait` runs, the reader's page says an agent is listening; when it
-returns, the page says the opposite within seconds. Do not leave `wait`
+While `wait` runs, and while you answer the question it returned, the
+reader's page says an agent is listening; when it returns anything else, the
+page says the opposite within seconds. Do not leave `wait`
 running to look present when you are not going to answer, and do not loop it
 to keep a queue drained: the queue survives you, and the reader is told so.

package/skills/thurview-design/SKILL.md

@@ -173,9 +173,27 @@ finishes is a design nobody decided on. A shape that works:
 code that exists at the pinned commit; a plain fence is a sketch. The reader
 tells them apart at a glance, and that difference is the whole trust model.
 
-Sequence diagrams work for a proposed flow: give a message a `code:` string
-rather than an `anchor:` where the code does not exist yet, and an `anchor:`
-where it does. See the `thurview` skill's Components reference for the shape.
+**Pick the diagram by the reader's question, or draw none.** The `thurview`
+skill's Components reference carries the table under "Choosing a shape" and the
+shape of every fence. Two rows decide most design documents:
+
+- A proposed flow across actors is a `sequence`: give a message a `code:`
+  string where the code does not exist yet, and an `anchor:` where it does.
+- **A choice between two designs is not a diagram.** Drawing the one you picked
+  shows the reader how it works and never why it beat the other. That argument
+  is prose with anchors, under **What was considered and dropped** above.
+
+No component renders two options side by side, and a design has no diff, so a
+`callstack` here must list the same frames in the same order on both sides.
+`publish` refuses most of what differs; the rest it renders as unchanged,
+because the diff runs on the callee anchor alone and a `{ calls: [...] }` hop
+whose parent differs reads as the same frame. Either way the reader never sees
+the base list.
+
+The map is the one before-and-after the vocabulary carries, and it puts today
+against your one proposal rather than one proposal against another: `base` for
+the structure as it stands, `nodes` for the structure proposed (step 5). It
+shows what the design moves, never why that beat the alternative.
 
 ### 5. Map the shape, when there is one
 
@@ -250,6 +268,9 @@ A design with no stated cost and no rejected alternative reads as advocacy, and
 readers approve it without deciding anything — which is the failure this whole
 document kind exists to prevent.
 
+A diagram of the design you picked is not a stated cost. It renders the option
+that won, so it reads as advocacy too, however carefully it is drawn.
+
 ## Completion criteria
 
 Report completion only when all of these hold: