@erclx/canon 5.24.0 → 5.25.0

package/claude/skills/role-orchestrator/scripts/poll.ts

@@ -20,7 +20,6 @@ interface Review {
 
 export interface Payload {
   comments?: Comment[]
-  headRefOid?: string
   reviews?: Review[]
 }
 
@@ -416,11 +415,80 @@ const parseJson = (text: string): unknown => {
   }
 }
 
+/**
+ * One JSON object per line, which is what `.[] | <projection> | @json` prints
+ * across every page. The projection keeps stdout to the fields the mappers
+ * read, since a whole REST row carries user objects and links and a long thread
+ * could overrun the spawn buffer and read as unreadable. A failed read and a
+ * line that does not parse both return null, so neither reads as a thread with
+ * nothing on it.
+ */
+const readRows = (
+  path: string,
+  fields: string,
+): null | Record<string, unknown>[] => {
+  const read = run('gh', [
+    'api',
+    '--paginate',
+    `repos/{owner}/{repo}/${path}`,
+    '--jq',
+    `.[] | {${fields}} | @json`,
+  ])
+  if (!read.isOk) return null
+
+  const rows: Record<string, unknown>[] = []
+  for (const line of read.stdout.split('\n')) {
+    if (line.trim() === '') continue
+    const row = parseJson(line)
+    if (typeof row !== 'object' || row === null) return null
+    rows.push(row as Record<string, unknown>)
+  }
+
+  return rows
+}
+
+const text = (value: unknown): null | string =>
+  typeof value === 'string' ? value : null
+
+/**
+ * The REST rows carry snake_case names, mapped onto the camelCase shape the
+ * classifiers read. `commit_id` becomes `commit.oid`. A pending review has no
+ * `submitted_at`, which maps to null.
+ */
+export const toReview = (row: Record<string, unknown>): Review => ({
+  body: text(row.body),
+  commit: { oid: text(row.commit_id) },
+  submittedAt: text(row.submitted_at),
+})
+
+export const toComment = (row: Record<string, unknown>): Comment => ({
+  body: text(row.body),
+  createdAt: text(row.created_at),
+})
+
+/**
+ * Two reads feed one payload, so either failing makes the pull request
+ * unreadable rather than a thread missing half its rows.
+ */
+const readPayload = (number: string): null | Payload => {
+  const reviews = readRows(
+    `pulls/${number}/reviews?per_page=100`,
+    'body, commit_id, submitted_at',
+  )
+  const comments = readRows(
+    `issues/${number}/comments?per_page=100`,
+    'body, created_at',
+  )
+  if (reviews === null || comments === null) return null
+
+  return { comments: comments.map(toComment), reviews: reviews.map(toReview) }
+}
+
 type Snapshot = { baseline: Baseline } | { row: Row }
 
 const nowSeconds = (): number => Math.floor(Date.now() / 1000)
 
