@erclx/canon 5.39.0 → 5.41.0

package/docs/agents/pr-lift.md

@@ -1,132 +0,0 @@
----
-title: The pull request draft lift
-description: How canon pr lift removes the draft mark once the reviews, evidence, standing, and CI all read clear at the head, the gate order and what each reads, the wait on a pending run, the re-read before the write, the refusal reasons it names, and what --check reports
----
-
-# The pull request draft lift
-
-`canon pr lift` takes a pull request out of draft. It reads the gate itself, so
-any session that closes a review can run it, and nobody has to judge whether a
-message asking for the lift came from someone entitled to ask.
-
-```bash
-canon pr lift 1341 --json
-canon pr lift 1341 --check --json
-```
-
-With no number it resolves the one open pull request on the checked-out branch.
-The ship chain marks every pull request a draft, and this is the verb that
-undoes it.
-
-## What it reads
-
-Five gates, read in this order. The first four need no wait, so they all run
-before the check runs are read.
-
-| Gate       | Clear when                                                                                    |
-| ---------- | --------------------------------------------------------------------------------------------- |
-| `review`   | The newest `## Review` pass is closed, and its marker names the head.                         |
-| `ui`       | The newest `## UI review` verdict is closed at the head. Binds only where a checklist exists. |
-| `evidence` | `canon pr evidence --check` reads `settled`, meaning no post-pull-request step is owed.       |
-| `standing` | The head merges into the freshly fetched base, and the base moved no path the branch writes.  |
-| `ci`       | Every check run on the branch tip concluded and none failed.                                  |
-
-The head is the branch tip read from the remote, not the pull request object's
-head, which trails a push by up to a minute. A review marker names the commit
-the reviewer read, and it covers the head when it is that commit or a prefix of
-it.
-
-The UI gate binds only when `canon pr evidence --check --json` carries a
-`checklist` field. The verb branches on that field and not on the exit, so a
-branch with no rendered surface owes no UI review.
-
-A review pass with no read-time marker refuses as `review-unmarked`. Its covered
-commit would be the stamp GitHub wrote at submission, which the marker exists to
-replace, and lifting on it reintroduces the defect `canon pr review-state`
-documents.
-
-## The wait
-
-A pending CI run is waited on rather than refused. `--wait <seconds>` bounds it,
-defaulting to 1200, and the check runs are read every 30 seconds until one of
-four things happens:
-
-- every run passed, and the verb goes on to the write
-- a run failed, which refuses `ci-failing` at once
-- the branch conflicts with its base, which refuses `ci-conflicted` at once,
-  since no run starts for a conflicted branch and the wait could not end
-- the deadline passed, which refuses `ci-timeout`
-
-A refusal on any of the first four gates comes before the wait starts. A code
-reviewer whose UI partner is still driving refuses `ui-open` immediately
-instead of holding a turn through a CI run.
-
-## The re-read
-
-A push during the wait moves the head off the commit every earlier gate
-cleared. After the wait, and immediately before the write, the verb reads the
-pull request, the branch tip, and the reviews again. A tip that moved refuses
-`head-moved`, and a review that opened refuses with its own reason. The
-standing is read again as well, so a sibling merging during the wait refuses
-`standing-stale` instead of lifting a branch that read fresh before it. A pull
-request already out of draft by then reports `already-ready`.
-
-Two reviewers closing within seconds of each other can each read the other's
-review as still open and both refuse. The re-read narrows that window and does
-not close it, so a draft whose reviews both read closed is the controlling
-session's to lift.
-
-## The write
-
-The lift is the `markPullRequestReadyForReview` GraphQL mutation, because the
-REST pull request update carries no draft field. It is the one GraphQL call the
-verb makes, and every read stays on REST. The verb reads `isDraft` back from the
-mutation's answer, and a response that does not say `false` refuses `gh-failed`
-rather than reporting a lift.
-
-A cloud session's proxy refuses GraphQL, so a reviewer running there reaches
-`gh-failed` on the write and hands the lift to the controlling session.
-
-## What it reports
-
-`reason` on the record is what a caller branches on. Exit 0 covers `lifted` and
-`already-ready`, so the second of two reviewers to close owes nobody a message.
-Every other reason exits 1.
-
-| Reason              | What it means                                                          |
-| ------------------- | ---------------------------------------------------------------------- |
-| `lifted`            | The mark came off.                                                     |
-| `already-ready`     | The pull request was not a draft. Nothing is written.                  |
-| `clear`             | Under `--check`, every gate reads clear.                               |
-| `pull-closed`       | The pull request is closed.                                            |
-| `review-missing`    | The thread carries no code review.                                     |
-| `review-open`       | The newest code review is open.                                        |
-| `review-unmarked`   | The newest code review carries no marker.                              |
-| `review-behind`     | The newest code review closed on an earlier commit than the head.      |
-| `ui-missing`        | A checklist exists and no UI review has been posted.                   |
-| `ui-open`           | The newest UI review is open.                                          |
-| `ui-unmarked`       | The newest UI review carries no head marker.                           |
-| `ui-behind`         | The newest UI review closed on an earlier commit than the head.        |
-| `evidence-owed`     | The evidence check reads `owed`.                                       |
-| `standing-stale`    | The base moved under a path the branch writes.                         |
-| `standing-conflict` | The head does not merge cleanly into the base.                         |
-| `standing-unknown`  | The head or base did not resolve, which a fork or deleted head leaves. |
-| `ci-pending`        | Under `--check`, a run has yet to conclude.                            |
-| `ci-failing`        | A check run failed.                                                    |
-| `ci-conflicted`     | The branch conflicts, so no run will start.                            |
-| `ci-timeout`        | A run was still pending when `--wait` ran out.                         |
-| `head-moved`        | A push landed during the wait.                                         |
-| `gh-failed`         | A read or the write was refused, so nothing is reported as lifted.     |
-
-`standing-unknown` waits on a person, matching the orchestrator poll's own rule
-for a head it cannot resolve.
-
-## `--check`
-
-`--check` reports every gate and writes nothing. It reads the check runs once
-and does not wait, so a pending run reports `ci-pending`. The record carries a
-`gates` array with each gate's name, whether it is clear, and its reason, so a
-caller sees every gate that blocks and not the first alone.
-
-The orchestrator's poll and a session deciding whether to run the verb read the
-same answer this way, rather than each restating the gate.

