@erclx/canon 5.48.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'
 
@@ -128,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 {
@@ -925,6 +946,7 @@ async function resolveStem(
 export async function archiveTask(
   root: string,
   selector: TaskSelector,
+  options: ArchiveOptions = {},
 ): Promise<ArchiveOutcome> {
   const dir = tasksDir(root)
 
@@ -944,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),
     )
   }
 
@@ -966,11 +992,18 @@ export async function archiveTask(
   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 && operator.length === 0) {
@@ -1038,6 +1071,106 @@ export async function archiveTask(
   }
 }
 
+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/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())
@@ -1516,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
@@ -1566,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 }}