thurview 0.14.0 → 0.16.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "thurview",
-  "version": "0.14.0",
+  "version": "0.16.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,8 +1,8 @@
 ---
 name: thurview
-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. For a design, an architecture proposal or an implementation plan — a change not written yet — use the thurview-design skill instead. 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.
+description: Author and publish a thurview review - a guided, evidence-anchored explanation of a change, a review of a branch, pull request or commit range, which the reader opens in the browser, annotates, asks questions about, and approves or sends back. To explain a codebase or one subsystem as it stands, use the thurview-explain skill; for a design, an architecture proposal or an implementation plan — a change not written yet — use the thurview-design skill. Use when the user asks to review a branch or PR, to explain or walk through a change, "review my branch against main", or invokes /thurview. Not for a pass/fail bug hunt.
 user-invocable: true
-argument-hint: "[<pr-number|pr-url> | --base <ref> --head <ref> | explain [<path>]]"
+argument-hint: "[<pr-number|pr-url> | --base <ref> --head <ref>]"
 ---
 
 # thurview
@@ -16,8 +16,9 @@ request asks for.
 - 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.
+  states what it did not examine. It is a separate skill —
+  `thurview-explain`, installed beside this one; run `thurview skill` for its
+  path. Stop here and read that instead.
 - A **design** explains a change that is NOT WRITTEN YET: a design, an
   architecture proposal, an implementation plan. It is pinned to the one commit
   it argues from, its anchors are the code as it stands, and what it would
@@ -64,10 +65,9 @@ directory; `thurview <command> --help` shows flags and examples.
 $ARGUMENTS
 
 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). A request for how something
+number or URL: that pull request. `--base`/`--head`: that range. A request to
+explain the codebase, a subsystem or its architecture rather than a change: a
+code explainer, per the `thurview-explain` skill. A request for how something
 _should_ be built rather than what was built: a design, per the
 `thurview-design` skill.
 
@@ -86,8 +86,7 @@ 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`. Read [Code explainer](references/code-explainer.md) when
-the request is a codebase rather than a change.
+write `theme.yaml`.
 
 ## Workflow
 
@@ -170,6 +169,13 @@ 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.
 
+Answer one question explicitly while you are in there: where does the change
+let input cross a trust boundary? What counts is defined once, in the
+`thurview-fix` skill's `SKILL.md` under "Findings" - read it there rather than
+deciding again, and record the answer in `data.yaml` under `security` in step 5.
+It is a place for the reader to look, not a finding and not a severity; a
+repository with a SAST tool already has that job covered.
+
 Do not spend the review on naming, formatting, import order, or missing
 defensive checks. Linters, type checkers and `/code-review` catch those, and a
 reader who wanted them would have run those instead.
@@ -226,6 +232,13 @@ 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.
 
+Then answer the security question from step 3 in the same file: `security: none`
+when the change crosses no trust boundary, or one entry per place it does, each
+with a head anchor the reader opens. Both are answers; leaving the key out is
+not, and publishes as "not assessed". See
+[Document authoring](references/document-authoring.md) and
+[Components](references/components.md).
+
 ### 6. Theme the review after the project
 
 Read [Theme](references/theme.md). Decide the look in its order: what the
@@ -258,6 +271,8 @@ Tell the user, in a few lines and nothing more:
 - 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
+- the `security` verdict, in one clause: what the change crosses, or that it
+  crosses nothing
 - 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
@@ -323,11 +338,11 @@ 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.
 
-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.
+Run `thurview explain [<path>]` instead and follow the `thurview-explain`
+skill. 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.
 
 ## Designing a change rather than reviewing one
 
@@ -343,6 +358,8 @@ Report completion only when all of these hold:
 - The reader has the URL of a published revision.
 - Every `error` diagnostic is resolved.
 - The map is published, or you said why it is not.
+- `security` in `data.yaml` is answered: `none`, or the crossings. A review
+  published as "not assessed" is not finished.
 - The review is waiting on the reader, accepted, closed, dismissed or deleted.
 
 Close with the decision and its summary (`wait.decision`), and the URL. When

package/skills/thurview/references/components.md

@@ -42,6 +42,10 @@ interfaces:
     change: added                         # added | changed | removed
     capability: Validate a review without sealing a revision.
     anchor: dryRunFlag                    # must hold a line the diff moved
+
+security:                                 # a review only; omit until you have looked
+  - boundary: The --shell flag reaches execFile's argv unquoted.
+    anchor: spawn                         # a head anchor, with a peek
 ```
 
 An anchor without `peek` can label a map node but cannot open code.
