@erclx/canon 5.47.0 → 5.48.0

package/src/pr/merge.ts

@@ -0,0 +1,175 @@
+import type { ChecksGate } from '@/pr/lift'
+import { readSection } from '@/pr/paths'
+import { UI_PASS_MARKER } from '@/pr/tick'
+
+/** Why the verb did not merge, in the order the refusals are read. */
+export type MergeRefusal =
+  | 'pull-closed'
+  | 'pull-draft'
+  | 'missing-summary'
+  | 'missing-key-changes'
+  | 'ci-failing'
+  | 'ci-conflicted'
+  | 'ci-pending'
+  | 'head-moved'
+  | 'not-mergeable'
+  | 'gh-failed'
+
+export interface MergePull {
+  readonly isOpen: boolean
+  readonly isDraft: boolean
+  readonly title: string
+  readonly body: string
+  /** The head the merge is pinned to, so a push after the read refuses. */
+  readonly head: string
+}
+
+export interface MergeRequest {
+  readonly title: string
+  readonly description: string
+  readonly sha: string
+}
+
+/** What the merge endpoint answered, with 409 and 405 told apart from a merge. */
+export type MergeOutcome =
+  | { readonly kind: 'merged'; readonly sha: string }
+  | { readonly kind: 'head-moved' }
+  | { readonly kind: 'not-mergeable' }
+  | { readonly kind: 'failed' }
+
+/**
+ * Everything the verb reads or writes, injected so every refusal runs without
+ * a network. A read that failed returns undefined, and the verb refuses
+ * `gh-failed` rather than reading absence as a pass.
+ */
+export interface MergeApi {
+  readPull(): Promise<MergePull | undefined>
+  readChecks(head: string): Promise<ChecksGate | undefined>
+  putMerge(request: MergeRequest): Promise<MergeOutcome>
+}
+
+export interface MergeOptions {
+  readonly number: number
+  readonly isDryRun: boolean
+}
+
+export interface MergeRecord {
+  readonly reason: 'merged' | 'dry-run' | MergeRefusal
+  readonly isOk: boolean
+  readonly number: number
+  readonly title?: string
+  readonly description?: string
+  /** The squash commit, present only on a merge. */
+  readonly sha?: string
+}
+
+export type Composed =
+  | { readonly kind: 'composed'; readonly description: string }
+  | {
+      readonly kind: 'refused'
+      readonly reason: 'missing-summary' | 'missing-key-changes'
+    }
+
+/** A section's text with the UI pass line dropped, or undefined when nothing is left. */
+function keptSection(body: string, title: string): string | undefined {
+  const text = readSection(body, title)
+    ?.split('\n')
+    .filter((line) => !line.includes(UI_PASS_MARKER))
+    .join('\n')
+    .trim()
+  return text === undefined || text === ''
+    ? undefined
+    : `## ${title}\n\n${text}`
+}
+
+/**
+ * The squash description: Summary, Key changes, and Technical context, in that
+ * order, under their headings. Testing, the reviewer requests, and the UI pass
+ * line describe the review rather than the change, so none reaches the trunk.
+ * Technical context is optional, and an empty one leaves no bare heading.
+ */
+export function composeDescription(body: string): Composed {
+  const summary = keptSection(body, 'Summary')
+  if (summary === undefined)
+    return { kind: 'refused', reason: 'missing-summary' }
+  const keyChanges = keptSection(body, 'Key changes')
+  if (keyChanges === undefined) {
+    return { kind: 'refused', reason: 'missing-key-changes' }
+  }
+  const context = keptSection(body, 'Technical context')
+  return {
+    kind: 'composed',
+    description: [summary, keyChanges, context]
+      .filter((block) => block !== undefined)
+      .join('\n\n'),
+  }
+}
+
+/** The suffix the web merge adds and the trunk log carries. */
+export function mergeTitle(title: string, number: number): string {
+  return `${title} (#${number})`
+}
+
+function refused(
+  reason: MergeRefusal,
+  number: number,
+  message: { title?: string; description?: string } = {},
+): MergeRecord {
+  return { reason, isOk: false, number, ...message }
+}
+
+/**
+ * Squash-merges one ready pull request with a message carrying only the
+ * change. Every refusal is read before the one write, and the write sends the
+ * head it read as `sha`, so GitHub refuses rather than merging a commit pushed
+ * after the checks were read. The verb reads the draft flag and not the review
+ * comments, since a ready pull request already passed the lift's gates.
+ */
+export async function merge(
+  api: MergeApi,
+  opts: MergeOptions,
+): Promise<MergeRecord> {
+  const { number } = opts
+
+  const pull = await api.readPull()
+  if (pull === undefined) return refused('gh-failed', number)
+  if (!pull.isOpen) return refused('pull-closed', number)
+  if (pull.isDraft) return refused('pull-draft', number)
+
+  const title = mergeTitle(pull.title, number)
+  const composed = composeDescription(pull.body)
+  if (composed.kind === 'refused') {
+    return refused(composed.reason, number, { title })
+  }
+  const message = { title, description: composed.description }
+
+  const checks = await api.readChecks(pull.head)
+  if (checks === undefined) return refused('gh-failed', number, message)
+  if (checks.state === 'failing') return refused('ci-failing', number, message)
+  if (checks.state !== 'passing') {
+    return refused(
+      checks.isConflicted ? 'ci-conflicted' : 'ci-pending',
+      number,
+      message,
+    )
+  }
+
+  if (opts.isDryRun)
+    return { reason: 'dry-run', isOk: true, number, ...message }
+
+  const outcome = await api.putMerge({ ...message, sha: pull.head })
+  if (outcome.kind === 'merged') {
+    return {
+      reason: 'merged',
+      isOk: true,
+      number,
+      ...message,
+      sha: outcome.sha,
+    }
+  }
+  return refused(
+    outcome.kind === 'failed' ? 'gh-failed' : outcome.kind,
+    number,
+    message,
+  )
+}

