@erclx/canon 5.39.0 → 5.40.0

package/docs/agents/pr-evidence.md

@@ -1,273 +0,0 @@
----
-title: The pull request evidence comparison
-description: What canon pr evidence compares, the marker that lets it edit its own comment rather than duplicate it, the refusal reasons it names, what the --check read reports as owed, and why the comparison anchors at the merge base rather than the previous push
----
-
-# The pull request evidence comparison
-
-`canon pr evidence` renders one comment naming every changed image under an
-`evidence/` path segment, comparing each against the pull request's merge base.
-`git-pr` posts it when a pull request opens or is edited, and `git-followup`
-posts it again after every later push, so a reviewer never has to open Files
-Changed to see what a case looked like before and after.
-
-```bash
-canon pr evidence
-canon pr evidence 1341 --json
-```
-
-## Why the comparison anchors at the merge base
-
-The comparison is always base against the current head, never the previous
-push against the new one. A follow-up only ever moves the after side of the
-comment, so what the comment claims can only grow to match what the branch
-actually shows, and a reviewer who opens it midway through a review round
-never reads a stale before image describing an intermediate commit nobody is
-looking at anymore.
-
-## What counts as evidence
-
-A changed path qualifies when one of its segments is literally `evidence` and
-its filename carries an image extension (`png`, `jpg`, `jpeg`, `gif`, `webp`,
-`avif`, `svg`). The second half of that test exists because an `evidence/`
-folder holds whatever else a project keeps beside its captures. This
-repository's own tree carries eight `.md` files, two `.sh` scripts, a `.tsv`,
-a `.json`, and an `.html` file against a single `.png`, and every one of them
-would render as a broken image embed without the extension filter.
-
-## What the record carries
-
-The record groups every evidence path by state, the remainder of its
-directory under the `evidence/` segment, and within a state by filename stem,
-so a `before/hero.png` and an `after/hero.png` naming the same case group as
-one entry, not two files. Each entry carries whether it existed at the base
-commit, so the comment shows a base image or marks it new. Each `<img>` takes
-its PNG width, at most 1000. `canon docs pr-evidence-layout` covers how the body
-groups those entries by view.
-
-`reason` on the record is what a caller branches on, not the exit code:
-
-| Reason                 | What it means                                                                           |
-| ---------------------- | --------------------------------------------------------------------------------------- |
-| `ok`                   | A body was rendered. `commentId` is set when a marked comment already exists.           |
-| `no-evidence`          | No `evidence/` segment in the diff and no `--checklist` or `--preview`. A silent no-op. |
-| `unreadable-checklist` | `--checklist` named a path that could not be read, or one holding nothing.              |
-| `gh-missing`           | `gh` is not on the path, so no pull request could be resolved.                          |
-| `gh-failed`            | `gh` could not answer for this repository or branch, or read its comments.              |
-| `no-branch`            | The pull request carries no head branch name.                                           |
-| `no-object-head`       | The pull request object reported no head commit.                                        |
-| `no-base`              | GitHub reported no merge base for the pull request.                                     |
-| `unreadable-changes`   | GitHub could not list what the pull request changed.                                    |
-| `would-empty`          | The render holds no cases and the marked comment holds some. No body.                   |
-| `check-writes`         | `--check` was passed with `--preview`, `--local`, or `--checklist`.                     |
-
-`no-evidence` is not a refusal a caller reports. A project on a stack that
-carries no evidence path, such as `base` or `python`, hits this reason on
-every pull request and posts nothing, which is the correct behavior rather
-than a gap.
-
-Both `ok` and `no-evidence` also report what the marked comment already
-shows a reviewer, each field present only when that comment holds it:
-
-| Field       | What it carries                                                   |
-| ----------- | ----------------------------------------------------------------- |
-| `preview`   | The hosted `**Preview:**` address on the comment's address line.  |
-| `local`     | The `**Local preview:**` address beside it.                       |
-| `checklist` | The checklist between its delimiters, with any ticked boxes kept. |
-| `boxes`     | Each box's `number`, `text`, tick, `stamp`, and `isTaste`.        |
-
-These come from the comment already posted, never from the flags the call
-passed, so a skill driving a review reads which address and which checklist a
-reviewer has without parsing the comment itself. A checklist posted raw, which
-only the fallback for a refused render does now, carries no marker, so the
-record reports none of the three for it. Reading
-them means the thread is read before the `no-evidence` answer too, so an
-unreadable thread refuses as `gh-failed` on both reasons rather than
-reporting the fields absent.
-
-`ok` also carries `states`, the comparison the body renders as data: each
-state's items with `path`, `stem`, `added`, and `width` and `baseWidth` when
-read. `review-ui` matches a frame against it so it publishes no image the
-worker's evidence already shows. `canon docs pr-frames` covers that store.
-`widthUnread` lists a failed read as `head:<path>` or `base:<path>`.
-
-## What `[number]` selects, and what it does not
-
-Naming a number picks the pull request the whole record describes: its head
-commit, its merge base, its changed set, and the marked comment to edit in
-place. The changed paths and whether each was added or modified come from the
-pull request's files endpoint, paged to the end, and the merge base comes from
-the compare endpoint, so the record is the same from any checkout. A run from
-the main worktree against a branch built elsewhere renders that branch's
-comparison.
-
-The trade is that the verb no longer sees evidence that is uncommitted or
-unpushed, which the comment's head-pinned image links could not show anyway.
-A path the pull request renamed or copied counts as added, since the new path
-has no counterpart at the merge base, so a rename loses its before image and
-reads as new. A path the pull request removed is dropped, since it has no
-head image to show. A failed files read refuses as `unreadable-changes` rather
-than rendering a short set, and a missing merge base refuses as `no-base`.
-
-## A render never empties a comment that carries cases
-
-When the render holds no cases and the marked comment holds some, the verb
-refuses `would-empty` and prints no body. A render with no cases cannot tell a
-case removed on purpose from a short read, so the destructive direction needs a
-person: they edit the comment directly. The record keeps `commentId` and the
-carried fields, so the caller can still find the comment. A comment holding
-only a preview or a checklist has no cases to lose and still re-renders `ok`.
-`no-evidence` without a flag returns before any render, so the guard touches
-only `--preview`, `--local`, and `--checklist` calls.
-
-## One comment, found by its own marker
-
-Every body this verb renders ends with a trailing marker naming the head it
-describes:
-
-```markdown
-<!-- pr-evidence: head=<sha> -->
-```
-
-`canon pr evidence` reads that marker back off every comment on the pull
-request, the same way `canon pr review-state` reads its own marker off a
-review body, and reports the REST id of whichever comment carries it as
-`commentId`. A caller with no `commentId` posts a new comment. A caller
-holding one edits that comment in place with a `PATCH` rather than posting a
-second one.
-
-Putting the lookup here, in the one place both `git-pr` and `git-followup`
-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
-details wrapper lands once, not twice.
-
-## The preview line
-
-Every body opens with `## Evidence`. Under it sits one address line carrying
-whichever previews apply, joined by a middle dot:
-
-```plaintext
-## Evidence
-
-**Preview:** <url> · **Local preview:** <url>
-
-**Base:** [`<base>`](<base-commit-url>) · **Head:** [`<head>`](<head-commit-url>)
-```
-
-The Base and Head line follows only when the comment carries screenshots.
-
-`--preview <url>` puts the branch's hosted address on that line, and a run
-without it carries forward the address the marked comment already holds. With
-no evidence in the diff and an address in hand, the body is the heading, the
-address line, and the marker alone, reported as `ok`. `canon docs pr-preview`
-covers where the address comes from.
-
-A carried hosted address is dropped when a deploy workflow resolves and its
-push path filter matches no path the pull request changed, since the site it
-links shows none of the change. An explicit `--preview` is always kept.
-
-The carry-forward reads every line above the commit line, the checklist, and
-the comparison for each prefix, wherever it sits. A comment posted before the
-heading opened the body, with each address on a line of its own at the top,
-reads the same way, so an open pull request keeps its links on its first
-re-render.
-
-## The checklist line
-
-`--checklist <path>` closes the body with a visual checklist, below the
-comparison it annotates, so one comment carries the preview address, the
-screenshots, and what a reviewer has to look at. The file is what
-`canon:ui-checklist` writes to `.canon/tmp/handoff/ui-checklist/<slug>.md`, and
-`git-pr` passes it here rather than posting it as a second comment.
-
-A run without the option carries forward whatever checklist the marked comment
-already holds, the same way the preview address is carried. That is what keeps
-`git-followup`'s re-render after a push from dropping the checklist, since
-`git-pr` deletes the handoff once the first post reports success and no later
-call has a file to pass. `canon docs pr-tick` covers what a tick carries.
-
-The option decides `no-evidence` on its own. A branch with a checklist and no
-changed evidence image renders `ok` with a marked body holding the checklist,
-so the checklist always lands in the one comment a later call finds and edits.
-The raw post survives only as the caller's fallback when the render is refused.
-A path that cannot be read, or one holding nothing, refuses as
-`unreadable-checklist` rather than rendering without it: the caller deletes the
-handoff once a post succeeds, so a silently dropped checklist is the only copy
-gone.
-
-## The local preview line
-
-`--local <url>` adds `**Local preview:** <url>` to the address line, after the
-hosted segment when there is one and alone when there is not. A run without the
-option carries forward the local address the marked comment already holds, the
-same as the other two.
-
-The option does not turn `no-evidence` into `ok` on its own. A branch with a
-dev server running and no rendered change would otherwise get a comment holding
-a link and nothing else. Together with `--checklist` the link and the
-checklist land in one comment.
-`canon docs pr-local` covers where the address comes from and how the line is
-removed at close.
-
-## What a pull request is still owed
-
-`--check` reads the same changed set and the same thread, renders no body, and
-reports which steps of the ship chain that run after the pull request opens
-never landed on it. It reads the pull request rather than any session's account
-of what it ran, so a session that stopped after opening the pull request leaves
-a branch the check can tell apart from one that needed neither step.
-
-```bash
-canon pr evidence 1341 --check --json
-```
-
-| Reason    | What it means                                                      |
-| --------- | ------------------------------------------------------------------ |
-| `settled` | Nothing is owed. `owed` is empty.                                  |
-| `owed`    | `owed` lists `evidence`, `preview`, or both, always in that order. |
-
-- `evidence` is owed when the changed set carries an evidence image and no
-  comment carries the marker.
-- `preview` is owed when the pull request has a marked comment or an evidence
-  change, a deploy workflow resolves in the checkout the verb runs from, its
-  push path filter matches a path the pull request changed, and the marked
-  comment carries no `**Preview:**` address. A `**Local preview:**` address
-  does not satisfy it. A project deploying nothing is never owed a preview,
-  and neither is a branch its deploy does not build from.
-
-The record carries `owed`, `commentId` when a marked comment exists, and the
-same `preview`, `local`, and `checklist` fields the other reasons carry, so a
-caller reads one shape. It never carries `body`, so a writer branching on `ok`
-and posting `body` cannot act on a check record. Passing `--preview`, `--local`,
-or `--checklist` with it refuses as `check-writes` before any `gh` call, since
-those ask a read to write.
-
-The thread cannot separate a skipped preview step from a failed one. A pull
-request whose deploy failed or timed out reads as owing a preview, and the
-session that ran it holds the cause. A checklist-only branch posts a marked
-comment, so it reads as owing a preview once that comment exists and a deploy
-workflow resolves. The deploy workflow is read from the checkout rather than
-the pull request's head, so one adding or removing its own reads trunk's.
-
-An unreadable thread refuses as `gh-failed` rather than reporting `settled` off
-a thread it never read. The check skips the merge base read, which only the
-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.
-
-## When the comment opens
-
-The comment opens every block while it carries six images or fewer and closes
-every block past that. A line under `## Evidence` names the compared base and
-head as linked short shas, which tells a reader whether the images match the
-latest push. `canon docs pr-evidence-layout` covers the count and the blocks.
-
-## 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
-redundant. The diff view shows what moved between two commits a reader has
-already opened, and the comment is what lets a reader see the same comparison
-without opening it at all.

