@erclx/canon 5.39.0 → 5.41.0

package/docs/agents/markdown-audit-weight.md

@@ -1,83 +0,0 @@
----
-title: Markdown audit weight
-description: The advisory sections of the markdown audit, being bullet and paragraph weight, run depth, the two cadence numbers, and the length ceiling, with the samples behind each checkpoint and which of those numbers gate through density
----
-
-# Markdown audit weight
-
-## Bullets, paragraphs, and depth
-
-Bullet weight and depth are the checks that moved off `canon context audit`, carrying what they measured at the time. A top-level bullet reports past roughly 200 characters with continuation lines folded in and nested items left out. A run reports past roughly 40 rendered lines, measured at 80 columns, where a heading breaks one and so does a bold section marker taking the whole line at column zero, either ending in a colon, or holding one whole code span at any width, or running to 20 characters or fewer, skipping fenced blocks and exempting a flat peer list averaging under 130 characters a bullet and a run that is entirely table rows. Each file reports its longest run alone, so a second run past the checkpoint in the same file is never named.
-
-Every weight and depth measure counts the text a reader is shown. A link reduces to its anchor text and an autolink drops whole, since no reader is shown either destination. A backticked path stays counted, which is where these measures part from the ban scan `markdown-audit.md` describes: that one blanks a code span so a standard quoting its own banned character does not report itself, and discounting the same span here would under-report a paragraph carrying several. One file holds both span sets and each answers its own question.
-
-A code span is walked around rather than through, so a path quoting link or angle-bracket syntax keeps the width the page gives it. Masking inside one takes back the decision to count it, and the placeholders this toolkit writes are where that shows.
-
-The paragraph check measures both halves of one rule. `markdown.md` caps a paragraph at four sentences, and a sentence cap on its own is satisfied by writing fewer and longer ones: 15 paragraphs in this corpus sit inside four sentences and past the weight checkpoint, and the heaviest of those runs 886 characters. The standard therefore states a weight beside the sentence cap, and the verb reads it as its own checkpoint.
-
-A sentence boundary closes on terminal punctuation ahead of a capital or a code span. The capital is what keeps a version pin and a decimal from each reading as two sentences, and the code span is admitted beside it because a command name opening a sentence carries no capital to find.
-
-The paragraph weight sits at 350 and the bullet weight at 200, the two density lengths in `markdown-audit.md`, so this advisory warning and the density finding that gates read one number. Both shipped at 400 and have moved twice, each time against a sample of its own. They are separate checkpoints in the standard and separate patterns in the parser, so a read that moves one leaves the other where it is.
-
-### The sample behind the paragraph number
-
-The checkpoint shipped at 400 as a borrowed number and was decided against a read of the prose it reports. Thirty-six findings were sampled, six from each of six weight bands, drawn at even spacing through each band ordered by path and line, and each was classed as prose a reader wants split or prose the checkpoint should not have reported.
-
-Every band below was measured before the scan stopped counting link syntax as prose, so a paragraph sitting in one of these bands is heavier than a paragraph reported at the same number today. The re-sample in the section below re-reads the same range against the corrected measure and reaches the opposite verdict on it, which is the measure moving rather than the reader.
-
-| Band      | Wants the split | Reads as written |
-| --------- | --------------- | ---------------- |
-| 400 - 425 | 1               | 5                |
-| 425 - 450 | 2               | 4                |
-| 450 - 500 | 2               | 4                |
-| 500 - 600 | 2               | 4                |
-| 600 - 750 | 6               | 0                |
-| Past 750  | 6               | 0                |
-
-Precision is what moved the number rather than the finding count. Below 600 the checkpoint was right about seven of twenty-four sampled paragraphs, and past 600 it was right about all twelve. A checkpoint is a prompt to look, and a prompt wrong three times in four teaches a reader to stop looking. The distribution offers no seam to place the number against, with a median of 487 and a seventy-fifth percentile of 563, so the read is the whole of the evidence.
-
-Nothing inside the 500 to 600 band separated the two classes by length, which is the reason the number did not land there. The two paragraphs wanting a split ran 543 and 590 characters against four reading well at 515, 532, 555, and 569.
-
-The sample is thirty-six paragraphs against a reported population in the hundreds, and one reader classed all of them. Treat a band's rate as the order of magnitude it is rather than as a measured precision, and re-sample before moving the number again.
-
-### The re-sample that moved the number to 700
-
-That re-sample ran once the scan stopped counting link syntax as prose. Findings at 604, 633, and 677 characters each read as an ordinary four-sentence paragraph on one topic, density arrived around 760 and was plain by 860, and the move cut the weight half of the report roughly in half while leaving the sentence cap untouched.
-
-### The read that moved it to 350
-
-The operator read sample rewrites at 400 and 350 side by side and picked 350, the length of the reference sample, in groundwork `154`. The bullet number moved to 200 in the same read, since no rewritten one-fact bullet passed 151. Both now gate as density limits, so the earlier verdict that a long paragraph reads well as written no longer holds.
-
-A bullet, a heading, a table row, a blockquote, a blank line, and a fence each end a paragraph, so a heavy bullet is reported by the bullet check alone and never counted twice.
-
-## Bullet stacks
-
-A run of more than 5 plain bullets is one of the six density limits in `markdown-audit.md`, which reports and gates it. This section keeps what counts as a run. A run of consecutive top-level bullets reports past 5. A blank line, an indented continuation, and a nested item do not break the run, and a paragraph, a heading, or any other column-zero line does. A fenced line is skipped without breaking it. The count is of items rather than weight, so it catches a catalog of short bullets the 200-character checkpoint above passes.
-
-Two shapes are exempt. A run whose every item opens with a bold label or a link names its own subject per item and reads as a table of entries, and a numbered list states an order, so numbered items never count. Governance rules and `REQUIREMENT.md` sit outside the density scope rather than being exempted here, since a rule is one imperative per bullet.
-
-## Cadence
-
-Uniform cadence is the failure a ban list cannot express. A ban set states negatives, and fragments, verbless clauses, and sentences that all run one length are each the absence of something, so no word added to a ban list reaches any of them. The shape layer already measured a bullet, a paragraph, and a run, and stopped one level above where that failure lives.
-
-Cadence measures a paragraph on two numbers. The spread is the words between its longest and shortest sentence, and the opener count is the times one word opens a sentence in it. A spread of five words or under reads as one cadence, and a word opening more than two sentences is a pattern rather than a coincidence. Both come from `## Rhythm` in the `write-human` skill, which states them about prose a person reads, and this measures against that statement rather than setting a threshold of its own.
-
-Words are counted off the text a reader is shown. A link contributes its anchor text, an autolink contributes nothing, and the sentence boundaries do not move under that masking, since the boundary pattern requires whitespace after the terminal punctuation and no destination carries any. An opening word is lowercased and stripped of punctuation, so a sentence opening on a backticked command name reports the command.
-
-A paragraph carrying fewer than three sentences is skipped rather than scored. A two-sentence configuration note has no spread worth reading, and the opener rule is written about a third sentence turning a coincidence into a pattern, so neither number says anything before the floor. That is the cheap form of a wider exemption: a shape-aware one, exempting a short reference block by what it is rather than by how many sentences it holds, waits on a second case.
-
-The unit is the paragraph and each file names its worst on each measure, which follows the depth check rather than setting a precedent. A file's flattest paragraph and its most repetitive one are named only when each crosses its checkpoint, so a file reading healthy names nothing rather than offering its least healthy paragraph as a finding.
-
-Neither number gates and neither names a file wrong. This is a weaker claim than the one the weight checkpoints make, because a healthy range differs by surface: a catalog entry is several short sentences carrying one fact each, and a page arguing a decision is not, so one range applied across the corpus would report the surfaces that are correct. The run therefore states where the numbers came from beside them, and the counts are what a reader compares against.
-
-A reading of that spread across the whole corpus is what backs the range above, taken once against this repository's own tracked markdown rather than against a target project's.
-
-That reading travels with the command rather than staying here. `BASELINE` in `src/markdown/structure.ts` carries the overall share, the per-file range, and the ten-paragraph floor beneath which a file's own rate says nothing, and the run prints all four in the legend beside the rate it measured. A count with no range beside it reads as a finding, and naming that a healthy range differs by surface states that a range exists rather than what it looks like. This page is toolkit-internal, so a reader running the command in a project that installed no standards would otherwise have two counts and nothing to place them against.
-
-Two of the rules `write-human` states are deliberately not implemented. A sentence's grammatical shape and whether it carries a finite verb each need a parse rather than a match, and an imperative would read as a defect under a pattern that approximated either. The verbless share is the measure closest to the reported symptom, which is exactly why shipping it wrong would discredit the two that hold.
-
-The condition on that was something identifying a finite verb rather than guessing at one, and two parsers have now been run against it over 11,389 paragraph sentences. They disagree by a factor of four. `compromise` reports 2 percent and reads a fronted past participle as a finite verb, so `Measured at <sha> on <date>.` counts as carrying one. `wink-pos-tagger` reports 9 percent, fixes that class, and is still wrong on roughly three in four, because an imperative's verb tags as a proper noun and a noun-ambiguous predicate tags as a noun, which makes `Each maps to a skill.` read verbless. Separating those needs to know which token is the predicate, and that is syntax rather than a tag. The measure stays unimplemented, now against a mechanism rather than against the idea of one.
-
-## Length
-
-The Length step sums rendered lines over the whole source, frontmatter and fenced blocks included, and lists each document past the 300-line ceiling, longest first. A changelog and a document carrying a whole-line `<!-- canon-length-exempt: <reason> -->` outside a fence are counted in one line rather than listed. Each `--json` entry carries `renderedLines` and `exempt`, the stated reason or `null`, and `checkpoints` carries `ceiling`.

