@erclx/canon 5.47.0 → 5.49.0

package/src/tasks/archive.ts

@@ -1,7 +1,11 @@
 import { existsSync } from 'node:fs'
+import { execa } from 'execa'
 import { mkdir, readdir, readFile, rename, writeFile } from 'node:fs/promises'
 import { basename, dirname, join, relative, resolve, sep } from 'node:path'
+import { gitEnv } from '@/git/env'
 import { regenOne } from '@/indexes/regen'
+import { rerenderRow } from '@/tasks/board'
+import { planBranch } from '@/tasks/branch'
 import { isUnder } from '@/tasks/paths'
 import { recordDir, recordDirs } from '@/roots/record'
 
@@ -115,6 +119,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. */
@@ -126,8 +132,25 @@ export interface ArchiveRefused {
   readonly reason: ArchiveRefusal
   readonly message: string
   readonly detail: readonly string[]
+  /**
+   * The slice plan a merged pull request settled while its task stayed open,
+   * moved into the archive. Set only on `earlier-slice` and `open-outcomes`.
+   */
+  readonly slice?: PlanMove
 }
 
+/**
+ * Answers the head branch a pull request merged from, or undefined when it
+ * cannot be read. Tests supply one rather than reaching for `gh`.
+ */
+export type HeadReader = (pullRequest: number) => Promise<string | undefined>
+
+export interface ArchiveOptions {
+  readonly head?: HeadReader
+}
+
+const GH_TIMEOUT_MS = 15_000
+
 export type ArchiveOutcome = ArchiveSuccess | ArchiveRefused
 
 export interface DeclineSuccess {
@@ -159,6 +182,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 +222,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 +260,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 +281,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 }
 }
 
 /**
@@ -913,6 +946,7 @@ async function resolveStem(
 export async function archiveTask(
   root: string,
   selector: TaskSelector,
+  options: ArchiveOptions = {},
 ): Promise<ArchiveOutcome> {
   const dir = tasksDir(root)
 
@@ -932,9 +966,13 @@ export async function archiveTask(
   // while the last slice is still open. Only the last number closes the task.
   const last = readPullRequest(text).at(-1)
   if (selector.kind === 'pull-request' && last !== selector.number) {
-    return refuse(
-      'earlier-slice',
-      `${stem} lists #${last} after #${selector.number}, so the task closes when #${last} merges.`,
+    return withMergedSlice(
+      refuse(
+        'earlier-slice',
+        `${stem} lists #${last} after #${selector.number}, so the task closes when #${last} merges.`,
+      ),
+      { dir, root, stem, text, number: selector.number },
+      options.head ?? ghHeadReader(root),
     )
   }
 
@@ -951,17 +989,24 @@ export async function archiveTask(
     )
   }
 
-  const { open, closed, cut } = readOutcomes(text)
+  const { open, closed, cut, operator } = readOutcomes(text)
 
   if (open.length > 0) {
-    return refuse(
+    const refused = refuse(
       'open-outcomes',
       `${stem} has ${open.length} open outcome(s). Close them, or cut one with \`- ~~<outcome>~~ <why>\`, then archive.`,
       open,
     )
+    return selector.kind === 'pull-request'
+      ? withMergedSlice(
+          refused,
+          { dir, root, stem, text, number: selector.number },
+          options.head ?? ghHeadReader(root),
+        )
+      : refused
   }
 
-  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,11 +1065,112 @@ export async function archiveTask(
     ready: ready || undefined,
     closed: closed.length,
     cut: cut.length,
+    operatorChecks: operator,
     relinked,
     relinkFailed: failed,
   }
 }
 
+interface MergedSlice {
+  readonly dir: string
+  readonly root: string
+  readonly stem: string
+  readonly text: string
+  readonly number: number
+}
+
+/**
+ * Moves the slice plan a merged pull request built into the archive while its
+ * task stays open, and retargets the task's `Plan:` line at it, so the board
+ * row drops the slice through `livePlans`. The refusal still answers, since
+ * the task did not close.
+ *
+ * Only a task citing more than one live plan has a slice to drop. The plan is
+ * the one whose derived branch is the pull request's head, so a plan a worker
+ * renamed off its branch matches nothing and moves nothing. A plan another
+ * live task cites stays, for the reason `plansToArchive` gives, and an
+ * unreadable head leaves everything as it was.
+ */
+async function withMergedSlice(
+  refused: ArchiveRefused,
+  merged: MergedSlice,
+  head: HeadReader,
+): Promise<ArchiveRefused> {
+  const { dir, root, stem, text } = merged
+  const live = readPlanTargets(text).flatMap((target) => {
+    const path = resolveLivePlan(target, dir, root)
+    return path && existsSync(path) ? [{ target, path }] : []
+  })
+  if (new Set(live.map((entry) => entry.path)).size < 2) return refused
+
+  const branch = await head(merged.number)
+  if (branch === undefined) return refused
+
+  const slice = live.find((entry) => {
+    const derived = planBranch(root, entry.path)
+    return derived.ok && derived.branch === branch
+  })
+  if (!slice) return refused
+
+  const shared = await otherTasksCitingPlan(dir, root, slice.path, stem)
+  if (shared.length > 0) return refused
+
+  const move = {
+    from: slice.path,
+    to: join(recordDir(root, PLANS, ARCHIVE), basename(slice.path)),
+  }
+  if (existsSync(move.to)) return refused
+
+  await movePlans([move])
+  const targets = live.filter((entry) => entry.path === slice.path)
+  await writeFile(
+    join(dir, `${stem}.md`),
+    retargetPlanLine(
+      text,
+      new Map(targets.map((entry) => [entry.target, linkTo(dir, move.to)])),
+    ),
+  )
+  // The closing path clears its row, and this one keeps it, so the row is
+  // rendered again to drop the slice from its Plan and Touches cells. A row
+  // the board cannot write, being absent or busy, stays for `validate` to report.
+  await rerenderRow(root, stem)
+
+  return { ...refused, slice: move }
+}
+
+/**
+ * Reads a pull request's head branch through `gh`, in the repository `root`
+ * resolves to. No `gh` on the path, or a failed read, answers undefined, so a
+ * machine without it keeps a slice plan live rather than guessing.
+ */
+export function ghHeadReader(root: string): HeadReader {
+  return async (pullRequest) => {
+    if (Bun.which('gh') === null) return undefined
+
+    try {
+      // `gh` resolves its repository through git, so the hook's resolution
+      // variables would point it elsewhere. `reclaim.ts` strips them the same way.
+      const result = await execa(
+        'gh',
+        [
+          'pr',
+          'view',
+          String(pullRequest),
+          '--json',
+          'headRefName',
+          '--jq',
+          '.headRefName',
+        ],
+        { cwd: root, timeout: GH_TIMEOUT_MS, env: gitEnv(), extendEnv: false },
+      )
+      const branch = result.stdout.trim()
+      return branch.length > 0 ? branch : undefined
+    } catch {
+      return undefined
+    }
+  }
+}
+
 interface PlansToArchive {
   readonly moves: readonly PlanMove[]
   /** Each moved target as the line wrote it, mapped to its link from `taskDir`. */

package/src/tasks/board.ts

@@ -13,6 +13,7 @@ import {
   BOARD_GROUPS,
   type BoardGroup,
   backlogPath,
+  declaredRows,
   type FindingKind,
   groupRuleFindings,
   orderingPath,
@@ -30,8 +31,15 @@ export const GROUP_COLUMNS: Readonly<Record<BoardGroup, readonly string[]>> = {
   'Needs a plan': ['Task', 'Waiting on'],
 }
 
-/** How many declared paths a `Touches` cell spells out before it counts the rest. */
-const TOUCHES_SHOWN = 3
+/**
+ * How many folders a `Touches` cell names. A backticked path never wraps, so
+ * three of them pushed a table past an editor preview, and two short folders
+ * fit beside the count.
+ */
+const TOUCHES_FOLDERS = 2
+
+/** How deep a `Touches` folder reads, as in `src/tasks/` or `claude/skills/`. */
+const FOLDER_DEPTH = 2
 
 /**
  * The widest a `Waiting on` cell may render. The live board's cells measured 14
@@ -205,6 +213,8 @@ export interface DerivedCells {
   readonly task: string
   readonly touches: string
   readonly plan: string
+  /** The declared paths the Touches cell counts, which the overlap checks read in its place. */
+  readonly paths: readonly string[]
 }
 
 function titleOf(text: string): string | undefined {
@@ -227,17 +237,41 @@ function planLabel(path: string): string {
 }
 
 /**
- * The first `TOUCHES_SHOWN` declared paths, then a count of the rest. A task
- * sliced over several plans reads their union, so the tail names the plans in
- * the plural.
+ * The folder a path sits under, `FOLDER_DEPTH` segments deep at most and with a
+ * trailing slash, or undefined for a file at the root.
  */
-export function touchesCell(paths: readonly string[], plans: number): string {
-  const shown = paths.slice(0, TOUCHES_SHOWN).map((path) => `\`${path}\``)
-  const rest = paths.length - shown.length
-  if (rest === 0) return shown.join(', ')
+function folderOf(path: string): string | undefined {
+  const segments = path.split('/').slice(0, -1).slice(0, FOLDER_DEPTH)
+  return segments.length === 0 ? undefined : `${segments.join('/')}/`
+}
 
-  const lists = plans > 1 ? 'the plans list' : 'the plan lists'
-  return `${shown.join(', ')}, and ${rest} more files ${lists}`
+/**
+ * A count of the declared paths and the folders holding most of them, at most
+ * `TOUCHES_FOLDERS`, with ties going to the folder declared first. The file
+ * list lives in the plan the row links, so the cell only says where a row
+ * works. Root files count and name no folder.
+ */
+export function touchesCell(paths: readonly string[]): string {
+  if (paths.length === 0) return ''
+
+  const counts = new Map<string, number>()
+  for (const path of paths) {
+    const folder = folderOf(path)
+    if (folder !== undefined) counts.set(folder, (counts.get(folder) ?? 0) + 1)
+  }
+
+  const folders = [...counts.entries()]
+    .sort((left, right) => right[1] - left[1])
+    .map(([folder]) => folder)
+  const shown = folders
+    .slice(0, TOUCHES_FOLDERS)
+    .map((folder) => `\`${folder}\``)
+  const files = paths.length === 1 ? '1 file' : `${paths.length} files`
+  if (shown.length === 0) return files
+
+  const rest = folders.length - shown.length
+  const tail = rest === 0 ? '' : `, and ${rest} more`
+  return `${files} under ${shown.join(', ')}${tail}`
 }
 
 /**
@@ -270,6 +304,7 @@ export async function deriveCells(
       task: `[${row.label || row.stem}](${row.stem}.md)`,
       touches: '',
       plan: '',
+      paths: [],
     }
   }
 
@@ -279,13 +314,15 @@ export async function deriveCells(
     plans.map(async (plan) => readDeclarations(await readFile(plan, 'utf8'))),
   )
   const dir = tasksDir(root)
+  const paths = [...new Set(declared.flat())]
 
   return {
     task: `[${titleOf(text) ?? (row.label || row.stem)}](${row.stem}.md)`,
-    touches: touchesCell([...new Set(declared.flat())], plans.length),
+    touches: touchesCell(paths),
     plan: plans
       .map((plan) => `[${planLabel(plan)}](${linkTo(dir, plan)})`)
       .join(', '),
+    paths,
   }
 }
 
@@ -594,7 +631,8 @@ async function writeLocked(
 
   if (edited.ruled) {
     const forbidden = GROUP_RULES[edited.ruled]
-    const broken = (await groupRuleFindings(readBoard(text).rows, root)).filter(
+    const rows = await declaredRows(readBoard(text).rows, root)
+    const broken = (await groupRuleFindings(rows, root)).filter(
       (finding) => finding.subject === stem && forbidden.includes(finding.kind),
     )
     if (broken.length > 0) {
@@ -793,6 +831,23 @@ export async function promoteOnLink(
     : { moved: false, from: found.group, note: outcome.message }
 }
 
+/**
+ * Rewrites the board with a task's row where it sits, so its derived cells
+ * catch up with a plan that moved under it. A merged slice archives its plan
+ * from the post-merge hook, where no other board verb runs.
+ */
+export async function rerenderRow(
+  root: string,
+  stem: string,
+): Promise<BoardOutcome> {
+  return writeBoard(root, stem, (board) => {
+    const found = findRow(board, stem)
+    if (!found) return refuse('no-row', `${stem} has no row on the board.`)
+
+    return { board, group: found.group, from: found.group, ruled: undefined }
+  })
+}
+
 /** Repositions a row inside the group it already sits in. */
 export async function moveTask(
   root: string,

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

@@ -23,6 +23,9 @@ import { gitTrunkReader, type TrunkReader } from '@/tasks/trunk'
 const ORDERING_FILE = 'priority.md'
 const BACKLOG_FILE = 'backlog.md'
 
+/** The opening `touchesCell` writes, as in `12 files under` or a bare `2 files`. */
+const DERIVED_COUNT = /^\d+ files?(?: under |$)/
+
 /**
  * The readiness headings `claude/skills/task-board/references/board.md` fixes. The names are the
  * contract rather than a suggestion, so a board grouping under names of its own
@@ -152,7 +155,11 @@ export interface BoardRow {
   readonly label: string
   readonly stem: string | undefined
   readonly plan: string | undefined
-  /** Absent when the group fixes no `Touches` column, empty when it read none. */
+  /**
+   * Absent when the group fixes no `Touches` column, empty when it read none.
+   * `readBoard` reads the written cell, and `declaredRows` replaces it with the
+   * paths the task's plans declare.
+   */
   readonly touches: readonly string[] | undefined
   /** The `Touches` cell as written, which the stale check compares against the derivation. */
   readonly touchesText: string | undefined
@@ -235,8 +242,14 @@ function stemOf(target: string): string | undefined {
  * An extension opens with a letter, which is what separates `commands.md` from
  * a task version like `v40.2`. Reading the version as a path would collide two
  * rows that merely cite the same task.
+ *
+ * A cell a board verb derived opens with its file count, and its folders say
+ * where the row works rather than claiming every file under them, so it yields
+ * nothing. Its reader takes the declared paths from the plans instead.
  */
 export function readPaths(cell: string): string[] {
+  if (DERIVED_COUNT.test(cell.trim())) return []
+
   const spans = cell.match(/`[^`]+`/g) ?? []
   const paths = spans
     .map((span) => span.slice(1, -1).trim())
@@ -1315,8 +1328,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) {
@@ -1514,6 +1529,29 @@ async function checkStaleTouches(
   return found.filter((finding): finding is Finding => finding !== undefined)
 }
 
+/**
+ * Gives each row the paths its task's live plans declare in place of the ones
+ * read off its `Touches` cell, which states a count and folders rather than
+ * files. A row whose task is gone, or whose plans declare nothing, keeps what
+ * its cell named, so a hand-written cell still feeds the overlap checks.
+ */
+export async function declaredRows(
+  rows: readonly BoardRow[],
+  root: string,
+): Promise<BoardRow[]> {
+  return Promise.all(
+    rows.map(async (row) => {
+      if (row.touches === undefined || !row.stem) return row
+
+      const { paths } = await deriveCells(root, {
+        stem: row.stem,
+        label: row.label,
+      })
+      return paths.length === 0 ? row : { ...row, touches: paths }
+    }),
+  )
+}
+
 /**
  * The claims a group name makes about a row, being a stated plan and file set
  * under `## Run now`, a live plan under `## Up next`, and none under
@@ -1564,10 +1602,11 @@ export async function validateBoard(
   }
 
   const {
-    rows,
+    rows: written,
     groups,
     findings: shapeFindings,
   } = readBoard(await readFile(ordering, 'utf8'))
+  const rows = await declaredRows(written, root)
 
   if (groups.length === 0) {
     return refuse(

package/tooling/base/configs/.github/workflows/pr-local-preview.yml

@@ -24,7 +24,7 @@ jobs:
         with:
           bun-version: latest
 
-      - name: Drop the preview line from the evidence comment
+      - name: Drop the evidence preview line and mask UI review addresses
         if: github.event.pull_request.head.repo.full_name == github.repository
         env:
           GH_TOKEN: ${{ github.token }}

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": [