@@ -70,6 +74,40 @@ Each entry in `interfaces` does one of two things, and never both:
 "`thurview publish` gains `--dry-run`", not "added a boolean to
 PublishOptions".
 
+## security
+
+Where this change lets input cross a trust boundary. The browser shows it under
+the interface delta, so the reader is told either way rather than left to
+remember to look for it.
+
+**What counts as a trust boundary is defined once**, in the `thurview-fix`
+skill's `SKILL.md` under "Findings". Read it there. Nothing here repeats it, so
+the two cannot drift into disagreeing about what counts. That skill turns what
+it names into a ranked finding; this one only puts the place in front of the
+reader, so the same definition selects the lines and stops there.
+
+Three states, and they are three different claims:
+
+- **omitted**, or the word `pending` - you have not looked yet. The panel says
+  "not assessed", which is what a stub published before the walkthrough should
+  be saying.
+- **`security: none`** - you looked, and the change crosses none. Say it
+  explicitly: it is what makes this panel worth reading the next time.
+- **a list** - one entry per place. `boundary` is one sentence in the reader's
+  terms; `anchor` is a head anchor with a `peek`, because a crossing is the
+  boundary as the change leaves it.
+
+`publish` refuses an unknown anchor, an anchor with no `peek` and a `graph: base`
+anchor: an anchor that opens nothing is how a reader stops trusting the ones that
+do. It also refuses an empty list - write `none` rather than leave the reader to
+work out which of the two you meant. Resolving a crossing marks its anchor used,
+so an anchor that only a crossing names raises no "defined but never used".
+
+There is no severity here. A crossing is a place for the reader to look; the
+severity that exists belongs to the findings in `thurview-fix`, not to this
+document. An explainer and a design are pinned to one commit and have no change,
+so `publish` refuses the key on either.
+
 ## Anchor link
 
 ```markdown

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

@@ -94,6 +94,25 @@ only when one of these holds:
 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.
 
+## Trust boundaries
+
+Every review answers where the change lets input cross a trust boundary, in
+`data.yaml` under `security`. It is not a section you write: the browser shows
+it under the interface delta, one line per place with the anchor the reader
+opens.
+
+Answer it after you have read the diff and the graph, and answer it either way.
+`security: none` is the whole answer for a change that crosses none, and writing
+it is what makes the panel worth reading on the review where it is not none. A
+review that leaves the key out publishes as "not assessed", which is honest for
+a stub and is not an answer.
+
+What counts as a trust boundary is defined once, in the `thurview-fix` skill's
+`SKILL.md` under "Findings" - read it there rather than deciding again. Do not
+turn this into an audit: thurview surfaces the places, it does not rank them,
+and a repository that runs a SAST tool already has the other job covered. See
+[Components](components.md) for the shape and what `publish` refuses.
+
 ## Evidence
 
 Every claim about code carries an anchor. An anchor is a named source range

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

package/skills/thurview-design/SKILL.md

@@ -54,11 +54,11 @@ whole repository. The rest of the request is what to design.
 
 ## Which kind is this
 
-| The request is about                                          | Kind       | Skill                                    |
-| ------------------------------------------------------------- | ---------- | ---------------------------------------- |
-| code that is written — a branch, a PR, a range                | review     | `thurview`                               |
-| code that exists, explained — "how does this work"            | explainer  | `thurview`, its code-explainer reference |
-| code that is **not written yet** — "how should we build this" | **design** | this one                                 |
+| The request is about                                          | Kind       | Skill              |
+| ------------------------------------------------------------- | ---------- | ------------------ |
+| code that is written — a branch, a PR, a range                | review     | `thurview`         |
+| code that exists, explained — "how does this work"            | explainer  | `thurview-explain` |
+| code that is **not written yet** — "how should we build this" | **design** | this one           |
 
 A plan for work already done is a review. An explanation with a
 recommendation stapled on is an explainer that broke its own rule. If the

package/skills/{thurview/references/code-explainer.md → thurview-explain/SKILL.md}

@@ -1,33 +1,80 @@
-# Code explainer
+---
+name: thurview-explain
+description: Author and publish a thurview code explainer - a guided, evidence-anchored explanation of a codebase, or one subsystem of it, at a single pinned commit, which the reader opens in the browser, annotates, asks questions about, and sends back or marks done. Every claim is anchored to a file and line range, a software map carries the parts the prose does not reach, and coverage states what was never examined. Use when the user asks to explain or walk through a codebase, how a system or a subsystem works, where its design problems might be, "explain this repository", "how does the server work", or invokes /thurview-explain. Not for reviewing a change that is already written, which is the thurview skill.
+user-invocable: true
+argument-hint: "[<path scope>] [--commit <ref>]"
+---
+
+# thurview explain
 
 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
+revisions and the publish → wait → answer loop with the `thurview` skill's
+review. 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_ |
+
+## Which kind is this
 
 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.
+"I want to see the architecture".
+
+| The request is about                                          | Kind          | Skill             |
+| ------------------------------------------------------------- | ------------- | ----------------- |
+| code that exists, explained - "how does this work"            | **explainer** | this one          |
+| code that is written - a branch, a PR, a range                | review        | `thurview`        |
+| code that is **not written yet** - "how should we build this" | design        | `thurview-design` |
 
 If the request is a change, do not reach for an explainer because the change is
-large. A large change is still a change.
+large. A large change is still a change. An explanation with a recommendation
+stapled on is an explainer that broke its own rule - see "Surface structure; do
+not grade it" below, and write the design instead when the request is genuinely
+"explain this, then propose a change".
+
+## Request
+
+$ARGUMENTS
+
+A path scope narrows the explainer to one part of the system; with none it is
+the whole repository.
+
+## Before authoring
+
+Read the guidance files that exist, in this order; the second wins on conflict.
+
+1. `~/.thurview/THURVIEW.md` (or `$THURVIEW_HOME/THURVIEW.md`), user guidance.
+2. `THURVIEW.md` at the repository root, repository guidance.
+
+`thurview explain` lists the ones it found under `guidance`.
+
+The `thurview` skill ships the references this one shares - document authoring,
+components, software map, theme, lifecycle. `thurview skill` prints the path of
+every bundled SKILL.md; the references sit beside each one. Read **Document
+authoring** before you write `review.md`, **Components** before you edit
+`data.yaml`, **Software map** before you author `map.yaml`, **Theme** before you
+write `theme.yaml`, and **Lifecycle** for statuses, storage and thread rules -
+they are identical for all three kinds.
+
+Run the CLI as `thurview`; `npx -y thurview` runs the published package with
+the same commands. Every command prints TOON on stdout - the result, then
+`help[]` with the next commands. Errors are structured on stdout too (`error`,
+`code`, `help`); exit 1 is a failure, 2 a usage error. If a command answers
+`unknown command` for something this skill tells you to run, the installed CLI
+is older than the skill: run `thurview update`, retry once, then report it.
 
 ## The document kind, in one command
 
@@ -59,7 +106,8 @@ So work in three layers, and let each carry what it is good at.
    `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.
