@erclx/canon 5.43.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/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/gov/audit.ts

@@ -27,12 +27,13 @@ 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,
 ]

package/src/markdown/scope.ts

@@ -8,19 +8,28 @@ const BULLET_RUN_SCOPE = [
   /^(?:claude|\.claude)\/skills\/[^/]+\/references\/.+\.md$/,
 ]
 
+/**
+ * The requirement beside each skill. Its findings gate only on a `GATED_PATHS`
+ * entry naming the file itself, so the prefix that gates a skill's body never
+ * sweeps in a requirement the rewrite has not reached yet.
+ */
+const REQUIREMENT_SCOPE =
+  /^(?:claude|\.claude)\/skills\/[^/]+\/REQUIREMENT\.md$/
+
 /**
  * The tracked documents the density limits hold: the context entries, the docs
- * pages, the skill bodies and references of both skill trees, the tooling
- * seeds and stack references, the wiki, and the two root guides.
+ * pages, the skill bodies, references, and requirements of both skill trees,
+ * the tooling seeds and stack references, the wiki, and the two root guides.
  *
  * Rules stay out, since a rule is one imperative per bullet. So do
- * `CLAUDE.md`, the requirement and design records, a seed carrying one of
- * those three names, the changelog, the examples, and every `.canon/` record,
- * each with a shape and cap of its own. Named here and nowhere else, so the
- * audit, the gate stage reading its exit, and their tests read one scope.
+ * `CLAUDE.md`, the project requirement and design records, a seed carrying one
+ * of those three names, the changelog, the examples, and every `.canon/`
+ * record, each with a shape and cap of its own. Named here and nowhere else, so
+ * the audit, the gate stage reading its exit, and their tests read one scope.
  */
 const DENSITY_SCOPE = [
   ...BULLET_RUN_SCOPE,
+  REQUIREMENT_SCOPE,
   /^tooling\/[^/]+\/seeds\/(?:.+\/)?(?!(?:CLAUDE|REQUIREMENTS|DESIGN)\.md$)[^/]+\.md$/,
   /^tooling\/[^/]+\/reference\.md$/,
   /^wiki\/.+\.md$/,
@@ -105,35 +114,35 @@ export const GATED_PATHS: readonly string[] = [
   'claude/skills/docs-sync/references/readme.md',
   'claude/skills/document-health/SKILL.md',
   'claude/skills/document-health/references/axes.md',
-  'claude/skills/draft-and-pick/SKILL.md',
-  'claude/skills/draft-and-pick/references/live-arms.md',
-  'claude/skills/draft-doc/SKILL.md',
-  'claude/skills/draft-doc/references/context.md',
-  'claude/skills/draft-doc/references/docs.md',
-  'claude/skills/draft-doc/references/readme.md',
-  'claude/skills/draft-doc/references/readme/agent-facing.md',
-  'claude/skills/draft-doc/references/readme/application.md',
-  'claude/skills/draft-doc/references/readme/cli.md',
-  'claude/skills/draft-doc/references/readme/library.md',
-  'claude/skills/draft-doc/references/readme/plugin.md',
-  'claude/skills/draft-doc/references/requirements.md',
-  'claude/skills/draft-doc/references/wiki-kind.md',
-  'claude/skills/draft-doc/references/wiki.md',
-  'claude/skills/draft-figure/SKILL.md',
-  'claude/skills/draft-figure/references/architecture-set.md',
-  'claude/skills/draft-figure/references/figures.md',
-  'claude/skills/draft-figure/references/hand-drawn.md',
-  'claude/skills/draft-figure/references/mermaid-path.md',
-  'claude/skills/draft-figure/references/mermaid.md',
-  'claude/skills/draft-identity/SKILL.md',
-  'claude/skills/draft-identity/references/card-route.md',
-  'claude/skills/draft-ready/SKILL.md',
-  'claude/skills/draft-ready/references/assembly.md',
-  'claude/skills/draft-ready/references/ready.md',
-  'claude/skills/draft-screencast/SKILL.md',
-  'claude/skills/draft-screencast/references/beats-template.md',
-  'claude/skills/draft-slides/SKILL.md',
-  'claude/skills/draft-slides/references/deck.md',
+  'claude/skills/pick-by-eye/SKILL.md',
+  'claude/skills/pick-by-eye/references/live-arms.md',
+  'claude/skills/write-doc/SKILL.md',
+  'claude/skills/write-doc/references/context.md',
+  'claude/skills/write-doc/references/docs.md',
+  'claude/skills/write-doc/references/readme.md',
+  'claude/skills/write-doc/references/readme/agent-facing.md',
+  'claude/skills/write-doc/references/readme/application.md',
+  'claude/skills/write-doc/references/readme/cli.md',
+  'claude/skills/write-doc/references/readme/library.md',
+  'claude/skills/write-doc/references/readme/plugin.md',
+  'claude/skills/write-doc/references/requirements.md',
+  'claude/skills/write-doc/references/wiki-kind.md',
+  'claude/skills/write-doc/references/wiki.md',
+  'claude/skills/draw-figure/SKILL.md',
+  'claude/skills/draw-figure/references/architecture-set.md',
+  'claude/skills/draw-figure/references/figures.md',
+  'claude/skills/draw-figure/references/hand-drawn.md',
+  'claude/skills/draw-figure/references/mermaid-path.md',
+  'claude/skills/draw-figure/references/mermaid.md',
+  'claude/skills/design-identity/SKILL.md',
+  'claude/skills/design-identity/references/card-route.md',
+  'claude/skills/plan-ready/SKILL.md',
+  'claude/skills/plan-ready/references/assembly.md',
+  'claude/skills/plan-ready/references/ready.md',
+  'claude/skills/script-screencast/SKILL.md',
+  'claude/skills/script-screencast/references/beats-template.md',
+  'claude/skills/make-deck/SKILL.md',
+  'claude/skills/make-deck/references/deck.md',
   'claude/skills/git-branch/SKILL.md',
   'claude/skills/git-branch/references/branch.md',
   'claude/skills/git-branch/references/slug.md',
@@ -301,6 +310,7 @@ export function densityGates(
   gated: readonly string[] = GATED_PATHS,
 ): boolean {
   if (!inDensityScope(rel)) return false
+  if (REQUIREMENT_SCOPE.test(rel)) return gated.includes(rel)
   if (
     ALWAYS_GATED.includes(kind) &&
     BULLET_RUN_SCOPE.some((pattern) => pattern.test(rel))

package/src/migrate/record-layout.ts

@@ -346,7 +346,7 @@ function entriesOf(dir: string, isDirectory: boolean): string[] {
 }
 
 /**
- * What `draft-and-pick` Step 6 writes into the folder it archives a choice to:
+ * What `pick-by-eye` Step 6 writes into the folder it archives a choice to:
  * a capture per canvas frame, named `arm-<id>`. A design handoff marks a pick
  * folder an earlier skill wrote. A folder carrying neither is evidence.
  */