package/docs/agents/pr-local.md

@@ -1,111 +0,0 @@
----
-title: The pull request local preview
-description: How canon pr local finds the server a worktree is running, why a server in another worktree is never reported, the refusal reasons it names, and how a close workflow drops the address line with --remove
----
-
-# The pull request local preview
-
-`canon pr local` reports the `localhost` address of the dev server the current
-worktree is running. `git-pr` calls it ahead of the evidence comparison and
-passes the address through `canon pr evidence --local`, so a reviewer on the
-same machine gets the running branch to click into beside the screenshots and
-the checklist. A workflow on the pull request's `closed` event calls it again
-with `--remove`, which drops the address line and leaves nothing in its place.
-
-```bash
-canon pr local --json
-canon pr local 1341 --remove --json
-```
-
-## How it finds the server
-
-The verb reads every TCP socket in `LISTEN` with the process that owns it. It
-keeps a socket when that process's working directory sits inside the
-worktree's toplevel, including a subfolder, since some tools change into one
-before they listen. It then requests `/` on each kept port and reports the
-lowest one serving an HTML page.
-
-The HTML test is there because a working tree often holds more than one
-listener. A test runner's own server, or a dev server's reload socket, answers
-HTTP too, and a reviewer opening either gets a bare 404 rather than the branch.
-
-Sockets are read from `/proc/net/tcp` and `/proc/net/tcp6` wherever they exist,
-matched against each process's `fd` table, and through `lsof` on a machine
-without them. Linux reads `/proc` even with `lsof` installed, since `lsof` 4.95
-drops a process whose truncated name holds an unmatched `(`, which is what
-Next's `next-server (vX.Y.Z)` title is cut down to. A machine with neither
-refuses as `no-listener-reader`.
-
-The port is never derived from the worktree. A port helper needs a per-stack
-base port the toolkit cannot know, and a server started by hand or by an
-earlier session would not match it anyway.
-
-## Why another worktree's server is never reported
-
-A server running in a different worktree shows a different branch, and a link
-to it on this pull request would show a reviewer the wrong code.
-
-- A sibling linked worktree sits outside this one's toplevel, so its process
-  never matches.
-- The main checkout's server, read from a linked worktree, sits outside the
-  linked worktree's toplevel for the same reason.
-- A linked worktree's server, read from the main checkout, sits inside the main
-  toplevel. The verb excludes everything under `.claude/worktrees/` for that
-  case alone.
-
-## What the record carries
-
-`reason` on the record is what a caller branches on, not the exit code:
-
-| Reason               | What it means                                                         |
-| -------------------- | --------------------------------------------------------------------- |
-| `ok`                 | A server answered. `url` carries the address and `port` the port.     |
-| `no-server`          | Nothing inside this worktree served an HTML page.                     |
-| `no-listener-reader` | Neither `lsof` nor `/proc` is available, so no socket could be read.  |
-| `removed`            | `--remove` dropped the address line from the evidence comment.        |
-| `no-comment`         | `--remove` found no comment carrying the evidence marker.             |
-| `no-line`            | `--remove` found the comment but no address line on it.               |
-| `gh-missing`         | `--remove` needs `gh` and it is not on the path.                      |
-| `gh-failed`          | `--remove` could not read the comments or could not edit the comment. |
-
-The exit is 0 on `ok` and on every `--remove` outcome that finished, including
-the two no-ops, and 1 on every refusal. A caller on an older binary gets an
-unknown-subcommand error instead of a record, which `git-pr` reads as a skip.
-
-## Removing the link at close
-
-The link goes dead once the branch's server stops, and nothing on the pull
-request says so. `--remove` runs on the pull request's `closed` event, merged or
-abandoned, from a workflow seeded into every target:
-
-```yaml
-on:
-  pull_request:
-    types: [closed]
-```
-
-It reads the comment carrying the `pr-evidence` marker, drops the address line
-under `## Evidence`, the hosted `**Preview:**` segment and the
-`**Local preview:**` segment together, and edits the comment itself through
-`gh api`. The hosted link goes too because the deploy workflow deletes the
-branch's preview deployments on the same close. No note replaces the line, and
-the blank line it sat on goes with it so no gap doubles under the heading. A
-comment in the older layout, with each address on its own line at the top,
-loses both lines the same way.
-
-The verb writes here rather than handing a body back, because its caller is a
-workflow with no session to post one. Every other byte of the comment stays as
-it was, which keeps the marker, the checklist delimiters, and any ticked box
-intact. A second run finds no line and reports `no-line`.
-
-A fork pull request gets a read-only token, so the workflow skips the edit with
-a notice rather than failing the close.
-
-## What this does not cover
-
-The link can still go dead while the pull request is open, such as when the
-session holding the server retires. Only the close is covered, and a re-render
-after a push carries the line forward whether the server still answers or not.
-
-`canon docs pr-preview` covers how the hosted address is minted and when it is
-refused.

