@erclx/canon 5.47.0 → 5.48.0

package/src/commands/pr.ts

@@ -63,6 +63,7 @@ import {
 } from '@/pr/frames'
 import { type HeadRefusal, resolveHead, resolveTip } from '@/pr/head'
 import {
+  type ChecksGate,
   DEFAULT_WAIT_SECONDS,
   type EvidenceGate,
   type GitRunner,
@@ -73,6 +74,13 @@ import {
   readBaseStanding,
   readChangedPaths,
 } from '@/pr/lift'
+import {
+  merge,
+  type MergeApi,
+  type MergeOutcome,
+  type MergeRefusal,
+  type MergeRequest,
+} from '@/pr/merge'
 import { machineListenerReader } from '@/listeners/machine'
 import { loadPaintedPatterns } from '@/pr/painted'
 import {
@@ -93,7 +101,9 @@ import {
   servesChange,
   type WorkflowFile,
 } from '@/pr/preview'
+import { coversHead, resolveUiScope } from '@/pr/review-scope'
 import {
+  countTicksAtHead,
   readUiPassHead,
   type TickRefusal,
   tickBoxes,
@@ -150,6 +160,10 @@ interface LiftCommandOptions extends ReadOptions {
   readonly wait?: string
 }
 
+interface MergeCommandOptions extends ReadOptions {
+  readonly dryRun?: boolean
+}
+
 interface ReviewStateOptions extends ReadOptions {
   readonly wait?: string
 }
@@ -165,6 +179,7 @@ interface TickOptions extends ReadOptions {
 
 type TickReason =
   | TickRefusal
+  | 'count-mismatch'
   | 'stale-head'
   | 'bad-boxes'
   | 'no-comment'
@@ -177,6 +192,8 @@ const TICK_REFUSALS: Record<TickReason | 'gh-failed', string> = {
     'The head named is not the branch tip on the remote, so a tick would claim a pass on a commit that is no longer the pull request. Re-drive the checklist at the tip.',
   'bad-boxes':
     '--boxes takes box numbers as a comma-separated list of positive whole numbers, such as 1,3, and --head takes the commit that was driven.',
+  'count-mismatch':
+    'The newest UI verdict at this head passed a different number of boxes than the ticks this call would leave at the head. Nothing was written. With fewer ticks than passed, re-run once with every box that passed. With more, a box ticked earlier at this head has since failed, which only the operator can untick.',
   'no-comment': 'No comment on this pull request carries the evidence marker.',
   'no-checklist': 'The evidence comment carries no checklist to tick.',
   'no-box':
@@ -834,7 +851,9 @@ export function register(program: Command): void {
         '            on an earlier commit still holds when it is an ancestor of the',
         '            head and no painted path changed since, and the record names',
         '            it as `carriedFrom`. A painted change refuses `ui-behind` and',
-        '            lists the paths as `paintedPaths`',
+        '            lists the paths as `paintedPaths`. A close whose count line',
+        '            shows boxes not driven and none passed, failed, or needing',
+        '            eyes refuses `ui-undriven`, carried or not',
         '  evidence  the evidence check reads settled',
         '  standing  the head is fresh against the base, not stale or conflicted',
         '  ci        every check run on the tip passed, waited on up to --wait',
@@ -860,7 +879,7 @@ export function register(program: Command): void {
         '  lifted, already-ready, redrafted, clear (--check)',
         '  pull-closed, review-missing, review-open, review-unmarked,',
         '  review-behind, ui-missing, ui-open, ui-unmarked, ui-behind,',
-        '  evidence-owed, standing-stale, standing-conflict, standing-unknown,',
+        '  ui-undriven, evidence-owed, standing-stale, standing-conflict, standing-unknown,',
         '  ci-pending (--check), ci-failing, ci-conflicted, ci-timeout,',
         '  head-moved, gh-failed',
         '',
@@ -881,6 +900,57 @@ export function register(program: Command): void {
       process.exitCode = await runLift(number, opts)
     })
 
+  pr.command('merge')
+    .description(
+      'Squash-merge a ready pull request with a message carrying only its Summary, Key changes, and Technical context',
+    )
+    .argument('[number]', 'Pull request to merge, defaulting to this branch')
+    .helpOption('-h, --help', 'Show this help message')
+    .option('--root <path>', 'Repository to read, defaulting to the cwd')
+    .option('--json', 'Add a machine-readable record on stdout')
+    .option('--dry-run', 'Print the title and description and merge nothing')
+    .addHelpText(
+      'after',
+      [
+        '',
+        'The operator runs this verb, and no skill calls it. A permissions deny',
+        'rule on `canon pr merge` and `gh pr merge` keeps an agent off it.',
+        '',
+        'The title is the pull request title plus ` (#<number>)`. The',
+        "description is the body's `## Summary`, `## Key changes`, and",
+        '`## Technical context`, in that order under their headings, with the',
+        'UI pass line dropped. Technical context is optional. Testing, the',
+        'reviewer requests, and every other section stay out of the trunk.',
+        '',
+        'Refusals are read before the one write, which sends the head it read',
+        'as `sha`, so a push after the read refuses rather than merging. The',
+        'verb reads the draft flag and not the reviews, since a ready pull',
+        'request already passed `canon pr lift`. It does not wait on checks or',
+        'delete the branch.',
+        '',
+        'Reasons:',
+        '  merged, dry-run (--dry-run)',
+        '  pull-closed, pull-draft, missing-summary, missing-key-changes,',
+        '  ci-failing, ci-conflicted, ci-pending, head-moved, not-mergeable,',
+        '  gh-failed',
+        '',
+        'The merge is the REST `PUT pulls/<number>/merge` with',
+        '`merge_method=squash`, never `gh pr merge`, which runs on GraphQL.',
+        '',
+        'Exit codes:',
+        '  0  merged, or every refusal clear under --dry-run',
+        '  1  refused, with the reason in the JSON record',
+        '',
+        'Examples:',
+        '  canon pr merge 1341 --dry-run',
+        '  canon pr merge 1341 --json',
+        '',
+      ].join('\n'),
+    )
+    .action(async (number: string | undefined, opts: MergeCommandOptions) => {
+      process.exitCode = await runMerge(number, opts)
+    })
+
   pr.command('preview')
     .description(
       "Deploy the pull request's branch to a Cloudflare Pages preview and report its address",
@@ -1048,9 +1118,19 @@ export function register(program: Command): void {
         'driver can run is ticked, counts taste boxes apart, and is the only',
         'body text this verb writes, so hand edits elsewhere survive.',
         '',
+        'Before writing it reads the newest UI verdict. One that covers the tip',
+        'and carries a count line must match the ticks this call leaves at the',
+        'tip, so a re-drive passes every box that passed, since a new head',
+        'clears the older ticks. Any other verdict leaves the check unrun.',
+        '',
         'Read `reason` on the JSON record:',
         '  ticked       the boxes were ticked and the body line written, with the',
-        '               tip in `head`',
+        '               tip in `head` and `countCheck` as matched or unchecked',
+        '  count-mismatch the verdict passed a different number of boxes than',
+        '               this call leaves ticked at the tip, nothing written,',
+        '               `passed` and `ticked` carry the two counts. Fewer ticks',
+        '               owe a re-run with every passed box, more ticks owe the',
+        '               operator an untick of a box that has since failed',
         '  body-refused the comment is ticked but gh could not edit the body,',
         '               exit 1 with `commentTicked`. Re-run to retry the body.',
         '  stale-head   --head is not the remote branch tip, nothing written',
@@ -2977,6 +3057,32 @@ async function runTick(
   const result = tickBoxes(marked.body, numbers.map(Number), reading.tip)
   if (result.kind === 'refused') return refuseTick(result.reason)
 
+  // Read ahead of the write so a short list refuses before it leaves the
+  // comment half ticked. A verdict that does not cover the tip, carries no
+  // count line, or cannot be read leaves the check unrun and says so.
+  const ticked = countTicksAtHead(
+    readChecklistBoxes(findEvidenceChecklist([{ body: result.body }]) ?? ''),
+    reading.tip,
+  )
+  const reviews = await listReviews(root, String(identity.number))
+  const verdict = resolveUiScope({
+    reviews: reviews.kind === 'read' ? reviews.rows.map(reviewRowOf) : [],
+  })
+  const isCounted =
+    verdict.counts !== undefined &&
+    verdict.commit !== undefined &&
+    coversHead(verdict.commit, reading.tip)
+  if (isCounted && verdict.counts.passed !== ticked) {
+    return refuseWith(
+      'count-mismatch',
+      TICK_REFUSALS['count-mismatch'],
+      emitJson,
+      root,
+      { passed: verdict.counts.passed, ticked },
+    )
+  }
+  const countCheck = isCounted ? 'matched' : 'unchecked'
+
   if (result.body !== marked.body) {
     const patched = await gh(root, [
       'api',
@@ -2995,14 +3101,7 @@ async function runTick(
   const driven = boxes.filter((box) => !box.isTaste)
   const summary: UiPassSummary = {
     kind: 'passed',
-    // A tick counts as this pass's only when stamped at the tip, since an
-    // unstamped one is the author's claim and an older stamp names another head.
-    passed: driven.filter(
-      (box) =>
-        box.isTicked &&
-        box.stamp !== undefined &&
-        reading.tip.startsWith(box.stamp),
-    ).length,
+    passed: countTicksAtHead(boxes, reading.tip),
     total: driven.length,
     taste: boxes.length - driven.length,
     head: reading.tip,
@@ -3024,6 +3123,7 @@ async function runTick(
           reason: 'body-refused',
           message: TICK_REFUSALS['body-refused'],
           commentTicked: true,
+          countCheck,
           head: reading.tip,
           boxes: numbers.map(Number),
           commentId,
@@ -3044,6 +3144,7 @@ async function runTick(
         root,
         number: identity.number,
         reason: 'ticked',
+        countCheck,
         head: reading.tip,
         boxes: numbers.map(Number),
         commentId,
@@ -3443,6 +3544,8 @@ const LIFT_REFUSALS: Record<LiftRefusal | 'bad-wait' | 'gh-missing', string> = {
     'The newest UI review carries no head marker, so the commit it covers is a GitHub stamp this gate does not trust.',
   'ui-behind':
     'The newest UI review closed on an earlier commit than the head.',
+  'ui-undriven':
+    'The newest UI review closed having driven no box, so it looked at nothing. Re-drive the checklist on an address that answers.',
   'evidence-owed':
     'The evidence check reads owed, so the ship chain left a step undone.',
   'standing-stale':
@@ -3564,6 +3667,34 @@ async function readEvidenceGate(
   }
 }
 
+async function readChecksGate(
+  root: string,
+  number: string,
+  tip: string,
+): Promise<ChecksGate | undefined> {
+  const [listed, pulled] = await Promise.all([
+    gh(root, [
+      'api',
+      `repos/{owner}/{repo}/commits/${tip}/check-runs?per_page=100`,
+    ]),
+    gh(root, ['api', `repos/{owner}/{repo}/pulls/${number}`]),
+  ])
+  if (listed === null) return undefined
+  try {
+    const mergeState =
+      pulled === null
+        ? undefined
+        : mergeStateOf((JSON.parse(pulled) as RestPull).mergeable_state)
+    const reading = withMergeState(
+      mergeState,
+      collapseChecks(tip, JSON.parse(listed) as CheckRunListing),
+    )
+    return { state: reading.state, isConflicted: reading.conflicted }
+  } catch {
+    return undefined
+  }
+}
+
 function liftApi(root: string, number: string, baseRef: string): LiftApi {
   const git = gitRunner(root)
 
@@ -3601,29 +3732,7 @@ function liftApi(root: string, number: string, baseRef: string): LiftApi {
     readEvidence: () => readEvidenceGate(root, number),
     readStanding: (head) =>
       readBaseStanding(git, Number(number), head, baseRef),
-    readChecks: async (tip) => {
-      const [listed, pulled] = await Promise.all([
-        gh(root, [
-          'api',
-          `repos/{owner}/{repo}/commits/${tip}/check-runs?per_page=100`,
-        ]),
-        gh(root, ['api', `repos/{owner}/{repo}/pulls/${number}`]),
-      ])
-      if (listed === null) return undefined
-      try {
-        const mergeState =
-          pulled === null
-            ? undefined
-            : mergeStateOf((JSON.parse(pulled) as RestPull).mergeable_state)
-        const reading = withMergeState(
-          mergeState,
-          collapseChecks(tip, JSON.parse(listed) as CheckRunListing),
-        )
-        return { state: reading.state, isConflicted: reading.conflicted }
-      } catch {
-        return undefined
-      }
-    },
+    readChecks: (tip) => readChecksGate(root, number, tip),
     markReady: (nodeId) =>
       flipDraft(
         root,
@@ -3725,6 +3834,160 @@ async function runLift(
   return record.isOk ? 0 : 1
 }
 
+const MERGE_REFUSALS: Record<MergeRefusal | 'gh-missing', string> = {
+  'gh-missing': PULL_REFUSALS['gh-missing'],
+  'pull-closed': 'The pull request is closed, so there is nothing to merge.',
+  'pull-draft':
+    'The pull request is a draft, so its reviews have not lifted the mark.',
+  'missing-summary':
+    'The body carries no `## Summary` with text under it, so the description has no change to state.',
+  'missing-key-changes':
+    'The body carries no `## Key changes` with text under it, so the description has no change to state.',
+  'ci-failing': 'A check run on the head failed.',
+  'ci-conflicted': 'The branch conflicts with its base.',
+  'ci-pending':
+    'A check run on the head has yet to conclude. Run the verb again once it does.',
+  'head-moved':
+    'The head moved after the read, so GitHub refused rather than merging unread commits.',
+  'not-mergeable': 'GitHub answered that the pull request is not mergeable.',
+  'gh-failed':
+    'A read or the merge was refused, so nothing is reported as merged.',
+}
+
+/**
+ * The REST merge, never `gh pr merge`, which runs on the GraphQL a cloud
+ * session's proxy refuses. gh reports the status only as the `(HTTP <code>)`
+ * tail of its stderr, so 409 and 405 are read off it.
+ */
+async function putSquashMerge(
+  root: string,
+  number: string,
+  request: MergeRequest,
+): Promise<MergeOutcome> {
+  const result = await execa(
+    'gh',
+    [
+      'api',
+      '-X',
+      'PUT',
+      `repos/{owner}/{repo}/pulls/${number}/merge`,
+      '-f',
+      `commit_title=${request.title}`,
+      '-f',
+      `commit_message=${request.description}`,
+      '-f',
+      `sha=${request.sha}`,
+      '-f',
+      'merge_method=squash',
+    ],
+    {
+      cwd: root,
+      reject: false,
+      timeout: GH_TIMEOUT_MS,
+      env: gitEnv(),
+      extendEnv: false,
+    },
+  )
+  if (result.exitCode !== 0) {
+    const status = /\(HTTP (\d{3})\)/.exec(String(result.stderr))?.[1]
+    if (status === '409') return { kind: 'head-moved' }
+    if (status === '405') return { kind: 'not-mergeable' }
+    return { kind: 'failed' }
+  }
+  try {
+    const body = JSON.parse(String(result.stdout)) as {
+      merged?: unknown
+      sha?: unknown
+    }
+    return body.merged === true && typeof body.sha === 'string'
+      ? { kind: 'merged', sha: body.sha }
+      : { kind: 'failed' }
+  } catch {
+    return { kind: 'failed' }
+  }
+}
+
+function mergeApi(root: string, number: string): MergeApi {
+  return {
+    readPull: async () => {
+      const stdout = await gh(root, [
+        'api',
+        `repos/{owner}/{repo}/pulls/${number}`,
+      ])
+      if (stdout === null) return undefined
+      try {
+        const row = JSON.parse(stdout) as RestPull
+        if (row.head?.sha === undefined || typeof row.title !== 'string') {
+          return undefined
+        }
+        return {
+          isOpen: row.state === 'open',
+          isDraft: row.draft === true,
+          title: row.title,
+          body: row.body ?? '',
+          head: row.head.sha,
+        }
+      } catch {
+        return undefined
+      }
+    },
+    readChecks: (head) => readChecksGate(root, number, head),
+    putMerge: (request) => putSquashMerge(root, number, request),
+  }
+}
+
+async function runMerge(
+  number: string | undefined,
+  opts: MergeCommandOptions,
+): Promise<number> {
+  const root = resolve(opts.root ?? process.cwd())
+  const emitJson = opts.json ?? false
+
+  intro('canon pr merge')
+
+  if (Bun.which('gh') === null) {
+    return refuseWith(
+      'gh-missing',
+      MERGE_REFUSALS['gh-missing'],
+      emitJson,
+      root,
+    )
+  }
+
+  const resolved = await resolvePullNumber(root, number)
+  if (resolved.kind === 'refused') {
+    return refuseWith(
+      resolved.reason,
+      PULL_REFUSALS[resolved.reason],
+      emitJson,
+      root,
+    )
+  }
+
+  const record = await merge(mergeApi(root, resolved.number), {
+    number: Number(resolved.number),
+    isDryRun: opts.dryRun ?? false,
+  })
+
+  logStep(record.reason)
+  logInfo(
+    record.reason === 'merged'
+      ? `#${record.number} squash-merged as ${record.sha?.slice(0, 8)}`
+      : record.reason === 'dry-run'
+        ? `#${record.number} would merge with the message below`
+        : MERGE_REFUSALS[record.reason],
+  )
+  outro()
+
+  if (emitJson) {
+    process.stdout.write(`${JSON.stringify({ root, ...record })}\n`)
+  } else if (record.reason === 'dry-run') {
+    process.stdout.write(`${record.title}\n\n${record.description}\n`)
+  }
+
+  return record.isOk ? 0 : 1
+}
+
 /**
  * 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
@@ -3739,13 +4002,16 @@ function refuseWith(
   message: string,
   emitJson: boolean,
   root: string,
+  extra: Record<string, unknown> = {},
 ): number {
   logStep('Refused')
   logWarn(message)
   outro()
 
   if (emitJson) {
-    process.stdout.write(`${JSON.stringify({ root, reason, message })}\n`)
+    process.stdout.write(
+      `${JSON.stringify({ root, reason, message, ...extra })}\n`,
+    )
   }
   return 1
 }

package/src/commands/tasks.ts

@@ -680,7 +680,9 @@ export function register(program: Command): void {
         '                  the last listed, so a later number closes the issue',
         '  lookup-failed   the pull request lookup failed while the task already',
         '                  lists a pull request, so an earlier slice cannot be ruled out',
-        '  open-outcomes   an outcome is still open, so a later slice closes it',
+        '  open-outcomes   an outcome is still open, so a later slice closes it.',
+        '                  A `- [ ] Operator check: <outcome>` line holds nothing open and',
+        '                  is listed under `operatorChecks`',
         '  pending-branch  another branch is on `Pending branch:`',
         '  no-outcomes     the task carries no outcomes',
         '',
@@ -1544,6 +1546,7 @@ function reportCloses(
         issues: outcome.issues,
         closing: outcome.closing,
         reason: outcome.reason,
+        operatorChecks: outcome.operatorChecks ?? [],
       })}\n`,
     )
     return 0
@@ -1556,6 +1559,9 @@ function reportCloses(
       ? `${outcome.stem} names ${outcome.issues.map((n) => `#${n}`).join(', ')}, ${outcome.reason}`
       : `${outcome.stem} names no issue`,
   )
+  for (const check of outcome.operatorChecks ?? []) {
+    logInfo(`operator check: ${check}`)
+  }
   outro()
 
   return 0
@@ -2199,6 +2205,7 @@ function report(
   logRelinked(outcome.relinked, outcome.relinkFailed, root)
   if (outcome.indexRegenerated) logInfo('regenerated index.md')
   if (outcome.cut > 0) logInfo(`${outcome.cut} outcome(s) cut`)
+  for (const check of outcome.operatorChecks) logInfo(check)
   outro()
 
   return 0
@@ -2289,6 +2296,7 @@ function recordFor(
       : null,
     closed: outcome.closed,
     cut: outcome.cut,
+    operatorChecks: outcome.operatorChecks,
     relinked: relinkedFor(outcome.relinked, root),
     relinkFailed: relinkFailedFor(outcome.relinkFailed, root),
   }

package/src/migrate/session-defaults.ts

@@ -1,6 +1,7 @@
 /**
  * Adds the session defaults the seeded `.claude/settings.json` carries to a
- * target that was seeded before them.
+ * target that was seeded before them: the subagent deny, the memory default, and
+ * the merge deny entries.
  *
  * `canon claude init` copies a seed only when the file is absent, so a target
  * holding its own settings never sees a later seed change. This verb adds each
@@ -21,6 +22,12 @@ import {
 /** Both names, since `Task` is the tool's name before Claude Code renamed it. */
 export const DENIED_TOOLS: readonly string[] = ['Agent', 'Task']
 
+/** The merge entries the seeded deny list carries, so a session cannot merge. */
+export const MERGE_DENIED: readonly string[] = [
+  'Bash(canon pr merge:*)',
+  'Bash(gh pr merge:*)',
+]
+
 export interface SessionDefaultsPlan {
   readonly keys: readonly SettingsKey[]
   readonly next: SettingsRecord
@@ -31,6 +38,8 @@ export interface SessionDefaultsPlan {
    * on purpose, which is how an operator opts back into subagents.
    */
   readonly predates: boolean
+  /** True when the deny list lacks any merge entry, whatever else it holds. */
+  readonly lacksMergeDeny: boolean
 }
 
 export type SessionDefaultsRead =
@@ -52,8 +61,8 @@ function isRecord(value: unknown): value is SettingsRecord {
 }
 
 /**
- * Appends the denied tools a list lacks, keeping the list's own order, so the
- * diff a person reads is the added entries alone.
+ * Appends the denied tools and merge entries a list lacks, keeping the list's
+ * own order, so the diff a person reads is the added entries alone.
  */
 export function planSessionDefaults(
   current: SettingsRecord,
@@ -62,7 +71,9 @@ export function planSessionDefaults(
   const permissions = isRecord(current.permissions) ? current.permissions : {}
   const deny = Array.isArray(permissions.deny) ? permissions.deny : []
 
-  const missing = DENIED_TOOLS.filter((tool) => !deny.includes(tool))
+  const subagentsMissing = DENIED_TOOLS.filter((tool) => !deny.includes(tool))
+  const mergeMissing = MERGE_DENIED.filter((entry) => !deny.includes(entry))
+  const missing = [...subagentsMissing, ...mergeMissing]
   if (missing.length > 0) {
     next.permissions = { ...permissions, deny: [...deny, ...missing] }
   }
@@ -78,7 +89,11 @@ export function planSessionDefaults(
     keys,
     next,
     changed: keys.some((key) => key.changed),
-    predates: memoryAbsent && missing.length === DENIED_TOOLS.length,
+    predates:
+      memoryAbsent &&
+      subagentsMissing.length === DENIED_TOOLS.length &&
+      mergeMissing.length === MERGE_DENIED.length,
+    lacksMergeDeny: mergeMissing.length > 0,
   }
 }
 

package/src/pr/lift.ts

@@ -4,6 +4,7 @@ import {
   type ReviewRow,
   resolveReviewScope,
   resolveUiScope,
+  type UiCounts,
 } from '@/pr/review-scope'
 import { DEFAULT_PAINTED, isPainted, type PaintedPatterns } from '@/pr/painted'
 
@@ -24,6 +25,7 @@ export type LiftRefusal =
   | 'ui-open'
   | 'ui-unmarked'
   | 'ui-behind'
+  | 'ui-undriven'
   | 'evidence-owed'
   | 'standing-stale'
   | 'standing-conflict'
@@ -170,6 +172,20 @@ function carried(gates: readonly GateResult[]): {
   }
 }
 
+/**
+ * Whether a verdict's counts show boxes left undriven and none driven. An empty
+ * pass, with nothing not driven either, looked at no box because none was owed.
+ */
+function droveNothing(counts: UiCounts | undefined): boolean {
+  return (
+    counts !== undefined &&
+    counts.failed === 0 &&
+    counts.eyes === 0 &&
+    counts.passed === 0 &&
+    counts.notDriven > 0
+  )
+}
+
 /**
  * Binds only where the evidence record carries a checklist to drive.
  *
@@ -192,6 +208,9 @@ export async function uiGate(
   if (scope.state === 'open') return fail('ui', 'ui-open')
   if (scope.source !== 'marker') return fail('ui', 'ui-unmarked')
   if (scope.commit === undefined) return fail('ui', 'ui-behind')
+  // Ahead of the head test so a close carried across commits is refused too.
+  // A verdict whose count line did not parse reads as unchecked and goes on.
+  if (droveNothing(scope.counts)) return fail('ui', 'ui-undriven')
   if (coversHead(scope.commit, head)) return pass('ui')
 
   const changed = await api.readChanged(scope.commit, head)