thurview 0.1.4

package/skills/thurview/SKILL.md

@@ -0,0 +1,219 @@
+---
+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.
+user-invocable: true
+argument-hint: "[<pr-number|pr-url> | --base <ref> --head <ref> | <architecture topic>]"
+---
+
+# thurview
+
+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
+browser with live code peeks, diffs, diagrams and a map. The reader asks
+questions, leaves anchored comments, and approves or requests changes. The
+agent answers, updates, republishes.
+
+```mermaid
+flowchart LR
+  A[scaffold: pin base and head] --> B[author review.md, data.yaml, map.yaml]
+  B --> C[publish: validate and seal revision]
+  C --> D[open: reader reviews in the browser]
+  D -->|question| E[threads reply]
+  E --> D
+  D -->|request changes| B
+  D -->|approve| F[done]
+```
+
+Run the CLI as `thurview`. When it is not on PATH, `npx -y thurview` runs
+the published package with the same commands; substitute it everywhere below.
+
+Every command prints TOON on stdout: the result, then `help[]` with the next
+commands. Errors are structured on stdout too (`error`, `code`, `help`); exit
+code 1 is a failure, 2 a usage error such as an unknown flag. Progress goes to
+stderr; do not scrape it. `thurview` alone shows the reviews of the current
+directory; `thurview <command> --help` shows flags and examples.
+
+## Request
+
+$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.
+
+## 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 scaffold` lists the ones it found under `guidance`.
+
+Read [Document authoring](references/document-authoring.md) before you write.
+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`.
+
+## Workflow
+
+### 1. Resolve the review
+
+Run `thurview info` in the source worktree. It lists reviews bound to that
+worktree with `inSync` (HEAD equals the pinned head). Reuse a review that
+matches the requested change. Otherwise run `thurview scaffold` with the
+matching flags:
+
+```sh
+thurview scaffold                      # current branch vs trunk fork point
+thurview scaffold --pr 123             # pull request (needs gh)
+thurview scaffold --base <ref> --head <ref>
+thurview scaffold --new                # another review for the same binding
+thurview scaffold --update --review <id>   # re-pin after the branch moved
+```
+
+Record from the scaffold output: `review.id` (short id accepted everywhere),
+`review.dir`, `review.base`, `review.head`, `files.document`, `files.data`,
+`files.map`, `files.theme`, `change` (files, additions, deletions) and
+`guidance`.
+
+Resolve refs before passing them. Pass commit ids or plain ref names; do not
+pass `<rev>^` inside a jj workspace.
+
+### 2. Show small changes at once
+
+When `change.additions + change.deletions` is under 300, publish first and
+land the reader on the diff, then write the document:
+
+```sh
+thurview publish --review <id> --view files --open
+```
+
+The scaffolded stub validates as long as `README.md` exists at head; if it
+does not, point the `entry` anchor at any file that does. Larger changes skip
+this step.
+
+### 3. Study the change
+
+Read the whole diff once (`git diff <base> <head>`). Then read each changed
+symbol's callers and callees at head. Trace the main flow through storage,
+network and configuration boundaries. 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.
+
+Read every range you anchor from the pinned commit, not the working tree:
+`git show <head>:<path>` or `git show <base>:<path>`.
+
+### 4. Author the document
+
+Edit `review.md` and `data.yaml` in the review directory following
+[Document authoring](references/document-authoring.md). Keep it short.
+Default to anchor links for evidence; use an inline peek only when the reader
+must see the code to follow the main claim.
+
+### 5. Theme the review after the project
+
+Read [Theme](references/theme.md). Decide the look in its order: what the
+user asked for, then the reviewed project's own design system read from its
+files at head, then the default skin. Write `theme.yaml` in the review
+directory when steps 1 or 2 yield tokens; leave it empty otherwise. Say
+which source you used when you hand over the review.
+
+### 6. Author the map
+
+Dispatch one sub-agent to write `map.yaml` per
+[Software map](references/software-map.md) while you write the document, with
+this prompt filled in:
+
+```text
+Use the thurview skill's software-map reference (`thurview skill` prints the
+SKILL.md path; the reference is in references/software-map.md beside it).
+
+Review directory: <dir>
+Source worktree: <worktree>
+Base commit: <base>
+Head commit: <head>
+
+Author <dir>/map.yaml: the head structure under nodes/edges and the base
+structure under base. Do not edit review.md or data.yaml. Do not publish.
+Return when `thurview publish --review <id>` reports no map.yaml errors, or
+report the errors you could not fix.
+```
+
+Without a sub-agent facility, write the map yourself after the document, or
+leave `nodes: []` and say the map is not published.
+
+### 7. Publish
+
+```sh
+thurview publish --review <id>
+```
+
+Read every row of `diagnostics`. Fix each `error` and publish again. A
+`warning` does not block. `publish` refuses (code `THREADS_OPEN`) when a
+submitted comment thread is still open (see step 9). On success `published`
+carries `rev` and `url`; the status becomes `awaiting-review`.
+
+Then open it for the reader:
+
+```sh
+thurview open --review <id>            # prints url; --view files|commits|map
+```
+
+Give the user the `url` from the output.
+
+### 8. Wait for the reader
+
+```sh
+thurview wait --review <id>
+```
+
+It blocks until the reader needs you and prints `wait.reason` with the
+threads that need you:
+
+- `question`: an "Ask now" thread. Answer each thread in `threads` with
+  `thurview threads reply <threadId> --review <id> --body "<answer>"`. Do
+  not change the document for a question. Wait again.
+- `awaiting-agent-updates`: the reader submitted with "Request changes".
+  `threads` lists what to address and `wait.decision` the summary. Go to
+  step 9.
+- `accepted`: approved. Report and stop.
+- `review-dismissed` or `review-deleted`: stop.
+- error `TIMEOUT` (exit code 1, after `--timeout` seconds, default 3600):
+  wait again, or report that the reader has not responded.
+
+### 9. Address requested changes
+
+For each thread in `thurview threads list --review <id> --open`:
+
+- A document problem: fix `review.md` or `data.yaml`.
+- A code change request: change the branch under the normal rules (failing
+  test first), then `thurview scaffold --update --review <id>` to re-pin, and
+  re-read every anchored range that moved.
+- Answer in the thread with `threads reply` when the reader asked something
+  or when it is not obvious what you changed.
+- `thurview threads resolve <threadId> --review <id>` once the requested
+  change is present. Do not resolve a thread you did not address.
+
+Then publish again (step 7), and wait again (step 8). A republish requires
+zero open submitted comment threads; questions do not block.
+
+## Architecture reviews
+
+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.
+
+## 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.
+- The review is waiting on the reader, accepted, dismissed or deleted.

package/skills/thurview/references/components.md

@@ -0,0 +1,120 @@
+# Components
+
+`data.yaml` holds typed inputs. `review.md` references them by id. Validation
+is strict: an unknown key fails `publish`.
+
+## data.yaml
+
+```yaml
+actors:
+  agent: { label: Agent }
+  server: { label: Server, map: system.server }   # map: optional node id
+
+anchors:
+  spawn:
+    title: PTY spawn site                 # required
+    detail: Cold-path fallback branch     # optional, shown with the peek
+    map: system.server                    # optional node id
+    peek:                                 # required for links, peeks and diagrams
+      file: src/pty.ts                    # path at the pinned commit
+      from: 214                           # 1-based, inclusive
+      to: 223                             # >= from
+      graph: head                         # head (default) or base
+
+stores:
+  reviewDb:
+    kind: relational                      # relational (tables) or document (documents)
+    label: review.db
+    tables:
+      threads:
+        label: threads                    # optional
+        key: id                           # optional
+        schema:
+          id: { type: text, pk: true }
+          body: { type: text }
+```
+
+An anchor without `peek` can label a map node but cannot open code.
+
+## Anchor link
+
+```markdown
+[the spawn site](anchor:spawn)
+```
+
+Opens the range in the side peek. The anchor needs a `peek`.
+
+## peek
+
+````markdown
+```peek
+spawn
+```
+````
+
+Renders the range inline with title, path and detail.
+
+## sequence
+
+````markdown
+```sequence
+label: Open a trace quote
+messages:
+  - { from: agent, to: server, label: "startLogin(cols, rows)", anchor: spawn }
+  - { from: server, to: server, label: "spawnPty(dims)", code: "spawnPty(dims)" }
+  - { from: server, to: { label: CLI }, label: ready, anchor: ready }
+```
+````
+
+`from` and `to` are actor ids or an inline `{ label }`. Each message needs an
+`anchor` (peekable) or `code` (a string, or `{ language, text }`). Clicking a
+message opens its anchor.
+
+## callstack
+
+````markdown
+```callstack
+title: Warm allocation
+base: [reconcile, auth, enqueueWork]
+head:
+  - reconcile
+  - enqueueWork
+  - { calls: [enqueueWork, processItem], reason: dispatched via the work queue }
+```
+````
+
+Rules:
+
+1. List order is the stack; each frame calls the one below it.
+2. One anchor per frame, at the call site or the function head.
+3. The diff is positional over anchor identity. A frame kept in both stacks
+   is one head-graph anchor listed in both lists; it renders as context.
+4. A frame only in `base` is a removed call; its anchor must use
+   `graph: base`. Frames in `head` must use head anchors.
+5. `{ calls: [parent, child], reason }` marks a hop that is hard to follow
+   (queue, callback, RPC). It renders the child with a dashed `≈`.
+6. One component is one linear stack. Use two for two flows.
+7. `publish` checks each `-` frame against deleted lines and each `+` frame
+   against added lines in the pinned diff. Listing a frame on one side only
+   for contrast is rejected.
+
+## database
+
+````markdown
+```database
+title: Thread storage
+stores: [reviewDb]
+usecases:
+  - id: resolve
+    label: Resolve a thread
+    summary: optional one-liner
+    ops:
+      - { op: read,  store: reviewDb.threads,      actor: agent, label: load open threads, anchor: loadThreads }
+      - { op: write, store: reviewDb.threads.body, actor: agent, label: mark resolved,     anchor: markResolved }
+```
+````
+
+`store` is `storeId.collection` or `storeId.collection.field`. A read flows
+store to actor; a write flows actor to store; `op` sets the direction. Every
+store used must be listed in `stores`. Every `actor` must exist in
+`data.yaml`. Add this component only when a storage view materially helps.

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

@@ -0,0 +1,107 @@
+# Document authoring
+
+## Reader contract
+
+The reader sees the original request and your document. Not your reasoning,
+not the implementation session, not the names you used while working.
+Jargon coined during implementation is noise to them.
+
+The H1 is the review's title in the browser and on the home page. Make it
+short and specific to the change ("Publish pipeline: single mount"), never
+generic.
+
+Write short. Decide what to leave out before deciding what to put in. Every
+sentence costs the reader attention; spend it on what they cannot get from the
+diff: intent, the shape of the change, risk, what was left out and why.
+
+Write in plain, direct sentences. One idea per sentence. No praise of the
+change ("robust", "comprehensive"). Describe it.
+
+## Structure
+
+Open with a landing section between the H1 and the first H2:
+
+```markdown
+# Audit every login
+
+**Summary**
+
+- login() now records every attempt before checking the user
+- failed attempts are logged too, which the old code skipped
+- one new module, no interface change
+
+**Why**
+
+Support could not tell whether a locked-out user had tried at all. The
+request was "log every attempt, not only successes".
+```
+
+Then fewer than five further sections when practical. Pick those that fit:
+
+- requirements
+- design
+- interface change
+- lifecycle or data flow
+- state or storage
+- testing evidence
+- decision log
+
+Add implementation detail only where it lets the reader check an important
+claim. In the decision log, keep the user's requirements in the user's words
+and add the implementation decisions that shaped the result.
+
+Do not invent user-impact risks. When risk depends on usage you do not know,
+say so or ask.
+
+Collapse optional detail with `{collapsed}` at the end of an H2:
+
+```markdown
+## Edge cases {collapsed}
+```
+
+Progressive disclosure: every `##` heading is a section the reader can fold.
+
+## Evidence
+
+Every claim about code carries an anchor. An anchor is a named source range
+at the pinned base or head commit, defined in `data.yaml`. Link prose to it
+with an anchor link; the browser opens the range beside the document:
+
+```markdown
+The [spawn site](anchor:spawn) falls back to 120x30.
+```
+
+Show code inline only when the reader must see it to follow the main claim:
+
+````markdown
+```peek
+spawn
+```
+````
+
+Use the smallest range that proves the claim. Read the range from the pinned
+commit before you anchor it. `publish` rejects an anchor whose file or lines
+do not exist at that commit, and an anchor link to an anchor with no `peek`.
+
+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
+- `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).
+
+Add a diagram only when it materially helps. A document with one good
+sequence diagram beats one with four.
+
+## Files you edit
+
+Only `review.md`, `data.yaml`, `map.yaml` and `theme.yaml` in the review
+directory. Never
+edit `review.json`, `threads.json` or `revisions/`. Threads change only
+through `thurview threads`.

package/skills/thurview/references/lifecycle.md

@@ -0,0 +1,88 @@
+# Lifecycle and storage
+
+## Binding and pins
+
+A review binds to one unit of change: a branch, a pull request, or an
+explicit range. Scaffold resolves and records exact base and head commit
+ids. Everything is read from those commits, so moving the checkout changes
+nothing the reader sees.
+
+Choose the base deliberately:
+
+- bare scaffold: the trunk fork point (`merge-base` with `origin/HEAD`)
+- one commit: `--base <head>~1 --head <head>`
+- a stack: the branch directly below it
+
+`thurview scaffold --update --review <id>` re-pins from the binding: a branch
+follows its local tip, a PR asks GitHub. Publication never moves pins; it
+warns when the branch moved past them.
+
+## Statuses
+
+| Status                   | Owner and next action                                    |
+| ------------------------ | -------------------------------------------------------- |
+| `draft`                  | Agent authors and publishes.                             |
+| `awaiting-review`        | Reader reads, asks, comments, decides.                   |
+| `awaiting-agent-updates` | Agent addresses threads, resolves them, republishes.     |
+| `accepted`               | Terminal. Cannot be republished.                         |
+| `rejected`               | Terminal.                                                |
+
+"Ask now" does not change the status. "Submit review" with "Request changes"
+sets `awaiting-agent-updates`; with "Approve" sets `accepted`.
+
+Dismissal is separate: the reader removes the review from the active list and
+`wait` returns `review-dismissed`. A new publication restores it.
+
+## Threads
+
+Two kinds, chosen by the reader when creating one:
+
+- `ask` mode (a question): delivered at once. `wait` returns `question`.
+  Answer with `threads reply`. It stays open until the reader resolves it;
+  open questions never block a republish.
+- `review` mode (a comment): held as pending until the reader submits. Then
+  `wait` returns `awaiting-agent-updates` with the submitted threads.
+
+Targets: a document block (with an optional quoted selection), a file line
+on the base or head side, a map node, or the whole review.
+
+`publish` after the first revision requires zero open submitted comment
+threads. Resolve a thread only when its requested change is present. Do not
+rewrite or merge threads.
+
+```sh
+thurview threads list --review <id> [--open]
+thurview threads get <threadId> --review <id>
+thurview threads reply <threadId> --review <id> --body "<text>"
+thurview threads resolve <threadId> --review <id>
+```
+
+## Storage
+
+```text
+${THURVIEW_HOME:-~/.thurview}/
+├── THURVIEW.md              user guidance (optional)
+├── server.json              running server, if any
+└── reviews/<id>/
+    ├── review.md            you edit
+    ├── data.yaml            you edit
+    ├── map.yaml             you edit
+    ├── theme.yaml           you edit (project look; empty = default skin)
+    ├── review.json          binding, pins, status, presented revision
+    ├── threads.json         threads and decisions (use the CLI)
+    └── revisions/<n>/       sealed copies plus compiled document.json, map.json
+```
+
+A failed publish leaves the last sealed revision in place. The reader can
+switch between revisions in the browser.
+
+## wait
+
+`thurview wait --review <id> [--timeout <s>]` polls the review and returns
+`wait.reason` in `question`, `awaiting-agent-updates`, `accepted`,
+`rejected`, `review-dismissed`, `review-deleted`, with the threads that need
+you. After the timeout it fails with code `TIMEOUT` (exit 1). A question
+already answered by the agent is not reported again.
+
+`thurview threads get <id>` truncates bodies over 1500 characters; pass
+`--full` when the hint says so.

package/skills/thurview/references/software-map.md

@@ -0,0 +1,42 @@
+# 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.
+
+```yaml
+nodes:
+  - { id: app, kind: system, label: Review app, description: Local server and UI }
+  - { id: app.cli, kind: container, label: CLI, files: ["src/cli.ts"] }
+  - { id: app.server, kind: container, label: Server, files: ["src/server/**"] }
+  - { id: app.server.threads, kind: component, label: Threads, files: ["src/threads.ts"], anchor: createThread }
+  - { id: reader, kind: person, label: Reader }
+edges:
+  - { from: reader, to: app.server, label: reviews in the browser }
+  - { from: app.cli, to: app.server, label: publishes revisions }
+base:                      # optional: structure at the base commit
+  nodes: [...]
+  edges: [...]
+```
+
+Rules:
+
+- `id` is a dot path. Every parent must exist as a node (`app` before
+  `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.
+- 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.
+
+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
+shows as added or removed.
+
+`thurview publish` validates the map with the document; map errors block
+publication like document errors. An empty `nodes: []` means no map.