package/docs/agents/pr-preview.md

@@ -1,155 +0,0 @@
----
-title: The pull request preview deploy
-description: How canon pr preview finds a fenced Cloudflare Pages deploy, refuses a branch its push filter does not serve, dispatches it on a pull request's branch, reads the alias the run prints, the refusal reasons it names, and why an unfenced deploy is refused before anything runs
----
-
-# The pull request preview deploy
-
-`canon pr preview` publishes a pull request's branch to a Cloudflare Pages
-preview and reports the address. `git-pr` calls it after the evidence
-comparison, then re-renders that comment through `canon pr evidence --preview`
-so the link sits on the address line under its heading. A reviewer gets a page
-to click into before merging rather than screenshots and a checklist alone.
-
-```bash
-canon pr preview --json
-canon pr preview 1341 --json --timeout 20
-canon pr preview 1341 --check --json
-```
-
-## Which workflow it dispatches
-
-The verb reads `.github/workflows/*.yml` and `*.yaml` in the checkout and picks
-the first file, in path order, that meets four tests:
-
-- It runs `pages deploy`.
-- It carries a `workflow_dispatch` trigger, since nothing else lets a caller
-  start it on a branch.
-- Its deploy passes `--branch=${{ github.ref_name }}`.
-- It prints a `canon-preview-alias:` line.
-
-The workflow is read before the pull request, so a project with no fenced
-deploy is refused without a network call.
-
-## Which branches it serves
-
-A dispatch runs the workflow whatever its `on.push.paths` filter says, so a
-branch that touched nothing the site builds from would get a preview showing
-none of its change. The verb reads the pull request's changed paths and matches
-them against the picked workflow's own `on.push.paths` or `on.push.paths-ignore`
-list, applying `!` patterns in order the way GitHub does. When nothing matches,
-it refuses as `unserved` and dispatches nothing. `--check` answers `unserved`
-the same way.
-
-The push filter is the one statement of what the site builds from, since it
-already decides when production deploys. A workflow with neither list, with no
-push trigger, or that does not parse as YAML serves every change, so a project
-whose every change ships keeps minting for every branch.
-
-A removed path counts, the same as GitHub's own push filter counts it, so a
-branch whose only site change deletes a file still gets a preview.
-
-## Why an unfenced deploy is refused
-
-Cloudflare Pages publishes a deploy that names no branch to production. A
-dispatch from an unmerged branch through such a workflow ships that branch to
-the live site, so the verb refuses as `unfenced` and dispatches nothing. The
-fix is one flag on the deploy command, and the cloudflare stack's
-`deploy.yml` already carries it.
-
-## Where the address comes from
-
-The workflow prints the alias Cloudflare returned for the deploy, read from
-`wrangler-action`'s `pages-deployment-alias-url` output, on a fixed line:
-
-```plaintext
-canon-preview-alias: https://<alias>.<project>.pages.dev
-```
-
-The verb reads that line out of the finished run's log rather than computing
-the address from the branch name. Cloudflare flattens a branch into its alias
-and may truncate it, and a computed address that is wrong is worse than none.
-The output needs wrangler 3.78 or later, so the workflow pins
-`wranglerVersion`.
-
-`gh workflow run` reports no run id. The verb lists the branch's dispatched
-runs before dispatching and takes the one id that appears afterwards, which
-keeps the match independent of the local clock.
-
-## What the record carries
-
-`reason` on the record is what a caller branches on, not the exit code:
-
-| Reason               | What it means                                                              |
-| -------------------- | -------------------------------------------------------------------------- |
-| `ok`                 | The preview was published. `url` carries the address and `runId` the run.  |
-| `no-deploy`          | No dispatchable workflow runs `pages deploy`.                              |
-| `unserved`           | The push path filter matches no changed path, so nothing was dispatched.   |
-| `unreadable-changes` | The pull request's changed paths could not be read.                        |
-| `unfenced`           | The deploy passes no `--branch`, so nothing was dispatched.                |
-| `no-alias`           | The workflow prints no alias line, or the finished run's log carried none. |
-| `run-failed`         | The deploy run finished without succeeding. `runId` names it.              |
-| `timeout`            | The run did not finish inside `--timeout` minutes, 15 by default.          |
-| `bad-timeout`        | `--timeout` was not a positive number.                                     |
-| `gh-missing`         | `gh` is not on the path.                                                   |
-| `gh-failed`          | `gh` could not read the pull request, or list or dispatch the workflow.    |
-| `no-branch`          | The pull request carries no head branch name.                              |
-| `check-timeout`      | `--check` was combined with `--timeout`.                                   |
-
-The exit is 0 on `ok` and 1 on every refusal. A `timeout` leaves the run
-going, so the preview may still land after the verb has given up on it.
-
-## Checking which head a preview was built from
-
-`--check` dispatches nothing and waits on nothing. It lists the branch's
-`workflow_dispatch` runs, takes the newest successful one by creation time, and
-compares the head it ran at with the branch tip read from the remote. The tip
-comes from the remote rather than the pull request object's `headRefOid`, which
-lags a push. `--check` takes no `--timeout` and refuses one as `check-timeout`.
-
-The alias serves the newest successful deployment for the branch and names no
-sha, so the run listing is the only record of the built head. The
-`workflow_dispatch` filter also drops the cleanup run a closed pull request
-fires, which concludes `success` with its deploy skipped. A project that deploys
-on `push` to a feature branch would need that filter widened.
-
-| Reason     | What it means                                                         |
-| ---------- | --------------------------------------------------------------------- |
-| `fresh`    | The newest successful deploy built the tip. Exit 0.                   |
-| `stale`    | It built an earlier head. `built` and `tip` name both. Mint again.    |
-| `building` | A deploy of the tip is still running. Wait rather than minting again. |
-| `no-build` | No deploy of the branch has succeeded.                                |
-
-The record also carries `runId` for the deploy it read. The check covers the
-hosted address only, so a local address has no run to read and stays unverified.
-`review-ui` runs it before driving a hosted preview and posts nothing on any
-reason but `fresh`.
-
-## How the address reaches the pull request
-
-`canon pr evidence --preview <url>` puts `**Preview:** <url>` on the address
-line under the evidence body's `## Evidence` heading. With no evidence image in
-the diff, the body is the heading, that line, and the trailing marker alone, so
-a pull request whose screenshots did not change still gets one comment a later
-call can find and edit.
-
-A later `canon pr evidence` run without `--preview` reads the address off the
-marked comment and carries it into the new body. `git-followup` re-renders the
-comment after every push, and without that carry the first push would delete
-the link. A visual checklist folded in through `--checklist` carries the same
-way, which is what keeps that push from wiping boxes a reviewer already ticked.
-
-## Removing a preview
-
-A `pull_request` trigger on `closed` in the same workflow runs a cleanup job
-that deletes every preview deployment Cloudflare holds for the branch. The
-deploy job carries `if: github.event_name != 'pull_request'`, so a closed pull
-request never deploys. The same close runs `canon pr local --remove`, which
-drops the address line from the evidence comment, hosted link included, so the
-comment never links a deployment that no longer exists.
-
-## What this does not cover
-
-The verb builds only the deployed-and-public case. A private repository whose
-previews need access protection waits for a project that needs it. A local
-server stands in where there is no deploy, through `canon docs pr-local`.