package/docs/agents/pr-evidence-layout.md

@@ -1,70 +0,0 @@
----
-title: The pull request evidence layout
-description: How canon pr evidence groups screenshots into one block per view with a row per width and a column per theme, when a base column appears, where a name outside the form lands, how the commit line links, and when the blocks open
----
-
-# The pull request evidence layout
-
-`canon pr evidence` renders the screenshots of a pull request as blocks a
-reviewer reads by view. The record behind them, and the reasons a run can
-refuse, are in `canon docs pr-evidence`.
-
-## One block per view
-
-A case name that ends in `-dark-<width>` or `-light-<width>` belongs to the
-view named by everything before that suffix, so `menu-open-light-1440` is the
-`menu-open` view. The name is split from the right because a view may carry
-hyphens of its own.
-
-Each view is one `<details>` block. Its summary carries the view and its case
-count, a row holds one width in ascending number order, and a column holds one
-theme:
-
-```markdown
-| Width | Dark | Light |
-```
-
-A view with any case already at the base takes a base and a head column per
-theme, and a case the pull request added shows `*(new)*` in its base cell:
-
-```markdown
-| Width | Dark base | Dark head | Light base | Light head |
-```
-
-A cell with no case in it stays empty. A theme no case of the view carries has
-no column. A state under a named directory titles its blocks
-`<state> / <view>`, so two states holding one view never repeat a name.
-
-## Names outside the form
-
-A case name that does not split into a view, a theme, and a width lands in a
-flat `Case | Base | Head` block for its state, or `Case | Head` when every case
-in it is new. Nothing is dropped, so `board.png` or a name with no width still
-shows.
-
-## The commit line
-
-Under `## Evidence`, the Base and Head line names each commit as a short sha
-that links to the full commit:
-
-```markdown
-**Base:** [`<base>`](https://github.com/<repo>/commit/<base-sha>) · **Head:** [`<head>`](https://github.com/<repo>/commit/<head-sha>)
-```
-
-A reader opens what the screenshots were taken against in one click. The base
-is the merge base the compare endpoint returns, not trunk's tip.
-
-## When the blocks open
-
-Every block opens while the comment carries six images or fewer, counting one
-per case for the head plus one per case that is not new. Past that every block
-closes, so the whole comment is open or closed together.
-
-## What reads the body back
-
-The case count that `would-empty` compares is the number of head images in the
-body. It holds for the grouped rows, where one row carries up to two cases, and
-for every layout posted before, so a comment rendered under an older shape
-still counts. The bold `**Base:**` label and the `<details>` blocks are
-unchanged, which keeps the address reader and the review skills working on both
-layouts. An older comment keeps its shape until the next run edits it in place.

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.