package/skills/thurview/references/theme.md

@@ -0,0 +1,90 @@
+# Theme
+
+A review looks like the project it reviews. `theme.yaml` in the review
+directory carries the tokens; `publish` validates it and seals it with the
+revision. An empty or absent file gives the default skin.
+
+## Decide the look, in this order
+
+Move to the next step only when the current one yields nothing.
+
+1. The user asked for a specific look or named a design system: use that.
+2. Inspect the reviewed project at the head commit and match its own design
+   system: a Tailwind or theme config, CSS custom properties or design
+   tokens, a component library theme, brand assets, an existing styled page
+   or website directory, font files it ships. Read the real values; do not
+   guess. Record what you read in `source`.
+3. Nothing found: keep the default skin. Do not invent a palette.
+
+State which of the three you used when you hand over the review.
+
+## theme.yaml
+
+```yaml
+name: acme-web                       # shown in the review menu
+source: tailwind.config.ts, src/styles/tokens.css
+mode: light                          # dark (default) or light
+
+colors:                              # any CSS color; every key optional
+  bg: "#ffffff"                      # page
+  bg2: "#f6f7f9"                     # panels, bars
+  bg3: "#eef0f3"                     # hover
+  code: "#f8fafc"                    # code surfaces
+  fg: "#111827"                      # text
+  fg2: "#4b5563"                     # secondary text
+  muted: "#9ca3af"
+  line: "#e5e7eb"                    # borders
+  accent: "#2563eb"                  # headings, primary actions, status
+  link: "#2563eb"                    # links and anchor links
+  ok: "#16a34a"
+  warn: "#d97706"
+  del: "#dc2626"
+  add: "rgb(22 163 74 / .12)"        # added-line background
+  remove: "rgb(220 38 38 / .12)"     # deleted-line background
+  select: "rgb(217 119 6 / .18)"     # highlighted-line background
+
+fonts:
+  display: "Inter, sans-serif"       # brand, buttons, document headings
+  body: "Inter, sans-serif"
+  mono: "'JetBrains Mono', monospace"
+  stylesheets:                       # external font css, loaded by the page
+    - https://fonts.googleapis.com/css2?family=Inter:wght@400;700&display=swap
+  files:                             # font files the project ships, read at head
+    - { family: Acme Sans, path: web/public/fonts/acme-sans.woff2, weight: "400 700" }
+
+shape:
+  radius: 8px                        # 0 in the default skin
+  bevel: false                       # pixel bevels on panels and buttons
+  glow: false                        # neon text glow on headings and tabs
+  scanlines: false                   # CRT overlay
+  headingTransform: none             # uppercase in the default skin
+
+code:                                # syntax palette; any key optional
+  keyword: "#7c3aed"
+  string: "#15803d"
+  function: "#b45309"
+  type: "#b45309"
+  variable: "#0369a1"
+  number: "#b45309"
+  comment: "#9ca3af"
+  punctuation: "#6b7280"
+  operator: "#374151"
+  tag: "#be185d"
+  fg: "#111827"
+
+css: |                               # optional extra rules, appended last
+  .doc h1 { letter-spacing: 0; }
+```
+
+Rules:
+
+- Keep contrast readable: body text against `bg`, code against `code`.
+- A light project gets `mode: light` and light backgrounds; the default skin
+  is dark and its bevels, glow and scanlines are off by default only when you
+  set them so.
+- `fonts.files` paths must exist at the pinned head commit; `publish`
+  rejects a missing one. Font stylesheets are fetched by the reader's
+  browser.
+- Map the project's semantic roles, not its whole palette: primary to
+  `accent` and `link`, success/warning/danger to `ok`/`warn`/`del`.
+- Unknown keys fail validation.