@erclx/canon 5.41.0 → 5.42.0

package/src/markdown/scope.ts

@@ -42,41 +42,113 @@ export const GATED_PATHS: readonly string[] = [
   'canon/context/context-model.md',
   'canon/context/index.md',
   'claude/skills/api-design/SKILL.md',
+  'claude/skills/api-design/references/adopted.md',
   'claude/skills/auto-ship/SKILL.md',
+  'claude/skills/auto-ship/references/draft-mark.md',
+  'claude/skills/auto-ship/references/failure-recovery.md',
+  'claude/skills/auto-ship/references/fan-in.md',
+  'claude/skills/auto-ship/references/tier-failures.md',
+  'claude/skills/auto-ship/references/ui-checklist.md',
+  'claude/skills/auto-ship/references/verb-absent.md',
+  'claude/skills/auto-ship/references/worktree-name.md',
   'claude/skills/backlog-triage/SKILL.md',
   'claude/skills/backlog-triage/references/apply.md',
   'claude/skills/build-in-slices/SKILL.md',
+  'claude/skills/build-in-slices/references/adopted.md',
   'claude/skills/canon-cli/SKILL.md',
   'claude/skills/canon-feedback-triage/SKILL.md',
   'claude/skills/canon-feedback/SKILL.md',
+  'claude/skills/canon-feedback/references/template.md',
   'claude/skills/canvas-board/SKILL.md',
+  'claude/skills/canvas-board/references/canvas.md',
+  'claude/skills/canvas-board/references/design.md',
   'claude/skills/ci-workflow/SKILL.md',
+  'claude/skills/ci-workflow/references/workflows.md',
   'claude/skills/code-craft/SKILL.md',
+  'claude/skills/code-craft/references/adopted.md',
   'claude/skills/codebase-layout/SKILL.md',
+  'claude/skills/codebase-layout/references/adopted.md',
+  'claude/skills/codebase-layout/references/frontend.md',
+  'claude/skills/codebase-layout/references/tests.md',
   'claude/skills/context-fold/SKILL.md',
+  'claude/skills/context-fold/references/classify.md',
+  'claude/skills/context-fold/references/completion-report.md',
+  'claude/skills/context-fold/references/context-refresh.md',
+  'claude/skills/context-fold/references/context.md',
+  'claude/skills/context-fold/references/unusable-baseline.md',
   'claude/skills/create-rule/SKILL.md',
+  'claude/skills/create-rule/references/rule.md',
   'claude/skills/create-skill/SKILL.md',
+  'claude/skills/create-skill/references/skill-disclosure.md',
+  'claude/skills/create-skill/references/skill-frontmatter.md',
+  'claude/skills/create-skill/references/skill-paths.md',
+  'claude/skills/create-skill/references/skill-practice.md',
+  'claude/skills/create-skill/references/skill-reference.md',
+  'claude/skills/create-skill/references/skill-requirement.md',
+  'claude/skills/create-skill/references/skill.md',
   'claude/skills/decision-escalate/SKILL.md',
   'claude/skills/deploy-app/SKILL.md',
+  'claude/skills/deploy-app/references/cloudflare.md',
+  'claude/skills/deploy-app/references/vercel.md',
   'claude/skills/deprecation-migration/SKILL.md',
+  'claude/skills/deprecation-migration/references/adopted.md',
   'claude/skills/design-taste/SKILL.md',
+  'claude/skills/design-taste/references/adopted.md',
+  'claude/skills/design-taste/references/craft.md',
+  'claude/skills/design-taste/references/kinds.md',
+  'claude/skills/design-taste/references/preflight.md',
+  'claude/skills/design-taste/references/systems.md',
+  'claude/skills/design-taste/references/tells.md',
+  'claude/skills/design-taste/references/vocabulary.md',
   'claude/skills/docs-sync/SKILL.md',
+  'claude/skills/docs-sync/references/docs.md',
+  'claude/skills/docs-sync/references/readme.md',
   'claude/skills/document-health/SKILL.md',
+  'claude/skills/document-health/references/axes.md',
   'claude/skills/draft-and-pick/SKILL.md',
+  'claude/skills/draft-and-pick/references/live-arms.md',
   'claude/skills/draft-doc/SKILL.md',
+  'claude/skills/draft-doc/references/context.md',
+  'claude/skills/draft-doc/references/docs.md',
+  'claude/skills/draft-doc/references/readme.md',
+  'claude/skills/draft-doc/references/readme/agent-facing.md',
+  'claude/skills/draft-doc/references/readme/application.md',
+  'claude/skills/draft-doc/references/readme/cli.md',
+  'claude/skills/draft-doc/references/readme/library.md',
+  'claude/skills/draft-doc/references/readme/plugin.md',
+  'claude/skills/draft-doc/references/requirements.md',
+  'claude/skills/draft-doc/references/wiki-kind.md',
+  'claude/skills/draft-doc/references/wiki.md',
   'claude/skills/draft-figure/SKILL.md',
+  'claude/skills/draft-figure/references/architecture-set.md',
+  'claude/skills/draft-figure/references/figures.md',
+  'claude/skills/draft-figure/references/hand-drawn.md',
+  'claude/skills/draft-figure/references/mermaid-path.md',
+  'claude/skills/draft-figure/references/mermaid.md',
   'claude/skills/draft-identity/SKILL.md',
   'claude/skills/draft-identity/references/card-route.md',
   'claude/skills/draft-ready/SKILL.md',
+  'claude/skills/draft-ready/references/assembly.md',
+  'claude/skills/draft-ready/references/ready.md',
   'claude/skills/draft-screencast/SKILL.md',
   'claude/skills/draft-screencast/references/beats-template.md',
   'claude/skills/draft-slides/SKILL.md',
   'claude/skills/draft-slides/references/deck.md',
   'claude/skills/git-branch/SKILL.md',
+  'claude/skills/git-branch/references/branch.md',
+  'claude/skills/git-branch/references/slug.md',
   'claude/skills/git-commit/SKILL.md',
+  'claude/skills/git-commit/references/commit.md',
+  'claude/skills/git-commit/references/versioning.md',
   'claude/skills/git-followup/SKILL.md',
   'claude/skills/git-issue/SKILL.md',
+  'claude/skills/git-issue/references/issue.md',
   'claude/skills/git-pr/SKILL.md',
+  'claude/skills/git-pr/references/final-command.md',
+  'claude/skills/git-pr/references/labels.md',
+  'claude/skills/git-pr/references/pr.md',
+  'claude/skills/git-pr/references/publish.md',
+  'claude/skills/git-pr/references/task-number.md',
   'claude/skills/git-ship/SKILL.md',
   'claude/skills/git-ship/references/ci-watch.md',
   'claude/skills/git-split/SKILL.md',
@@ -86,45 +158,117 @@ export const GATED_PATHS: readonly string[] = [
   'claude/skills/git-worktree/SKILL.md',
   'claude/skills/git-worktree/references/cleanup.md',
   'claude/skills/markdown-craft/SKILL.md',
+  'claude/skills/markdown-craft/references/markdown.md',
   'claude/skills/plan-feature/SKILL.md',
   'claude/skills/plan-feature/references/batches.md',
+  'claude/skills/plan-feature/references/plan-lifecycle.md',
+  'claude/skills/plan-feature/references/plan.md',
   'claude/skills/plan-groundwork/SKILL.md',
+  'claude/skills/plan-groundwork/references/groundwork-spikes.md',
+  'claude/skills/plan-groundwork/references/groundwork.md',
   'claude/skills/plan-groundwork/references/output.md',
   'claude/skills/plan-intake-answer/SKILL.md',
   'claude/skills/plan-intake/SKILL.md',
+  'claude/skills/plan-intake/references/intake.md',
+  'claude/skills/pr-evidence/SKILL.md',
+  'claude/skills/pr-evidence/references/evidence.md',
   'claude/skills/read-frames/SKILL.md',
   'claude/skills/record-screencast/SKILL.md',
   'claude/skills/review-address/SKILL.md',
+  'claude/skills/review-address/references/post-review-findings.md',
+  'claude/skills/review-address/references/rebase-conflicts.md',
   'claude/skills/review-address/references/rebase-only.md',
+  'claude/skills/review-address/references/rest-reads.md',
   'claude/skills/review-craft/SKILL.md',
+  'claude/skills/review-craft/references/adopted.md',
+  'claude/skills/review-craft/references/security.md',
+  'claude/skills/review-craft/references/ui.md',
   'claude/skills/review-pr/SKILL.md',
+  'claude/skills/review-pr/references/body-variants.md',
+  'claude/skills/review-pr/references/close-out.md',
+  'claude/skills/review-pr/references/key-changes.md',
+  'claude/skills/review-pr/references/post.md',
+  'claude/skills/review-pr/references/scope.md',
   'claude/skills/review-ui/SKILL.md',
+  'claude/skills/review-ui/references/close-out.md',
+  'claude/skills/review-ui/references/driving.md',
   'claude/skills/review-ui/references/hosted-preview.md',
+  'claude/skills/review-ui/references/post.md',
+  'claude/skills/review-ui/references/tick.md',
   'claude/skills/role-orchestrator/SKILL.md',
+  'claude/skills/role-orchestrator/references/orchestrator-cloud-launch.md',
+  'claude/skills/role-orchestrator/references/orchestrator-dispatch.md',
   'claude/skills/role-orchestrator/references/orchestrator-filing.md',
+  'claude/skills/role-orchestrator/references/orchestrator-handback.md',
+  'claude/skills/role-orchestrator/references/orchestrator-handoff.md',
+  'claude/skills/role-orchestrator/references/orchestrator-inbound.md',
+  'claude/skills/role-orchestrator/references/orchestrator-launch.md',
+  'claude/skills/role-orchestrator/references/orchestrator-output.md',
+  'claude/skills/role-orchestrator/references/orchestrator-parked.md',
+  'claude/skills/role-orchestrator/references/orchestrator-poll.md',
+  'claude/skills/role-orchestrator/references/orchestrator-refill.md',
+  'claude/skills/role-orchestrator/references/orchestrator-resume.md',
+  'claude/skills/role-orchestrator/references/orchestrator-review-dispatch.md',
+  'claude/skills/role-orchestrator/references/orchestrator-reviewer-launch.md',
+  'claude/skills/role-orchestrator/references/orchestrator-sweep.md',
+  'claude/skills/role-orchestrator/references/orchestrator-watch.md',
   'claude/skills/role-planner/SKILL.md',
   'claude/skills/role-reviewer/SKILL.md',
   'claude/skills/role-worker/SKILL.md',
   'claude/skills/search-craft/SKILL.md',
+  'claude/skills/search-craft/references/adopted.md',
   'claude/skills/session-compact/SKILL.md',
+  'claude/skills/session-compact/references/handoff-note.md',
   'claude/skills/session-map/SKILL.md',
+  'claude/skills/session-map/references/session.md',
   'claude/skills/session-relay/SKILL.md',
   'claude/skills/session-resume/SKILL.md',
   'claude/skills/session-worktree/SKILL.md',
+  'claude/skills/session-worktree/references/install-command.md',
+  'claude/skills/session-worktree/references/main-root-writes.md',
   'claude/skills/systematic-debugging/SKILL.md',
+  'claude/skills/systematic-debugging/references/adopted.md',
   'claude/skills/target-check/SKILL.md',
+  'claude/skills/target-check/references/domains.md',
   'claude/skills/target-setup/SKILL.md',
+  'claude/skills/target-setup/references/detect.md',
+  'claude/skills/target-setup/references/indexes.md',
+  'claude/skills/target-setup/references/verify.md',
   'claude/skills/task-board/SKILL.md',
+  'claude/skills/task-board/references/board.md',
   'claude/skills/task-board/references/create-report.md',
+  'claude/skills/task-board/references/decline.md',
+  'claude/skills/task-board/references/tasks-decline.md',
+  'claude/skills/task-board/references/tasks.md',
   'claude/skills/task-complete/SKILL.md',
+  'claude/skills/task-complete/references/archive.md',
+  'claude/skills/task-complete/references/receipt-sweep.md',
+  'claude/skills/task-complete/references/unusable-baseline.md',
   'claude/skills/teach-workspace/SKILL.md',
+  'claude/skills/teach-workspace/references/glossary.md',
+  'claude/skills/teach-workspace/references/lesson-build.md',
+  'claude/skills/teach-workspace/references/lesson-craft.md',
+  'claude/skills/teach-workspace/references/pedagogy.md',
+  'claude/skills/teach-workspace/references/promotion-fold.md',
+  'claude/skills/teach-workspace/references/promotion.md',
+  'claude/skills/teach-workspace/references/revisit.md',
+  'claude/skills/teach-workspace/references/teach.md',
   'claude/skills/test-craft/SKILL.md',
+  'claude/skills/test-craft/references/adopted.md',
+  'claude/skills/test-craft/references/component.md',
+  'claude/skills/test-craft/references/e2e.md',
+  'claude/skills/test-craft/references/unit.md',
   'claude/skills/test-first/SKILL.md',
+  'claude/skills/test-first/references/adopted.md',
   'claude/skills/ui-checklist/SKILL.md',
   'claude/skills/ux-audit/SKILL.md',
   'claude/skills/ux-measure/SKILL.md',
   'claude/skills/video-craft/SKILL.md',
+  'claude/skills/video-craft/references/adopted.md',
   'claude/skills/write-human/SKILL.md',
+  'claude/skills/write-human/references/adopted.md',
+  'claude/skills/write-human/references/density.md',
+  'claude/skills/write-human/references/machine-tells.md',
   'claude/skills/youtube-transcripts/SKILL.md',
   '.claude/skills/internal-',
   'docs/',

package/src/pr/lift.ts

@@ -144,7 +144,10 @@ function fail(gate: GateName, reason: LiftRefusal): GateResult {
  * since the commit it covers is a stamp GitHub wrote at submission, which the
  * marker exists to replace.
  */
-function reviewGate(reviews: readonly ReviewRow[], head: string): GateResult {
+export function reviewGate(
+  reviews: readonly ReviewRow[],
+  head: string,
+): GateResult {
   const scope = resolveReviewScope({ reviews })
   if (scope.state === 'none') return fail('review', 'review-missing')
   if (scope.state === 'open') return fail('review', 'review-open')
@@ -175,8 +178,8 @@ function carried(gates: readonly GateResult[]): {
  * checklist the reviewer drove as true as it was. A close that is not an
  * ancestor, which a force-push or a rebase leaves, never carries.
  */
-async function uiGate(
-  api: LiftApi,
+export async function uiGate(
+  api: Pick<LiftApi, 'readChanged'>,
   painted: PaintedPatterns,
   reviews: readonly ReviewRow[],
   head: string,

package/src/pr/review-state.ts

@@ -0,0 +1,182 @@
+import {
+  CHECKS_POLL_MS,
+  type GateResult,
+  type LiftApi,
+  type LiftRefusal,
+  reviewGate,
+  uiGate,
+} from '@/pr/lift'
+import { DEFAULT_PAINTED, type PaintedPatterns } from '@/pr/painted'
+import {
+  coversHead,
+  type ReviewRow,
+  type ReviewScope,
+  resolveReviewScope,
+  resolveUiScope,
+  type UiScope,
+} from '@/pr/review-scope'
+
+/**
+ * The reads the verb makes, a subset of the lift's so a worker waiting here and
+ * a reviewer lifting read one answer. A read that failed returns undefined, and
+ * the verb refuses `gh-failed` rather than reading absence as no pass.
+ */
+export type ReviewStateApi = Pick<
+  LiftApi,
+  'readReviews' | 'readEvidence' | 'readChanged' | 'sleep' | 'now'
+> & {
+  /** The branch tip from the remote, which is what a pass has to cover. */
+  readTip(): Promise<string | undefined>
+}
+
+/** One family's standing at the tip. */
+export interface FamilyState {
+  /** The lift's refusal for this family, absent when its gate passes. */
+  readonly reason?: LiftRefusal
+  /**
+   * Whether a pass covers the tip, which is what a waiting worker reads. True
+   * when the gate passes, or when the newest pass, open or unmarked, names the
+   * tip. The reason alone cannot answer it, since the lift reads an open pass
+   * before it reads currency.
+   */
+  readonly isCovered: boolean
+}
+
+export interface UiState extends UiScope, FamilyState {
+  /** Whether the evidence comment carries a checklist, which binds the family. */
+  readonly isBound: boolean
+  readonly carriedFrom?: string
+  readonly paintedPaths?: readonly string[]
+}
+
+export interface ReviewStateRecord {
+  readonly head: string
+  readonly scope: ReviewScope
+  readonly review: FamilyState
+  readonly ui: UiState
+}
+
+export type ReviewStateRead =
+  | { readonly kind: 'read'; readonly record: ReviewStateRecord }
+  | { readonly kind: 'refused'; readonly reason: 'gh-failed' }
+
+export type ReviewWait =
+  | {
+      readonly kind: 'read'
+      readonly reason: 'covered' | 'timeout'
+      readonly record: ReviewStateRecord
+      readonly waitedSeconds: number
+    }
+  | {
+      readonly kind: 'refused'
+      readonly reason: 'gh-failed'
+      readonly waitedSeconds: number
+    }
+
+export interface WaitOptions {
+  readonly waitSeconds: number
+  readonly pollMs?: number
+  readonly painted?: PaintedPatterns
+}
+
+function familyOf(gate: GateResult, commit: string | undefined, tip: string) {
+  return {
+    ...(gate.reason !== undefined && { reason: gate.reason }),
+    isCovered: gate.isOk || (commit !== undefined && coversHead(commit, tip)),
+  }
+}
+
+/**
+ * Both families at the tip through the lift's own gates, so a worker and the
+ * lift never disagree on a reason. The evidence is read by the caller, since a
+ * wait reads it once rather than once per poll.
+ */
+async function readAt(
+  api: ReviewStateApi,
+  hasChecklist: boolean,
+  painted: PaintedPatterns,
+): Promise<ReviewStateRead> {
+  const [tip, reviews] = await Promise.all([api.readTip(), api.readReviews()])
+  if (tip === undefined || reviews === undefined) {
+    return { kind: 'refused', reason: 'gh-failed' }
+  }
+
+  const listing: { reviews: readonly ReviewRow[] } = { reviews }
+  const scope = resolveReviewScope(listing)
+  const uiScope = resolveUiScope(listing)
+  const ui = await uiGate(api, painted, reviews, tip, hasChecklist)
+  if (ui.reason === 'gh-failed') return { kind: 'refused', reason: 'gh-failed' }
+
+  return {
+    kind: 'read',
+    record: {
+      head: tip,
+      scope,
+      review: familyOf(reviewGate(reviews, tip), scope.commit, tip),
+      ui: {
+        ...uiScope,
+        ...familyOf(ui, uiScope.commit, tip),
+        isBound: hasChecklist,
+        ...(ui.carriedFrom !== undefined && { carriedFrom: ui.carriedFrom }),
+        ...(ui.paintedPaths !== undefined && { paintedPaths: ui.paintedPaths }),
+      },
+    },
+  }
+}
+
+export async function readReviewState(
+  api: ReviewStateApi,
+  painted: PaintedPatterns = DEFAULT_PAINTED,
+): Promise<ReviewStateRead> {
+  const evidence = await api.readEvidence()
+  if (evidence === undefined) return { kind: 'refused', reason: 'gh-failed' }
+  return readAt(api, evidence.hasChecklist, painted)
+}
+
+/**
+ * Holds until every bound family has a pass covering the tip, or the deadline
+ * passes. The tip is read again every poll, so a push during the wait moves
+ * what a pass has to cover. The evidence is read once, since a checklist
+ * appearing mid-wait is a ship-chain write the waiting worker made before it
+ * started.
+ */
+export async function waitForReviews(
+  api: ReviewStateApi,
+  opts: WaitOptions,
+): Promise<ReviewWait> {
+  const pollMs = opts.pollMs ?? CHECKS_POLL_MS
+  const painted = opts.painted ?? DEFAULT_PAINTED
+  const started = api.now()
+  const deadline = started + opts.waitSeconds * 1000
+  const waited = () => Math.round((api.now() - started) / 1000)
+
+  const evidence = await api.readEvidence()
+  if (evidence === undefined) {
+    return { kind: 'refused', reason: 'gh-failed', waitedSeconds: waited() }
+  }
+
+  for (;;) {
+    const read = await readAt(api, evidence.hasChecklist, painted)
+    if (read.kind === 'refused') {
+      return { ...read, waitedSeconds: waited() }
+    }
+    const { record } = read
+    if (record.review.isCovered && record.ui.isCovered) {
+      return {
+        kind: 'read',
+        reason: 'covered',
+        record,
+        waitedSeconds: waited(),
+      }
+    }
+    if (api.now() + pollMs > deadline) {
+      return {
+        kind: 'read',
+        reason: 'timeout',
+        record,
+        waitedSeconds: waited(),
+      }
+    }
+    await api.sleep(pollMs)
+  }
+}

package/claude/skills/git-pr/references/evidence.md

@@ -1,124 +0,0 @@
----
-title: Rendered-surface evidence
-description: How git-pr finds the UI checklist and the local server, posts the evidence comparison or the checklist alone as the fallback for a git refusal, and adds the preview address, for a change that touches a rendered surface
----
-
-# Rendered-surface evidence
-
-The rendered-surface step of `git-pr`, reached after the final command printed the pull request number. The step runs on every pull request, with no test on the diff ahead of it. `no-evidence` is the silent branch, so a pull request that changes no rendered surface posts nothing.
-
-## Contents
-
-- [Find the UI checklist](#find-the-ui-checklist)
-- [Find the local server](#find-the-local-server)
-- [Post the evidence comparison](#post-the-evidence-comparison)
-- [Post the UI checklist alone](#post-the-ui-checklist-alone)
-- [Post the preview address](#post-the-preview-address)
-
-## Find the UI checklist
-
-`ui-checklist` writes a visual checklist to `.canon/tmp/handoff/ui-checklist/<slug>.md` at the main worktree root when a change needs visual verification, with `<slug>` derived per `${CLAUDE_SKILL_DIR}/../git-branch/references/slug.md`. This skill is the file's sole consumer. Resolve the main root the way `session-worktree` does (`git worktree list --porcelain | grep -m 1 '^worktree ' | cut -d' ' -f2-`, falling back to `pwd`) and check for the file there. A missing file means no checklist was produced, and the two steps below each skip their checklist half.
-
-When it exists, scan it against `${CLAUDE_SKILL_DIR}/references/publish.md` before either step posts it, the same as the pull request body in the skill's pre-publish scan.
-
-Where it lands is decided by the evidence step below rather than here, since a checklist reads next to the screenshots it annotates and posting it on its own is the fallback for a refused render.
-
-## Find the local server
-
-A reviewer on the operator's machine can open the branch's running dev server, which screenshots and a checklist cannot stand in for. Ask the verb for the server this worktree is running before the evidence step, so the first evidence comment already carries the link:
-
-```bash
-canon pr local --json
-```
-
-The verb reads the listening sockets on this machine, keeps those whose process runs inside this worktree, and reports the lowest port serving an HTML page. A server in another worktree or in the main checkout is never reported, since it shows a different branch. `canon pr local --help` states the contract. Read `reason` on the record rather than the exit code.
-
-- `ok`: hold the record's `url` for the evidence step below.
-- `no-server` or `no-listener-reader`: hold the reason for the closing report, pass no link, and move on. Do not start a server here, since one started inside the ship chain has no owner to stop it.
-- Anything else, including no record at all: move on silently. An installed binary older than the verb answers with an unknown-subcommand error, which is a skip rather than a stop.
-
-Pass `--local` to the evidence step only on an `ok` here. The binary answering `ok` is the one carrying the flag, so a binary lacking the verb never meets a flag it would reject.
-
-With a checklist, a diff carrying no evidence image still renders `ok`, and a local link rides in the same comment on the address line under `## Evidence`, above the checklist, so a reviewer gets both in one place. A local link with neither an evidence image nor a checklist still reports `no-evidence`, which keeps a branch that changed no rendered surface from getting a comment holding a link and nothing else.
-
-A seeded workflow drops the whole address line once the pull request closes, hosted and local segments together and with no note in their place, so neither link outlives the branch it points at.
-
-## Post the evidence comparison
-
-Run the verb once against the number the skill's final command printed. Pass `--checklist` when the checklist step found a file, and `--local` when the step above returned `ok`. Leave each flag off otherwise:
-
-```bash
-canon pr evidence <number> --checklist <main-root>/.canon/tmp/handoff/ui-checklist/<slug>.md --local <url> --json
-```
-
-One call answers both questions because a checklist decides `no-evidence`. The verb renders `ok` on a diff carrying a checklist and no evidence image, with a marked body holding the checklist, so the checklist always lands in the one comment a later call finds and edits. Without a checklist, a diff carrying no evidence image reports `no-evidence`.
-
-Pass `--checklist` only for a file that exists. The verb refuses as `unreadable-checklist` on a path it cannot read or one holding nothing, which is a caller bug rather than a transient failure, so stop and repair the path rather than posting a body with the checklist silently dropped.
-
-Read `reason` on the record rather than the exit code.
-
-- `no-evidence`: nothing changed under an `evidence/` segment and no checklist was passed, so no body was rendered. Say nothing about the evidence and move on.
-- `ok`: write `body` to `.canon/tmp/pr/evidence/body-<number>.md` at the main worktree root (resolved the way `session-worktree` does), then post or update the comment:
-
-```bash
-gh api -X POST repos/{owner}/{repo}/issues/<number>/comments -F body=@<main-root>/.canon/tmp/pr/evidence/body-<number>.md --silent
-```
-
-Both posts in this file go through the REST issue-comments endpoint, since the `gh pr` subcommands run on GraphQL and a cloud session's GitHub proxy refuses it. `git-followup` mints a preview through this file, so a GraphQL post here would break the cloud review-address leg.
-
-When the record carries a `commentId`, edit that comment in place instead of posting a second one, reading the body field from the tmp file with `@`, which needs the typed-field flag `-F` because the raw-string flag `-f` posts the path itself as the body:
-
-```bash
-gh api -X PATCH repos/{owner}/{repo}/issues/comments/<commentId> -F body=@<main-root>/.canon/tmp/pr/evidence/body-<number>.md
-```
-
-Delete the handoff file once that call reports success, per the cleanup below, since the checklist now lives on the pull request. Clean up the tmp body file the same way.
-
-Any other `reason` is one of the mirrored git refusals (`gh-missing`, `gh-failed`, `no-base`, `unreadable-changes`, `would-empty`). Report it and move on without stopping the chain: a branch that carries no evidence images most of the time should not fail here on a transient git or `gh` read. Fall through to the checklist step, which posts the checklist alone rather than losing it to a transient read.
-
-## Post the UI checklist alone
-
-Run this step only as the fallback, when the evidence step above reported one of the git refusals and a checklist file exists, since every other branch with a checklist rendered `ok` and carried it. The comment this posts carries no marker, so a later `canon pr evidence` call reports no `checklist` for it. Post it as its own comment on `<number>`:
-
-```bash
-gh api -X POST repos/{owner}/{repo}/issues/<number>/comments -F body=@<main-root>/.canon/tmp/handoff/ui-checklist/<slug>.md --silent
-```
-
-Run the cleanup below only once the call that carried the checklist reports success, whichever of the two steps that was. On a failure, stop and leave the file in place: a retry needs the checklist to still be there, and deleting it on a failed post loses the only copy with nothing landed on the pull request.
-
-The cleanup is a main-root delete, so it goes out as a plain `rm` and then a plain `rmdir`, the file and then the folder, routed the way `session-worktree` states:
-
-```bash
-rm <main-root>/.canon/tmp/handoff/ui-checklist/<slug>.md
-```
-
-```bash
-rmdir <main-root>/.canon/tmp/handoff/ui-checklist 2>/dev/null || true
-```
-
-The `rmdir` is a no-op when another branch's pending checklist still sits in the folder, which keeps this step from deleting a handoff that is not its own.
-
-Deleting the file is what makes the later re-render safe. `git-followup` re-runs `canon pr evidence` with no `--checklist`, and the verb carries the checklist forward out of the comment it is editing, so the checklist survives the push. A tick survives a render at the head its stamp names and is cleared by one at a newer head, which leaves the next UI pass to earn it again.
-
-## Post the preview address
-
-Run this step when the evidence step above returned `ok`, a checklist was posted by the fallback, or `canon pr evidence <number> --check --json` lists `preview` in `owed`. The first two mean the pull request changes a rendered surface, and a reviewer holding a checklist with no screenshots needs the live page most. The third is how `git-ship` reaches this step alone when an earlier run's deploy timed out, so no evidence step ran in the current one. Otherwise skip it silently.
-
-The evidence comment is already posted, so the reviewer has the screenshots while the deploy runs. Mint the preview against the same `<number>`:
-
-```bash
-canon pr preview <number> --json
-```
-
-The verb dispatches the project's Pages deploy on the pull request's branch and waits on the run for up to 15 minutes. It refuses before dispatching anything when the deploy command passes no `--branch`, since that deploy would publish the branch to production, and when the workflow's own push path filter matches no path the pull request changed, since a dispatch ignores that filter and the site it published would show none of the change. `canon pr preview --help` states the contract. Read `reason` on the record rather than the exit code.
-
-- `ok`: re-render the evidence body with the address on the line under `## Evidence`, then post or update it exactly as the evidence step does, through the same tmp file and the `commentId` the record carries:
-
-```bash
-canon pr evidence <number> --preview <url> --json
-```
-
-The hosted address opens the address line and a local link already on the comment follows it on the same line, carried forward with no flag.
-
-- `no-deploy` or `unserved`: the project deploys nothing a dispatch can start, or nothing this branch changed is something its site builds from. Say nothing and move on.
-- Any other `reason`, being `unfenced`, `no-alias`, `run-failed`, `timeout`, or a mirrored `gh` refusal: report it with the record's `message` and move on without stopping the chain. A missing link costs the reviewer a click, and a held ship costs the whole chain.