@erclx/canon 5.43.0 → 5.45.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

@@ -1,4 +1,5 @@
-import { resolve } from 'node:path'
+import { existsSync } from 'node:fs'
+import { join, resolve } from 'node:path'
 import type { Command } from 'commander'
 import { checkoutMismatchWarning, PROJECT_ROOT } from '@/roots/project'
 import {
@@ -12,11 +13,16 @@ import { buildStackSummaries, describeStack } from '@/tooling/list'
 import {
   isStackExcluded,
   listStacks,
+  loadManifest,
   type Manifest,
   resolveChain,
   stackExists,
 } from '@/tooling/manifest'
-import { readReference, resolveReference } from '@/tooling/read'
+import {
+  readReference,
+  renderStackSections,
+  resolveReference,
+} from '@/tooling/read'
 import { scan, type ScanResult } from '@/tooling/scan'
 import { recordToolingChain } from '@/tooling/stamp'
 import { subfolderPath } from '@/tooling/subfolder'
@@ -302,6 +308,8 @@ function printReference(stack: string): number {
 
   logStep(resolved.source)
   process.stdout.write(readReference(resolved))
+  const manifest = loadManifest(resolved.root, stack)
+  if (manifest) process.stdout.write(renderStackSections(manifest))
   outro()
   return 0
 }
@@ -625,12 +633,16 @@ function report(result: ScanResult, target: string): void {
     if (entry.state === 'missing') logAdd(entry.rel)
   }
 
-  if (result.hasPackageJson) {
+  if (result.newManifest) {
+    logStep('Scanning package.json')
+    logAdd('package.json')
+    reportPackage(result)
+  } else if (result.hasPackageJson) {
     reportPackage(result)
-  } else {
+  } else if (existsSync(join(target, 'package.json'))) {
     logStep('Scanning package.json')
     logWarn(
-      "Skipped scripts and deps: no package.json found (run 'bun init' to enable)",
+      `Skipped scripts and deps: package.json is not valid JSON (fix it in ${target}, then sync again)`,
     )
   }
 
@@ -688,6 +700,7 @@ function summarize(result: ScanResult): string {
     if (count > 0) parts.push(`${count} ${label}`)
   }
 
+  add(result.newManifest ? 1 : 0, 'package.json')
   add(
     result.configs.filter((entry) => entry.state !== 'matching').length,
     'configs',

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/design/components.ts

@@ -520,7 +520,7 @@ html.sb-shut .pane { border-left: 0; }
 }
 
 /* A bar link is its own tap target rather than a line of text, so it carries
-   the 24 pixel minimum the a11y rule sets. */
+   the 24 pixel minimum the keyboard rule sets. */
 .mast a,
 .mast summary {
   min-height: 1.6rem;

package/src/gov/audit.ts

@@ -27,14 +27,30 @@ export type RuleLimit = keyof typeof RULE_LIMITS | 'emphasis'
  * Rule folders whose findings fail `--gate`, as path prefixes from the root.
  *
  * Each folder's rewrite appends its own line once that folder reaches zero, so
- * the slices merge without touching one another's entries. `canon/` waits on
- * `plan.md`, which a later slice rewrites.
+ * the slices merge without touching one another's entries.
  */
 export const RULE_GATED_FOLDERS: readonly string[] = [
+  join('governance', 'rules', 'canon') + sep,
   join('governance', 'rules', 'claude') + sep,
   join('governance', 'rules', 'code') + sep,
+  join('governance', 'rules', 'framework') + sep,
   join('governance', 'rules', 'writing') + sep,
   join('internal', 'rules') + sep,
+  join('governance', 'rules', 'lang') + sep,
+  join('governance', 'rules', 'lib') + sep,
+  join('governance', 'rules', 'ui') + sep,
+  join('governance', 'rules', 'tooling') + sep,
+]
+
+/**
+ * Rule files in a gated folder whose findings `--gate` still passes, one path
+ * each and never a folder, so a new rule beside one is gated the day it lands.
+ *
+ * `ui/canvas.md` carries a shape finding and no ledger, and v149.2 removes the
+ * rule, so this entry goes with it.
+ */
+export const RULE_GATE_EXEMPT: readonly string[] = [
+  join('governance', 'rules', 'ui', 'canvas.md'),
 ]
 
 /** The folders whose rules claim outside practice, so each carries a ledger. */
@@ -428,13 +444,18 @@ export function hasFinding(reading: RuleReading): boolean {
  */
 export function auditExit(
   report: Extract<RuleAuditReport, { kind: 'measured' }>,
-  options: { readonly gate: boolean; readonly gated: readonly string[] },
+  options: {
+    readonly gate: boolean
+    readonly gated: readonly string[]
+    readonly exempt?: readonly string[]
+  },
 ): number {
   const failing = report.rules.filter(
     (reading) =>
       hasFinding(reading) &&
       (!options.gate ||
-        options.gated.some((prefix) => reading.file.startsWith(prefix))),
+        (options.gated.some((prefix) => reading.file.startsWith(prefix)) &&
+          !options.exempt?.includes(reading.file))),
   )
   return failing.length > 0 ? 2 : 0
 }

package/src/init/plan.ts

@@ -1,4 +1,4 @@
-export const SKIPPABLE_DOMAINS = ['wiki', 'governance', 'records'] as const
+export const SKIPPABLE_DOMAINS = ['governance', 'records'] as const
 
 export type SkippableDomain = (typeof SKIPPABLE_DOMAINS)[number]
 
@@ -97,13 +97,6 @@ export function planInit(flags: InitFlags): InitPlan {
     })
   }
 
-  if (!flags.skip.skipped.has('wiki')) {
-    preview.push({
-      level: 'info',
-      text: 'wiki (.claude/wiki/ with a stub index)',
-    })
-  }
-
   if (!flags.skip.skipped.has('records')) {
     preview.push({
       level: 'info',

package/src/init/steps.ts

@@ -55,14 +55,6 @@ export function buildSteps(
     })
   }
 
-  if (!flags.skip.skipped.has('wiki')) {
-    steps.push({
-      kind: 'run',
-      label: 'Wiki',
-      run: child(['wiki', 'init', resolved]),
-    })
-  }
-
   if (!flags.skip.skipped.has('records')) {
     // `skip` here means there is nothing to run non-interactively, not that
     // the caller opted out, unlike every other push of this kind above.

package/src/inventory/subjects.ts

@@ -27,7 +27,7 @@ export interface Subject {
 
 /**
  * Reports what each element changes about itself when it takes focus, which is
- * the reading `governance/rules/ui/a11y.md` states three rules against and
+ * the reading `governance/rules/ui/keyboard.md` states three rules against and
  * nothing measures.
  *
  * The difference between rest and focus is the treatment, rather than the