@erclx/canon 5.40.0 → 5.42.0

package/src/commands/records.ts

@@ -44,6 +44,7 @@ import {
   plural,
 } from '@/cli/ui'
 import { currentWorktreeRoot, mainWorktreeRoot } from '@/git/worktree'
+import { fanInFindings } from '@/tasks/fan-in'
 import { readLivePlans, stackFindings } from '@/tasks/stack'
 
 /** Returned when a record carries a finding, which is the gating result. */
@@ -742,7 +743,7 @@ async function runValidate(
 }
 
 /**
- * Appends the one plans finding that reads across files. It sits in the command
+ * Appends the plans findings that read across files. They sit in the command
  * layer because `src/records/` sits below `src/tasks/`.
  */
 async function validateWithStacks(
@@ -752,9 +753,16 @@ async function validateWithStacks(
   const outcome = await validateRecords(root, kind)
   if (!outcome.ok || kind !== 'plans') return outcome
 
-  const stacked = stackFindings(await readLivePlans(root))
+  const live = await readLivePlans(root)
 
-  return { ...outcome, findings: [...outcome.findings, ...stacked] }
+  return {
+    ...outcome,
+    findings: [
+      ...outcome.findings,
+      ...stackFindings(live),
+      ...fanInFindings(live),
+    ],
+  }
 }
 
 function report(

package/src/context/shape-gated.ts

@@ -19,6 +19,7 @@ export const SHAPE_GATED_FOLDERS: readonly string[] = [
   'canon/context/features/',
   'canon/context/surfaces/',
   'canon/context/workflow/',
+  'tooling/base/seeds/',
 ]
 
 /** Whether a repository-relative entry path sits under a gated prefix. */

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,48 +158,124 @@ 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/',
+  'tooling/',
+  'wiki/',
+  'README.md',
+  'CONTRIBUTING.md',
 ]
 
 /**
@@ -136,8 +284,8 @@ export const GATED_PATHS: readonly string[] = [
  * entries, the docs pages, and the skill bodies and references through a stage
  * of its own before this measure existed, and waiting on `GATED_PATHS` would
  * reopen that hole. The seeds, the stack references, the wiki, and the root
- * guides were never held to it, and seven runs in the stack references would
- * fail the push on the day this lands, so those wait for their batch.
+ * guides were never held to it, so they joined `GATED_PATHS` only once their
+ * rewrite brought them to zero.
  */
 const ALWAYS_GATED: readonly DensityKind[] = ['bullet-run']
 

package/src/pr/frames.ts

@@ -19,6 +19,9 @@ const PASS_PATTERN = /^\d{8}T\d{6}Z$/
 /** How many times an add rebuilds on a tip another writer moved. */
 const ADD_ATTEMPTS = 3
 
+/** One half of a reference address. It opens on a letter or digit and holds no separator, so `..` and `/` cannot survive it. */
+const REFERENCE_PART = /^[A-Za-z0-9][A-Za-z0-9._-]*$/
+
 const FOLDER_PATTERN = /^pr-(\d+)$/
 
 const DAY_MS = 86_400_000
@@ -77,7 +80,8 @@ export interface FrameInput {
   readonly number: number
   readonly head: string
   readonly pass: string
-  readonly box: number
+  readonly box?: number
+  readonly reference?: string
   readonly theme?: FrameTheme
   readonly bytes: Uint8Array
 }
@@ -158,6 +162,39 @@ export function frameLink(repo: string, path: string): string {
   return `https://github.com/${repo}/blob/${FRAMES_BRANCH}/${path}?raw=true`
 }
 
+/**
+ * The file-name slug of a `<page>/<frame>` address, or undefined when the
+ * address would not round-trip. Each half must open on a letter or digit and
+ * hold only letters, digits, dots, underscores, and dashes, and neither may
+ * carry `--`, so the joined slug reads back as the same two names and a path
+ * never gains a directory or escapes the pass folder.
+ */
+export function referenceSlug(address: string): string | undefined {
+  const parts = address.split('/')
+  if (parts.length !== 2) return undefined
+  const [page, frame] = parts as [string, string]
+  const valid = [page, frame].every(
+    (part) => REFERENCE_PART.test(part) && !part.includes('--'),
+  )
+  return valid ? `${page}--${frame}` : undefined
+}
+
+/**
+ * Where a design reference capture lands, beside the evidence frames of one
+ * pass. The slug repeats for one reference, so a second capture in a pass
+ * overwrites only itself. Undefined when the address has no valid slug.
+ */
+export function referencePath(
+  number: number,
+  head: string,
+  pass: string,
+  address: string,
+): string | undefined {
+  const slug = referenceSlug(address)
+  if (slug === undefined) return undefined
+  return `pr-${number}/${head.slice(0, SHORT_HEAD_LENGTH)}/${pass}/ref-${slug}.png`
+}
+
 /** The frame's bytes, or undefined when the file is absent, empty, or not a PNG. */
 export async function readFrame(path: string): Promise<Uint8Array | undefined> {
   const bytes = await readFile(path).catch(() => undefined)
@@ -179,17 +216,24 @@ export async function pushFrame(
   api: FramesApi,
   input: FrameInput,
 ): Promise<PushResult> {
-  const path = framePath(
-    input.number,
-    input.head,
-    input.pass,
-    input.box,
-    input.theme,
-  )
+  const path =
+    input.reference === undefined
+      ? framePath(
+          input.number,
+          input.head,
+          input.pass,
+          input.box ?? 0,
+          input.theme,
+        )
+      : referencePath(input.number, input.head, input.pass, input.reference)
+  if (path === undefined) return { kind: 'refused', reason: 'push-failed' }
   const blob = await api.createBlob(Buffer.from(input.bytes).toString('base64'))
   if (blob === undefined) return { kind: 'refused', reason: 'push-failed' }
   const entry: TreeEntry = { path, mode: '100644', type: 'blob', sha: blob }
-  const message = `chore(frames): add box ${input.box} of #${input.number}`
+  const message =
+    input.reference === undefined
+      ? `chore(frames): add box ${input.box} of #${input.number}`
+      : `chore(frames): add reference ${input.reference} of #${input.number}`
 
   for (let attempt = 0; attempt < ADD_ATTEMPTS; attempt += 1) {
     const tip = await api.readTip()

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/src/records/validate.ts

@@ -48,6 +48,7 @@ export const FINDING_KINDS = [
   'batch-unsplit',
   'source-unquoted',
   'stack-foldable',
+  'fan-in-unmatched',
 ] as const
 
 export type FindingKind = (typeof FINDING_KINDS)[number]