package/docs/agents/pr-frames.md

@@ -1,131 +0,0 @@
----
-title: The pull request frame store
-description: How canon pr frames pushes a UI review frame to a never-merged branch through the GitHub API and returns a branch-path link, which ref it writes, the pass segment that keeps an earlier image fixed, the refusal reasons it names, and how --drop and --prune rewrite the branch so a dropped frame leaves history
----
-
-# The pull request frame store
-
-`canon pr frames` gives a review comment an image it can embed. `review-ui`
-drives a pull request's checklist and captures a frame per box, and a frame
-on the reviewer's disk resolves for nobody else. The verb pushes one frame to
-the `canon/frames` branch and returns a link to its path there.
-
-```bash
-canon pr frames 1341 --add frames/3.png --box 3 --head <sha> --pass 20261002T154450Z --json
-canon pr frames 1341 --add frames/3-dark.png --box 3 --theme dark --head <sha> --pass 20261002T154450Z --json
-canon pr frames 1341 --drop --json
-canon pr frames --prune 30 --json
-```
-
-## What it writes
-
-An add writes `refs/heads/canon/frames` and no other ref. Every call goes
-through the GitHub git data API, being blobs, trees, commits, and that one ref,
-so nothing is checked out, no worktree is entered, and neither `main` nor any
-branch a pull request holds is touched. The branch never merges.
-
-A frame lands at `pr-<number>/<short-head>/<pass>/box-<n>.png`, or at
-`box-<n>-<theme>.png` when `--theme` names `dark` or `light`, so two shots of
-one box in one pass never take the same path. A frame without `--theme` keeps
-the plain form. `--head` names
-the commit the pass drove, 7 to 40 lowercase hex characters, and defaults to
-the head the pull request object reports. `--pass` is the instant the pass
-started, in compact UTC as `date -u +%Y%m%dT%H%M%SZ` prints it, which
-`review-ui` records once at its first step. A second pass at the same head and
-box therefore writes a new file rather than replacing the image an earlier
-comment shows, which matters when a preview is minted again at one head.
-
-`link` uses the same `blob/<ref>/<path>?raw=true` form as the evidence comment,
-naming the `canon/frames` branch rather than a commit. Every drop rewrites the
-branch, and a link pinned to a commit would stop resolving for every other pull
-request's frames once GitHub collects the commit it names. A path link lives
-exactly as long as its file, so it survives every rewrite that drops another
-pull request and ends only when its own is dropped.
-
-The first `--add` creates the branch with a root commit holding the
-frame, so a project needs no setup. An add only fast-forwards the ref. When
-another writer moved it between the read and the move, the add rebuilds on the
-new tip, up to three times, before refusing as `ref-conflict`.
-
-Only a frame of the address the pass drove belongs here. The branch is as
-public as the repository, so a frame of a private or pre-release state would
-be published with it.
-
-## What the record carries
-
-`reason` on the record is what a caller branches on, not the exit code:
-
-| Reason             | What it means                                                                    |
-| ------------------ | -------------------------------------------------------------------------------- |
-| `ok`               | An add pushed, or a drop or prune finished, including one that removed nothing.  |
-| `bad-mode`         | Not exactly one of `--add`, `--drop`, `--prune`, or a number with `--prune`.     |
-| `no-number`        | `--add` or `--drop` named no pull request.                                       |
-| `bad-box`          | `--add` carried no positive `--box`.                                             |
-| `bad-head`         | `--head`, or the head the pull request reported, is not a 7 to 40 character sha. |
-| `bad-pass`         | `--add` carried no `--pass` stamp in compact UTC.                                |
-| `bad-theme`        | `--theme` is neither `dark` nor `light`, or came without `--add`.                |
-| `bad-days`         | `--prune` carried no positive number of days.                                    |
-| `unreadable-frame` | The `--add` file is missing, empty, or not a PNG. Nothing is called.             |
-| `read-only`        | GitHub refused a write with 403 or 404, which is what a fork's token gets.       |
-| `unreadable-tip`   | The branch exists and could not be read.                                         |
-| `push-failed`      | A write failed partway and the ref did not move.                                 |
-| `ref-conflict`     | Another writer kept moving the ref through every attempt.                        |
-| `no-object-head`   | No `--head` and the pull request reported none.                                  |
-| `gh-missing`       | `gh` is not on the path.                                                         |
-| `gh-failed`        | `gh` could not name the repository or read the pull request.                     |
-
-An add's `ok` record carries `link`, `commit`, `path`, `box`, `theme` when one was passed, `head`, `pass`,
-and `created`, which is true when the add made the branch. A drop's carries
-`removed`, the pull requests whose folders went, plus `commit` for the rewrite
-or `deleted` when it emptied the branch. A prune adds `kept` and `unread`.
-
-`review-ui` reads every reason but `ok` as a cue to describe the frame in words
-and name the reason, so a refused push never fails the pass.
-
-## Dropping frames
-
-A plain delete commit would keep every image reachable through history, so
-`--drop` and `--prune` write one root commit holding everything else and
-force-move the ref to it. A rewrite that leaves the branch empty deletes it,
-and the next add recreates it. Dropping a pull request with no frames, or on a
-missing branch, reports `ok` with nothing removed, so a scheduled run never
-fails on an empty branch.
-
-`--prune <days>` reads every `pr-<n>/` folder, asks GitHub for each pull
-request's state, and drops every one reading closed with a close date more
-than that many days ago, in a single rewrite. It keeps one still open, one
-reopened after closing, one closed exactly the given days ago, and one whose
-state could not be read, listing that last kind under `unread`.
-
-## The legacy branch
-
-Frames lived on `canon-frames` before the rename to `canon/frames`. An add
-never writes it. `--drop` and `--prune` also run against it after the
-current branch, remove only, and delete it once empty. `--prune` drains it
-as its pull requests expire, and `--drop` clears one pull request at once.
-The record carries `legacy: true` when that
-pass changed the ref, and its `removed` list folds both branches in, naming
-a pull request once. A missing or unreadable legacy ref never fails a run
-the current branch finished.
-
-A link minted before the rename points at `blob/canon-frames/...` and keeps
-resolving until its pull request has been closed 30 days or `--drop` runs.
-
-This repository runs `--prune 30` daily from
-`.github/workflows/pr-frames-cleanup.yml`. A frame's file stays on the branch
-until its own pull request has been closed for 30 days, so a link in a review
-comment keeps resolving for about a month after its pull request closes,
-whatever other pull requests the branch drops in between. A target project
-carries no such workflow yet and keeps its frames until someone runs `--drop`.
-
-## What a rewrite does not do
-
-A force-move leaves the old commits unreachable without purging them. GitHub
-serves an unreachable commit by sha until it collects it, so a dropped frame
-stays reachable to anyone holding a sha from an earlier record, and a frame
-holding sensitive content needs a purge request to GitHub. Its path link stops
-resolving at the drop, since the branch no longer carries the file.
-
-A drop racing an add can lose the add's frame, since GitHub's ref update has no
-compare-and-swap for a force-move. The drop builds from the tip it reads, and
-the window is the length of one rewrite.

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.