@erclx/canon 5.13.0 → 5.14.0

package/docs/agents/pr-frames.md

@@ -0,0 +1,112 @@
+---
+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 --drop --json
+canon pr frames --prune 30 --json
+```
+
+## What it writes
+
+The verb 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`. `--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-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`, `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`.
+
+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/workflow/skill-map.md

@@ -38,20 +38,21 @@ This page is the corpus the coverage claim is measured against: every name `cano
 
 ## Build the feature
 
-| Skill                        | When to use                                                                                                |
-| ---------------------------- | ---------------------------------------------------------------------------------------------------------- |
-| `canon:session-worktree`     | At the plan-to-execute boundary, to get an isolated tree and branch, or to route a refused main-root write |
-| `canon:auto-ship`            | After plan approval, to chain implement, verify, review, draft PR                                          |
-| `canon:project-commands`     | When the project's own command needs running                                                               |
-| `canon:test-first`           | Before implementing a planned change, to run its test red, green, then refactor                            |
-| `canon:test-craft`           | When writing or changing any test, to pick its layer and filter what it asserts                            |
-| `canon:build-in-slices`      | While building a plan, to commit each tested slice and note out-of-scope defects rather than fix them      |
-| `canon:api-design`           | When changing what a caller sees, being an export, a flag, an output shape, or a retried write             |
-| `canon:code-craft`           | Before writing a function, class, or module, to pick the shape the next change needs                       |
-| `canon:review-craft`         | When reviewing a change, for what to look for and how much evidence a finding needs                        |
-| `canon:systematic-debugging` | When a test fails or a bug surfaces, to force root cause first                                             |
-| `canon:design-taste`         | When drafting or judging an interface, or when output reads generic, to settle which decision comes first  |
-| `canon:ui-checklist`         | After a UI change, to write what to look at and name what ships untested                                   |
+| Skill                         | When to use                                                                                                |
+| ----------------------------- | ---------------------------------------------------------------------------------------------------------- |
+| `canon:session-worktree`      | At the plan-to-execute boundary, to get an isolated tree and branch, or to route a refused main-root write |
+| `canon:auto-ship`             | After plan approval, to chain implement, verify, review, draft PR                                          |
+| `canon:project-commands`      | When the project's own command needs running                                                               |
+| `canon:test-first`            | Before implementing a planned change, to run its test red, green, then refactor                            |
+| `canon:test-craft`            | When writing or changing any test, to pick its layer and filter what it asserts                            |
+| `canon:build-in-slices`       | While building a plan, to commit each tested slice and note out-of-scope defects rather than fix them      |
+| `canon:api-design`            | When changing what a caller sees, being an export, a flag, an output shape, or a retried write             |
+| `canon:deprecation-migration` | When deleting or replacing code something may still call, to migrate its callers and prove none remain     |
+| `canon:code-craft`            | Before writing a function, class, or module, to pick the shape the next change needs                       |
+| `canon:review-craft`          | When reviewing a change, for what to look for and how much evidence a finding needs                        |
+| `canon:systematic-debugging`  | When a test fails or a bug surfaces, to force root cause first                                             |
+| `canon:design-taste`          | When drafting or judging an interface, or when output reads generic, to settle which decision comes first  |
+| `canon:ui-checklist`          | After a UI change, to write what to look at and name what ships untested                                   |
 
 ## Check the work before it leaves the branch
 

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@erclx/canon",
   "type": "module",
-  "version": "5.13.0",
+  "version": "5.14.0",
   "description": "Runs your agent's work and keeps its code good, on one setup for every repo.",
   "license": "MIT",
   "bin": {

package/src/claude/cases/misc.ts

@@ -84,6 +84,11 @@ export const MISC_CASES: readonly SkillCase[] = [
       "I've got the plan approved and it touches the parser, the command, and the docs. How should I build it so I don't end up with one giant diff?",
     expect: 'build-in-slices',
   },
+  {
+    prompt:
+      'The old parseDate helper was replaced months ago. Can I just delete it, or could a few files still be calling it?',
+    expect: 'deprecation-migration',
+  },
   {
     prompt: 'Does our github about text still match what the readme says?',
     expect: 'repo-metadata',

package/src/claude/skills-audit.ts

@@ -39,6 +39,7 @@ export const PRACTICE_SKILLS: readonly string[] = [
   join(SHIPPED_CORPUS, 'api-design'),
   join(SHIPPED_CORPUS, 'code-craft'),
   join(SHIPPED_CORPUS, 'build-in-slices'),
+  join(SHIPPED_CORPUS, 'deprecation-migration'),
 ]
 
 /** The closing H2s a practice skill carries, matched exactly outside fences. */

package/src/commands/pr.ts

@@ -36,6 +36,19 @@ import {
   readOwed,
   renderEvidenceBody,
 } from '@/pr/evidence'
+import {
+  dropFrames,
+  FRAMES_BRANCH,
+  type FramesApi,
+  type FramesRefusal,
+  frameLink,
+  isFrameHead,
+  isFramePass,
+  pruneFrames,
+  pushFrame,
+  readFrame,
+  type TreeEntry,
+} from '@/pr/frames'
 import { type HeadRefusal, resolveHead, resolveTip } from '@/pr/head'
 import {
   findLocalServer,
@@ -116,6 +129,55 @@ const LOCAL_REFUSALS: Record<LocalRefusal | 'gh-failed', string> = {
     'gh could not read or edit the marked comment on this pull request.',
 }
 
+interface FramesOptions extends ReadOptions {
+  readonly add?: string
+  readonly box?: string
+  readonly head?: string
+  readonly pass?: string
+  readonly drop?: boolean
+  readonly prune?: string
+}
+
+type FramesCommandRefusal =
+  | FramesRefusal
+  | 'bad-mode'
+  | 'no-number'
+  | 'bad-box'
+  | 'bad-head'
+  | 'bad-pass'
+  | 'bad-days'
+  | 'unreadable-frame'
+  | 'read-only'
+  | 'gh-missing'
+  | 'gh-failed'
+  | 'no-object-head'
+
+const FRAMES_REFUSALS: Record<FramesCommandRefusal, string> = {
+  'bad-mode':
+    'Pass exactly one of --add, --drop, or --prune. --prune reads every pull request on the branch, so it takes no number.',
+  'no-number':
+    '--add and --drop write for one pull request, so name its number.',
+  'bad-box':
+    '--add takes --box <n>, a positive whole number naming the checklist box.',
+  'bad-head':
+    '--head takes a commit sha, 7 to 40 lowercase hex characters. A branch name or a path would file the frame under a folder that names no commit.',
+  'bad-pass':
+    '--add takes --pass <stamp>, the instant the pass started in compact UTC such as 20261002T154450Z, so a second pass never replaces an earlier one.',
+  'bad-days': '--prune takes a positive whole number of days.',
+  'unreadable-frame':
+    'The file named by --add is missing, empty, or not a PNG, so it would embed as a broken image. Nothing is pushed.',
+  'read-only': `GitHub refused the write to ${FRAMES_BRANCH}. The token cannot write this repository, which is what a fork pull request's workflow token gets, so describe the frame in words instead.`,
+  'gh-missing':
+    'gh is not on the path, so the branch could not be read or written.',
+  'gh-failed':
+    'gh could not answer for this repository or pull request, so no link could be built.',
+  'no-object-head':
+    'The pull request object reported no head commit and no --head was passed, so the frame has no head to file under.',
+  'unreadable-tip': `The ${FRAMES_BRANCH} branch could not be read, so nothing was written. A missing branch is not this, since an add creates it.`,
+  'push-failed': `A write to ${FRAMES_BRANCH} failed partway. The ref did not move, so the branch is as it was.`,
+  'ref-conflict': `Another writer kept moving ${FRAMES_BRANCH} through every attempt, so the add gave up. Re-run it.`,
+}
+
 interface PreviewOptions extends ReadOptions {
   readonly timeout?: string
   readonly check?: boolean
@@ -659,6 +721,82 @@ export function register(program: Command): void {
           ? await runLocalRemove(number, opts)
           : await runLocal(opts)
     })