+   the prose will not reach. See the `thurview` skill's Software map
+   reference 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.
@@ -85,7 +133,7 @@ puts one of three states on it:
 
 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
+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:
@@ -106,8 +154,8 @@ 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
+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.
 
@@ -145,17 +193,19 @@ the code" - not a finding.
    `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).
+   Dispatch a sub-agent for it if you have one, exactly as the `thurview`
+   skill's review does.
+4. Author `review.md` and `data.yaml` per **Document authoring**, minus the
+   interface-delta section: an explainer has none, and declaring
+   `interfaces` in `data.yaml` is an error. So is `security`, which is what a
+   change carries input across and an explainer has no change. So is
+   `graph: base` on an anchor - there is one commit.
+5. `theme.yaml` as usual - see **Theme**.
 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).
+   **Lifecycle**.
 
 ## Hand over
 
@@ -164,3 +214,18 @@ 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.
+
+## Completion criteria
+
+Report completion only when all of these hold:
+
+- The reader has the URL of a published revision.
+- Every `error` diagnostic is resolved.
+- The map is published, or you said why it is not - and the coverage split says
+  the same thing the document does.
+- The explainer is waiting on the reader, accepted, closed, dismissed or
+  deleted.
+
+Close with the decision and its summary (`wait.decision`) and the URL. When the
+reader has not responded, say so and leave it open; a later session picks it up
+from `thurview` in the same worktree.