@erclx/canon 4.100.0 → 4.101.0

package/README.md

@@ -99,7 +99,10 @@ Two of the outputs are documents you open rather than files you run. A `SLIDES.m
 
 The workflow this toolkit ships is the workflow that built it. Several Claude Code sessions run at once, each in its own git worktree on its own branch, and each opens its own pull request.
 
-![The canon landing page scrolling from the dispatch section to the branch graph, three workers and a planner on disjoint file sets with the pull request each opened](demos/agent-view.gif)
+<picture>
+  <source media="(prefers-color-scheme: dark)" srcset="demos/agent-view.gif">
+  <img src="demos/agent-view-light.gif" alt="The canon landing page scrolling from the dispatch section to the branch graph, three workers and a planner on disjoint file sets with the pull request each opened">
+</picture>
 
 That recording is the landing page's own `dispatch` and `workers` sections, driven by `canon demo run` against a local build. The branch graph beside the pull request numbers is authored rather than read, because nothing on a build machine records which files four sessions held.
 

package/claude/.claude-plugin/plugin.json

@@ -1,7 +1,7 @@
 {
   "name": "canon",
   "description": "Automated governance, versioning, and discovery tools for Claude Code.",
-  "version": "4.100.0",
+  "version": "4.101.0",
   "author": {
     "name": "Eric Le",
     "url": "https://github.com/erclx"

package/docs/agents/demo.md

@@ -26,6 +26,8 @@ The plan is committed, not scratch. Its timing is a starting point tuned by watc
 
 A plan can carry an optional `colorScheme` of `light` or `dark`, which the recording context starts in so a page following the system preference paints that scheme with no click beat of its own. An absent field keeps the engine's default, which is light, and `compile` never seeds it. Any other value makes the plan unreadable. A page keyed on a stored theme rather than the preference ignores the field.
 
+A recording that has to match both themes takes one plan per scheme, committed side by side, rather than one plan run twice. The pair shares its beats and differs in `colorScheme`, `slug`, and the `output` paths. Neither plan clicks a theme toggle, since a stored theme overrides the preference. Nothing checks that the two plans keep the same beats, so an edit to one is made to both.
+
 `record-screencast` is the routed way to run both verbs from a draft path: it compiles only when no plan exists yet, then runs, stopping to report any field still unresolved rather than guessing one.
 
 | Option          | Behavior                                                          |

package/docs/agents/tasks.md

@@ -292,6 +292,30 @@ Exit codes: `0` closed, `1` refused. The `reason` field adds `no-outcomes`, `out
 
 Both verbs exist because the write is an edit inside a file that already exists. `Edit` and `Write` refuse a main-root path from a linked worktree, and a shell stream editor is banned for in-place edits, so a verb resolving the board root in-process is the only route a skill body has. Creating a whole file needs no verb, because a heredoc through `Bash` writes it safely.
 
+## List
+
+`canon tasks list` reports each live task file with its readiness, so a reader learns which file is parked and which is live without opening `priority.md` or `backlog.md`. It reads and never writes, and every file stays in the folder it is in.
+
+```bash
+canon tasks list
+canon tasks list --json
+```
+
+| Option          | Effect                                      |
+| --------------- | ------------------------------------------- |
+| `--json`        | Emit a machine-readable record on stdout    |
+| `--root <path>` | Board root, defaulting to the main worktree |
+
+The record carries `tasks`, one entry per file with its `stem` and its `readiness`. Readiness is one of `Run now`, `Up next`, `Needs a plan`, `backlog`, `unplaced`, or `both`. The first three are the group names the board standard fixes, `backlog` is a line on `backlog.md`, `unplaced` is a file neither surface names, and `both` is a file both surfaces name, which `validate` reports as a finding and this verb does not judge.
+
+The verb calls the parsers `validate` uses, so the two cannot disagree on what a surface names. It lists the live root only, never `archive/` or `declined/`, and skips the same siblings `validate` skips.
+
+Exit codes: `0` derived, `1` refused with `no-board`.
+
+```bash
+canon tasks list --json | jq -r '.tasks[] | select(.readiness == "backlog") | .stem'
+```
+
 ## Validate
 
 `canon tasks validate` reports what each row of `priority.md` claims against what the tree holds. It reads and never writes, because a row is a session's claim about readiness and a validator that repaired one would be asserting the claim it exists to test.

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@erclx/canon",
   "type": "module",