package/docs/agents/pr-reads.md

@@ -1,111 +0,0 @@
----
-title: Head-sensitive pull request reads
-description: Resolving a branch tip from the remote rather than from the pull request object, reading what a review pass covered off its own marker rather than off GitHub's submission stamps, why an empty run list is not a pass, the refusal reasons each verb names, and what the remote read costs
----
-
-# Head-sensitive pull request reads
-
-`canon pr head`, `canon pr checks`, and `canon pr review-state` each answer about a commit, and each exists because the field GitHub offers answers a different question. The first two resolve the branch tip from the remote with `git ls-remote` rather than taking the pull request object's word for which commit the branch is on. The third reads what a review pass covered off a marker the pass wrote, rather than off the head GitHub stamped when the review was submitted.
-
-```bash
-canon pr head
-canon pr head 1341 --json
-canon pr checks
-canon pr checks 1341 --json
-canon pr review-state
-canon pr review-state 1341 --json
-```
-
-## The pull request object is not the authority for a head
-
-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.
-
-The remote ref carries no such lag. `git ls-remote --heads origin <branch>` asks the remote itself rather than a tracking ref, which is only as current as the last fetch, and the push worth catching is the one this process never saw.
-
-The argument is stated here once. The shipped skill bodies call the verb rather than repeating it, because a sentence telling a session to compare two shas is a sentence a session can decide it already followed.
-
-## What each verb answers
-
-`canon pr head` reports `fresh` when the object and the remote name the same commit and `stale` when they disagree, with both shas on the record. The tip is the authority and the object's head is the claim being checked against it.
-
-`canon pr checks` reads `repos/{owner}/{repo}/commits/<tip>/check-runs` and collapses it to `passing`, `failing`, or `pending`. A failure outranks a run still going, since a run in flight cannot clear a job that already failed.
-
-`canon pr review-state` reports `heading` and `state` for the newest pass in the review family, `commit` and `readAt` for what it covered, `submittedAt` for when GitHub recorded it, and `source` for which of those readings answered. A thread carrying no pass reports `state` and `source` both as `none` with nothing else on the record.
-
-`gh pr checks` cannot be made to answer this question at all, which is the argument for the move rather than a preference between two working commands. Its `--json` field set is `bucket, completedAt, description, event, link, name, startedAt, state, workflow`, with no sha among them, so a caller cannot even learn which commit its answer describes.
-
-## A review's stamps describe the submission, not the read
-
-`commit.oid` on a review names whatever the pull request head was at the instant the review was submitted. `submittedAt` names that instant. Neither names the commit the reviewing session actually opened, and the two are only the same when nothing was pushed while the comment was being written.
-
-A push landing in that window moves both onto a commit nobody reviewed. The next pass then scopes its delta past that commit and reports it covered, which is the failure direction that loses work: the commit is skipped rather than re-read. It fired on a pull request in this toolkit on 2026-09-07, where a pass read one commit, the branch pushed another during the compose, and the poll reported the second as already seen. What it skipped was a genuine fix, and a reader comparing the sha in the report against the sha in the pass caught it.
-
-`review-pr` therefore ends every body it posts with a marker naming what it read:
-
-```markdown
-<!-- review-pr: commit=<sha> read-at=<iso8601> -->
-```
-
-Both values are taken at the top of the pass rather than at the post, so the compose window falls outside what the marker claims. An HTML comment renders as nothing on GitHub, so a reader of the thread never meets it.
-
-The last non-empty line is where it has to sit, and the reader looks nowhere else. Searching a body for the last match instead reads a marker the body was displaying rather than claiming, since a fenced block showing the format on its own line trims to exactly the pattern, and a pass carrying no marker of its own would then hand the next reader a commit taken from an illustration. That is the same defect through a second door, so position rather than shape is what separates a claim from a quotation.
-
-`canon pr review-state` is the only parser of that format. Two parsers was the alternative, one in the shipped skill body and one in the orchestrator poll's own filters, and those two ship on different cadences, so a format change to either would leave the other reading a reviewed commit as unreviewed.
-
-`source` on the record says which reading answered, and a caller checks it before trusting the rest:
-
-| Source     | What it means                                                                               |
-| ---------- | ------------------------------------------------------------------------------------------- |
-| `marker`   | The pass wrote its own read-time record, which is the authority                             |
-| `fallback` | A pass posted before this shipped, read off the submission stamps and carrying their defect |
-| `none`     | The thread carries no pass, so the next one is a first pass                                 |
-
-The record carries `submittedAt` beside `readAt` rather than in place of it, because each is right about a different question. What a pass had read is a fact about the read, and how long a posted comment has waited on a human is a fact about the submission. The orchestrator poll reads the first for its coverage test and the second for its age test.
-
-A `PUT` rewrite of a standing close-out inherits the fix without a mechanism of its own. That request replaces the body and the marker rides in it, so a rewritten comment names the commit the rewriting pass read. `submittedAt` stays pinned to the original submission, which is the reading the age test wants anyway.
-
-## An empty run list is not a pass
-
-Keying the query on a sha is necessary and not sufficient. The endpoint answered with `total_count` 2 and an empty row list during a measured window on 2026-09-02, so a reader that finds no run for the tip and reports `passing` reproduces the false green behind a better query.
-
-Both empty cases report `pending` instead: a tip carrying no run yet, and a listing whose rows all belong to some other commit. The record separates them, since `matched` counts the runs belonging to the tip and `foreign` counts the rest, and a caller that wants to tell "not started" from "still going" reads those two numbers rather than the state alone.
-
-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. 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.
-
-A count above the rows returned reports `pending` for the same reason. The query asks for 100 rows against the endpoint's default of 30, and a commit carrying more than that comes back short, so the verb reports the tip as unread rather than collapsing the page it happens to hold. `reported` against `matched` and `foreign` is where a reader sees which of the three shapes produced the answer.
-
-## Reading the answer
-
-Branch on the record rather than on the exit. Both verbs exit 0 whenever they resolved a tip, whatever the verdict, and 1 only when they refused. An operator shell profile can wrap `canon` in a function whose status comes from a trailing command, which flattens every non-zero exit to 0, so the exit is not a channel either verb puts a verdict on. `gh pr checks` reserving exit 8 for pending is the pattern being replaced rather than one to copy.
-
-Each refusal names a different repair:
-
-| Reason               | What it means                                                                              |
-| -------------------- | ------------------------------------------------------------------------------------------ |
-| `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           |
-| `no-object-head`     | The pull request object reported no head, so `head` has nothing to compare the tip against |
-| `runs-unreadable`    | The check runs for the tip could not be read, which is unread rather than none             |
-| `reviews-unreadable` | The reviews on the pull request could not be parsed, which is unread rather than none      |
-
-A failed remote read and a branch the remote does not carry stay apart rather than collapsing into one reason. Reading the first as the second would report a network refusal as a deleted branch, and the repairs have nothing in common.
-
-## What it costs
-
-One remote round trip per call, sampled here at 0.41s, 0.55s, and 0.67s on 2026-09-01 and 2026-09-02, against 0.001s for the local ref read. The spread is the network rather than the command, so read it as roughly half a second and not as a figure to compare a later reading against. Every caller pointed at these verbs already spends a `gh` round trip on the same line, so the added cost lands on a path that was never local to begin with.
-
-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 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 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/agents/pr-tick.md

@@ -1,72 +0,0 @@
----
-title: The pull request checklist tick
-description: How canon pr tick marks the checklist boxes a UI pass drove, the stamp that names the commit each passed at, why a render at a newer head clears a tick, the refusal reasons it names, and why a taste box is never ticked
----
-
-# The pull request checklist tick
-
-`canon pr tick` ticks the boxes of the visual checklist on the pull request's
-evidence comment. `review-ui` calls it once its verdict has posted, for every
-box that passed at the head it drove, so the person merging reads a checklist
-a driver worked through instead of one that stays empty.
-
-```bash
-canon pr tick 1341 --boxes 1,2,4 --head <sha> --json
-```
-
-Box numbers come from the `boxes` field of `canon pr evidence --json`, which
-numbers the checklist's box lines in order. A caller never counts lines itself.
-
-## What a tick looks like
-
-A ticked box ends in the commit it passed at, visible on the comment:
-
-```markdown
-- [x] click "Pricing" in the header → the pricing page opens · passed at `<short-sha>`
-```
-
-The stamp is visible rather than an HTML comment because the person it is for
-reads the merge record, and a hidden head would tell the machine what the
-reader cannot see. The reader matches the stamp only as the trailing segment of
-a line, so a box whose own text says `passed at` is left alone.
-
-## When a tick is cleared
-
-A tick is a claim about one commit, so a render at another commit does not
-carry it forward. `canon pr evidence` settles the checklist before it renders:
-
-- A tick stamped for the render's head stays.
-- A tick stamped for any other head is cleared and loses its stamp.
-- A tick with no stamp, such as one an author or the operator added by hand,
-  stays only when the comment it came from described the render's head.
-
-A render at the same head after `--preview` keeps every tick. A push that
-reaches the branch without a render leaves its ticks in place until the next
-one, and the stamp still shows which head earned them.
-
-## What it refuses
-
-`reason` on the record is what a caller branches on, not the exit code:
-
-| Reason         | What it means                                                                                                |
-| -------------- | ------------------------------------------------------------------------------------------------------------ |
-| `ticked`       | The boxes were ticked, with the remote tip in `head`.                                                        |
-| `stale-head`   | `--head` is not the branch tip on the remote. Nothing is written.                                            |
-| `taste-box`    | A named box ends in `(taste)`. Nothing is written.                                                           |
-| `no-box`       | A named number is past the end of the checklist. Nothing is written.                                         |
-| `no-checklist` | The evidence comment carries no checklist.                                                                   |
-| `no-comment`   | No comment on the pull request carries the evidence marker.                                                  |
-| `bad-boxes`    | `--boxes` is not a list of positive whole numbers, or `--head` is not a hex sha of seven characters or more. |
-
-A taste box is a judgment of look or feel that a driver reports as needing a
-person's eyes. Refusing it in the verb makes that rule a check rather than a
-sentence a driver can talk itself out of, and a refusal writes none of the
-boxes named beside it.
-
-The head is compared against the tip read from the remote rather than the pull
-request object, which lags a push by up to a minute. A push landing between
-that read and the write leaves a tick at an older head until the next render
-clears it, the same window `canon pr head` documents.
-
-The verb edits the marked comment in place with a `PATCH`, the way
-`canon pr local --remove` does, and ticking a box again restamps it.