@erclx/canon 4.107.0 → 4.109.0

package/src/cli.ts

@@ -43,169 +43,10 @@ import { register as census } from '@/commands/census'
 import { register as targets } from '@/commands/targets'
 import { register as upgrade } from '@/commands/upgrade'
 import { readInstalled, UNKNOWN_LABEL } from '@/version/installed'
-import { palette } from '@/ui'
-
-const HELP_WIDTH = 80
-const SIGNATURE_WIDTH = 19
-const ROW_INDENT = '│    '.length
-
-type CommandRow = [signature: string, description: string]
-
-// The grouping mirrors the README's domain table and has no other source, so a
-// command added to the program needs a row here or help-option.test.ts fails.
-const COMMAND_GROUPS: { title: string; rows: CommandRow[] }[] = [
-  {
-    title: 'Project',
-    rows: [
-      ['init [path]', 'Bootstrap a project with toolkit domains'],
-      ['sync [path]', 'Sync all installed domains in a project'],
-      ['upgrade', 'Reinstall the CLI with the manager that installed it'],
-      ['migrate [cmd]', 'Move a project off a retired name or layout'],
-      ['targets [cmd]', 'Projects this toolkit installed into (list, pulls)'],
-    ],
-  },
-  {
-    title: 'Domains',
-    rows: [
-      ['gov [cmd]', 'Governance rules (install, sync, list)'],
-      ['standards [cmd]', 'Standards (install, sync, list, <name>)'],
-      ['snippets [cmd]', 'Prompt snippets (create, list)'],
-      ['tooling [cmd]', 'Tooling stacks (sync, ref, create)'],
-      ['claude [cmd]', 'Claude workflow (init, sync, setup)'],
-      ['wiki [cmd]', 'Wiki pages (init)'],
-      ['indexes [cmd]', 'Regenerate index.md files (regen)'],
-      ['docs [cmd|topic]', 'Emit toolkit reference docs (list, <topic>)'],
-    ],
-  },
-  {
-    title: 'Author and render',
-    rows: [
-      ['design [cmd]', 'Design system (render, board)'],
-      ['slides [cmd]', 'Slide decks (render, list)'],
-      ['capture [source]', 'Render HTML capture sources to PNG'],
-      ['serve [dir]', 'Serve a directory on localhost, print the link'],
-      ['demo [cmd]', 'Record a running app (compile, run)'],
-      ['inventory [subj]', 'Report one computed property across every route'],
-      ['drive <url> <run>', 'Walk a page through interactions, measure each'],
-      ['transcripts <url>', 'Fetch a YouTube transcript with frontmatter'],
-      ['teach [cmd]', 'Learning workspaces (list, open, resource, glossary)'],
-    ],
-  },
-  {
-    title: 'Session and ship',
-    rows: [
-      ['sandbox [cat:cmd]', 'Provision and run sandbox scenarios'],
-      ['tasks [cmd]', 'Task board (validate, archive)'],
-      ['intake [cmd]', 'Intake folders under .canon/intake/ (list, answer)'],
-      ['records [cmd]', 'Session records (validate, size, push, pull)'],
-      ['sessions [cmd]', 'Resolve live sessions to worktree and branch'],
-      ['worktrees [cmd]', 'Reclaim worktrees whose branches merged'],
-      ['autoship [cmd]', 'Decide whether a changed set needs review'],
-      ['pr [cmd]', 'Read a pull request (key-changes, head, checks)'],
-      ['feedback', 'Write toolkit feedback from stdin'],
-    ],
-  },
-  {
-    title: 'Repo reports',
-    rows: [
-      ['audits [cmd]', 'Run every health check as one set (run, list)'],
-      ['gate [cmd]', 'Run the merge gate stage by stage (run)'],
-      ['secrets [cmd]', 'Scan the shipped tree for credentials (scan)'],
-      ['deps [cmd]', 'Read the dependency set for advisories (audit)'],
-      ['labels [cmd]', 'Read a changed set against the label map (audit)'],
-      ['comments [cmd]', 'Measure comment density and trend (scan)'],
-      ['context [cmd]', 'Report context folder health (audit)'],
-      ['markdown [cmd]', 'Report markdown against the standards (audit)'],
-      ['repo [cmd]', 'Remote metadata (metadata propose, apply)'],
-      ['census [path]', 'Report file count, extensions, and line totals'],
-    ],
-  },
-]
-
-// A row past the width is cut rather than wrapped, since a wrapped row breaks
-// the alignment the grouping exists to buy.
-function commandRow(signature: string, description: string): string {
-  const { GREY, NC } = palette(process.stdout)
-  const room = HELP_WIDTH - ROW_INDENT - SIGNATURE_WIDTH - '# '.length
-  const text =
-    description.length > room
-      ? `${description.slice(0, room - 1)}…`
-      : description
-  return `${GREY}│${NC}    ${signature.padEnd(SIGNATURE_WIDTH)}${GREY}# ${text}${NC}`
-}
+import { renderHelp } from '@/help'
 
 function showHelp(): void {
-  // The help text is the one framed surface written to stdout, so it asks
-  // about that stream rather than the stderr every other writer here uses.
-  const { GREY, NC, WHITE } = palette(process.stdout)
-  const lines = [
-    `${GREY}┌${NC}`,
-    `${GREY}├${NC} ${WHITE}Usage:${NC} canon [command]`,
-    `${GREY}│${NC}`,
-    `${GREY}│${NC}  ${WHITE}Commands:${NC}`,
-    ...COMMAND_GROUPS.flatMap((group) => [
-      `${GREY}│${NC}`,
-      `${GREY}│${NC}  ${WHITE}${group.title}${NC}`,
-      ...group.rows.map(([signature, description]) =>
-        commandRow(signature, description),
-      ),
-    ]),
-    `${GREY}│${NC}`,
-    `${GREY}│${NC}  ${WHITE}Sandbox:${NC}`,
-    `${GREY}│${NC}    canon sandbox             ${GREY}# Interactive scenario picker${NC}`,
-    `${GREY}│${NC}    canon sandbox git:commit  ${GREY}# Run specific scenario${NC}`,
-    `${GREY}│${NC}    canon sandbox reset       ${GREY}# Reset sandbox to baseline${NC}`,
-    `${GREY}│${NC}    canon sandbox clean       ${GREY}# Wipe the sandbox${NC}`,
-    `${GREY}│${NC}`,
-    `${GREY}│${NC}  ${WHITE}Examples:${NC}`,
-    `${GREY}│${NC}    canon sync ../my-app`,
-    `${GREY}│${NC}    canon sandbox git:commit`,
-    `${GREY}│${NC}    canon gov install react`,
-    `${GREY}│${NC}    canon gov sync ../my-app`,
-    `${GREY}│${NC}    canon gov restated --json`,
-    `${GREY}│${NC}    canon standards markdown`,
-    `${GREY}│${NC}    canon snippets list`,
-    `${GREY}│${NC}    canon init ../my-app`,
-    `${GREY}│${NC}    canon tooling sync base`,
-    `${GREY}│${NC}    canon tooling create`,
-    `${GREY}│${NC}    canon claude init`,
-    `${GREY}│${NC}    canon indexes regen`,
-    `${GREY}│${NC}    canon indexes regen --dry-run --json`,
-    `${GREY}│${NC}    canon docs list --json`,
-    `${GREY}│${NC}    canon docs agents`,
-    `${GREY}│${NC}    canon design render`,
-    `${GREY}│${NC}    canon design board`,
-    `${GREY}│${NC}    canon slides render`,
-    `${GREY}│${NC}    canon slides list --json`,
-    `${GREY}│${NC}    canon capture assets/captures/install.html --selector .window --out assets/evidence`,
-    `${GREY}│${NC}    canon serve .canon/teach`,
-    `${GREY}│${NC}    canon inventory focus --json`,
-    `${GREY}│${NC}    canon drive http://localhost:4173 run.json --json`,
-    `${GREY}│${NC}    pbpaste | canon feedback`,
-    `${GREY}│${NC}    canon transcripts https://youtu.be/VIDEO_ID`,
-    `${GREY}│${NC}    canon tasks archive --pull-request 673 --json`,
-    `${GREY}│${NC}    canon intake list toolkit-overview --unread --json`,
-    `${GREY}│${NC}    canon teach list --json`,
-    `${GREY}│${NC}    canon comments scan src --json`,
-    `${GREY}│${NC}    canon context audit --json`,
-    `${GREY}│${NC}    canon markdown audit .claude/rules --json`,
-    `${GREY}│${NC}    canon records validate plans`,
-    `${GREY}│${NC}    canon records size --json`,
-    `${GREY}│${NC}    canon records push --json`,
-    `${GREY}│${NC}    canon sessions list --json`,
-    `${GREY}│${NC}    canon worktrees list --json`,
-    `${GREY}│${NC}    canon worktrees reclaim --dry-run`,
-    `${GREY}│${NC}    canon secrets scan --json`,
-    `${GREY}│${NC}    canon deps audit --json`,
-    `${GREY}│${NC}    canon labels audit --json`,
-    `${GREY}│${NC}    canon repo metadata propose --json`,
-    `${GREY}│${NC}    canon census --json`,
-    `${GREY}│${NC}    canon audits run --json`,
-    `${GREY}│${NC}    canon gate run --all --no-write`,
-    `${GREY}│${NC}    canon upgrade --json`,
-    `${GREY}└${NC}`,
-  ]
-  console.log(lines.join('\n'))
+  console.log(renderHelp(process.stdout))
 }
 
 const program = new Command()