-  "version": "4.100.0",
+  "version": "4.101.0",
   "description": "Infrastructure and quality tooling for developer workflows",
   "license": "MIT",
   "bin": {

package/src/commands/tasks.ts

@@ -14,6 +14,7 @@ import {
   planCitations,
 } from '@/tasks/archive'
 import { type LabelOutcome, nextLabel } from '@/tasks/label'
+import { listTasks } from '@/tasks/list'
 import {
   type Claim,
   type Holder,
@@ -114,6 +115,11 @@ interface OutcomeCommandOptions {
   readonly root?: string
 }
 
+interface ListCommandOptions {
+  readonly json?: boolean
+  readonly root?: string
+}
+
 interface NextLabelCommandOptions {
   readonly json?: boolean
   readonly root?: string
@@ -522,6 +528,37 @@ export function register(program: Command): void {
     .action(async (opts: NextLabelCommandOptions) => {
       process.exitCode = await runNextLabel(opts)
     })
+
+  tasks
+    .command('list')
+    .description('Report each live task file with its readiness')
+    .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',
+      [
+        '',
+        'Readiness is one of Run now, Up next, Needs a plan, backlog, unplaced,',
+        'or both, read from priority.md and backlog.md through the parsers',
+        'validate uses. It lists the live root only, never archive/ or declined/.',
+        '',
+        'Exit codes:',
+        '  0  the list is derived',
+        '  1  refused with no-board',
+        '',
+        'It reports and never writes, and judges nothing: a file named on both',
+        'surfaces reads as both, and validate owns the finding.',
+        '',
+        'Examples:',
+        '  canon tasks list',
+        '  canon tasks list --json',
+        '',
+      ].join('\n'),
+    )
+    .action(async (opts: ListCommandOptions) => {
+      process.exitCode = await runList(opts)
+    })
 }
 
 function collectPosition(value: string, previous: string[]): string[] {
@@ -792,6 +829,38 @@ function reportOutcome(
   return 0
 }
 
+async function runList(opts: ListCommandOptions): Promise<number> {
+  const root = opts.root ?? (await mainWorktreeRoot())
+  const outcome = await listTasks(root)
+
+  if (!outcome.ok) {
+    if (opts.json) {
+      process.stdout.write(
+        `${JSON.stringify({ ok: false, reason: outcome.reason, message: outcome.message })}\n`,
+      )
+      return 1
+    }
+
+    intro('canon tasks list')
+    logStep('Refused')
+    logError(outcome.message)
+    outro()
+    return 1
+  }
+
+  if (opts.json) {
+    process.stdout.write(`${JSON.stringify({ ...outcome, root })}\n`)
+    return 0
+  }
+
+  intro('canon tasks list')
+  logStep(`${outcome.tasks.length} task files`)
+  for (const task of outcome.tasks) logInfo(`${task.readiness}: ${task.stem}`)
+  outro()
+
+  return 0
+}
+
 async function runNextLabel(opts: NextLabelCommandOptions): Promise<number> {
   const root = opts.root ?? (await mainWorktreeRoot())
   const outcome = await nextLabel(root)

package/src/tasks/list.ts

@@ -0,0 +1,98 @@
+import { existsSync } from 'node:fs'
+import { readFile } from 'node:fs/promises'
+import { listTaskStems, tasksDir } from '@/tasks/archive'
+import {
+  BOARD_GROUPS,
+  type BoardGroup,
+  backlogPath,
+  orderingPath,
+  readBacklog,
+  readBoard,
+} from '@/tasks/validate'
+
+/**
+ * The three board group names plus the states outside them. A file named on
+ * both surfaces is `validate`'s finding, so it reports as `both` rather than
+ * being judged here.
+ */
+export const READINESS_VALUES = [
+  ...BOARD_GROUPS,
+  'backlog',
+  'unplaced',
+  'both',
+] as const
+
+export type Readiness = (typeof READINESS_VALUES)[number]
+
+export interface ListedTask {
+  readonly stem: string
+  readonly readiness: Readiness
+}
+
+export interface TaskList {
+  readonly ok: true
+  readonly tasks: readonly ListedTask[]
+}
+
+export interface ListRefused {
+  readonly ok: false
+  readonly reason: 'no-board'
+  readonly message: string
+}
+
+export type ListOutcome = TaskList | ListRefused
+
+/**
+ * Reports each live task file's readiness from the board and the backlog. It
+ * reads through the parsers `validate` exports rather than reading either file
+ * a second time, so the two verbs cannot disagree on what a surface names. An
+ * absent ordering file or backlog reads as empty, since a file in neither
+ * surface is reported `unplaced` rather than refused.
+ */
+export async function listTasks(root: string): Promise<ListOutcome> {
+  const dir = tasksDir(root)
+  if (!existsSync(dir)) {
+    return {
+      ok: false,
+      reason: 'no-board',
+      message: `No task board at ${dir}.`,
+    }
+  }
+
+  const ordering = orderingPath(root)
+  const { rows } = existsSync(ordering)
+    ? readBoard(await readFile(ordering, 'utf8'))
+    : { rows: [] }
+
+  const backlogFile = backlogPath(root)
+  const backlog = existsSync(backlogFile)
+    ? readBacklog(await readFile(backlogFile, 'utf8'))
+    : []
+
+  const groupOf = new Map<string, BoardGroup>()
+  for (const row of rows) {
+    if (row.stem) groupOf.set(row.stem, row.group)
+  }
+  const parked = new Set(backlog.flatMap((row) => (row.stem ? [row.stem] : [])))
+
+  const stems = await listTaskStems(dir)
+
+  return {
+    ok: true,
+    tasks: stems.map((stem) => ({
+      stem,
+      readiness: readinessOf(groupOf.get(stem), parked.has(stem)),
+    })),
+  }
+}
+
+function readinessOf(
+  group: BoardGroup | undefined,
+  isParked: boolean,
+): Readiness {
+  if (group && isParked) return 'both'
+  if (group) return group
+  if (isParked) return 'backlog'
+
+  return 'unplaced'
+}

package/standards/tasks.md

@@ -37,6 +37,8 @@ Does not govern:
 └── v13.0-toolkit-drift.md   # canon-allow-reference: illustrates the vXX.Y-slug filename this section defines
 ```
 
+`canon tasks list` reports each file's readiness from those two surfaces, so a reader never infers it from the folder.
+
 One file per task is what keeps the board safe under parallel sessions. Two sessions working different tasks never write the same file, which matters because a gitignored board has no history to recover a clobbered write from.
 
 Siblings sit in the folder without being tasks, and each earns its place by being governed somewhere. `index.md`, `priority.md`, and `backlog.md` are governed here. Every `session-` file is a pre-compaction handoff governed by `session.md`, and each is optional: a project whose sessions never approach a compaction carries none. Anything filtering the folder to tasks skips all of them, so a name outside the set is a task whatever it holds.

package/tooling/web/configs/e2e/screenshot.ts

@@ -137,10 +137,15 @@ async function settle(
       for (const frame of document.querySelectorAll('iframe')) {
         try {
           const inner = frame.contentDocument
-          if (inner !== null && inner.readyState !== 'complete') return false
+          if (inner === null) continue
+          if (inner.readyState !== 'complete') return false
+          // A frame's own fonts load after its `readyState` reads complete, and
+          // the swap reflows its text. The outer document's fonts never cover
+          // them.
+          if (inner.fonts.status !== 'loaded') return false
         } catch {
-          // Cross-origin, so there is no readyState to read and nothing here
-          // can wait on it.
+          // Cross-origin, so there is nothing here to read and nothing to
+          // wait on.
         }
       }
       return true