@erclx/canon 5.48.0 → 5.50.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

@@ -1,6 +1,7 @@
 import { existsSync, statSync } from 'node:fs'
 import { readdir, readFile } from 'node:fs/promises'
 import { join, resolve } from 'node:path'
+import { codeSpans, unbrokenRun } from '@/markdown/tables'
 import {
   archiveDir,
   declinedDir,
@@ -23,6 +24,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 +156,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 +243,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())
@@ -1071,28 +1085,30 @@ function checkFolderClaims(
 /**
  * The widest the longest unbroken run in a code span may be before a table
  * scrolls in the preview pane. A 57-character span fit and a 78-character one
- * did not, so the limit sits at the nearest round number above the first.
+ * did not, so the limit sits at the nearest round number above the first. It
+ * is still too high: a 36-character path with no hyphen widened a board column
+ * until the next one ran off the pane, which is why a table cell reads the same
+ * measure at 30. The board keeps 60 until its own report is revisited.
  */
 const WIDE_LIMIT = 60
 
 /**
- * Reports a code span a table cell cannot wrap. A span breaks only at
- * whitespace, so the longest whitespace-free run is what is measured, and a
- * link target is stripped first because only its label renders. Every group is
- * scanned, since the overflow this exists for happened under `## Up next`,
- * where the folder-claim scan would not have looked. Prose breaks at spaces
- * and bare words at hyphens, so only a span is read.
+ * Reports a code span a table cell cannot wrap, measured by `unbrokenRun`,
+ * which `canon markdown audit` reads for a table too. A rendered preview breaks
+ * a span at whitespace and after a hyphen or a slash, so a long run either
+ * widens its column or splits mid-token. Every group is scanned, since the
+ * overflow this exists for happened under `## Up next`, where the folder-claim
+ * scan would not have looked. Prose breaks at spaces and bare words at hyphens,
+ * so only a span is read.
  */
 function checkWideTokens(rows: readonly BoardRow[]): WideToken[] {
   const wide: WideToken[] = []
 
   for (const row of rows) {
     for (const cell of row.cells) {
-      const spans = cell.replace(/\]\([^)]*\)/g, ']').match(/`[^`]+`/g) ?? []
-
-      for (const span of spans) {
-        const text = span.slice(1, -1)
-        const run = Math.max(...text.split(/\s+/).map((part) => part.length))
+      for (const text of codeSpans(cell)) {
+        const span = `\`${text}\``
+        const run = unbrokenRun(text)
 
         if (/\{[^}]*,[^}]*\}/.test(text)) {
           wide.push({
@@ -1516,6 +1532,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 +1605,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

@@ -57,6 +57,7 @@ A project installed before the board became a folder still holds `.claude/TASKS.
 
 - Fill in the seed's placeholder project name, description, and key paths after init
 - Keep its sections `Context`, `Commands`, and `Key paths`, since skills detect, extend, or skip by heading
+- Group `Key paths` under H3s, each opening on a lead sentence, before it runs past 5 bullets. `canon markdown audit` and `canon claude sync` both report a longer run.
 - Keep the `Context` section to one line pointing at the state docs, since `plan-feature` does the parallel read when invoked
 
 ## Seed docs

package/tooling/claude/seeds/.claude/hooks/standards-audit.sh

@@ -81,6 +81,11 @@ colons=$(printf '%s' "$record" |
 density=$(printf '%s' "$record" |
   jq -r '.entries[]?.density[]? | ":\(.line)  \(.kind)  " + (if .limit == null then "opens with neither a paragraph nor a table" else "\(.value) past \(.limit)" end) + (if .gating then "  gating" else "" end)' 2>/dev/null)
 
+# Table findings report and never gate, so each kind is handed back with the
+# fix its shape takes rather than the seam a density finding splits at.
+tables=$(printf '%s' "$record" |
+  jq -r '.entries[]?.tables[]? | ":\(.line)  \(.kind)  " + (if .limit == null then "a list follows the table with no lead sentence" else "\(.value) past \(.limit)" end)' 2>/dev/null)
+
 # A page marked `kind: reference` carries reference shape findings, handed back
 # whole the same way, since a gated one fails the push like a density finding.
 shape=$(printf '%s' "$record" |
@@ -92,7 +97,7 @@ shape=$(printf '%s' "$record" |
 empty=$(printf '%s' "$record" |
   jq -r '[.bans.emptySets[]?] | join(", ")' 2>/dev/null)
 
-[ -z "$hits" ] && [ -z "$headings" ] && [ -z "$colons" ] && [ -z "$density" ] && [ -z "$shape" ] && [ -z "$unread" ] && [ -z "$empty" ] && exit 0
+[ -z "$hits" ] && [ -z "$headings" ] && [ -z "$colons" ] && [ -z "$density" ] && [ -z "$tables" ] && [ -z "$shape" ] && [ -z "$unread" ] && [ -z "$empty" ] && exit 0
 
 nl=$'\n'
 msg=""
@@ -125,6 +130,11 @@ if [ -n "$density" ]; then
   msg="${msg:+$msg$nl}$found"
 fi
 
+if [ -n "$tables" ]; then
+  found=$(printf 'Standards-audit: %s breaks the markdown table limits, being a 120-character cell, 8 body rows, a list directly after a table, and a code span holding a run past 30 characters. These report and never fail a push. Move a long cell into a bullet under the table'"'"'s lead, split a long table into groups each under a lead sentence, give a trailing list its own lead sentence, and move a wide token out of the table.\n%s' "$file" "$tables")
+  msg="${msg:+$msg$nl}$found"
+fi
+
 if [ -n "$shape" ]; then
   found=$(printf 'Standards-audit: %s is marked kind: reference and breaks its shape, being an opening, then Output, Refusals, and See also, each at most once and in that order, no H3, and no flag table. Point at the command'"'"'s own --help for flags. A finding marked gating fails the push.\n%s' "$file" "$shape")
   msg="${msg:+$msg$nl}$found"

package/tooling/claude/seeds/CLAUDE.md

@@ -15,5 +15,14 @@
 
 ## Key paths
 
+### Code
+
+[One sentence on what the code paths below hold]
+
 - `src/`: [description]
+
+### Content
+
+[One sentence on what the content paths below hold]
+
 - `canon/DESIGN.md`: visual intent, pointing at the stylesheet that holds the values