package/src/commands/pr.ts

@@ -20,7 +20,11 @@ import {
   compareKeyChanges,
   treeRoots,
 } from '@/pr/bijection'
-import { type CheckRunListing, collapseChecks } from '@/pr/checks'
+import {
+  type CheckRunListing,
+  collapseChecks,
+  withMergeState,
+} from '@/pr/checks'
 import {
   findEvidenceChecklist,
   findEvidenceCommentId,
@@ -307,6 +311,11 @@ export function register(program: Command): void {
         'an empty row list, and reading that as passing is the false green the',
         'sha key alone does not close.',
         '',
+        'A branch conflicting with its base gets no merge ref, so no run ever',
+        'starts for it and the state stays pending. The record carries',
+        '`conflicted: true` beside it when `mergeStateStatus` reads DIRTY and no',
+        'run belongs to the tip, and a caller stops waiting and rebases.',
+        '',
         'Exit codes:',
         '  0  the runs for the tip were read, whatever they say',
         '  1  refused, with the reason on stderr or in the JSON record',
@@ -865,6 +874,7 @@ interface PullIdentity {
   readonly number: number | undefined
   readonly branch: string
   readonly head?: string
+  readonly mergeState?: string
 }
 
 type IdentityRead =
@@ -911,12 +921,17 @@ async function readIdentity(
 
   const args = ['pr', 'view']
   if (number !== undefined) args.push(number)
-  args.push('--json', 'number,headRefName,headRefOid')
+  args.push('--json', 'number,headRefName,headRefOid,mergeStateStatus')
 
   const stdout = await gh(cwd, args)
   if (stdout === null) return { kind: 'refused', reason: 'gh-failed' }
 
-  let row: { number?: number; headRefName?: string; headRefOid?: string }
+  let row: {
+    number?: number
+    headRefName?: string
+    headRefOid?: string
+    mergeStateStatus?: string
+  }
   try {
     row = JSON.parse(stdout)
   } catch {
@@ -933,6 +948,9 @@ async function readIdentity(
       number: row.number,
       branch: row.headRefName,
       ...(row.headRefOid !== undefined && { head: row.headRefOid }),
+      ...(row.mergeStateStatus !== undefined && {
+        mergeState: row.mergeStateStatus,
+      }),
     },
   }
 }
@@ -1071,7 +1089,10 @@ async function runChecks(
     )
   }
 
-  const reading = collapseChecks(resolved.tip, listing)
+  const reading = withMergeState(
+    identity.mergeState,
+    collapseChecks(resolved.tip, listing),
+  )
 
   logStep('Scope')
   logInfo(
@@ -1101,6 +1122,10 @@ async function runChecks(
     logInfo('every run on the tip completed and none failed')
   } else if (reading.state === 'failing') {
     logWarn('a run on the tip failed, which no run still going can clear')
+  } else if (reading.conflicted) {
+    logWarn(
+      'the branch conflicts with its base, so no run will start for the tip. Rebase onto the base rather than waiting.',
+    )
   } else if (reading.matched === 0) {
     logInfo(
       `no run belongs to the tip yet${reading.reported > 0 ? `, against a reported count of ${reading.reported}` : ''}. That is unread rather than clean.`,

package/src/commands/tasks.ts

@@ -13,7 +13,12 @@ import {
   type PlanCitations,
   planCitations,
 } from '@/tasks/archive'
-import { type LabelOutcome, nextLabel } from '@/tasks/label'
+import {
+  type LabelOutcome,
+  type LabelRefused,
+  claimLabel,
+  nextLabel,
+} from '@/tasks/label'
 import { listTasks } from '@/tasks/list'
 import {
   type Claim,
@@ -122,6 +127,7 @@ interface ListCommandOptions {
 
 interface NextLabelCommandOptions {
   readonly json?: boolean
+  readonly claim?: boolean
   readonly root?: string
 }
 
@@ -503,6 +509,7 @@ export function register(program: Command): void {
     )
     .helpOption('-h, --help', 'Show this help message')
     .option('--json', 'Emit a machine-readable record on stdout')
+    .option('--claim', 'Reserve the label so a second claim gets another')
     .option('--root <path>', 'Board root, defaulting to the main worktree')
     .addHelpText(
       'after',
@@ -515,14 +522,18 @@ export function register(program: Command): void {
         'Exit codes:',
         '  0  the label is derived',
         '  1  refused with no-board',
+        '  2  refused with label-contended, on --claim only',
         '',
-        'It reports and never writes. Two sessions calling it in the same',
-        'second can still take the same answer, since the board is',
-        'gitignored files rather than a store with a lock.',
+        'Bare, it reports and never writes, so two sessions calling it in the',
+        'same second can take the same answer. --claim reserves the label',
+        'under .canon/ordinal-locks/ and counts every reservation in the',
+        'scan, so two claims return different labels. A dead claim leaves a',
+        'gap, which standards/versioning.md permits.',
         '',
         'Examples:',
         '  canon tasks next-label',
         '  canon tasks next-label --json',
+        '  canon tasks next-label --claim --json',
         '',
       ].join('\n'),
     )
@@ -864,11 +875,15 @@ async function runList(opts: ListCommandOptions): Promise<number> {
 
 async function runNextLabel(opts: NextLabelCommandOptions): Promise<number> {
   const root = opts.root ?? (await mainWorktreeRoot())
-  const outcome = await nextLabel(root)
+  const outcome = opts.claim ? await claimLabel(root) : await nextLabel(root)
 
   return reportNextLabel(outcome, opts.json ?? false, root)
 }
 
+function refusalExit(outcome: LabelRefused): number {
+  return outcome.reason === 'label-contended' ? 2 : 1
+}
+
 function reportNextLabel(
   outcome: LabelOutcome,
   emitJson: boolean,
@@ -879,14 +894,14 @@ function reportNextLabel(
       process.stdout.write(
         `${JSON.stringify({ ok: false, reason: outcome.reason, message: outcome.message })}\n`,
       )
-      return 1
+      return refusalExit(outcome)
     }
 
     intro('canon tasks next-label')
     logStep('Refused')
     logError(outcome.message)
     outro()
-    return 1
+    return refusalExit(outcome)
   }
 
   if (emitJson) {

package/src/help.ts

@@ -0,0 +1,196 @@
+import { palette } from '@/ui'
+
+const HELP_WIDTH = 80
+const SIGNATURE_WIDTH = 19
+const SANDBOX_SIGNATURE_WIDTH = 26
+const ROW_INDENT = '│    '.length
+
+type CommandRow = [signature: string, description: string]
+type HelpStream = { isTTY?: boolean }
+
+// The grouping mirrors the README's domain table and has no other source, so a
+// command added to the program needs a row here or help-option.test.ts fails.
+export const COMMAND_GROUPS: { title: string; rows: CommandRow[] }[] = [
+  {
+    title: 'Project',
+    rows: [
+      ['init [path]', 'Bootstrap a project with toolkit domains'],
+      ['sync [path]', 'Sync all installed domains in a project'],
+      ['upgrade', 'Reinstall the CLI with the manager that installed it'],
+      ['migrate [cmd]', 'Move a project off a retired name or layout'],
+      ['targets [cmd]', 'Projects this toolkit installed into (list, pulls)'],
+    ],
+  },
+  {
+    title: 'Domains',
+    rows: [
+      ['gov [cmd]', 'Governance rules (install, sync, list)'],
+      ['standards [cmd]', 'Standards (install, sync, list, <name>)'],
+      ['snippets [cmd]', 'Prompt snippets (create, list)'],
+      ['tooling [cmd]', 'Tooling stacks (sync, ref, create)'],
+      ['claude [cmd]', 'Claude workflow (init, sync, setup)'],
+      ['wiki [cmd]', 'Wiki pages (init)'],
+      ['indexes [cmd]', 'Regenerate index.md files (regen)'],
+      ['docs [cmd|topic]', 'Emit toolkit reference docs (list, <topic>)'],
+    ],
+  },
+  {
+    title: 'Author and render',
+    rows: [
+      ['design [cmd]', 'Design system (render, board)'],
+      ['slides [cmd]', 'Slide decks (render, list)'],
+      ['capture [source]', 'Render HTML capture sources to PNG'],
+      ['serve [dir]', 'Serve a directory on localhost, print the link'],
+      ['demo [cmd]', 'Record a running app (compile, run)'],
+      ['inventory [subj]', 'Report one computed property across every route'],
+      ['drive <url> <run>', 'Walk a page through interactions, measure each'],
+      ['transcripts <url>', 'Fetch a YouTube transcript with frontmatter'],
+      ['teach [cmd]', 'Learning workspaces (list, open, resource, glossary)'],
+    ],
+  },
+  {
+    title: 'Session and ship',
+    rows: [
+      ['sandbox [cat:cmd]', 'Provision and run sandbox scenarios'],
+      ['tasks [cmd]', 'Task board (validate, archive)'],
+      ['intake [cmd]', 'Intake folders under .canon/intake/ (list, answer)'],
+      ['records [cmd]', 'Session records (validate, size, push, pull)'],
+      ['sessions [cmd]', 'Resolve live sessions to worktree and branch'],
+      ['worktrees [cmd]', 'Reclaim worktrees whose branches merged'],
+      ['autoship [cmd]', 'Decide whether a changed set needs review'],
+      ['pr [cmd]', 'Read a pull request (key-changes, head, checks)'],
+      ['feedback', 'Write toolkit feedback from stdin'],
+    ],
+  },
+  {
+    title: 'Repo reports',
+    rows: [
+      ['audits [cmd]', 'Run every health check as one set (run, list)'],
+      ['gate [cmd]', 'Run the merge gate stage by stage (run)'],
+      ['secrets [cmd]', 'Scan the shipped tree for credentials (scan)'],
+      ['deps [cmd]', 'Read the dependency set for advisories (audit)'],
+      ['labels [cmd]', 'Read a changed set against the label map (audit)'],
+      ['comments [cmd]', 'Measure comment density and trend (scan)'],
+      ['context [cmd]', 'Report context folder health (audit)'],
+      ['markdown [cmd]', 'Report markdown against the standards (audit)'],
+      ['repo [cmd]', 'Remote metadata (metadata propose, apply)'],
+      ['census [path]', 'Report file count, extensions, and line totals'],
+    ],
+  },
+]
+
+const SANDBOX_ROWS: CommandRow[] = [
+  ['canon sandbox', 'Interactive scenario picker'],
+  ['canon sandbox git:commit', 'Run specific scenario'],
+  ['canon sandbox reset', 'Reset sandbox to baseline'],
+  ['canon sandbox clean', 'Wipe the sandbox'],
+]
+
+const EXAMPLES = [
+  'canon sync ../my-app',
+  'canon sandbox git:commit',
+  'canon gov install react',
+  'canon gov sync ../my-app',
+  'canon gov restated --json',
+  'canon standards markdown',
+  'canon snippets list',
+  'canon init ../my-app',
+  'canon tooling sync base',
+  'canon tooling create',
+  'canon claude init',
+  'canon indexes regen',
+  'canon indexes regen --dry-run --json',
+  'canon docs list --json',
+  'canon docs agents',
+  'canon design render',
+  'canon design board',
+  'canon slides render',
+  'canon slides list --json',
+  'canon capture assets/captures/install.html --selector .window --out assets/evidence',
+  'canon serve .canon/teach',
+  'canon inventory focus --json',
+  'canon drive http://localhost:4173 run.json --json',
+  'pbpaste | canon feedback',
+  'canon transcripts https://youtu.be/VIDEO_ID',
+  'canon tasks archive --pull-request 673 --json',
+  'canon intake list toolkit-overview --unread --json',
+  'canon teach list --json',
+  'canon comments scan src --json',
+  'canon context audit --json',
+  'canon markdown audit .claude/rules --json',
+  'canon records validate plans',
+  'canon records size --json',
+  'canon records push --json',
+  'canon sessions list --json',
+  'canon worktrees list --json',
+  'canon worktrees reclaim --dry-run',
+  'canon secrets scan --json',
+  'canon deps audit --json',
+  'canon labels audit --json',
+  'canon repo metadata propose --json',
+  'canon census --json',
+  'canon audits run --json',
+  'canon gate run --all --no-write',
+  'canon upgrade --json',
+]
+
+// The frame follows stdout's TTY state rather than `palette`, whose blank
+// palette keeps every glyph so the stderr frames a captured run quotes stay
+// framed. A glyph is rendering rather than color, so NO_COLOR keeps it.
+function isFramed(stream: HelpStream): boolean {
+  return stream.isTTY === true
+}
+
+function gutter(stream: HelpStream): string {
+  if (!isFramed(stream)) return ''
+  const { GREY, NC } = palette(stream)
+  return `${GREY}│${NC}`
+}
+
+// A row past the width is cut rather than wrapped, since a wrapped row breaks
+// the alignment the grouping exists to buy. The cut is computed from the framed
+// prefix in both forms, so a pipe carries the same text as a terminal.
+export function commandRow(
+  signature: string,
+  description: string,
+  stream: HelpStream,
+): string {
+  const { GREY, NC } = palette(stream)
+  const room = HELP_WIDTH - ROW_INDENT - SIGNATURE_WIDTH - '# '.length
+  const text =
+    description.length > room
+      ? `${description.slice(0, room - 1)}…`
+      : description
+  return `${gutter(stream)}    ${signature.padEnd(SIGNATURE_WIDTH)}${GREY}# ${text}${NC}`
+}
+
+export function renderHelp(stream: HelpStream): string {
+  const { GREY, NC, WHITE } = palette(stream)
+  const bar = gutter(stream)
+  const usage = `${WHITE}Usage:${NC} canon [command]`
+  const lines = [
+    ...(isFramed(stream)
+      ? [`${GREY}┌${NC}`, `${GREY}├${NC} ${usage}`]
+      : [usage]),
+    bar,
+    `${bar}  ${WHITE}Commands:${NC}`,
+    ...COMMAND_GROUPS.flatMap((group) => [
+      bar,
+      `${bar}  ${WHITE}${group.title}${NC}`,
+      ...group.rows.map(([signature, description]) =>
+        commandRow(signature, description, stream),
+      ),
+    ]),
+    bar,
+    `${bar}  ${WHITE}Sandbox:${NC}`,
+    ...SANDBOX_ROWS.map(
+      ([signature, description]) =>
+        `${bar}    ${signature.padEnd(SANDBOX_SIGNATURE_WIDTH)}${GREY}# ${description}${NC}`,
+    ),
+    bar,
+    `${bar}  ${WHITE}Examples:${NC}`,
+    ...EXAMPLES.map((example) => `${bar}    ${example}`),
+    ...(isFramed(stream) ? [`${GREY}└${NC}`] : []),
+  ]
+  return lines.join('\n')
+}

package/src/pr/checks.ts

@@ -29,6 +29,35 @@ export interface ChecksReading {
   readonly collapsed: number
 }
 
+export interface ConflictedReading extends ChecksReading {
+  /** The branch conflicts with its base, so no run will ever start for the tip. */
+  readonly conflicted: boolean
+  /** The pull request's `mergeStateStatus`, absent when the read carried none. */
+  readonly mergeState?: string
+}
+
+/**
+ * Tells a conflicted pull request from a tip whose runs have not started.
+ *
+ * A branch that conflicts with its base gets no merge ref, so no
+ * `pull_request` workflow runs and the listing stays empty, which
+ * `collapseChecks` can only call pending. Only `DIRTY` separates the two, and
+ * only while no run belongs to the tip: a conflict arising after runs
+ * completed leaves those runs standing as a real answer. `UNKNOWN` is
+ * transient while GitHub computes it, so it reads as not conflicted and costs
+ * a caller one more poll.
+ */
+export function withMergeState(
+  mergeState: string | undefined,
+  reading: ChecksReading,
+): ConflictedReading {
+  return {
+    ...reading,
+    conflicted: mergeState === 'DIRTY' && reading.matched === 0,
+    ...(mergeState !== undefined && { mergeState }),
+  }
+}
+
 /**
  * Puts a check-run row into the shape `rollup` reads.
  *