@erclx/canon 5.24.0 → 5.26.0

package/claude/skills/review-ui/SKILL.md

@@ -26,15 +26,23 @@ rather than inside it, so the two passes finish on their own clocks.
 
 ## Step 1: resolve the pull request
 
-Resolve the number with `gh pr view --json number,headRefName,headRefOid`, or take the one the launch names. Take `<head>` off `canon pr head <number> --json`, reading its `tip`, and fall back to `headRefOid` when no record comes back. The first seven characters are `<short-sha>`. Record `<pass>` once, as the instant this pass starts, with `date -u +%Y%m%dT%H%M%SZ`. Every frame Step 5 pushes files under it, so a later pass at the same head never replaces an image this one's comment shows.
+Resolve the number and the head through `canon pr head <number> --json` for the number the launch names, or `canon pr head --json` for the current branch when it names none. Take `<number>` off the record's `number` and `<head>` off its `tip`. The first seven characters are `<short-sha>`. Record `<pass>` once, as the instant this pass starts, with `date -u +%Y%m%dT%H%M%SZ`. Every frame Step 5 pushes files under it, so a later pass at the same head never replaces an image this one's comment shows.
 
-Read the newest UI verdict for the head guard:
+Every read in this step runs on REST, since the `gh pr` lookups run on GraphQL and a cloud session's GitHub proxy refuses it. A target whose CLI predates the verb gets no record back. When the launch named no number, fall back there to the open pull requests on the current branch, encoding it so a `/` in its name reaches the query as `%2F`, and stop when that prints anything but one number. Two open pull requests on one head against different bases leave nothing to say which one the launch meant. A named number skips that lookup, since this checkout's branch need not be the pull request's. Either way, read the head off the pull request itself:
 
 ```bash
-gh pr view <number> --json reviews,comments --jq '([.reviews[] | select(.body // "" | split("\n")[0] | rtrimstr("\r") | startswith("## UI review"))] | last) as $v | [($v.body // ""), ($v.submittedAt // ""), ([.comments[] | select(.body // "" | split("\n")[0] | rtrimstr("\r") | . == "## Review response" or . == "## Post-review findings") | .createdAt] | max // "")]'
+gh api "repos/{owner}/{repo}/pulls?head={owner}:$(git branch --show-current | jq -Rr @uri)&state=open" --jq '.[].number'
+gh api repos/{owner}/{repo}/pulls/<number> --jq .head.sha
 ```
 
-The three values are the verdict's body, when it was posted, and when the newest reply was. Take the sha off the body's last-line `<!-- review-ui: head=<sha> -->` marker. A body carrying none covers no head this pass can trust, so drive.
+Read the newest UI verdict for the head guard, and the newest reply:
+
+```bash
+gh api --paginate 'repos/{owner}/{repo}/pulls/<number>/reviews?per_page=100' --jq '.[] | select(.body // "" | split("\n")[0] | rtrimstr("\r") | startswith("## UI review")) | {body, submitted_at} | @json' | tail -n 1
+gh api --paginate 'repos/{owner}/{repo}/issues/<number>/comments?per_page=100' --jq '.[] | select(.body // "" | split("\n")[0] | rtrimstr("\r") | . == "## Review response" or . == "## Post-review findings") | .created_at' | tail -n 1
+```
+
+The first read prints the verdict's body and when it was posted as one JSON line, and the second prints when the newest reply was. `--paginate` runs the filter once per page, so `tail` outside it keeps the newest row in the thread rather than the newest on each page. The verdict goes out as JSON because its body spans many lines, and `tail` over the raw body would keep only its last one. An empty first read is a pull request carrying no verdict yet. Take the sha off the body's last-line `<!-- review-ui: head=<sha> -->` marker. A body carrying none covers no head this pass can trust, so drive.
 
 Read nothing else about the change. The diff, the plan, the task, and the description's Summary and Technical Context all carry the author's argument for it, and a pass that has heard it drives towards what it expects.
 

package/claude/skills/review-ui/references/post.md

@@ -68,7 +68,9 @@ Record the instant just before the post, in UTC, as `<posted-at>`. Step 8 keeps
 
 ```bash
 date -u +%Y-%m-%dT%H:%M:%SZ
-gh pr review <number> --comment --body-file .canon/tmp/pr/review-ui/body-<number>-<short-sha>.md
+gh api -X POST 'repos/{owner}/{repo}/pulls/<number>/reviews' -f event=COMMENT -F body=@.canon/tmp/pr/review-ui/body-<number>-<short-sha>.md --jq .html_url
 ```
 
