thurview 0.15.0 → 0.17.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "thurview",
-  "version": "0.15.0",
+  "version": "0.17.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/references/components.md

@@ -170,6 +170,53 @@ Rules:
    against added lines in the pinned diff. Listing a frame on one side only
    for contrast is rejected.
 
+## flow
+
+````markdown
+```flow
+label: Sign in
+steps:
+  - { id: land,  label: Visitor opens /login, actor: visitor, next: post }
+  - { id: post,  label: Credentials posted,   anchor: loginRoute, next: check }
+  - { id: check, label: Credentials valid?,   anchor: checkUser,
+      when: [{ case: valid, to: home }, { case: rejected, to: retry }] }
+  - { id: retry, label: Error shown,          anchor: renderError, next: post }
+  - { id: home,  label: Dashboard,            anchor: dashboard }
+```
+````
+
+A user journey and where it branches - the shape `sequence` cannot hold,
+because a decision is not a message. The first step is the entry; a step
+continues with `next` or branches with `when`, and one with neither ends the
+flow. Cycles are fine: a retry loop is what a journey does, and a step that
+leads back up is drawn down a lane on the right, one lane per loop so two
+retries never share a vertical run.
+
+Every step is either code or a person: `anchor` is where the code does it and
+the reader opens it by clicking, `actor` is a declared actor doing it outside
+the code, and a step carries at least one of the two. An actor-only step is
+drawn dashed, so the reader can see at a glance which parts open something.
+
+`publish` refuses:
+
+1. A step with neither `anchor` nor `actor`, and a block where no step has an
+   `anchor` at all - a flow nothing opens is prose in a box.
+2. `next` and `when` on one step, and a `when` with a single case. One is a
+   branch, the other is a `next`.
+3. A `next` or `to` naming a step the block does not declare, or naming itself.
+4. A step unreachable from the first one, a duplicate `id`, an unknown `actor`,
+   and an anchor with no `peek`.
+
+## Fences thurview does not render
+
+`mermaid`, `plantuml`, `puml`, `dot`, `graphviz` and `d2` in a document body are
+a publish error. They used to be neither components nor an error, so the block
+reached the reader as its own source text with nothing saying so. thurview draws
+only what it can anchor at the pinned commit: use `flow` for a journey and
+`sequence` for a message exchange. To quote one of those languages as source -
+reviewing a change to a repository's own diagrams - fence it as `text`, which
+renders as the code block it is.
+
 ## database
 
 ````markdown

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

@@ -142,11 +142,14 @@ A claim you cannot anchor is a question, not a fact. Write it as one.
 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 and operation carries an anchor, so the reader can open
-the code behind every arrow. See [Components](components.md).
+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).
 
 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

@@ -131,6 +131,7 @@ ${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
+├── 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>/
     ├── review.md            you edit
@@ -145,6 +146,26 @@ ${THURVIEW_HOME:-~/.thurview}/
 A failed publish leaves the last sealed revision in place. The reader can
 switch between revisions in the browser.
 
+## The queue
+
+The home page lists every document, grouped by repository and ordered by whose
+turn it is. It is read from the store on every load and never published, so it
+cannot go stale. Whose turn, most urgent first:
+
+| Turn   | When                                                                      |
+| ------ | ------------------------------------------------------------------------- |
+| you    | a decision on a change request that no `forge submit` has posted yet     |
+| you    | `awaiting-review`, pinned at the change request's head, no thread waiting |
+| agent  | the change request's head moved past the pin: `scaffold --update`         |
+| agent  | a thread `needsAgent`, or `awaiting-agent-updates`                        |
+| agent  | `draft`: nothing published yet                                            |
+| nobody | `accepted`, `closed`, dismissed, or the change request merged or closed   |
+
+The forge columns come from `forge/<id>.json`, which `scaffold --pr`, `forge
+status` and `forge submit` write for the document bound to that change request.
+Run `thurview forge status --review <id>` to refresh a row; until something
+has, the row says the forge was not read.
+
 ## wait
 
 `thurview wait --review <id> [--timeout <s>]` polls the review and returns