-const readHead = (number: string, payload: Payload): string => {
+const readHead = (number: string): string => {
   // The tip is the authority for the head, not the pull request object, which
   // lags the ref by up to a minute after a push. The object's head is the
   // fallback for a target on an older binary with no `pr head` verb.
@@ -432,13 +500,20 @@ const readHead = (number: string, payload: Payload): string => {
       ? (record as Record<string, unknown>).tip
       : undefined
 
-  return typeof tip === 'string' && tip !== ''
-    ? tip
-    : (payload.headRefOid ?? '')
+  if (typeof tip === 'string' && tip !== '') return tip
+
+  const pull = run('gh', [
+    'api',
+    `repos/{owner}/{repo}/pulls/${number}`,
+    '--jq',
+    '.head.sha',
+  ])
+
+  return pull.isOk ? pull.stdout.trim() : ''
 }
 
 /**
- * `gh pr view --json mergeable` reports UNKNOWN until GitHub finishes
+ * The pull read's `mergeable_state` reports unknown until GitHub finishes
  * computing it, which is exactly when a poll asks. merge-tree answers locally
  * against the base this machine has. It exits non-zero on a ref it cannot
  * resolve as well as on a real conflict, so both sides are checked first.
@@ -530,12 +605,9 @@ const main = (): number => {
   // one as GONE. That is a louder wrong answer than the one this script was
   // fixed for, so the run aborts rather than classify on it.
   const listed = run('gh', [
-    'pr',
-    'list',
-    '--state',
-    'open',
-    '--json',
-    'number',
+    'api',
+    '--paginate',
+    'repos/{owner}/{repo}/pulls?state=open&per_page=100',
     '--jq',
     '.[].number',
   ])
@@ -550,19 +622,10 @@ const main = (): number => {
 
   const snapshots: Snapshot[] = []
   for (const number of listed.stdout.split(/\s+/).filter((n) => n !== '')) {
-    // A query that failed and a pull request with no reviews both arrive as
-    // an empty result, so one query per pull request gives the failure a
-    // single place to surface.
-    const view = run('gh', [
-      'pr',
-      'view',
-      number,
-      '--json',
-      'headRefOid,reviews,comments',
-    ])
-    const payload = view.isOk
-      ? (parseJson(view.stdout) as Payload | null)
-      : null
+    // A read that failed and a pull request with no reviews both arrive as an
+    // empty result, so each read returns null on failure and the payload gives
+    // the failure a single place to surface.
+    const payload = readPayload(number)
     const old = known.get(number)
     const unreadable = (reason: string): void => {
       if (old === undefined) {
@@ -578,12 +641,12 @@ const main = (): number => {
       snapshots.push({ baseline: carryForward(old) })
     }
 
-    if (payload === null || typeof payload !== 'object') {
+    if (payload === null) {
       unreadable('could not be read')
       continue
     }
 
-    const head = readHead(number, payload)
+    const head = readHead(number)
     if (head === '') {
       unreadable('returned no head')
       continue

package/claude/skills/role-orchestrator/scripts/repo.ts

@@ -53,12 +53,10 @@ export const baseRef = (): string => {
   if (symbolic.isOk && ref !== '') return ref
 
   const repo = run('gh', [
-    'repo',
-    'view',
-    '--json',
-    'defaultBranchRef',
+    'api',
+    'repos/{owner}/{repo}',
     '--jq',
-    '.defaultBranchRef.name',
+    '.default_branch',
   ])
   const name = repo.isOk ? repo.stdout.trim() : ''
 

package/claude/skills/role-orchestrator/scripts/watch.ts

@@ -175,14 +175,11 @@ export const pass = (
 
 const readPulls = (): Read<string[]> => {
   const listed = run('gh', [
-    'pr',
-    'list',
-    '--state',
-    'open',
-    '--json',
-    'number,headRefName,title',
+    'api',
+    '--paginate',
+    'repos/{owner}/{repo}/pulls?state=open&per_page=100',
     '--jq',
-    '.[] | "PR-OPEN #\\(.number) \\(.headRefName) \\(.title)"',
+    '.[] | "PR-OPEN #\\(.number) \\(.head.ref) \\(.title)"',
   ])
   if (!listed.isOk) return { isOk: false }
 

package/docs/agents/canvas.md

@@ -5,7 +5,7 @@ description: The canvas server, its content format, and the verbs that list, arr
 
 # Canvas
 
-`canon canvas` serves a local canvas of pages and HTML frames and gives an agent the verbs the operator's mouse has. A page is a folder under `.canon/canvas/`, a frame is one HTML file in it, and `layout.json` beside them holds each frame's box.
+`canon canvas` serves a local canvas of pages and HTML frames and gives an agent the verbs the operator's mouse has. A page is a folder under `.canon/canvas/`, a frame is one HTML file in it, and `layout.json` beside them holds each frame's box. `standards/canvas.md` fixes that content format, and the `canvas` skill carries the procedure a session follows to drive the canvas.
 
 ## Serve
 

package/docs/agents/commands.md

@@ -11,50 +11,50 @@ Full help: `canon <command> --help`. Bare `canon --help` lists every top-level c
 
 One row per top-level command, in the order `canon --help` prints them. A domain's subcommands are in `## Domain commands` below.
 
-| Command                     | Purpose                                                                         |
-| --------------------------- | ------------------------------------------------------------------------------- |
-| `canon init [path]`         | Bootstrap a project with selected toolkit domains                               |
-| `canon sync [path]`         | Sync every installed domain, or report drift and version skew with `--check`    |
-| `canon upgrade`             | Reinstall the CLI globally with the package manager the install path names      |
-| `canon migrate <verb>`      | Move a project off a retired name or layout, reporting the plan until `--write` |
-| `canon targets <verb>`      | Report the projects this toolkit installed into                                 |
-| `canon gov <verb>`          | Install and sync governance rules, and audit the tree against them              |
-| `canon standards <verb>`    | List, audit, or print a standard by name                                        |
-| `canon tooling <verb>`      | Sync, diff, and verify tooling stacks                                           |
-| `canon claude <verb>`       | Install the Claude workflow and audit both skill corpora                        |
-| `canon wiki <verb>`         | Scaffold the wiki pages                                                         |
-| `canon indexes <verb>`      | Regenerate `index.md` files from sibling frontmatter, or flatten them           |
-| `canon docs [topic]`        | Emit toolkit reference docs (`list`, or a topic by name)                        |
-| `canon design <verb>`       | Render `canon/DESIGN.md` tokens, build the board, install the base stylesheet   |
-| `canon slides <verb>`       | Render a `.claude/SLIDES.md` deck, or list its layouts                          |
-| `canon capture [source]`    | Render HTML or a URL to PNG and prove each declared font resolved               |
-| `canon serve [dir]`         | Serve a directory on loopback and print the link that opens it                  |
-| `canon demo <verb>`         | Compile and record a running app                                                |
-| `canon inventory [subject]` | Group every route's elements by one computed property, never gating             |
-| `canon drive <url> <run>`   | Walk a page through named interactions and measure each state                   |
-| `canon transcripts <url>`   | Fetch a YouTube transcript with metadata frontmatter (needs `yt-dlp`)           |
-| `canon teach <verb>`        | Open and author learning workspaces                                             |
-| `canon canvas <verb>`       | Serve a local canvas of pages and HTML frames, arrange, edit, and capture them  |
-| `canon sandbox [cat:cmd]`   | Run sandbox scenarios, toolkit-only like the tree it reads                      |
-| `canon tasks <verb>`        | Read and write the task board, the plans it cites, and its archive              |
-| `canon intake <verb>`       | Report intake folders and write answers into them                               |
-| `canon records <verb>`      | Validate, size, prune, and back up the session records                          |
-| `canon sessions <verb>`     | Resolve live sessions to worktree and branch, and move one between machines     |
-| `canon worktrees <verb>`    | Report and remove worktrees whose pull request merged                           |
-| `canon hooks <verb>`        | Run the steps a git hook drives                                                 |
-| `canon autoship <verb>`     | Decide whether a changed set needs the review pass                              |
-| `canon pr <verb>`           | Read a pull request's diff, head, checks, and review, and post its evidence     |
-| `canon feedback`            | Write toolkit feedback from stdin, or open an issue with `--github`             |
-| `canon audits <verb>`       | Run every audit as one set under one verdict against the recorded baseline      |
-| `canon gate <verb>`         | Run every stage that guards a branch here                                       |
-| `canon secrets <verb>`      | Report credential-shaped values in the tree the package ships                   |
-| `canon deps <verb>`         | Report published advisories against the resolved dependency set                 |
-| `canon labels <verb>`       | Read a changed set against the label map, and scan pull request text            |
-| `canon comments <verb>`     | Measure comment density by language and kind, with a trend from git             |
-| `canon context <verb>`      | Report context folder health, and classify changed or stale sections            |
-| `canon markdown <verb>`     | Fail markdown on a banned character or a dead link, and report its structure    |
-| `canon repo <verb>`         | Propose and apply the remote's description, homepage, and topics                |
-| `canon census [path]`       | Report tracked file count, extensions, and a line total skipping binaries       |
+| Command                     | Purpose                                                                                    |
+| --------------------------- | ------------------------------------------------------------------------------------------ |
+| `canon init [path]`         | Bootstrap a project with selected toolkit domains                                          |
+| `canon sync [path]`         | Sync every installed domain, or report drift and version skew with `--check`               |
+| `canon upgrade`             | Reinstall the CLI globally with the package manager the install path names                 |
+| `canon migrate <verb>`      | Move a project off a retired name or layout, reporting the plan until `--write`            |
+| `canon targets <verb>`      | Report the projects this toolkit installed into                                            |
+| `canon gov <verb>`          | Install and sync governance rules, and audit the tree against them                         |
+| `canon standards <verb>`    | List, audit, or print a standard by name                                                   |
+| `canon tooling <verb>`      | Sync, diff, and verify tooling stacks                                                      |
+| `canon claude <verb>`       | Install the Claude workflow and audit both skill corpora                                   |
+| `canon wiki <verb>`         | Scaffold the wiki pages                                                                    |
+| `canon indexes <verb>`      | Regenerate `index.md` files from sibling frontmatter, or flatten them                      |
+| `canon docs [topic]`        | Emit toolkit reference docs (`list`, or a topic by name)                                   |
+| `canon design <verb>`       | Render or regenerate `canon/DESIGN.md` tokens, emit their CSS, install the base stylesheet |
+| `canon slides <verb>`       | Render a `.claude/SLIDES.md` deck, or list its layouts                                     |
+| `canon capture [source]`    | Render HTML or a URL to PNG and prove each declared font resolved                          |
+| `canon serve [dir]`         | Serve a directory on loopback and print the link that opens it                             |
+| `canon demo <verb>`         | Compile and record a running app                                                           |
+| `canon inventory [subject]` | Group every route's elements by one computed property, never gating                        |
+| `canon drive <url> <run>`   | Walk a page through named interactions and measure each state                              |
+| `canon transcripts <url>`   | Fetch a YouTube transcript with metadata frontmatter (needs `yt-dlp`)                      |
+| `canon teach <verb>`        | Open and author learning workspaces                                                        |
+| `canon canvas <verb>`       | Serve a local canvas of pages and HTML frames, arrange, edit, and capture them             |
+| `canon sandbox [cat:cmd]`   | Run sandbox scenarios, toolkit-only like the tree it reads                                 |
+| `canon tasks <verb>`        | Read and write the task board, the plans it cites, and its archive                         |
+| `canon intake <verb>`       | Report intake folders and write answers into them                                          |
+| `canon records <verb>`      | Validate, size, prune, and back up the session records                                     |
+| `canon sessions <verb>`     | Resolve live sessions to worktree and branch, and move one between machines                |
+| `canon worktrees <verb>`    | Report and remove worktrees whose pull request merged                                      |
+| `canon hooks <verb>`        | Run the steps a git hook drives                                                            |
+| `canon autoship <verb>`     | Decide whether a changed set needs the review pass                                         |
+| `canon pr <verb>`           | Read a pull request's diff, head, checks, and review, and post its evidence                |
+| `canon feedback`            | Write toolkit feedback from stdin, or open an issue with `--github`                        |
+| `canon audits <verb>`       | Run every audit as one set under one verdict against the recorded baseline                 |
+| `canon gate <verb>`         | Run every stage that guards a branch here                                                  |
+| `canon secrets <verb>`      | Report credential-shaped values in the tree the package ships                              |
+| `canon deps <verb>`         | Report published advisories against the resolved dependency set                            |
+| `canon labels <verb>`       | Read a changed set against the label map, and scan pull request text                       |
+| `canon comments <verb>`     | Measure comment density by language and kind, with a trend from git                        |
+| `canon context <verb>`      | Report context folder health, and classify changed or stale sections                       |
+| `canon markdown <verb>`     | Fail markdown on a banned character or a dead link, and report its structure               |
+| `canon repo <verb>`         | Propose and apply the remote's description, homepage, and topics                           |
+| `canon census [path]`       | Report tracked file count, extensions, and a line total skipping binaries                  |
 
 `canon serve` drives no browser, which is what separates it from the four that do. All four ship now that `capture` does, so the line between them is the engine rather than the package. A generated page loses its script to an editor preview and to a `file://` open, so the link is the delivery rather than a convenience, and every generated surface here reaches a reader through one. A teach lesson's stylesheet is embedded rather than linked, so only its script still needs a server. It binds `127.0.0.1` and never a wildcard, because what it is pointed at is routinely a gitignored record tree. It sends `cache-control: no-store`, since a preview exists to be edited and reloaded and a cached stylesheet reads as a fix that did not work.
 
@@ -91,7 +91,7 @@ Each domain exposes a consistent shape where applicable: `list`, `install`, `syn
 - `wiki`, in `scripting.md`: `init`
 - `indexes`, in `indexes.md`: `regen`, `list`
 - `docs`, in `docs.md`: `list`, `<topic>`
-- `design`, in `design-board.md`: `render`, `regen`, `board`, `css`, `install`, `sync`
+- `design`, in `install-and-sync.md` for `install` and `sync`, and described below for the rest: `render`, `regen`, `css`, `install`, `sync`
 - `slides`, described below: `render`, `list`
 - `demo`, in `demo.md`: `compile`, `run`, `frames`
 - `inventory`, described above: `run`

package/docs/agents/context-audit-checks.md

@@ -85,9 +85,9 @@ All three wireframe findings are printed under a bare run. The states-mismatch f
 
 The provenance check covers `canon/context/` alone, the reference-form check covers the split folders inside it, the required-section check covers `canon/context/` and `canon/wireframes/`, length and the table finding reach every audited folder, and the wireframe states check covers `canon/wireframes/` alone.
 
-What narrows the provenance check is stated in `standards/context.md`, which opens its scope by handing diagrams and wireframes to `diagrams.md` and `wireframes.md`, and the sibling standards do not restate it. A marker reported in a diagram entry would cite a rule that entry's own standard routes elsewhere. The split is between kinds of rule rather than kinds of folder, and what decides it is which tier states the rule rather than what the check measures.
+What narrows the provenance check is stated in `standards/context.md`, which opens its scope by handing figures to the `draft-figure` skill and wireframes to `wireframes.md`, and the sibling standards do not restate it. A marker reported in a diagram or wireframe entry would cite a rule that entry's own standard routes elsewhere. The split is between kinds of rule rather than kinds of folder, and what decides it is which tier states the rule rather than what the check measures.
 
-Length and the table finding generalize as judgments about how far a reader travels, so both reach wherever the audit is pointed. Required sections narrow for a plainer reason: each list is one standard's own, so it reaches the folder that standard governs. The context and wireframe standards each state a set, and the diagram standard states none.
+Length and the table finding generalize as judgments about how far a reader travels, so both reach wherever the audit is pointed. Required sections narrow for a plainer reason: each list is one standard's own, so it reaches the folder that standard governs. The context and wireframe standards each state a set, and an older install's diagrams folder has no standard to state one.
 
 The same test is what moved depth and bullet weight out of this command entirely. A rule stated at the attribute tier reaches every markdown file, and a check reaching every markdown file has no reason to require a folder that resolves.
 

package/docs/agents/index.md

@@ -20,7 +20,6 @@ CLI catalog and invocation rules for agents, split by command domain. Start with
 - [Doc classifier](context-classify.md): Classifying canonical-doc content as keep, replace/rewrite, history, or move in diff and sweep mode, the classifier setting pair, the record shape, and the exit codes
 - [Self-stated counts](counts.md): Reading a sentence that asserts a closed catalog's size, how a match is decided, the plausibility filter that keeps a generic word from matching a subset, and why the sweep reports rather than gates
 - [Demo](demo.md): Compiling a screencast draft into a runnable plan, driving a served application to a recording and a still, reading numbered frames back out of a recording, the pointer the recording paints, and what each refusal reports
-- [Design board](design-board.md): Generating a static index over a project's design surfaces, what each panel reads, and which two stay toolkit-checkout-only
 - [Docs](docs.md): How canon docs resolves the toolkit's own reference surface from an install root, and how a split domain is named
 - [Drift surfaces](drift-surfaces.md): The seven sections canon sync --check reports beside the per-domain scan, being seeds, superseded artifacts, unmigrated domains, surfaces at the old root, new rules and skills, and the reverse walk, with the managed-target gate and what counts toward the exit code
 - [Driver](driver.md): Walking a page through named interactions, the probe catalog and the false finding each one carries, why viewport heights are never defaulted, and what each refusal reports

package/docs/agents/key-changes.md

@@ -26,9 +26,9 @@ The positional is the pull request to read, defaulting to the one open on this b
 
 `--base` names the far side of that range and never the commit the comparison runs against directly. The reader resolves the merge base between `HEAD` and the ref, so `--base origin/main` measures what the branch wrote rather than what the trunk gained while the branch was open. Passing the trunk as it stands today is therefore safe on a branch of any age, and a ref sharing no history with `HEAD` refuses as `bad-base`.
 
-Without `--body` the body, the file list, and the head commit come back from one `gh pr view` call, because the three have to describe the same commit and reading them apart leaves a window where a push between them compares a body against another head's files.
+Without `--body` the body and the head commit come off the REST pull read and the file list off the paginated files endpoint. Every read runs on REST, since a cloud session's GitHub proxy refuses the GraphQL that `gh pr view` runs on. A push landing between the two reads compares a body against the next head's files, a window the verb accepts for the cloud reach.
 
-That view caps its file list at 100 rows and says nothing about having done so, measured against a pull request carrying 101 files where the view reported 100. A pull request at the cap therefore takes a second read through the paginated endpoint, and a failure there refuses with `gh-truncated` rather than comparing against a set known to be short. A set silently one file short is the worst input this takes, since the missing file is exactly what a correct bullet would then be accused of inventing.
+A failed page refuses as `gh-failed` rather than comparing against a set known to be short. A set silently one file short is the worst input this takes, since the missing file is exactly what a correct bullet would then be accused of inventing. With no number named, the verb reads the one pull request open on the checkout's branch, and refuses as `ambiguous-pull` when two are open against different bases.
 
 ## The two directions
 
@@ -91,7 +91,7 @@ Three refusals separate a clean pass from a read that produced nothing:
 
 An empty extraction read as a clean pass is the failure shape this repository has recorded twice, which is why the middle one is its own reason rather than a zero count.
 
-`gh-missing`, `gh-failed`, `gh-truncated`, `unreadable-body`, `unreadable-tree`, `no-base`, `bad-base`, and `unreadable-changes` cover the reads that never reached a comparison.
+`gh-missing`, `gh-failed`, `ambiguous-pull`, `unreadable-body`, `unreadable-tree`, `no-base`, `bad-base`, and `unreadable-changes` cover the reads that never reached a comparison.
 
 ## What it was measured against
 

package/docs/agents/pr-evidence.md

@@ -138,7 +138,7 @@ call, is what keeps two close-out comments from landing beside each other the
 way `review-pr` once posted, before that skill's own guard existed. It is
 also why this verb renders the whole comment body rather than handing each
 skill a record to format on its own: a fix to the table shape or the
-collapsed-details wrapper lands once, not twice.
+details wrapper lands once, not twice.
 
 ## The preview line
 
@@ -232,7 +232,16 @@ render needs, so it never refuses `no-base`. The orchestrator's draft lift is
 the caller, and lifts only on `settled`, so a refusal holds it the same as
 `owed` does.
 
-## What a collapsed comment still leaves to GitHub
+## When the comment opens
+
+The comment opens every state while it carries six images or fewer, counting one
+per row for the head plus one per row that is not new, and closes every state
+past that, so the whole comment is open or closed together. A line under
+`## Evidence` names the compared base and head as short shas, which tells a
+reader whether the images match the latest push. The base is the merge base the
+compare endpoint returns, not trunk's tip.
+
+## What the comment still leaves to GitHub
 
 GitHub already draws its own before-and-after comparison on the Files Changed
 tab for any tracked image that changed. This comment does not make that view

package/docs/agents/pr-reads.md

@@ -18,7 +18,7 @@ canon pr review-state 1341 --json
 
 ## The pull request object is not the authority for a head
 
-`gh pr view --json headRefOid` reads a field on the pull request object. That object trails the branch ref by up to a minute after a push and carries nothing saying how far behind it is, so a session that keys a read on it is describing whichever commit GitHub last folded into the object.
+The pull request's head sha, `head.sha` on the REST pull read and `headRefOid` in `gh pr view`, is a field on the pull request object. That object trails the branch ref by up to a minute after a push and carries nothing saying how far behind it is, so a session that keys a read on it is describing whichever commit GitHub last folded into the object.
 
 Two failures on 2026-09-01 came off that one field. A reviewing session posted a finding calling a pushed commit unpushed. A worker fired a green claim and retracted it on its own thread minutes later. Neither session did anything wrong with the value it was handed. The value was stale and said so nowhere.
 
@@ -74,7 +74,7 @@ Both empty cases report `pending` instead: a tip carrying no run yet, and a list
 
 The verb keeps the newest run per check name rather than rolling every matched run into the state. A workflow that fires twice on one commit used to leave its first, stale run beside the rerun, where a failing one could outvote a passing rerun. Grouping the matched set by name and keeping the highest `id` per group removes that stale run before the rollup runs. `collapsed` on the record counts what the fold discards, so a caller reading it against `matched` sees the dedupe directly, instead of reading a `matched` above the check count as the verb disagreeing with `gh pr checks`.
 
-A conflicted branch produces no `pull_request` check runs rather than a failing one. GitHub builds no merge ref for it, so no `pull_request` workflow starts and a repository running only that trigger leaves the listing empty, which reads as `pending` and never leaves it. A workflow triggered by a push to the branch still runs on the tip, so `matched` rises above zero, `conflicted` stays false, and the wait ends on those runs rather than on the reading. `mergeStateStatus` is the field that separates the two, and the record carries `conflicted: true` and `mergeState` when it reads `DIRTY` with no run belonging to the tip. A `DIRTY` reading beside runs on the tip leaves the state as those runs say, since a conflict arising after they completed does not unsay them. `UNKNOWN` is transient while GitHub computes the merge state, right after a push, so it reads as not conflicted and costs one more poll. A binary predating the field keeps answering `pending`.
+A conflicted branch produces no `pull_request` check runs rather than a failing one. GitHub builds no merge ref for it, so no `pull_request` workflow starts and a repository running only that trigger leaves the listing empty, which reads as `pending` and never leaves it. A workflow triggered by a push to the branch still runs on the tip, so `matched` rises above zero, `conflicted` stays false, and the wait ends on those runs rather than on the reading. The pull request's `mergeable_state` is the field that separates the two. The verb raises it to upper case, matching the GraphQL `mergeStateStatus` it replaced, and the record carries `conflicted: true` and `mergeState` when it reads `DIRTY` with no run belonging to the tip. A `DIRTY` reading beside runs on the tip leaves the state as those runs say, since a conflict arising after they completed does not unsay them. `UNKNOWN` is transient while GitHub computes the merge state, right after a push, so it reads as not conflicted and costs one more poll. A binary predating the field keeps answering `pending`.
 
 A listing carrying even one foreign run reports `pending` whatever the matching half says. A set that describes another commit says nothing about this one, so answering off the rows that happen to match would put a verdict on a set already known to be incomplete.
 
@@ -90,6 +90,7 @@ Each refusal names a different repair:
 | -------------------- | ------------------------------------------------------------------------------------------ |
 | `gh-missing`         | `gh` is not on the path, so no pull request resolved                                       |
 | `gh-failed`          | `gh` could not answer for this branch, so name a number instead                            |
+| `ambiguous-pull`     | Two open pull requests share the branch against different bases, so name a number          |
 | `no-branch`          | The pull request carries no head branch name, so no ref could be read                      |
 | `unresolvable-ref`   | The remote read failed, which is not the same answer as an absent branch                   |
 | `no-remote-branch`   | The remote carries no branch by that name, so there is no tip to compare against           |
@@ -105,6 +106,6 @@ One remote round trip per call, sampled here at 0.41s, 0.55s, and 0.67s on 2026-
 
 One head-sensitive read is left on the object deliberately. `canon targets pulls` reads `statusCheckRollup` for every open pull request across every target, where resolving a tip per row would cost one remote read per pull request across a dozen projects, against a surface that reports a listing rather than gating a push.
 
-The orchestrator poll spends that same read per open pull request and repeats it on a three-minute timer, which makes it the heaviest caller here rather than an exception to the paragraph above. Six open pull requests is around 120 remote reads an hour. It now spends a third read per pull request per tick besides, since `canon pr review-state` makes its own `gh pr view` call beside the payload the poll already fetched. That one is an API round trip rather than a remote ref read, and it buys a coverage test that answers about what a session read. What separates the two cases is what each reading decides rather than what it costs. The poll's head fires the review trigger, so a stale one sends a pass at a commit nobody read or withholds one that is owed. The listing decides nothing, so the same spend buys a fresher column in a report and no correctness at all.
+The orchestrator poll spends that same read per open pull request and repeats it on a three-minute timer, which makes it the heaviest caller here rather than an exception to the paragraph above. Six open pull requests is around 120 remote reads an hour. It reads over REST alone, one reviews read and one issue-comments read per pull request, plus a pull read only when `canon pr head` returns no tip. It spends a further read per pull request per tick besides, since `canon pr review-state` makes its own REST reviews read beside the payload the poll already fetched. That one is an API round trip rather than a remote ref read, and it buys a coverage test that answers about what a session read. What separates the two cases is what each reading decides rather than what it costs. The poll's head fires the review trigger, so a stale one sends a pass at a commit nobody read or withholds one that is owed. The listing decides nothing, so the same spend buys a fresher column in a report and no correctness at all.
 
-`canon pr key-changes` also stays on the object, for a different reason. It reads the body, the file list, and `headRefOid` in one call on purpose, so the three describe one commit. That is a consistency requirement rather than a freshness one, and keying its head elsewhere would break it.
+`canon pr key-changes` also stays on the object, for a different reason. It reads the body and the head off one pull read, so the two describe one commit. That is a consistency requirement rather than a freshness one, and keying its head elsewhere would break it. The file list comes off a second read, since only GraphQL returns it beside the body and a cloud session's proxy refuses GraphQL.

package/docs/target/projects.md

@@ -73,14 +73,14 @@ Scaffold installs tooling and seeds. It does not fill the planning docs or the d
 
 1. Fill `canon/REQUIREMENTS.md` and `canon/ARCHITECTURE.md`. The seed provides the files, the scope and decisions are yours to write. Each seed states its own caps, 12 decisions of at most 150 words and 6 risk bullets for the architecture record and 600 words for the requirements, and `canon context audit` gates on them. Edit a number in the record to loosen it.
 2. For a UI project, invoke `canon:design-extract` to draft `canon/DESIGN.md`. With no UI code yet it takes the greenfield path and proposes tokens from the requirements and a `## Personality` section. Skip for non-UI projects.
-3. Optionally invoke `canon:draft-diagram` to draft entries under `.canon/diagrams/` from the architecture and the requirements. One file per diagram kind, so a later refresh of one kind leaves the others untouched. It renders each diagram it writes to verify the layout, which downloads the Mermaid CLI on first use and takes about 15 seconds.
+3. Optionally invoke `canon:draft-figure` naming an architecture view, such as system context or components, and the document it belongs in. It draws the view from the architecture and the requirements and renders it to verify the layout, which downloads the Mermaid CLI on first use and takes about 15 seconds.
 4. Start the feature loop. See [AI workflow](../workflow/ai-workflow.md) for the per-feature sequence.
 
-A machine without a renderer still gets the diagrams and is told which check was skipped.
+A machine without a renderer still gets the figure and is told which check was skipped.
 
-Each diagram entry records the commit and date it was last verified against, and nothing maintains that record for you. The folder is redrawn on demand rather than swept on every ship, so `verified` carries the whole signal: an entry whose date sits far behind your branch is due a read, and no pass will name which one. Run `canon:draft-diagram` again when the code a kind is drawn from moves.
+Nothing watches a figure once it is drawn. Run `canon:draft-figure` again when the code a view is drawn from moves.
 
-`canon/ARCHITECTURE.md` carries the same mechanism on the same ship. `canon:context-fold` anchors a decision it amends to the paths that decision cites, and reports an anchored decision whose cited path the branch touched.
+`canon/ARCHITECTURE.md` is watched where a figure is not. `canon:context-fold` anchors a decision it amends to the paths that decision cites, and reports an anchored decision whose cited path the branch touched.
 
 ### Stack decision
 

package/docs/workflow/ai-workflow.md

@@ -26,7 +26,6 @@ canon/
 └── rules/           ← path-scoped governance rules, written by canon gov install
 
 .canon/
-├── diagrams/        ← one Mermaid entry per diagram kind with a generated index.md, redrawn on demand
 ├── tasks/           ← one file per task with a generated index.md, local scratch
 ├── plans/           ← one plan per feature, archived inside itself once it ships
 ├── memory/          ← durable session facts no context entry owns

package/docs/workflow/skill-map.md

@@ -6,7 +6,7 @@ category: Workflow
 
 # Skill map
 
-Groups run in the order a project meets them, so a reader at a known point scans to that group and reads across. The set reconciles the scenarios in [AI workflow](ai-workflow.md) with the lifecycle [target projects](../target/projects.md) describes, rather than inventing a third vocabulary beside those two, so a group name matches neither source exactly and every moment either one names has a group. Each row says when to reach for the skill. What it does is the skill's own description.
+Groups run in the order a project meets them. They reconcile the scenarios in [AI workflow](ai-workflow.md) with the lifecycle [target projects](../target/projects.md) describes, so every moment either one names has a group. Each row says when to reach for a skill, and its description says what it does.
 
 This page is the corpus the coverage claim is measured against: every name `canon claude skills list --names` reports takes exactly one row here. A skill serving two moments sits at the earlier one, and a mention on any other page is prose rather than routing. The landing page's skills field renders from this page, so its build refuses a skill with no row and a row naming no skill.
 
@@ -18,7 +18,6 @@ This page is the corpus the coverage claim is measured against: every name `cano
 | `canon:canon-operator` | On a project that already exists, to read what it carries before an install is picked                       |
 | `canon:sketch-design`  | Before `design-extract`'s greenfield path, to trace a design direction from reference images or URLs        |
 | `canon:design-extract` | Before the first UI feature, to draft `canon/DESIGN.md`                                                     |
-| `canon:draft-diagram`  | Once the architecture is written, to draft per-kind entries under `.canon/diagrams/`                        |
 | `canon:deploy-app`     | Once a project is ready to publish, to set up its Cloudflare or Vercel deploy and stop for token and domain |
 | `canon:repo-metadata`  | When the GitHub About text, homepage, or topics may have drifted, to reconcile them against the README      |
 
@@ -32,6 +31,7 @@ This page is the corpus the coverage claim is measured against: every name `cano
 | `canon:plan-groundwork`    | When the state is unmeasured and more than one approach is live                   |
 | `canon:decision-escalate`  | When open decisions turn on your preference and want batching into one set        |
 | `canon:draft-and-pick`     | When the call is taste and wants several candidates rendered side by side         |
+| `canon:canvas`             | When a direction should be drawn as frames the operator can see, select, and edit |
 | `canon:task-board`         | When a decided item needs a file on the board, or a shipped one needs archiving   |
 | `canon:plan-feature`       | When the approach is settled and the next step is a plan                          |
 | `canon:codebase-layout`    | When a plan or change adds a file and you need to decide which folder holds it    |
@@ -125,7 +125,7 @@ This page is the corpus the coverage claim is measured against: every name `cano
 | `canon:create-standard`   | For a new authoring convention                                                                                                                 |
 | `canon:draft-doc`         | For a brand-new `docs/` page, context entry, wireframe surface, wiki reference page, or `README.md`, drafted against the standard for its kind |
 | `canon:draft-ready`       | For finished files a worker should copy, written as a ready folder with its overview, thin plan, and task                                      |
-| `canon:draft-figure`      | For a hand-drawn figure inside an existing doc, drafted against `standards/figures.md` in Mermaid or freehand SVG                              |
+| `canon:draft-figure`      | For a hand-drawn figure or an architecture view inside an existing doc, drafted in Mermaid or freehand SVG                                     |
 | `canon:bash-cli-script`   | For a small non-interactive shell wrapper, stopping at 100 lines in favor of TypeScript on Bun                                                 |
 | `canon:ci-workflow`       | For a GitHub Actions workflow file                                                                                                             |
 | `canon:draft-slides`      | For a deck, drafted as `.claude/SLIDES.md` and rendered to PowerPoint                                                                          |

package/docs/workflow/visual-design-workflow.md

@@ -41,6 +41,7 @@ A cell no source anchors ends in `? verify`, and the preview shows that marker b
 - `canon:ux-audit` for UX gap detection on existing surfaces
 - `canon:ux-measure` for what a running surface costs to paint, read against published thresholds
 - `canon:draft-and-pick` for a call settled by looking, drafting several candidates onto one page and taking your pick
+- `canon:canvas` for a direction worked out over several turns, drawn as HTML frames you drag, select, and restyle in the browser while the session reads your changes back. Only the pick moves into `canon/DESIGN.md`, since the canvas folder is gitignored
 - `canon:ux-walkthrough` for a multi-finding inspection pass over a running app with the operator, drafting arms from the app's own markup and recording each pick for a builder
 - `canon:draft-identity` to draft a project's logo mark and compose it into an icon sequence and a social card, through `draft-and-pick`'s own render-and-pick loop. On an Astro project holding the card route scaffold, the card lands as a route the project keeps and is captured through a running server, so it reads the project's real stylesheet rather than typed copies of every color. Everywhere else it ships as a PNG and the run says so.
 - Anthropic's `frontend-design` plugin optional for light visual steering

package/governance/renames.toml

@@ -38,13 +38,11 @@
 "557-intake" = "657-intake"
 "558-plan" = "658-plan"
 "559-memory" = "659-memory"
-"560-diagrams" = "660-diagrams"
 "561-teach" = "661-teach"
 "562-session" = "662-session"
 "563-ready" = "663-ready"
 "500-prose" = "800-prose"
 "501-markdown" = "801-markdown"
-"502-mermaid" = "802-mermaid"
 "580-readme" = "880-readme"
 "591-standard-authoring" = "891-standard-authoring"
 "065-spelling" = "765-spelling"
@@ -61,13 +59,11 @@
 "656-groundwork" = "groundwork"
 "657-intake" = "intake"
 "659-memory" = "memory"
-"660-diagrams" = "diagrams"
 "661-teach" = "teach"
 "662-session" = "session"
 "663-ready" = "ready"
 "570-skill" = "skill"
 "590-rule-authoring" = "rule"
 "801-markdown" = "markdown"
-"802-mermaid" = "mermaid"
 "880-readme" = "readme"
 "891-standard-authoring" = "standard"

package/governance/rules/standards/markdown.md

@@ -13,3 +13,4 @@ paths:
 - Read it before a substantial markdown edit. Do not work the banned characters from memory.
 - Run `canon markdown audit <path>` after the edit, and rewrite the sentence carrying a hit rather than swapping the token for a near-synonym.
 - Voice, rhythm, and sentence construction are a separate topic. `800-prose` routes them.
+- Load the `canon:draft-figure` skill before drafting or revising a Mermaid fence or a figure, and report it rather than proceeding silently when it does not resolve.

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@erclx/canon",
   "type": "module",
-  "version": "5.24.0",
+  "version": "5.25.0",
   "description": "Runs your agent's work and keeps its code good, on one setup for every repo.",
   "license": "MIT",
   "bin": {
@@ -45,7 +45,6 @@
     "web:favicon": "bun scripts/core/regen-web-favicon.ts",
     "web:previews": "bun scripts/core/regen-web-previews.ts",
     "web:build": "bun run web:tokens && bun run web:favicon && bun run web:previews && cd web && astro check && astro build",
-    "web:gallery": "cd web && astro build --config gallery.config.mjs",
     "web:card": "cd web && astro dev --config card.config.mjs",
     "web:card:check": "PROJECT_ROOT=web bash tooling/astro/configs/scripts/check-card-exclusion.sh",
     "web:preview": "cd web && astro preview",

package/scripts/core/install-check.sh

@@ -101,7 +101,7 @@ log_step "Assert scaffold"
 # scaffold reads a standard through `canon standards <name>`, resolving against
 # the toolkit rather than a copy this gate could assert on. The two
 # rule paths stand for the `claude` and `canon` groups `base` takes whole.
-for path in "CLAUDE.md" ".claude/wiki/index.md" ".claude" "canon/context/index.md" "canon/wireframes/index.md" ".canon/diagrams/index.md" \
+for path in "CLAUDE.md" ".claude/wiki/index.md" ".claude" "canon/context/index.md" "canon/wireframes/index.md" \
   ".prettierrc" ".editorconfig" ".lintstagedrc" ".husky/pre-commit" ".github/workflows/verify.yml" "scripts/verify.sh" \
   ".claude/rules/canon/claude/565-behavior.md" ".claude/rules/canon/canon/604-scratch.md"; do
   if [ ! -e "$TARGET_DIR/$path" ]; then

package/src/audits/catalog.ts

@@ -587,8 +587,8 @@ export const AUDITS: readonly AuditSpec[] = [
     corpus: 'tracked',
     // The one reason this verb refuses for that is an absence rather than a
     // break, on the same test the reach check and the skill audit take: no
-    // target adopts `canon/context/`, `.canon/diagrams/`, and
-    // `canon/wireframes/` all at once, so without the allowance every such
+    // target adopts `canon/context/`, an older install's `.canon/diagrams/`,
+    // and `canon/wireframes/` all at once, so without the allowance every such
     // project reports the verb unmeasured on every run and never changes.
     absentReasons: ['no-folders'] satisfies ContextAuditRefusal[],
     counts: contextCounts,