@erclx/canon 5.42.0 → 5.44.0

package/src/commands/tasks.ts

@@ -3,6 +3,17 @@ import type { Command } from 'commander'
 import { execa } from 'execa'
 import { gitEnv } from '@/git/env'
 import { type AnswersOutcome, planAnswers } from '@/tasks/answers'
+import {
+  type BoardOutcome,
+  type BoardRefused,
+  blockTask,
+  moveTask,
+  PLANNED_WAITING,
+  type Position,
+  placeTask,
+  promoteTask,
+  WAITING_LIMIT,
+} from '@/tasks/board'
 import { type BranchOutcome, planBranch } from '@/tasks/branch'
 import {
   type ArchiveOutcome,
@@ -40,6 +51,7 @@ import {
   recordPullRequest,
 } from '@/tasks/record'
 import {
+  type BoardGroup,
   type Finding,
   type FolderClaim,
   type SharedFiles,
@@ -118,6 +130,7 @@ interface PullRequestCommandOptions {
 
 interface PlanLinkCommandOptions {
   readonly add?: boolean
+  readonly waiting?: string
   readonly json?: boolean
   readonly root?: string
 }
@@ -140,6 +153,31 @@ interface NextLabelCommandOptions {
   readonly root?: string
 }
 
+interface BoardCommandOptions {
+  readonly json?: boolean
+  readonly root?: string
+}
+
+interface PositionCommandOptions {
+  readonly top?: boolean
+  readonly bottom?: boolean
+  readonly before?: string
+  readonly after?: string
+}
+
+interface PlaceCommandOptions
+  extends BoardCommandOptions, PositionCommandOptions {
+  readonly group: string
+  readonly waiting?: string
+}
+
+interface PromoteCommandOptions extends BoardCommandOptions {
+  readonly waiting?: string
+}
+
+interface MoveCommandOptions
+  extends BoardCommandOptions, PositionCommandOptions {}
+
 export function register(program: Command): void {
   const tasks = program
     .command('tasks')
@@ -259,6 +297,10 @@ export function register(program: Command): void {
         '  every task file carries a board row or a backlog line, never both',
         '  no task carries more than one row',
         '  every Run now row names the files it touches',
+        '  every Touches cell matches what its plans derive',
+        '  every group header is the set of columns the group owns',
+        `  no Waiting on cell renders past ${WAITING_LIMIT} characters`,
+        '  a blocker citing a bare vNNN.N label settles like a linked one',
         '  a file two Run now rows share is listed, never failed',
         '',
         'Refusals, read off `reason`:',
@@ -493,6 +535,10 @@ export function register(program: Command): void {
       '--add',
       'Append the plan to the line, for a task sliced over plans',
     )
+    .option(
+      '--waiting <text>',
+      `The Waiting on cell a promoted row carries, "${PLANNED_WAITING}" when omitted`,
+    )
     .option('--json', 'Emit a machine-readable record on stdout')
     .option('--root <path>', 'Board root, defaulting to the main worktree')
     .addHelpText(
@@ -521,6 +567,10 @@ export function register(program: Command): void {
         'sliced task links one plan per slice. It reports unchanged when the',
         'plan is already listed and is allowed on a line holding several.',
         '',
+        'A row under Needs a plan moves to the bottom of Up next through the',
+        'board verbs, and `board` in the record says whether it moved and why',
+        'not. A row elsewhere, or a task with no row, stays where it is.',
+        '',
         'Examples:',
         '  canon tasks plan-link v28.1-trigger-escalation dispatch-answer-gate',
         '  canon tasks plan-link v28.1-trigger-escalation second-slice --add',
@@ -661,6 +711,327 @@ export function register(program: Command): void {
     .action(async (opts: ListCommandOptions) => {
       process.exitCode = await runList(opts)
     })
+
+  registerBoardWrites(tasks)
+}
+
+const BOARD_WRITE_REFUSALS = [
+  'Refusals, read off `reason`:',
+  '  no-board        the repository holds no `.canon/tasks/` board',
+  '  no-ordering     the board has no priority.md',
+  '  no-match        no task file carries the stem',
+  '  no-row          the task has no row on the board',
+  '  unreadable-row  a row names no task, or its header cannot place its blocker',
+  '  board-busy      another board verb held the lock past the wait, so run it again',
+  '  board-changed   a hand edit landed while this one rendered, so run it again',
+  '  group-rule      the target group forbids the row, naming the validate kind',
+  '  no-column       the row sits under Run now, which has no Waiting on cell',
+  '  top-group       the row already sits under Run now',
+  `  cell-long       the Waiting on cell renders past ${WAITING_LIMIT} characters`,
+  '  bad-input       a malformed group, position, or Waiting on text',
+  '',
+  'Exit codes:',
+  '  0  the board was written',
+  '  1  refused, with the reason on stderr or in the JSON record',
+  '',
+  'Every write reads priority.md once, renders every table from the task',
+  'files and their plans, and writes it once. Task, Touches, and Plan are',
+  'derived, so only Waiting on is typed. Safe from a linked worktree, since',
+  'it resolves the board root in-process.',
+]
+
+const GROUP_FLAGS: Readonly<Record<string, BoardGroup>> = {
+  'run-now': 'Run now',
+  'up-next': 'Up next',
+  'needs-a-plan': 'Needs a plan',
+}
+
+function withPosition(command: Command): Command {
+  return command
+    .option('--top', 'Put the row first in its group')
+    .option('--bottom', 'Put the row last in its group, the default')
+    .option('--before <task>', 'Put the row right above this sibling')
+    .option('--after <task>', 'Put the row right below this sibling')
+}
+
+function registerBoardWrites(tasks: Command): void {
+  withPosition(
+    tasks
+      .command('place')
+      .description(
+        'Put a task under a board group, from another group, the backlog, or nowhere',
+      )
+      .argument('<task>', 'Task filename stem, as in v28.1-trigger-escalation')
+      .requiredOption(
+        '--group <group>',
+        'Target group: run-now, up-next, or needs-a-plan',
+      )
+      .option('--waiting <text>', 'The Waiting on cell, kept when omitted'),
+  )
+    .helpOption('-h, --help', 'Show this help message')
+    .option('--json', 'Emit a machine-readable record on stdout')
+    .option('--root <path>', 'Board root, defaulting to the main worktree')
+    .addHelpText(
+      'after',
+      [
+        '',
+        ...BOARD_WRITE_REFUSALS,
+        '',
+        'A backlog line for the task is removed in the same call. The row keeps',
+        'its Waiting on cell when --waiting is omitted, and a row new to Up next',
+        'or Needs a plan has none to keep, so it needs one.',
+        '',
+        'Examples:',
+        '  canon tasks place v28.1-trigger-escalation --group needs-a-plan --bottom --waiting "Not planned yet"',
+        '  canon tasks place v28.1-trigger-escalation --group up-next --before v28.2-other --json',
+        '',
+      ].join('\n'),
+    )
+    .action(async (task: string, opts: PlaceCommandOptions) => {
+      process.exitCode = await runPlace(task, opts)
+    })
+
+  tasks
+    .command('promote')
+    .description('Move a row one group closer to Run now, to its bottom')
+    .argument('<task>', 'Task filename stem, as in v28.1-trigger-escalation')
+    .helpOption('-h, --help', 'Show this help message')
+    .option(
+      '--waiting <text>',
+      `The Waiting on cell a row entering Up next carries, "${PLANNED_WAITING}" when omitted`,
+    )
+    .option('--json', 'Emit a machine-readable record on stdout')
+    .option('--root <path>', 'Board root, defaulting to the main worktree')
+    .addHelpText(
+      'after',
+      [
+        '',
+        ...BOARD_WRITE_REFUSALS,
+        '',
+        'Up next moves to Run now, which reads as dispatched, so a dispatcher',
+        'runs it once a launch succeeds. Needs a plan moves to Up next.',
+        '',
+        'Examples:',
+        '  canon tasks promote v28.1-trigger-escalation',
+        '  canon tasks promote v28.1-trigger-escalation --json',
+        '',
+      ].join('\n'),
+    )
+    .action(async (task: string, opts: PromoteCommandOptions) => {
+      process.exitCode = await runPromote(task, opts)
+    })
+
+  withPosition(
+    tasks
+      .command('move')
+      .description('Reposition a row inside the group it sits in')
+      .argument('<task>', 'Task filename stem, as in v28.1-trigger-escalation'),
+  )
+    .helpOption('-h, --help', 'Show this help message')
+    .option('--json', 'Emit a machine-readable record on stdout')
+    .option('--root <path>', 'Board root, defaulting to the main worktree')
+    .addHelpText(
+      'after',
+      [
+        '',
+        ...BOARD_WRITE_REFUSALS,
+        '',
+        'Examples:',
+        '  canon tasks move v28.1-trigger-escalation --top',
+        '  canon tasks move v28.1-trigger-escalation --after v28.2-other --json',
+        '',
+      ].join('\n'),
+    )
+    .action(async (task: string, opts: MoveCommandOptions) => {
+      process.exitCode = await runMove(task, opts)
+    })
+
+  tasks
+    .command('block')
+    .description("Rewrite a row's Waiting on cell")
+    .argument('<task>', 'Task filename stem, as in v28.1-trigger-escalation')
+    .argument(
+      '<waiting>',
+      `What the row waits on, at most ${WAITING_LIMIT} rendered characters`,
+    )
+    .helpOption('-h, --help', 'Show this help message')
+    .option('--json', 'Emit a machine-readable record on stdout')
+    .option('--root <path>', 'Board root, defaulting to the main worktree')
+    .addHelpText(
+      'after',
+      [
+        '',
+        ...BOARD_WRITE_REFUSALS,
+        '',
+        'A link counts as its label alone toward the cap, since only the label',
+        'renders.',
+        '',
+        'Examples:',
+        '  canon tasks block v28.1-trigger-escalation "[v28.2](v28.2-other.md) merging"',
+        '  canon tasks block v28.1-trigger-escalation "The operator\'s call on the scope" --json',
+        '',
+      ].join('\n'),
+    )
+    .action(
+      async (task: string, waiting: string, opts: BoardCommandOptions) => {
+        process.exitCode = await runBlock(task, waiting, opts)
+      },
+    )
+}
+
+/**
+ * Reads the one position flag a call may carry. Two flags at once is refused
+ * rather than resolved by precedence, since either reading moves a row the
+ * caller did not mean to.
+ */
+function positionFrom(
+  opts: PositionCommandOptions,
+): Position | undefined | BoardRefused {
+  const given: Position[] = [
+    ...(opts.top ? [{ at: 'top' } as const] : []),
+    ...(opts.bottom ? [{ at: 'bottom' } as const] : []),
+    ...(opts.before ? [{ before: opts.before }] : []),
+    ...(opts.after ? [{ after: opts.after }] : []),
+  ]
+
+  if (given.length > 1) {
+    return {
+      ok: false,
+      reason: 'bad-input',
+      message: 'Pass one of --top, --bottom, --before, or --after.',
+      detail: [],
+    }
+  }
+
+  return given[0]
+}
+
+async function runPlace(
+  task: string,
+  opts: PlaceCommandOptions,
+): Promise<number> {
+  const emitJson = opts.json ?? false
+  const group = GROUP_FLAGS[opts.group]
+  if (!group) {
+    return reportRecord(
+      'canon tasks place',
+      {
+        ok: false,
+        reason: 'bad-input',
+        message: `Not a group: ${opts.group}. Pass run-now, up-next, or needs-a-plan.`,
+        detail: [opts.group],
+      },
+      emitJson,
+      process.cwd(),
+    )
+  }
+
+  const position = positionFrom(opts)
+  if (position && 'ok' in position) {
+    return reportRecord('canon tasks place', position, emitJson, process.cwd())
+  }
+
+  const root = opts.root ?? (await mainWorktreeRoot())
+  const outcome = await placeTask(root, task, group, {
+    waiting: opts.waiting,
+    position,
+  })
+
+  return reportBoardWrite('canon tasks place', outcome, emitJson, root)
+}
+
+async function runPromote(
+  task: string,
+  opts: PromoteCommandOptions,
+): Promise<number> {
+  const root = opts.root ?? (await mainWorktreeRoot())
+  const outcome = await promoteTask(root, task, { waiting: opts.waiting })
+
+  return reportBoardWrite(
+    'canon tasks promote',
+    outcome,
+    opts.json ?? false,
+    root,
+  )
+}
+
+async function runMove(
+  task: string,
+  opts: MoveCommandOptions,
+): Promise<number> {
+  const emitJson = opts.json ?? false
+  const position = positionFrom(opts)
+  if (position === undefined || 'ok' in position) {
+    return reportRecord(
+      'canon tasks move',
+      position ?? {
+        ok: false,
+        reason: 'bad-input',
+        message:
+          'No position named. Pass --top, --bottom, --before, or --after.',
+        detail: [],
+      },
+      emitJson,
+      process.cwd(),
+    )
+  }
+
+  const root = opts.root ?? (await mainWorktreeRoot())
+  const outcome = await moveTask(root, task, position)
+
+  return reportBoardWrite('canon tasks move', outcome, emitJson, root)
+}
+
+async function runBlock(
+  task: string,
+  waiting: string,
+  opts: BoardCommandOptions,
+): Promise<number> {
+  const root = opts.root ?? (await mainWorktreeRoot())
+  const outcome = await blockTask(root, task, waiting)
+
+  return reportBoardWrite(
+    'canon tasks block',
+    outcome,
+    opts.json ?? false,
+    root,
+  )
+}
+
+function reportBoardWrite(
+  title: string,
+  outcome: BoardOutcome,
+  emitJson: boolean,
+  root: string,
+): number {
+  if (!outcome.ok) return reportRecord(title, outcome, emitJson, root)
+
+  if (emitJson) {
+    process.stdout.write(
+      `${JSON.stringify({
+        ok: true,
+        root,
+        task: outcome.stem,
+        path: relative(root, outcome.path),
+        group: outcome.group,
+        from: outcome.from ?? null,
+        position: outcome.position,
+        backlog: outcome.backlog,
+      })}\n`,
+    )
+    return 0
+  }
+
+  intro(title)
+  logStep('Written')
+  logInfo(
+    `${outcome.stem} sits at ${outcome.position} under ${outcome.group}${outcome.from && outcome.from !== outcome.group ? `, from ${outcome.from}` : ''}`,
+  )
+  if (outcome.backlog) logRemove('its backlog line')
+  logAdd(relative(root, outcome.path))
+  outro()
+
+  return 0
 }
 
 function collectPosition(value: string, previous: string[]): string[] {
@@ -832,7 +1203,13 @@ async function runPlanLink(
 ): Promise<number> {
   const emitJson = opts.json ?? false
   const root = opts.root ?? (await mainWorktreeRoot())
-  const outcome = await recordPlan(root, task, plan, opts.add ?? false)
+  const outcome = await recordPlan(
+    root,
+    task,
+    plan,
+    opts.add ?? false,
+    opts.waiting,
+  )
 
   return reportPlanLink(outcome, emitJson, root)
 }
@@ -900,7 +1277,7 @@ async function runOutcome(
 
 function reportRecord(
   title: string,
-  refused: RecordRefused,
+  refused: RecordRefused | BoardRefused,
   emitJson: boolean,
   root: string,
 ): number {
@@ -985,6 +1362,7 @@ function reportPlanLink(
         plan: outcome.plan,
         action: outcome.action,
         replaced: outcome.replaced,
+        board: { ...outcome.board, from: outcome.board.from ?? null },
       })}\n`,
     )
     return 0
@@ -995,6 +1373,9 @@ function reportPlanLink(
   logInfo(`${outcome.stem} names plan ${outcome.plan}`)
   if (outcome.replaced) logInfo(`replaced ${outcome.replaced}`)
   if (outcome.action !== 'unchanged') logAdd(relative(root, outcome.path))
+  logInfo(
+    `board row ${outcome.board.moved ? '' : 'not moved, '}${outcome.board.note}`,
+  )
   outro()
 
   return 0

package/src/commands/tooling.ts

@@ -18,7 +18,7 @@ import {
 } from '@/tooling/manifest'
 import { readReference, resolveReference } from '@/tooling/read'
 import { scan, type ScanResult } from '@/tooling/scan'
-import { recordedStacks, recordToolingChain } from '@/tooling/stamp'
+import { recordToolingChain } from '@/tooling/stamp'
 import { subfolderPath } from '@/tooling/subfolder'
 import { verifyStack } from '@/tooling/verify-stack'
 import {
@@ -513,8 +513,8 @@ async function stampChain(chain: Manifest[], target: string): Promise<void> {
     new Date(),
   )
 
-  if (recorded) {
-    logInfo(`Recorded chain: ${recordedStacks(chain).join(' < ')}`)
+  if (recorded !== undefined) {
+    logInfo(`Recorded chain: ${recorded.join(' < ')}`)
     return
   }
 

package/src/commands/worktrees.ts

@@ -17,7 +17,9 @@ import {
   type WorktreeVerdict,
 } from '@/worktrees/reclaim'
 import { mainWorktreeRoot } from '@/git/worktree'
+import { machineListenerReader } from '@/listeners/machine'
 import { repairBareFlag } from '@/worktrees/bare-flag'
+import { type StopReport, stopListeners } from '@/worktrees/stop'
 import {
   removeReclaimable,
   type RemovalOutcome,
@@ -57,6 +59,12 @@ export interface ReclaimRecord {
   readonly removed: number
   readonly failed: number
   readonly pruned: boolean
+  /**
+   * Processes signaled, or that a dry run would signal, for listening inside a
+   * reclaimed worktree. Null when the machine offered no way to read
+   * listeners, which says nothing about what is still running.
+   */
+  readonly stopped: number | null
   readonly outcomes: readonly RemovalOutcome[]
 }
 
@@ -79,6 +87,8 @@ export type ReclaimSource =
        * from a run that was asked not to act.
        */
       readonly removal: RemovalReport | null
+      /** Null when no stop ran, which is a reading with nothing reclaimable. */
+      readonly stop?: StopReport | null
     }
 
 const REFUSALS: Record<Refusal, string> = {
@@ -198,6 +208,14 @@ export function register(program: Command): void {
         'deletes its branch, and a run carrying a directory that is already',
         'gone sweeps stale registrations once before the branch deletes.',
         '',
+        'Ahead of each removal it sends SIGTERM to every process listening from',
+        'inside a reclaimable worktree, so no dev server outlives the tree it',
+        'serves. A listener in the main checkout, in a refused worktree, or in',
+        'a worktree nested under another is left alone. A dry run signals',
+        'nothing and still reports what it would stop. "stopped" in the record',
+        'counts those processes, and reads null on a machine with neither lsof',
+        'nor /proc, where no listener could be read.',
+        '',
         'It deletes only what a reading called reclaimable. A worktree a live',
         'session holds is refused rather than removed here. `claude rm <id>`',
         'is meant to remove the session and its worktree together, but its',
@@ -324,11 +342,13 @@ export function reclaimRecord(source: ReclaimSource): ReclaimRecord {
       removed: 0,
       failed: 0,
       pruned: false,
+      stopped: 0,
       outcomes: [],
     }
   }
 
   const outcomes = source.removal?.outcomes ?? []
+  const stop = source.stop ?? null
 
   return {
     reason: null,
@@ -338,10 +358,30 @@ export function reclaimRecord(source: ReclaimSource): ReclaimRecord {
     removed: outcomes.filter((outcome) => outcome.removed).length,
     failed: outcomes.filter((outcome) => !outcome.removed).length,
     pruned: source.removal?.pruned ?? false,
+    stopped: stop === null ? 0 : countStopped(stop),
     outcomes,
   }
 }
 
+function countStopped(stop: StopReport): number | null {
+  if (stop.kind === 'unread') return null
+  return stop.stopped.reduce((sum, server) => sum + server.pids.length, 0)
+}
+
+/** Names each server a stop took, or would take on a dry run, and says when none could be read. */
+function reportStop(stop: StopReport, dryRun: boolean): void {
+  if (stop.kind === 'unread') {
+    logWarn(
+      'This machine offers neither lsof nor /proc, so listening servers were not read and none was stopped.',
+    )
+    return
+  }
+  const verb = dryRun ? 'Would stop' : 'Stopped'
+  for (const { path, ports } of stop.stopped) {
+    logInfo(`${verb} the server on ${ports.join(', ')} in ${path}`)
+  }
+}
+
 function emitReclaim(opts: ReclaimCommandOptions, source: ReclaimSource): void {
   if (opts.json !== true) return
   process.stdout.write(`${JSON.stringify(reclaimRecord(source))}\n`)
@@ -381,8 +421,14 @@ async function runReclaim(opts: ReclaimCommandOptions): Promise<number> {
   logInfo(plural(reclaimable.length, 'worktree'))
   pipeOutput(reclaimable.map(describe).join('\n'))
 
+  const stop = await stopListeners(
+    reclaimable.map((entry) => entry.path),
+    { reader: machineListenerReader(), dryRun },
+  )
+
   if (dryRun) {
     logStep('Dry run')
+    reportStop(stop, dryRun)
     logWarn('Nothing was removed. Run this again without --dry-run to remove.')
     outro()
     emitReclaim(opts, {
@@ -390,6 +436,7 @@ async function runReclaim(opts: ReclaimCommandOptions): Promise<number> {
       dryRun,
       reclaimable: reclaimable.length,
       removal: null,
+      stop,
     })
     return 0
   }
@@ -403,6 +450,7 @@ async function runReclaim(opts: ReclaimCommandOptions): Promise<number> {
   })
 
   logStep('Removed')
+  reportStop(stop, dryRun)
   for (const outcome of removal.outcomes) reportOutcome(outcome)
   if (removal.pruned) {
     logInfo(
@@ -423,6 +471,7 @@ async function runReclaim(opts: ReclaimCommandOptions): Promise<number> {
     dryRun,
     reclaimable: reclaimable.length,
     removal,
+    stop,
   })
   return failed.length > 0 ? 1 : 0
 }

package/src/context/audit.ts

@@ -209,7 +209,7 @@ const SENTENCE_END = /[.!?:;]\s(?=[^.!?:;]*$)/
  * reading that field for a gain of one word.
  *
  * `claude/skills/context-fold/references/context.md` opens its scope by handing figures to the
- * `draft-figure` skill, so a marker reported in a diagrams entry would cite a
+ * `draw-figure` skill, so a marker reported in a diagrams entry would cite a
  * rule that entry's own standard routes elsewhere. The length and table
  * checkpoints are quoted from the same standard and keep reaching every audited
  * folder, because a threshold on how far a reader travels generalizes across

package/src/demo/beats.ts

@@ -1,5 +1,5 @@
 /**
- * Reads the human-facing draft `draft-screencast` writes. Nothing here knows
+ * Reads the human-facing draft `script-screencast` writes. Nothing here knows
  * about a browser: the draft is prose aimed at a person, and turning it into
  * something executable is `@/demo/compile`'s job.
  */

package/src/gate/stages.ts

@@ -380,6 +380,21 @@ export const STAGES: readonly Stage[] = [
     ],
     success: 'Rule citations resolve',
   },
+  {
+    // Reads the whole rule corpus and fails only on a folder the verb lists as
+    // gated, so the finding count prints on every push while the rewrite moves
+    // folder by folder toward zero.
+    id: 'rule-shape',
+    label: 'Rule shape',
+    checks: [
+      {
+        kind: 'cli',
+        argv: ['gov', 'audit', '--gate'],
+        failure:
+          'A rule in a gated folder is past a shape limit or short of its ledger. Run bun src/cli.ts gov audit.',
+      },
+    ],
+  },
   {
     // A citation naming the old record root resolves to nothing once the
     // folders have moved, and the sweep that would repoint it only runs when a