package/src/pr/rest.ts

@@ -13,6 +13,7 @@ import type { ReviewRow } from '@/pr/review-scope'
 /** One row of `repos/{owner}/{repo}/pulls/<n>` or of the pulls listing. */
 export interface RestPull {
   readonly number?: number
+  readonly title?: string
   readonly body?: string | null
   readonly head?: { readonly ref?: string; readonly sha?: string }
   readonly base?: { readonly ref?: string }

package/src/pr/review-scope.ts

@@ -136,11 +136,21 @@ export const UI_HEADINGS = ['## UI review', '## UI review closed'] as const
 
 export type UiHeading = (typeof UI_HEADINGS)[number]
 
+/** The four totals on a verdict's count line. */
+export interface UiCounts {
+  readonly failed: number
+  readonly eyes: number
+  readonly passed: number
+  readonly notDriven: number
+}
+
 export interface UiScope {
   readonly heading?: UiHeading
   readonly state: ReviewState
   /** The head the verdict covered, a full or abbreviated sha. */
   readonly commit?: string
+  /** The counts the verdict wrote, absent when its count line does not parse. */
+  readonly counts?: UiCounts
   /** `marker` is the verdict's own record, `fallback` is GitHub's stamp. */
   readonly source: ScopeSource
 }
@@ -152,6 +162,32 @@ export interface UiScope {
  */
 const UI_MARKER = /^<!--\s*review-ui:\s*head=([0-9a-f]{7,40})\s*-->$/
 
+/**
+ * The count line `review-ui`'s `post.md` fixes as the verdict's first line
+ * under the heading. It is model-written prose, so a body that drifts from the
+ * form reads as no counts and a caller treats that as unchecked.
+ */
+const UI_COUNTS =
+  /^(\d+) failed · (\d+) need your eyes · (\d+) passed · (\d+) not driven$/
+
+export function readUiCounts(body: string): UiCounts | undefined {
+  for (const raw of body.split('\n').slice(1, 6)) {
+    const match = UI_COUNTS.exec(raw.trim())
+    if (match === null) continue
+    const [, failed, eyes, passed, notDriven] = match.map(Number)
+    if (
+      failed === undefined ||
+      eyes === undefined ||
+      passed === undefined ||
+      notDriven === undefined
+    ) {
+      return undefined
+    }
+    return { failed, eyes, passed, notDriven }
+  }
+  return undefined
+}
+
 function lastLine(body: string): string | undefined {
   const lines = body.split('\n')
 
@@ -185,9 +221,11 @@ export function resolveUiScope(listing: ReviewListing): UiScope {
   const line = lastLine(row.body ?? '')
   const match = line === undefined ? null : UI_MARKER.exec(line)
   const marked = match?.[1]
+  const counts = readUiCounts(row.body ?? '')
+  const counted = counts === undefined ? {} : { counts }
 
   if (marked !== undefined) {
-    return { heading, state, commit: marked, source: 'marker' }
+    return { heading, state, commit: marked, ...counted, source: 'marker' }
   }
 
   const oid = row.commit?.oid
@@ -195,6 +233,7 @@ export function resolveUiScope(listing: ReviewListing): UiScope {
     heading,
     state,
     ...(oid === undefined || oid === '' ? {} : { commit: oid }),
+    ...counted,
     source: 'fallback',
   }
 }

package/src/pr/tick.ts

@@ -1,4 +1,5 @@
 import {
+  type ChecklistBox,
   CHECKLIST_END,
   CHECKLIST_START,
   parseBoxLine,
@@ -7,7 +8,7 @@ import {
   writeBoxLine,
 } from '@/pr/evidence'
 
-const UI_PASS_MARKER = '<!-- pr-ui-pass -->'
+export const UI_PASS_MARKER = '<!-- pr-ui-pass -->'
 const TESTING_HEADING = /^## Testing\s*$/
 const SECTION_HEADING = /^## /
 const REVIEWER_HEADING = /^## For the reviewer\s*$/
@@ -48,6 +49,25 @@ export function uiPassLine(summary: UiPassSummary): string {
   return `- [${box}] UI pass, ${summary.passed} of ${summary.total} boxes passed at ${at}${tail} ${UI_PASS_MARKER}`
 }
 
+/**
+ * The driven boxes ticked at the head. A tick counts as this pass's only when
+ * stamped at the head, since an unstamped one is the author's claim and an
+ * older stamp names another head. Taste boxes are left out, as the body line
+ * leaves them out.
+ */
+export function countTicksAtHead(
+  boxes: readonly ChecklistBox[],
+  head: string,
+): number {
+  return boxes.filter(
+    (box) =>
+      !box.isTaste &&
+      box.isTicked &&
+      box.stamp !== undefined &&
+      head.startsWith(box.stamp),
+  ).length
+}
+
 /** The short sha the marked line names, absent when the body carries no such line. */
 export function readUiPassHead(body: string): string | undefined {
   const line = body.split('\n').find((row) => row.includes(UI_PASS_MARKER))

package/src/tasks/archive.ts

@@ -115,6 +115,8 @@ export interface ArchiveSuccess {
   readonly ready: ReadyMove | undefined
   readonly closed: number
   readonly cut: number
+  /** Unticked `Operator check:` outcomes the archive left as they were. */
+  readonly operatorChecks: readonly string[]
   /** Every task file whose links to the moved task were rewritten. */
   readonly relinked: readonly InboundRelink[]
   /** Every task file the pass could not read or write, left as it was. */
@@ -159,6 +161,8 @@ export interface TaskOutcomes {
   readonly open: readonly string[]
   readonly closed: readonly string[]
   readonly cut: readonly string[]
+  /** Unticked outcomes only the operator can check, which hold nothing open. */
+  readonly operator: readonly string[]
 }
 
 export function tasksDir(root: string): string {
@@ -197,6 +201,9 @@ const BULLET_PATTERN = /^- (?:\[([ xX])\] ?)?(.*)$/
  */
 const STRUCK_BODY_PATTERN = /^~~.+~~/
 
+/** The one spelling of an operator-owned outcome, anchored to the body's start. */
+const OPERATOR_BODY_PATTERN = /^Operator check: ?\S/
+
 /**
  * Marks the lines sitting inside a fenced block, the fence delimiters included.
  * A checkbox in a sample a task displays is not an outcome the task claims, and
@@ -232,6 +239,7 @@ export function readOutcomes(text: string): TaskOutcomes {
   const open: string[] = []
   const closed: string[] = []
   const cut: string[] = []
+  const operator: string[] = []
   const lines = text.split('\n')
   const fenced = fenceMask(lines)
 
@@ -252,13 +260,17 @@ export function readOutcomes(text: string): TaskOutcomes {
     if (box === undefined) continue
 
     if (box === ' ') {
-      open.push(body)
+      if (OPERATOR_BODY_PATTERN.test(body)) {
+        operator.push(body)
+      } else {
+        open.push(body)
+      }
     } else {
       closed.push(body)
     }
   }
 
-  return { open, closed, cut }
+  return { open, closed, cut, operator }
 }
 
 /**
@@ -951,7 +963,7 @@ export async function archiveTask(
     )
   }
 
-  const { open, closed, cut } = readOutcomes(text)
+  const { open, closed, cut, operator } = readOutcomes(text)
 
   if (open.length > 0) {
     return refuse(
@@ -961,7 +973,7 @@ export async function archiveTask(
     )
   }
 
-  if (closed.length === 0 && cut.length === 0) {
+  if (closed.length === 0 && cut.length === 0 && operator.length === 0) {
     return refuse(
       'no-outcomes',
       `${stem} carries no outcomes, so nothing marks it shipped.`,
@@ -1020,6 +1032,7 @@ export async function archiveTask(
     ready: ready || undefined,
     closed: closed.length,
     cut: cut.length,
+    operatorChecks: operator,
     relinked,
     relinkFailed: failed,
   }

package/src/tasks/closes.ts

@@ -29,6 +29,8 @@ export interface Closure {
   readonly issues: readonly number[]
   readonly closing: boolean
   readonly reason: ClosingReason
+  /** Unticked operator checks, read once the outcome test runs. */
+  readonly operatorChecks?: readonly string[]
 }
 
 export interface TaskClosure extends Closure {
@@ -108,16 +110,18 @@ export function decideClosing(
     return { issues, closing: false, reason: 'pending-branch' }
   }
 
-  const { open, closed, cut } = readOutcomes(text)
+  const { open, closed, cut, operator } = readOutcomes(text)
+  const operatorChecks = operator
+
   if (open.length > 0) {
-    return { issues, closing: false, reason: 'open-outcomes' }
+    return { issues, closing: false, reason: 'open-outcomes', operatorChecks }
   }
 
-  if (closed.length === 0 && cut.length === 0) {
-    return { issues, closing: false, reason: 'no-outcomes' }
+  if (closed.length === 0 && cut.length === 0 && operator.length === 0) {
+    return { issues, closing: false, reason: 'no-outcomes', operatorChecks }
   }
 
-  return { issues, closing: true, reason: 'last-slice' }
+  return { issues, closing: true, reason: 'last-slice', operatorChecks }
 }
 
 /** Resolves the task through the same selector `pull-request` takes. */

package/src/tasks/validate.ts

@@ -1315,8 +1315,10 @@ async function checkCitedTask(
   }
 
   const text = await readFile(live, 'utf8')
-  const { open, closed } = readOutcomes(text)
-  if (open.length > 0 || closed.length === 0) return nothing()
+  const { open, closed, operator } = readOutcomes(text)
+  if (open.length > 0 || closed.length + operator.length === 0) {
+    return nothing()
+  }
 
   const pending = readPendingBranches(text)
   if (pending.length > 0) {

package/tooling/claude/reference.md

@@ -69,7 +69,9 @@ A project installed before the board became a folder still holds `.claude/TASKS.
 - Keep only what is project-specific in the project file, since project settings layer over user settings
 - Expect `permissions.deny` to hold `Agent` and `Task`, so no session spawns a subagent and parallel work runs as separate background sessions
 - Expect `autoMemoryEnabled` to be `false`. A person turns it back on for themselves in `settings.local.json`.
-- Run `canon migrate session-defaults` on a target seeded before those two defaults, since sync never rewrites an existing settings file
+- Run `canon migrate session-defaults` on a target seeded before those two defaults or before the merge entries below, since sync never rewrites an existing settings file
+
+The seed's deny list also holds `Bash(canon pr merge:*)` and `Bash(gh pr merge:*)`, so the operator alone merges. An existing target gets both from `canon migrate session-defaults --write`, and `canon claude sync` warns while either is absent. Neither covers more than the form an agent writes by default.
 
 ## User settings
 

package/tooling/claude/seeds/.claude/settings.json

@@ -1,7 +1,7 @@
 {
   "autoMemoryEnabled": false,
   "permissions": {
-    "deny": ["Agent", "Task"]
+    "deny": ["Agent", "Task", "Bash(canon pr merge:*)", "Bash(gh pr merge:*)"]
   },
   "hooks": {
     "PreToolUse": [