-Never post through `--approve` or `--request-changes`, which carry a state the poll does not read and a weight this pass has not earned.
+The post goes through the REST reviews endpoint rather than the `gh pr` review subcommand, which runs on GraphQL and fails where a cloud session's GitHub proxy refuses it. `-F` reads the file into the body, where `-f` would post the path itself.
+
+Never pass `event=APPROVE` or `event=REQUEST_CHANGES`, which carry a state the poll does not read and a weight this pass has not earned.

package/claude/skills/role-orchestrator/references/orchestrator-cloud-launch.md

@@ -1,6 +1,6 @@
 ---
 title: Orchestrator cloud launch
-description: The cloud build shape, being the launch prompt that carries the plan as text and announces over GitHub, the create under a pseudo-terminal with its trust keys, and the readout that fails loudly on a missing session id
+description: The cloud build and review shapes, being the launch prompt that carries the plan as text and announces over GitHub, the reviewer prompt whose posted review is its announcement, the create under a pseudo-terminal with its trust keys, and the readout that fails loudly on a missing session id
 ---
 
 # Orchestrator cloud launch
@@ -9,6 +9,14 @@ Run this once `orchestrator-dispatch.md` has cleared a row and picked cloud for
 
 The shape needs a `SessionStart` hook in the repository that, on the VM alone, copies the plugin skills into `.claude/skills/` and puts `canon` on the path. A repository without one cannot take this shape, so fall back to a local worker there. Where the hook exists, the launch prompt calls `/auto-ship` with no `canon:` prefix, since the copied skills list as project skills.
 