+
+  pr.command('frames')
+    .description(
+      `Push a UI review frame to the never-merged ${FRAMES_BRANCH} branch and return its embed link, or drop frames from it`,
+    )
+    .argument(
+      '[number]',
+      'Pull request the frame belongs to, for --add and --drop',
+    )
+    .helpOption('-h, --help', 'Show this help message')
+    .option('--root <path>', 'Repository to answer for, defaulting to the cwd')
+    .option('--json', 'Add a machine-readable record on stdout')
+    .option('--add <file>', 'Push this PNG as a frame')
+    .option('--box <n>', 'The checklist box the frame shows, with --add')
+    .option(
+      '--head <sha>',
+      "The head the frame was driven at, with --add, defaulting to the pull request's",
+    )
+    .option(
+      '--pass <stamp>',
+      'The instant the pass started, in compact UTC such as 20261002T154450Z, with --add',
+    )
+    .option('--drop', "Rewrite the branch without this pull request's frames")
+    .option(
+      '--prune <days>',
+      'Drop the frames of every pull request closed more than this many days ago',
+    )
+    .addHelpText(
+      'after',
+      [
+        '',
+        `Writes only refs/heads/${FRAMES_BRANCH}, through the GitHub git data API,`,
+        'so nothing is checked out and no other branch is touched. A frame lands',
+        'at pr-<number>/<short-head>/<pass>/box-<n>.png, and `link` names that',
+        `path on ${FRAMES_BRANCH}, so it survives a rewrite that drops other pull`,
+        'requests and resolves until its own pull request is dropped. The pass',
+        'segment keeps a second pass at one head and box from replacing an image',
+        'an earlier comment shows. The first --add creates the branch.',
+        '',
+        '--drop and --prune write one root commit and force-move the ref,',
+        'since a delete commit would keep every image reachable through history.',
+        'A rewrite that empties the branch deletes it. --prune keeps a pull',
+        'request still open, reopened, closed exactly the given days ago, or one',
+        'whose state could not be read, listing that last kind under `unread`.',
+        '',
+        'Read `reason` on the JSON record:',
+        '  ok                an add pushed, or a drop or prune finished',
+        '  bad-mode          not exactly one of --add, --drop, --prune',
+        '  no-number         --add or --drop named no pull request',
+        '  bad-box           --add without a positive --box',
+        '  bad-head          --head is not 7 to 40 lowercase hex characters',
+        '  bad-pass          --add without a compact UTC --pass stamp',
+        '  bad-days          --prune without a positive number of days',
+        '  unreadable-frame  the --add file is missing, empty, or not a PNG',
+        '  read-only         GitHub refused the write, as on a fork token',
+        '  unreadable-tip    the branch could not be read',
+        '  push-failed       a write failed and the ref did not move',
+        '  ref-conflict      another writer kept moving the ref',
+        '  no-object-head    no head to file the frame under',
+        '  gh-missing        gh is not on the path',
+        '  gh-failed         gh could not answer for the repository',
+        '',
+        'Exit codes:',
+        '  0  pushed, or a drop or prune finished, including one removing nothing',
+        '  1  refused, with the reason on stderr or in the JSON record',
+        '',
+        'Examples:',
+        '  canon pr frames 1341 --add frames/3.png --box 3 --pass 20261002T154450Z --json',
+        '  canon pr frames 1341 --drop --json',
+        '  canon pr frames --prune 30 --json',
+        '',
+      ].join('\n'),
+    )
+    .action(async (number: string | undefined, opts: FramesOptions) => {
+      process.exitCode = await runFrames(number, opts)
+    })
 }
 
 interface PullRequestRead {
@@ -1743,6 +1881,7 @@ async function runEvidence(
         base,
         head: identity.head,
         body,
+        states,
         ...(commentId !== undefined && { commentId }),
         ...carried,
       })}\n`,
@@ -2198,6 +2337,319 @@ async function runLocalRemove(
   return finish('removed', `comment ${commentId}`)
 }
 
+const POSITIVE_WHOLE = /^[1-9]\d*$/
+
+/** One `gh api` call, keeping the HTTP status of a failure so a refused write can be told from a missing ref. */
+type ApiCall =
+  | { readonly ok: true; readonly data: unknown }
+  | { readonly ok: false; readonly status: number | undefined }
+
+type ApiCaller = (
+  method: string,
+  path: string,
+  body?: unknown,
+) => Promise<ApiCall>
+
+/**
+ * Runs `gh api` against the repository's own path, recording every write
+ * GitHub answered 403 or 404, which is how a token without write access
+ * reads, so a failed push can be reported as read-only rather than broken.
+ */
+function ghApiRunner(root: string): {
+  readonly call: ApiCaller
+  readonly refusedWrites: number[]
+} {
+  const refusedWrites: number[] = []
+  const call: ApiCaller = async (method, path, body) => {
+    const args = ['api', '-X', method, `repos/{owner}/{repo}/${path}`]
+    if (body !== undefined) args.push('--input', '-')
+    const result = await execa('gh', args, {
+      cwd: root,
+      timeout: GH_TIMEOUT_MS,
+      env: gitEnv(),
+      extendEnv: false,
+      reject: false,
+      ...(body !== undefined && { input: JSON.stringify(body) }),
+    })
+    if (result.exitCode !== 0) {
+      const status = /HTTP (\d{3})/.exec(String(result.stderr))?.[1]
+      const code = status === undefined ? undefined : Number(status)
+      if (method !== 'GET' && (code === 403 || code === 404)) {
+        refusedWrites.push(code)
+      }
+      return { ok: false, status: code }
+    }
+    const text = String(result.stdout).trim()
+    try {
+      return { ok: true, data: text === '' ? null : JSON.parse(text) }
+    } catch {
+      return { ok: false, status: undefined }
+    }
+  }
+  return { call, refusedWrites }
+}
+
+function shaOf(data: unknown): string | undefined {
+  if (typeof data !== 'object' || data === null || !('sha' in data)) {
+    return undefined
+  }
+  return typeof data.sha === 'string' ? data.sha : undefined
+}
+
+function isTreeEntry(value: unknown): value is TreeEntry {
+  if (typeof value !== 'object' || value === null) return false
+  const entry = value as Record<string, unknown>
+  return (
+    typeof entry.path === 'string' &&
+    typeof entry.mode === 'string' &&
+    (entry.type === 'blob' || entry.type === 'tree') &&
+    typeof entry.sha === 'string'
+  )
+}
+
+/**
+ * The git data API behind `canon pr frames`. A 422 on a ref write is GitHub
+ * refusing a move that is not a fast-forward, or a create or update on a ref
+ * that already exists or no longer does, which is another writer's doing and
+ * worth a re-read rather than a failure.
+ */
+function ghFramesApi(call: ApiCaller): FramesApi {
+  const ref = `git/refs/heads/${FRAMES_BRANCH}`
+  const refWrite = (result: ApiCall) =>
+    result.ok ? 'ok' : result.status === 422 ? 'conflict' : 'failed'
+  return {
+    async readTip() {
+      const head = await call('GET', `git/ref/heads/${FRAMES_BRANCH}`)
+      if (!head.ok) {
+        return head.status === 404
+          ? { kind: 'missing' }
+          : { kind: 'unreadable' }
+      }
+      const commit = (head.data as { object?: { sha?: unknown } } | null)
+        ?.object?.sha
+      if (typeof commit !== 'string') return { kind: 'unreadable' }
+      const read = await call('GET', `git/commits/${commit}`)
+      const tree = read.ok
+        ? (read.data as { tree?: { sha?: unknown } } | null)?.tree?.sha
+        : undefined
+      return typeof tree === 'string'
+        ? { kind: 'found', commit, tree }
+        : { kind: 'unreadable' }
+    },
+    async listTree(tree) {
+      const read = await call('GET', `git/trees/${tree}`)
+      if (!read.ok) return undefined
+      const entries = (read.data as { tree?: unknown } | null)?.tree
+      return Array.isArray(entries) && entries.every(isTreeEntry)
+        ? entries
+        : undefined
+    },
+    async createBlob(base64) {
+      const made = await call('POST', 'git/blobs', {
+        content: base64,
+        encoding: 'base64',
+      })
+      return made.ok ? shaOf(made.data) : undefined
+    },
+    async createTree(entries, base) {
+      const made = await call('POST', 'git/trees', {
+        tree: entries.map(({ path, mode, type, sha }) => ({
+          path,
+          mode,
+          type,
+          sha,
+        })),
+        ...(base !== undefined && { base_tree: base }),
+      })
+      return made.ok ? shaOf(made.data) : undefined
+    },
+    async createCommit(message, tree, parents) {
+      const made = await call('POST', 'git/commits', {
+        message,
+        tree,
+        parents,
+      })
+      return made.ok ? shaOf(made.data) : undefined
+    },
+    async createRef(commit) {
+      return refWrite(
+        await call('POST', 'git/refs', {
+          ref: `refs/heads/${FRAMES_BRANCH}`,
+          sha: commit,
+        }),
+      )
+    },
+    async moveRef(commit, force) {
+      return refWrite(await call('PATCH', ref, { sha: commit, force }))
+    },
+    async deleteRef() {
+      const gone = await call('DELETE', ref)
+      return gone.ok || gone.status === 422
+    },
+    async readPull(number) {
+      const read = await call('GET', `pulls/${number}`)
+      if (!read.ok) return undefined
+      const row = read.data as { state?: unknown; closed_at?: unknown } | null
+      if (row?.state !== 'open' && row?.state !== 'closed') return undefined
+      return {
+        state: row.state,
+        ...(typeof row.closed_at === 'string' && { closedAt: row.closed_at }),
+      }
+    },
+  }
+}
+
+/** Validates the mode and its arguments before anything reads the network. */
+function framesArgumentRefusal(
+  number: string | undefined,
+  opts: FramesOptions,
+): FramesCommandRefusal | undefined {
+  const modes = [
+    opts.add !== undefined,
+    opts.drop === true,
+    opts.prune !== undefined,
+  ]
+  if (modes.filter(Boolean).length !== 1) return 'bad-mode'
+  if (opts.prune !== undefined) {
+    if (number !== undefined) return 'bad-mode'
+    return POSITIVE_WHOLE.test(opts.prune) ? undefined : 'bad-days'
+  }
+  if (number === undefined || !POSITIVE_WHOLE.test(number)) return 'no-number'
+  if (
+    opts.add !== undefined &&
+    (opts.box === undefined || !POSITIVE_WHOLE.test(opts.box))
+  ) {
+    return 'bad-box'
+  }
+  if (opts.head !== undefined && !isFrameHead(opts.head)) return 'bad-head'
+  if (
+    opts.add !== undefined &&
+    (opts.pass === undefined || !isFramePass(opts.pass))
+  ) {
+    return 'bad-pass'
+  }
+  return undefined
+}
+
+async function readRepoName(root: string): Promise<string | undefined> {
+  const row = await gh(root, ['repo', 'view', '--json', 'nameWithOwner'])
+  if (row === null) return undefined
+  try {
+    const name = (JSON.parse(row) as { nameWithOwner?: unknown }).nameWithOwner
+    return typeof name === 'string' ? name : undefined
+  } catch {
+    return undefined
+  }
+}
+
+async function runFrames(
+  number: string | undefined,
+  opts: FramesOptions,
+): Promise<number> {
+  const root = resolve(opts.root ?? process.cwd())
+  const emitJson = opts.json ?? false
+  const refuseFrames = (reason: FramesCommandRefusal) =>
+    refuseWith(reason, FRAMES_REFUSALS[reason], emitJson, root)
+
+  intro('canon pr frames')
+
+  const invalid = framesArgumentRefusal(number, opts)
+  if (invalid !== undefined) return refuseFrames(invalid)
+
+  const bytes =
+    opts.add === undefined ? undefined : await readFrame(resolve(opts.add))
+  if (opts.add !== undefined && bytes === undefined) {
+    return refuseFrames('unreadable-frame')
+  }
+
+  if (Bun.which('gh') === null) return refuseFrames('gh-missing')
+  const runner = ghApiRunner(root)
+  const api = ghFramesApi(runner.call)
+  const refuseWrite = (reason: FramesRefusal) =>
+    refuseFrames(
+      reason === 'push-failed' && runner.refusedWrites.length > 0
+        ? 'read-only'
+        : reason,
+    )
+
+  const finish = (
+    record: Record<string, unknown>,
+    lines: readonly string[],
+  ): number => {
+    logStep('Frames')
+    for (const line of lines) logInfo(line)
+    outro()
+    if (emitJson) {
+      process.stdout.write(
+        `${JSON.stringify({ root, reason: 'ok', ...record })}\n`,
+      )
+    }
+    return 0
+  }
+
+  if (opts.prune !== undefined) {
+    const days = Number(opts.prune)
+    const result = await pruneFrames(api, days, new Date())
+    if (result.kind === 'refused') return refuseWrite(result.reason)
+    const { kind: _kind, ...rest } = result
+    return finish({ days, ...rest }, [
+      `removed ${plural(result.removed.length, 'pull request')}`,
+      ...(result.unread.length > 0
+        ? [`kept ${result.unread.map((n) => `#${n}`).join(', ')} unread`]
+        : []),
+    ])
+  }
+
+  const pull = Number(number)
+  if (opts.drop === true) {
+    const result = await dropFrames(api, [pull])
+    if (result.kind === 'refused') return refuseWrite(result.reason)
+    const { kind: _kind, ...rest } = result
+    return finish({ number: pull, ...rest }, [
+      result.removed.length === 0
+        ? `#${pull} holds no frames on ${FRAMES_BRANCH}`
+        : `dropped the frames of #${pull}`,
+    ])
+  }
+
+  const repo = await readRepoName(root)
+  if (repo === undefined) return refuseFrames('gh-failed')
+
+  let head = opts.head
+  if (head === undefined) {
+    const identity = await readIdentity(root, String(pull))
+    if (identity.kind === 'refused') return refuseFrames('gh-failed')
+    head = identity.identity.head
+  }
+  if (head === undefined || head === '') return refuseFrames('no-object-head')
+  if (!isFrameHead(head)) return refuseFrames('bad-head')
+
+  const box = Number(opts.box)
+  const pass = opts.pass ?? ''
+  const result = await pushFrame(api, {
+    number: pull,
+    head,
+    pass,
+    box,
+    bytes: bytes ?? new Uint8Array(),
+  })
+  if (result.kind === 'refused') return refuseWrite(result.reason)
+  const link = frameLink(repo, result.path)
+  return finish(
+    {
+      number: pull,
+      box,
+      head,
+      pass,
+      path: result.path,
+      commit: result.commit,
+      link,
+      created: result.created,
+    },
+    [link],
+  )
+}
+
 /**
  * Frames a refusal on stderr in both modes and puts the record on stdout alone,
  * so an operator reading the terminal sees the reason rather than a command