+## Contents
+
+- [Check the row is unclaimed](#check-the-row-is-unclaimed)
+- [The prompt](#the-prompt)
+- [The create](#the-create)
+- [Recognize the pull request](#recognize-the-pull-request)
+- [Dispatch a review to a cloud reviewer](#dispatch-a-review-to-a-cloud-reviewer)
+
 ## Check the row is unclaimed
 
 A cloud worker never appears in `canon sessions list` and never pushes the derived branch, since the cloud assigns it a `claude/` branch of its own. So the roster and the refs read clear on a row a cloud worker is already building. Run the local check in `orchestrator-dispatch.md` anyway, since a local worker on the same row still collides, then read the two places a cloud worker does show:
@@ -74,3 +82,32 @@ gh api 'repos/{owner}/{repo}/pulls/<number>/commits' --jq '.[].commit.message' |
 ```
 
 A count above zero matches the row. A count of zero is someone else's pull request, whatever its title says. Once it matches, record the number on the row's task yourself with `canon tasks pull-request <number> <task>`, since `git-pr` on the VM has no task file to write, then review it the way step 5 reviews any worker's pull request.
+
+## Dispatch a review to a cloud reviewer
+
+Run this once `orchestrator-review-dispatch.md` has sent a code review to a dispatched reviewer and the operator picked cloud for it. The reviewer needs the same `SessionStart` hook as the build shape, and a `canon` on the VM whose `pr` reads run on REST, since the proxy refuses GraphQL. A UI review never takes this shape, because it drives a browser the VM does not have.
+
+Confirm the VM's `canon` reads over REST before dispatching. In this repository the setup hook links the checkout's own CLI, so a pushed branch carries the reads. Any other repository's VM installs `canon` from npm, so its `pr` reads run on REST only once a release carrying them is published, and its copied skills carry the REST lookups only once that repository's skills are re-scaffolded from that release.
+
+Read `npm view @erclx/canon version` against the first release whose changelog names the REST reads, and check the target's copied `review-pr` the same way, by running `grep -rnE 'gh pr (list|view|review|diff|comment)'` over it and expecting no output. A version short of that release, or a hit, dispatches a reviewer that fails on its first GraphQL call, so take the local shape instead.
+
+Check this pass's launched record for a cloud reviewer already holding the number, and run `canon pr review-state <number> --json` for a pass already posted. A cloud reviewer never appears in `canon sessions list`, so the live-session check the local shape runs reads clear on a pull request one already holds.
+
+The create targets whichever repository the checkout it runs from names as `origin`. For a pull request in this repository, write the prompt to `.canon/tmp/cloud-review-<number>/prompt.md` at the main worktree root and run the create there. For a pull request in another repository, run the create from a checkout of that repository and write the prompt under that checkout's own `.canon/tmp/cloud-review-<number>/`, which its `.gitignore` has to cover before the create runs. A fresh clone made for this is untrusted, so the create takes the trust-prompt key variant under `## The create`:
+
+```plaintext
+/role-reviewer
+Then run /review-pr <number> on <owner>/<repo>.
+Your controller cannot receive a message from this session. The review you post is the announcement, so post nothing else for it. If you stop on a question before the review posts, comment on the pull request starting with QUESTION: review <number>.
+<the cross-branch facts>
+```
+
+The cross-branch facts are the ones `### What the brief may carry` in `orchestrator-launch.md` allows a reviewer brief, and nothing of this session's own read. Neither skill carries the invocation flag, so no position-zero expansion is at stake and the bare names reach the copied project skills.
+
+Create the session with the wrapper under `## The create`, setting `dir` to that prompt's folder, and keep its readout rule: no `session_` id means nothing was dispatched. Record the session id beside the number in this pass's launched record, and name the number, the repository, and the session id in the dispatch report.
+
+`poll.ts` lists every open pull request from this machine and reads each one's review state, so the posted `## Review` reaches the next poll like a local reviewer's. Start the poll when the dispatch goes out rather than at its fallback. A `QUESTION: review <number>` comment reaches the same poll as an unclassified reply, so answer it on the pull request.
+
+The pull request is the record to act on, and the transcript is read back only to check for a refused call. Run `claude --teleport <session>` under `script` from a throwaway clone of the target outside this repository, answer its trust prompt with the same piped keys, and set the terminal to 500 rows first, since only the screen tail is captured otherwise. Search the capture for `HTTP 403` and `graphql`. A hit names a call still on GraphQL, so report it as a finding rather than reading the posted review as clean.
+
+A cloud reviewer cannot be messaged after it posts. A re-review after a worker's address pass is a fresh dispatch, local or cloud by the same pick, rather than the message `orchestrator-handback.md` sends a live reviewer.

package/claude/skills/role-orchestrator/references/orchestrator-dispatch.md

@@ -5,6 +5,19 @@ description: The plan-answer gate, the collision check before a self-dispatch, t
 
 Run this at loop step 4, for a `## Run now` row whose plan is verified, in place of handing the worktree to a human. The disjointness gate below is where that row's file set is tested against every track in flight.
 
+## Contents
+
+- [Derive the candidate](#derive-the-candidate)
+- [Check the plan waits on nobody](#check-the-plan-waits-on-nobody)
+- [Check the branch is unclaimed](#check-the-branch-is-unclaimed)
+- [Hold what this pass already launched](#hold-what-this-pass-already-launched)
+- [Check the file sets are disjoint](#check-the-file-sets-are-disjoint)
+- [Pick the model](#pick-the-model)
+- [Pick local or cloud](#pick-local-or-cloud)
+- [Dispatch](#dispatch)
+- [Fall back to the human](#fall-back-to-the-human)
+- [Stop the loop](#stop-the-loop)
+
 ## Derive the candidate
 
 Run `canon tasks plan-branch <plan> --json` against the row's plan file and read `branch`, `type`, `slug`, and `conforms` off the record.

package/claude/skills/role-orchestrator/references/orchestrator-launch.md

@@ -103,6 +103,10 @@ claude --bg --model <model> -n "reviewer-<project>-<number>" "Run /canon:role-re
 
 Check `canon sessions list --json` for a live `reviewer-<project>-<number>` before launching, and message that session instead when one holds the pull request.
 
+## Dispatch a review to a cloud reviewer
+
+Read `${CLAUDE_SKILL_DIR}/references/orchestrator-cloud-launch.md` when the operator picked cloud for a code review. Its prompt opens with `/role-reviewer`, carries the cross-branch facts, and makes the posted review the announcement.
+
 ## Dispatch to drive a pull request's checklist
 
 `review-ui` is the second pass `role-reviewer` may run, so this shape reaches the role first the way the code reviewer's does. `orchestrator-review-dispatch.md` decides whether a pull request takes it, and it runs beside the code reviewer rather than after it.

package/claude/skills/role-orchestrator/references/orchestrator-poll.md

@@ -9,7 +9,7 @@ Run the orchestrator's review trigger. The poll reports pull request movement an
 
 ## When to run it
 
-Start the poll on an open pull request and stop it when the last one merges with nothing else out. That is the whole condition and it resolves from `gh pr list` without asking the operator. A release pull request alone does not qualify, since its sweep carries no findings.
+Start the poll on an open pull request and stop it when the last one merges with nothing else out. That is the whole condition and it resolves from the open list without asking the operator. A release pull request alone does not qualify, since its sweep carries no findings.
 
 A dispatch no longer starts it. The script reads pull requests and a building worker has none, so every interval between the launch and the push is a fixed cost returning nothing, measured as five consecutive runs reporting no movement across roughly fifteen minutes while one worker built. What replaces it is the worker announcing its own pull request the moment it opens one, per the `role-worker` skill that session loads, which covers exactly the transition the poll cannot observe.
 
@@ -71,15 +71,15 @@ The state reaches every stalled dispatch, since one threshold governs the headin
 
 ### The count behind the review dispatch
 
-The report is also where the load count in `orchestrator-review-dispatch.md` is legible, and that count decides where a first pass runs, here or in a dispatched reviewer. That threshold trips on open pull requests awaiting a first pass, which is what `OPENED` and a pull request with no prior pass name here and what `SEEN` excludes, so read the count off these lines rather than off `gh pr list`, which counts a branch closed out and waiting on a merge the same as one nobody has read. It is a separate condition from the poll-start fallback above, which decides when this loop runs rather than where a review runs.
+The report is also where the load count in `orchestrator-review-dispatch.md` is legible, and that count decides where a first pass runs, here or in a dispatched reviewer. That threshold trips on open pull requests awaiting a first pass, which is what `OPENED` and a pull request with no prior pass name here and what `SEEN` excludes, so read the count off these lines rather than off the open list, which counts a branch closed out and waiting on a merge the same as one nobody has read. It is a separate condition from the poll-start fallback above, which decides when this loop runs rather than where a review runs.
 
 The count used to read low, and it erred in the direction that breaks the trigger. A review's `commit.oid` is stamped with the head at submission rather than with the commit the reviewer read, so an author pushing between the diff read and the post left the pass recorded against a commit it never saw, and `SEEN` then fired on a head still awaiting its first look at that delta.
 
 The pass now carries its own record instead. `review-pr` writes the commit it read and the instant it read it as a marker on the last line of every body it posts, and both this script and that skill resolve the covered state through `canon pr review-state`, which is the one place the marker is parsed. A commit pushed inside a pass's compose window falls outside the marked range, so it reads as `MOVED` rather than as `SEEN`. A `SEEN` is a claim about what a session read rather than about what GitHub stamped, so it wants no second read to be believed.
 
-Read `source` on the record before trusting a `SEEN` on a thread whose newest pass is old. `marker` is the read-time record. `fallback` is a pass posted before the mechanism shipped, or a target whose CLI predates the verb, and it carries the defect above unchanged, so a `SEEN` under it is worth one `gh pr view --json reviews` before it is believed. `none` is a thread carrying no pass at all.
+Read `source` on the record before trusting a `SEEN` on a thread whose newest pass is old. `marker` is the read-time record. `fallback` is a pass posted before the mechanism shipped, or a target whose CLI predates the verb, and it carries the defect above unchanged, so a `SEEN` under it is worth one read of the pull's reviews before it is believed. `none` is a thread carrying no pass at all.
 
-The other side of that comparison used to lag as well, which made the two errors compound rather than cancel. `gh pr view --json headRefOid` answers from the pull request object and that object trails the branch ref by up to a minute after a push, reporting nothing about the trail, so a pass stamped ahead of the commit it read was compared against a head stamped behind the commit that exists. The head now comes from `canon pr head`, which resolves the tip through `git ls-remote` and reports which commit each source names, and the object's head stays behind it as the fallback for a target whose CLI predates the verb. Both halves of the comparison now answer about a commit somebody named rather than one GitHub stamped, which is what lets a `SEEN` be read as covered.
+The other side of that comparison used to lag as well, which made the two errors compound rather than cancel. The pull read's `head.sha` answers from the pull request object and that object trails the branch ref by up to a minute after a push, reporting nothing about the trail, so a pass stamped ahead of the commit it read was compared against a head stamped behind the commit that exists. The head now comes from `canon pr head`, which resolves the tip through `git ls-remote` and reports which commit each source names, and the object's head stays behind it as the fallback for a target whose CLI predates the verb. Both halves of the comparison now answer about a commit somebody named rather than one GitHub stamped, which is what lets a `SEEN` be read as covered.
 
 ## The watch beside it
 

package/claude/skills/role-orchestrator/references/orchestrator-review-dispatch.md

@@ -33,3 +33,9 @@ Hand what it finds to each reviewer as facts in the brief, per `### What the bri
 ## Launching the reviewer
 
 Take the reviewer shape in `orchestrator-launch.md`, or its UI reviewer shape for the UI trigger. Check `canon sessions list --json` for a live `reviewer-<project>-<number>`, or `reviewer-ui-<project>-<number>`, first and message it instead of launching a second, since two reviewers on one pull request post two verdicts. The re-review after a worker's address pass goes back the same way, per `orchestrator-handback.md`.
+
+## Local or cloud
+
+A code review goes to a cloud reviewer rather than `claude --bg` only on the operator's explicit pick for that dispatch, the same standing the build shape's pick holds in `orchestrator-dispatch.md`. The cloud session costs no local context and no machine slot, which matters when the load trigger fired. It also reads nothing this machine holds, so a review that needs the board, a local preview, or a sandbox stays local.
+
+This session hears a cloud reviewer through `poll.ts` alone, which already lists every open pull request from this machine, so the posted review is the announcement and no message arrives. `orchestrator-cloud-launch.md` carries the shape under `## Dispatch a review to a cloud reviewer`. A UI review always stays local.

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/claude/skills/search-craft/REQUIREMENT.md

@@ -18,7 +18,7 @@ The miss is measured. On 2026-10-02 two queries ran twice each with identical te
 
 The authorities in both pairs were named by the session unprompted once it was asked to, which is the argument for a method over a list. Two queries at one run each show the effect exists and do not size it.
 
-Access is a second gap a session cannot derive. Probed on 2026-10-02, Reddit refused its JSON search with a 403 and refused `WebFetch`, while its RSS feed answered 200. X redirected `curl` to a login page and returned 402 to `WebFetch`, so no free route reaches it.
+Access is a second gap a session cannot derive. Probed on 2026-10-02, Reddit refused its JSON search with a 403 and refused `WebFetch`, while its RSS feed answered 200. X redirected `curl` to a login page and returned 402 to `WebFetch`, so no free route reaches it. Re-probed on 2026-10-04, Reddit's RSS feed, its search feed, and its JSON listing and search all answered 403, so the feed that answered two days earlier no longer does.
 
 ## Must
 

package/claude/skills/search-craft/SKILL.md

@@ -44,10 +44,12 @@ The procedure that loaded this skill owns what the result is for and where it is
 
 Each line is a claim measured once, and `${CLAUDE_SKILL_DIR}/REQUIREMENT.md` records the date under its Gap. Sites change their blocking without notice, so re-check a line before relying on it. Add a line only for a failure a session actually hit, and record the date it hit in the requirement beside it.
 
-- Reddit answers its RSS feed and refuses its JSON search with a 403. `WebFetch` is refused for the site.
+- Reddit refuses its RSS feed and its JSON search alike with a 403. `WebFetch` is refused for the site, so no keyless route reaches it.
 - X answers nothing without paying or a login. `curl` redirects to a login page and `WebFetch` returns 402.
 - Stop and ask the operator before any route that pays, logs in, or works around a refusal. Never suggest scraping behind a login.
 
+Read `${CLAUDE_SKILL_DIR}/references/adopted.md` only when extending this guidance or arguing against a rule in it. It records which comparable skills were read, what was adopted and declined, and why.
+
 ## Excuses and rebuttals
 
 | Excuse                                   | Rebuttal                                                                                                                                    |

package/claude/skills/search-craft/references/adopted.md

@@ -0,0 +1,30 @@
+---
+title: Adopted and declined
+description: Which comparable research skills this skill was read against, what it took from them, what it declined, and which of its rules rest on measurement rather than a source
+---
+
+# Adopted and declined
+
+Three third-party research skills were read before this one was written. None of them was imported, and most of the body rests on paired searches measured in this skill's `REQUIREMENT.md` rather than on any of them. A later session extending the skill adds to this file rather than re-arguing an item settled here.
+
+## Adopted
+
+**Recording each route's failure.** [aghori3004/claude-research-stack](https://github.com/aghori3004/claude-research-stack) keeps one `research-sources` skill that orders sources cheapest first and writes down how each one fails. Adopted as the access note, which records a refusal a session hit rather than leaving the next session to learn it by failing.
+
+**Calling the tools directly.** The same skill ships no wrapper scripts, so it calls the command-line tools and servers it names. Adopted as the rule to reach a keyless API with a plain request rather than writing a wrapper for one search.
+
+**Treating a paid route as the operator's call.** [rohunvora/x-research-skill](https://github.com/rohunvora/x-research-skill) reaches X through the official API at a cost per search page. Adopted as the stop before any route that pays or logs in, since that cost is one the operator decides rather than one a session discovers.
+
+## Declined
+
+**A directory of sites per category.** None of the three is one, and each earns its keep on access and cost instead. A site list also rots with nobody noticing, so the body derives a field's authorities per question rather than reading them off a list.
+
+**Reaching walled sites through a logged-in browser.** `claude-research-stack` reaches Reddit and X through a desktop Chrome session holding the operator's login. Declined because the body never suggests working around a login.
+
+**A bundled engine.** [mvanhorn/last30days-skill](https://github.com/mvanhorn/last30days-skill) is a Python engine with its own test suite and paid aggregators behind it. Declined because a skill here ships no code, and access a session needs repeatedly becomes a `canon` verb.
+
+## Stated by no source
+
+**Naming the field and deriving its authorities.** No comparable skill takes a thinking step before searching. The step rests on the paired open and scoped searches recorded in `REQUIREMENT.md` under `Gap`, where the scoped run returned primary sources and caught a wrong version number the open run carried.
+
+**Preferring a public API over a fetched page.** It rests on the same probes, where the scholarly and reference APIs returned the dates, authors, and identifiers a citation needs and a fetched page returned a summary.

package/claude/skills/target-setup/references/detect.md

@@ -9,6 +9,14 @@ What the `install` and `gov` phases both do before they write anything. Stated
 once here rather than twice in the body, since the two phases differ in what
 they install rather than in how they read the project.
 
+## Contents
+
+- [Read the catalogs](#read-the-catalogs)
+- [Detect](#detect)
+- [Resolve arguments](#resolve-arguments)
+- [Gap handling](#gap-handling)
+- [Preview](#preview)
+
 ## Read the catalogs
 
 Run in parallel. Never hardcode stack, rule, or standards names. The

package/claude/skills/target-setup/references/indexes.md

@@ -12,6 +12,19 @@ user, and writes. The CLI handles validation and regeneration only.
 Read `canon docs indexes` from the toolkit if context on the system is needed
 before scanning.
 
+## Contents
+
+- [Scope](#scope)
+- [Scan](#scan)
+- [Present candidates](#present-candidates)
+- [Draft frontmatter](#draft-frontmatter)
+- [Scaffold the folder index](#scaffold-the-folder-index)
+- [Inject](#inject)
+- [Validate](#validate)
+- [Offer the convention seed](#offer-the-convention-seed)
+- [Closeout](#closeout)
+- [Reference](#reference)
+
 ## Scope
 
 - Bootstrap un-indexed folders only. Skip folders that already contain an `index.md`.

package/claude/skills/target-setup/references/verify.md

@@ -12,6 +12,14 @@ Two depths over one contract. Both read the `scripts` block from the project's
 own `package.json` and run what is declared there, so neither hardcodes a script
 name and a stack exposing a different set is covered without an edit here.
 
+## Contents
+
+- [Guards](#guards)
+- [Step 1: read scripts](#step-1-read-scripts)
+- [Step 2: run the chain](#step-2-run-the-chain)
+- [Step 3: report](#step-3-report)
+- [Out of scope](#out-of-scope)
+
 ## Guards
 
 A monorepo syncs each language root into its own subfolder, so the project root

package/claude/skills/test-first/SKILL.md

@@ -19,6 +19,8 @@ description: Write the failing test for a behavior before writing the code that
 - Changing what a function already does starts with changing what its test asserts. Run that changed test once before touching the implementation, and confirm it fails against the code as it stands today.
 - A test that already passes before any code changes proves nothing about the new behavior. Widen the assertion or add a case until the suite fails against the current implementation.
 
+Read `${CLAUDE_SKILL_DIR}/references/adopted.md` only when extending this guidance or arguing against a rule in it. It records which external sources the loop matches, which parts were declined, and which rules no source states.
+
 ## What this skill does not cover
 
 - Which layer a test belongs at and what makes it a good one. `canon:test-craft` owns that judgment, and step 1 loads it.

package/claude/skills/test-first/references/adopted.md

@@ -0,0 +1,36 @@
+---
+title: Adopted and declined
+description: Which external sources the test-first loop draws on, which parts it declined, and which of its rules no source states, so a later session extends the position instead of re-deriving it
+---
+
+# Adopted and declined
+
+The loop predates this ledger, so this file records the sources it matches rather than the ones it was drafted from. Each was opened before it was cited. A later session extending the skill adds to this file rather than re-arguing an item settled here.
+
+## Adopted
+
+**The loop itself.** Kent Beck's [Canon TDD](https://newsletter.kentbeck.com/p/canon-tdd) states it as turning one item into "an actual, concrete, runnable test", changing the code "to make the test (& all previous tests) pass", then refactoring. Adopted as steps 2, 4, 5, and 6, with the whole suite run after the pass rather than the new test alone.
+
+**Making it pass without designing.** The same post warns against "mixing refactoring into making the test pass", and keeps implementation design decisions for the refactor. Adopted as step 4's smallest change and step 6's cleanup of the shortcuts that change left.
+
+**Never faking the pass.** The same post lists deleting assertions "so the test pretends to pass" and "copying actual, computed values & pasting them into the expected values" as mistakes. Adopted as step 5's rule that a pass must be the one the test was written to prove.
+
+**Refactoring is a step, not an option.** Martin Fowler's [TestDrivenDevelopment](https://martinfowler.com/bliki/TestDrivenDevelopment.html) names "neglecting the third step" as the most common way to get the practice wrong. Adopted as step 6 being mandatory where Canon TDD writes "optionally refactor".
+
+## Declined
+
+**The test list.** Canon TDD opens by listing every expected variant of the new behavior before writing a test. Declined because a plan already names the behaviors a build covers, and `canon:build-in-slices` owns the order they land in, so a second list here would hold a second copy of the scope.
+
+**Refactoring only as far as the session needs.** Canon TDD warns against refactoring further than necessary and calls duplication "a hint, not a command". Declined as a separate rule, since `canon:code-craft` owns when an abstraction earns its place and step 6 already limits refactoring to what step 4 left.
+
+## Checked and not a source
+
+**Software Engineering at Google, [Testing Overview](https://abseil.io/resources/swe-book/html/ch11.html).** The default shelf's testing chapter covers why tests matter and how a suite is structured, and never addresses writing a test before its code or watching it fail. It informs `canon:test-craft`, which step 1 loads, rather than this loop.
+
+**Kent Beck's _Test-Driven Development: By Example_.** The book is the loop's origin, and no openable copy was available to cite a version from. Canon TDD is Beck's own later restatement and stands in for it here.
+
+## Stated by no source
+
+**Confirming the failure is the right one.** Step 3's rule, that a test failing for a typo or a wrong signature is a defect in the test, comes from the failure recorded in this skill's `REQUIREMENT.md` under `Gap` rather than from any source above.
+
+**Extending existing behavior.** The rule that a changed assertion must fail against the code as it stands today is the same failure applied to an edit, and carries no external source.

package/claude/skills/write-human/SKILL.md

@@ -67,4 +67,4 @@ Report each file written or updated by its full path from the project root.
 
 ## Source material
 
-The position on external writing guidance sits in `${CLAUDE_SKILL_DIR}/references/source-material.md`, which states what this skill adopted, what it declined, and the measurement behind each. Read it before importing a rule from outside this corpus. Do not re-derive that position, since a second answer will disagree with the recorded one.
+The position on external writing guidance sits in `${CLAUDE_SKILL_DIR}/references/adopted.md`, which states what this skill adopted, what it declined, and the measurement behind each. Read it before importing a rule from outside this corpus. Do not re-derive that position, since a second answer will disagree with the recorded one.

package/claude/skills/write-human/references/machine-tells.md

@@ -9,6 +9,19 @@ Each pattern below is a shape rather than a token, so no closed word set matches
 
 Work top down. The first three account for most of what a reader calls machine-written.
 
+## Contents
+
+- [Rule of three](#rule-of-three)
+- [Synonym cycling](#synonym-cycling)
+- [False ranges](#false-ranges)
+- [Inline-header lists](#inline-header-lists)
+- [Adverb propping](#adverb-propping)
+- [Passive voice with an unnamed actor](#passive-voice-with-an-unnamed-actor)
+- [Closing restatement](#closing-restatement)
+- [Question as transition](#question-as-transition)
+- [Escalating parallel clauses](#escalating-parallel-clauses)
+- [Empty superlative frames](#empty-superlative-frames)
+
 ## Rule of three
 
 A triad wherever a list appears, whatever the subject actually holds. Three adjectives, three clauses, three examples, over and over, until the count is the only thing a reader can predict.

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
 
@@ -39,7 +39,9 @@ A pick is refused as `address-mismatch` when the browser builds elements the fil
 
 `text` replaces the text of an element holding text alone and refuses one holding other elements as `not-text-only`. Every byte outside the element stays as it was. `--json` emits the page, frame, file, path, and the file's new `hash`.
 
-The operator edits the same set from the inspector, which posts to the same writer with the hash the frame was served with. An edit made against a version of the file Claude has since rewritten is refused as `stale-address` and the shell reloads the frame, so nothing lands on a shifted element. A color picked from the project's tokens is written as `var(--<name>)`. Both writers take the frame file's lock, and an edit that keeps the selected element where it was keeps the selection fresh.
+The operator edits the same set from the inspector, which posts to the same writer with the hash the frame was served with. An edit made against a version of the file Claude has since rewritten is refused as `stale-address` and the shell reloads the frame, so nothing lands on a shifted element. Both writers take the frame file's lock, and an edit that keeps the selected element where it was keeps the selection fresh.
+
+A color picked from the project's tokens is written as `var(--<name>)`, and below full opacity as a `color-mix()` of that `var()` with `transparent` at the opacity percent, so it keeps following the theme. A browser older than 2023 drops a `color-mix()` value, which leaves the property unset there. A hex is written as six digits, or eight below full opacity.
 
 Inline style beats a class, so an operator's edit masks a class change Claude makes later. Read a frame's inline styles before restyling it, and remove one the change should replace. The inspector marks a color or background set inline with the word `raw` when its value names no `var()` and is not `currentColor` or a CSS-wide keyword, since that value stays fixed when the theme changes. A property outside the set, or a value carrying `;`, `{`, `}`, `<`, `>`, or a line break, is refused as `invalid-edit`.
 

package/docs/agents/capture.md

@@ -44,7 +44,7 @@ Neither digest is ever written by hand. A digest is what the gate compares, so a
 
 Each source renders at `deviceScaleFactor` 2 with a transparent background, and the success line reports the pixel dimensions the element wrapped to. Size is reported and never asserted. The height of a terminal frame is whatever its text wrapped to at a fixed width, so pinning that number would harden an accident.
 
-What is asserted is the font. The command reads the first family the captured element declares and fails when the browser did not resolve it, because a fallback face rewraps the block and silently changes the output. Sources therefore name a real font rather than relying on `monospace`. A source that cannot render reports its own line and exits 1 without dropping the rest of the batch.
+What is asserted is the font. The command reads the first family of each rendered element holding text inside the captured element, and fails when the browser did not resolve one of them, because a fallback face rewraps the block and silently changes the output. A generic keyword as the first family, such as `monospace` or `system-ui`, also fails with its own reason, since it resolves to a different font on each machine, though a quoted `"monospace"` is a family name and goes through the probe. An element holding no text skips the check, since there is nothing to rewrap. Sources therefore name a real font rather than relying on `monospace`. A source that cannot render reports its own line and exits 1 without dropping the rest of the batch.
 
 A run refuses before it reads anything else when `--selector` is absent, naming the flag and pointing at `--help`. Ordering it first is what keeps the message about the invocation: the source defaults to `assets`, so checking that first would answer `assets not found` from whatever directory the caller happened to be in and say nothing about the flag that was actually missing. That source default is a deliberate choice rather than one inherited from some general convention: a missing folder still refuses loud, naming the argument, once the flag check passes, where the selector's dropped default cropped the wrong region in silence.