@erclx/canon 5.48.0 → 5.50.0

package/src/commands/tasks.ts

@@ -222,6 +222,11 @@ export function register(program: Command): void {
         'listed, and pending-branch while a Pending branch: line names a branch',
         'whose own pull request is not recorded yet. A stem skips both.',
         '',
+        'On an earlier-slice or open-outcomes refusal from --pull-request, the',
+        'slice plan whose derived branch is the pull request head, read through',
+        'gh, moves to the plans archive and the task stays open. The record',
+        'names it under `slice`.',
+        '',
         'Refusals, read off `reason`:',
         '  no-board        the repository holds no `.canon/tasks/` board',
         '  no-match        no task matches the selector',
@@ -2187,6 +2192,10 @@ function report(
     logStep('Refused')
     logError(outcome.message)
     if (outcome.detail.length > 0) pipeOutput(outcome.detail.join('\n'))
+    if (outcome.slice) {
+      logStep('Slice plan archived')
+      logPlanMoves([outcome.slice], root)
+    }
     outro()
     return 1
   }
@@ -2276,6 +2285,9 @@ function recordFor(
       reason: outcome.reason,
       message: outcome.message,
       detail: outcome.detail,
+      ...(outcome.slice
+        ? { slice: planMovesFor([outcome.slice], root)[0] }
+        : {}),
     }
   }
 

package/src/context/audit.ts

@@ -108,13 +108,14 @@ export const OTHER_FOLDERS = 'Other folders'
 export const SCRIPTS_HEADING = 'Scripts'
 
 /**
- * Whether an entry path is the development entry, being the flat entry, the
- * overview of a split one a target may still carry, or this repository's
- * `local-loop` entry. The standard exempts the
- * `Scripts` H3 for that entry alone, so the path is what tells.
+ * Whether an entry path is the development entry, being the flat entry or any
+ * entry directly under a `development/` folder, since a split folder names its
+ * scripts entry by project, as `local-loop` here and `local` in another. The
+ * standard exempts the `Scripts` H3 for that entry alone, so the path is what
+ * tells.
  */
 function isDevelopmentEntry(rel: string): boolean {
-  return /(?:^|\/)development(?:\/(?:overview|local-loop))?\.md$/.test(rel)
+  return /(?:^|\/)development(?:\/[^/]+)?\.md$/.test(rel)
 }
 
 /**

package/src/design/budget.ts

@@ -1,7 +1,7 @@
 import { canonicalHeading } from '@/design/parse'
 
 /**
- * The prose budget `claude/skills/canvas-board/references/design.md` sets for a design record, and the
+ * The prose budget `claude/skills/design-record/references/design.md` sets for a design record, and the
  * counter the `design` gate stage reads it through.
  *
  * The limits live here and in the standard, never in the stage, so the stage

package/src/design/components.ts

@@ -15,7 +15,7 @@
  * `buildDesignCss`'s `components` option, which is what widening that option
  * from a boolean to `boolean | readonly Component[]` bought.
  *
- * It does not live in `canon/DESIGN.md`. `claude/skills/canvas-board/references/design.md` keeps CSS class
+ * It does not live in `canon/DESIGN.md`. `claude/skills/design-record/references/design.md` keeps CSS class
  * names out of that record and says they live in code, which is here.
  */
 

package/src/design/document.ts

@@ -94,7 +94,7 @@ function borderRows(tokens: readonly BorderToken[]): string[][] {
  * and every reason behind them lives in the entry.
  */
 const LEAD = [
-  'Authoring guidance: `claude/skills/canvas-board/references/design.md`. Rendered from `src/design/tokens.ts` by `canon design regen`, so edit the module and never this file.',
+  'Authoring guidance: `claude/skills/design-record/references/design.md`. Rendered from `src/design/tokens.ts` by `canon design regen`, so edit the module and never this file.',
   'Why each value was chosen lives in `canon/context/features/design.md`.',
 ].join(' ')
 

package/src/design/regen.ts

@@ -16,7 +16,7 @@ import { NEUTRAL_TOKENS } from '@/design/neutral'
  * gate stage is what keeps silently out of it.
  */
 
-/** The rendered record, at the path `claude/skills/canvas-board/references/design.md` fixes for it. */
+/** The rendered record, at the path `claude/skills/design-record/references/design.md` fixes for it. */
 export const DESIGN_DOCUMENT = join('canon', 'DESIGN.md')
 
 /**

package/src/design/render.ts

@@ -105,7 +105,7 @@ interface Confidence {
 }
 
 /**
- * The columns the confidence ratio reads, fixed by `claude/skills/canvas-board/references/design.md`. The
+ * The columns the confidence ratio reads, fixed by `claude/skills/design-record/references/design.md`. The
  * first column of each table names its row, and `Multiplier` and `When used`
  * restate what the row already carries, so none of them is something a source
  * could anchor and none belongs in the denominator.

package/src/gate/hand-suite.ts

@@ -0,0 +1,52 @@
+/**
+ * Names the machine lock a gate holds while a stage's commands run, so the
+ * suite it spawns knows not to wait on its own parent.
+ */
+export const HELD_LOCK_VARIABLE = 'CANON_HELD_LOCK'
+
+/**
+ * The vitest invocation a hand-run lock decision reads.
+ */
+export interface VitestRun {
+  /** The CLI arguments after the vitest entry, as `process.argv.slice(2)`. */
+  readonly args: readonly string[]
+  readonly ci: boolean
+  readonly watch: boolean
+  /**
+   * The lock a parent gate already holds for this run, from `HELD_LOCK_VARIABLE`.
+   * A gate's own suite waiting on that lock would wait on its parent forever.
+   */
+  readonly heldLock: string | undefined
+}
+
+const SUBCOMMANDS = new Set(['run'])
+
+/** `-t` and its long forms filter by test name, which scopes the run. */
+function isNameFilter(arg: string): boolean {
+  return (
+    arg === '-t' ||
+    arg.startsWith('-t=') ||
+    arg === '--testNamePattern' ||
+    arg.startsWith('--testNamePattern=') ||
+    arg === '--test-name-pattern' ||
+    arg.startsWith('--test-name-pattern=')
+  )
+}
+
+/**
+ * Whether a hand-run vitest invocation runs the whole suite and so queues on
+ * the machine lock the gate's Tests stage holds.
+ *
+ * A scoped run is seconds of work, and queueing it behind a full suite costs
+ * more than any collision it causes. Vitest exposes no setup-time API naming
+ * the CLI filters, so any bare argument other than the subcommand reads as a
+ * file filter. That includes the value of a flag spelled `--flag value`, which
+ * misreads such a run as scoped. The misread skips a lock rather than queueing
+ * a scoped run, which is the side to err on.
+ */
+export function locksHandSuite(run: VitestRun): boolean {
+  if (run.ci || run.watch || run.heldLock !== undefined) return false
+
+  const args = SUBCOMMANDS.has(run.args[0] ?? '') ? run.args.slice(1) : run.args
+  return !args.some((arg) => isNameFilter(arg) || !arg.startsWith('-'))
+}

package/src/gate/measures.ts

@@ -56,7 +56,14 @@ export interface CommandResult {
   readonly spawnError?: string
 }
 
-export type RunCommand = (argv: readonly string[]) => Promise<CommandResult>
+/**
+ * Spawns one command. `env` adds variables to the child's environment, which a
+ * locked stage uses to tell its child which lock the gate already holds.
+ */
+export type RunCommand = (
+  argv: readonly string[],
+  env?: Readonly<Record<string, string>>,
+) => Promise<CommandResult>
 
 export interface MeasureContext {
   readonly root: string
@@ -331,7 +338,7 @@ export const designProse: Measure = async (ctx) => {
   if (failures.length > 0) {
     return {
       emissions: [],
-      failure: `${failures.join(' ')} Cut to the budget in claude/skills/canvas-board/references/design.md, moving the why to the context entry.`,
+      failure: `${failures.join(' ')} Cut to the budget in claude/skills/design-record/references/design.md, moving the why to the context entry.`,
     }
   }
   if (emissions.length === 0)

package/src/gate/sequencer.ts

@@ -8,6 +8,7 @@ import type {
   MeasureContext,
   RunCommand,
 } from '@/gate/measures'
+import { HELD_LOCK_VARIABLE } from '@/gate/hand-suite'
 import type { Check, Stage } from '@/gate/stages'
 import {
   acquireSuiteLock,
@@ -248,7 +249,7 @@ async function executeStage(
   }
 
   // CI runs one suite per runner, so a lock there queues behind nothing.
-  if (stage.lock === undefined || ctx.ci) return runChecks(stage, ctx, [])
+  if (stage.lock === undefined || ctx.ci) return runChecks(stage, ctx, [], {})
 
   const held = await acquireSuiteLock({
     path: machineLockPath(stage.lock),
@@ -266,8 +267,10 @@ async function executeStage(
         ]
 
   try {
+    // The suite's own global setup takes this lock for a hand run, so the
+    // child is told its parent holds it rather than waiting on the parent.
     const outcome = withLoadLine(
-      await runChecks(stage, ctx, queued),
+      await runChecks(stage, ctx, queued, { [HELD_LOCK_VARIABLE]: stage.lock }),
       stage,
       ctx,
     )
@@ -310,11 +313,12 @@ async function runChecks(
   stage: Stage,
   ctx: GateContext,
   leading: readonly Emission[],
+  env: Readonly<Record<string, string>>,
 ): Promise<StageOutcome> {
   const emissions: Emission[] = [...leading]
 
   for (const check of stage.checks) {
-    const outcome = await runCheck(check, ctx)
+    const outcome = await runCheck(check, ctx, env)
     emissions.push(...outcome.emissions)
 
     if (outcome.failure !== undefined) {
@@ -363,7 +367,11 @@ interface CheckOutcome {
   readonly unmeasured?: string
 }
 
-async function runCheck(check: Check, ctx: GateContext): Promise<CheckOutcome> {
+async function runCheck(
+  check: Check,
+  ctx: GateContext,
+  env: Readonly<Record<string, string>>,
+): Promise<CheckOutcome> {
   if (check.kind === 'measure') {
     const report = await check.measure(ctx)
     return {
@@ -378,7 +386,7 @@ async function runCheck(check: Check, ctx: GateContext): Promise<CheckOutcome> {
   }
 
   const run = check.kind === 'cli' ? ctx.cli : ctx.run
-  const result = await run(check.argv)
+  const result = await run(check.argv, env)
   return {
     emissions: [{ kind: 'output', text: result.all }],
     failure: result.exitCode === 0 ? undefined : check.failure,
@@ -492,7 +500,7 @@ export function exitCodeFor(results: readonly StageResult[]): number {
  * repository the hook points at rather than the tree being verified.
  */
 export function commandRunner(root: string): RunCommand {
-  return async (argv) => spawn(argv[0], argv.slice(1), root)
+  return async (argv, env) => spawn(argv[0], argv.slice(1), root, env)
 }
 
 /**
@@ -504,19 +512,20 @@ export function commandRunner(root: string): RunCommand {
  */
 export function cliRunner(root: string): RunCommand {
   const cli = join(PROJECT_ROOT, 'src', 'cli.ts')
-  return async (argv) => spawn(process.execPath, [cli, ...argv], root)
+  return async (argv, env) => spawn(process.execPath, [cli, ...argv], root, env)
 }
 
 async function spawn(
   file: string,
   args: readonly string[],
   cwd: string,
+  env: Readonly<Record<string, string>> = {},
 ): Promise<CommandResult> {
   const result = await execa(file, [...args], {
     cwd,
     reject: false,
     all: true,
-    env: { ...gitEnv(), CANON_NON_INTERACTIVE: '1' },
+    env: { ...gitEnv(), CANON_NON_INTERACTIVE: '1', ...env },
     extendEnv: false,
   })
 

package/src/hooks/post-merge.ts

@@ -161,8 +161,19 @@ function archiveLines(
   if (reason === undefined || reason === 'no-match' || reason === 'no-board') {
     return undefined
   }
+  // A merged slice moves its own plan while the task stays open, so the line
+  // names the plan that dropped off the board row.
+  const slice =
+    fields.slice !== null && typeof fields.slice === 'object'
+      ? text(fields.slice as Fields, 'from')
+      : undefined
+  const moved =
+    slice === undefined
+      ? ''
+      : `🗂️  Archived the slice plan ${slice}, and the task stays open.\n`
   return (
     `\n📋 Task not archived for #${number}: ${text(fields, 'message') ?? reason}\n` +
+    moved +
     `Run /task-complete archive #${number} to resolve it by hand.\n\n`
   )
 }

package/src/markdown/gated.ts

@@ -9,7 +9,7 @@ import {
 import { readFile } from 'node:fs/promises'
 import { dirname, join } from 'node:path'
 import { listRepositoryFiles } from '@/git/files'
-import { densityFindings, type DensityKind } from '@/markdown/density'
+import type { DensityKind } from '@/markdown/density'
 import { referenceShapeGates } from '@/markdown/gate'
 import {
   type ReferenceShapeKind,
@@ -20,7 +20,7 @@ import {
   densityGates,
   GATED_PATHS,
   GATED_SCOPE_ROOTS,
-  inDensityScope,
+  scopedDensityFindings,
 } from '@/markdown/scope'
 import { isOwnCheckout } from '@/roots/project'
 
@@ -198,11 +198,9 @@ export async function findingsUnder(
   const found = await Promise.all(
     under.map(async (rel) => {
       const source = await readFile(join(root, rel), 'utf8')
-      const density = inDensityScope(rel)
-        ? densityFindings(bodyLines(source)).filter((finding) =>
-            densityGates(rel, finding.kind, [prefix], false),
-          )
-        : []
+      const density = scopedDensityFindings(rel, bodyLines(source)).filter(
+        (finding) => densityGates(rel, finding.kind, [prefix], false),
+      )
       const shape = referenceShapeGates(rel, [prefix])
         ? referenceShapeFindings(source)
         : []

package/src/markdown/scope.ts

@@ -1,4 +1,9 @@
-import type { DensityKind } from '@/markdown/density'
+import {
+  type DensityFinding,
+  type DensityKind,
+  densityFindings,
+} from '@/markdown/density'
+import type { BodyLine } from '@/markdown/scan'
 
 /** The surfaces the retired bullet-stacks stage held, per `ALWAYS_GATED`. */
 const BULLET_RUN_SCOPE = [
@@ -21,11 +26,12 @@ const REQUIREMENT_SCOPE =
  * 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 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.
+ * Rules stay out, since a rule is one imperative per bullet, and so does every
+ * `CLAUDE.md` section but Key paths, which `KEY_PATHS_SCOPE` holds. So do 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,
@@ -36,10 +42,49 @@ const DENSITY_SCOPE = [
   /^(?:README|CONTRIBUTING)\.md$/,
 ]
 
+/**
+ * The root `CLAUDE.md` and its seed, measured inside `## Key paths` alone. That
+ * section is a catalog rather than rules, so it takes the run limit and the H3
+ * opening a grouped catalog needs, and nothing else a rule would breach.
+ */
+const KEY_PATHS_SCOPE = /^(?:tooling\/claude\/seeds\/)?CLAUDE\.md$/
+const KEY_PATHS_HEADING = /^## Key paths\s*$/
+const KEY_PATHS_KINDS: readonly DensityKind[] = ['bullet-run', 'h3-opening']
+
+/** The lines under `## Key paths` up to the next H1 or H2, keeping their numbers. */
+function keyPathsSection(lines: readonly BodyLine[]): readonly BodyLine[] {
+  const start = lines.findIndex(
+    (line) => !line.fenced && KEY_PATHS_HEADING.test(line.text),
+  )
+  if (start === -1) return []
+  const rest = lines.slice(start + 1)
+  const end = rest.findIndex(
+    (line) => !line.fenced && /^#{1,2}\s/.test(line.text),
+  )
+  return end === -1 ? rest : rest.slice(0, end)
+}
+
+/**
+ * The density findings a path takes, being every finding on a density-scope
+ * file and the Key paths findings on a `CLAUDE.md`. The audit, the init probe,
+ * and `canon claude sync` all read this, so the three agree on what counts.
+ */
+export function scopedDensityFindings(
+  rel: string,
+  lines: readonly BodyLine[],
+): DensityFinding[] {
+  if (inDensityScope(rel)) return densityFindings(lines)
+  if (!KEY_PATHS_SCOPE.test(rel)) return []
+  return densityFindings(keyPathsSection(lines)).filter((finding) =>
+    KEY_PATHS_KINDS.includes(finding.kind),
+  )
+}
+
 /**
  * The roots `canon init` gates in a new project when each passes at init time:
- * every density surface a target authors itself, leaving out the toolkit's own
- * `claude/skills/` and `tooling/` trees.
+ * every density surface a target authors itself and the Key paths of its
+ * `CLAUDE.md`, leaving out the toolkit's own `claude/skills/` and `tooling/`
+ * trees.
  */
 export const GATED_SCOPE_ROOTS: readonly string[] = [
   'canon/context/',
@@ -48,6 +93,7 @@ export const GATED_SCOPE_ROOTS: readonly string[] = [
   'wiki/',
   'README.md',
   'CONTRIBUTING.md',
+  'CLAUDE.md',
 ]
 
 /**
@@ -93,7 +139,6 @@ export const GATED_PATHS: readonly string[] = [
   'claude/skills/canvas-board/REQUIREMENT.md',
   'claude/skills/canvas-board/SKILL.md',
   'claude/skills/canvas-board/references/canvas.md',
-  'claude/skills/canvas-board/references/design.md',
   'claude/skills/ci-workflow/REQUIREMENT.md',
   'claude/skills/ci-workflow/SKILL.md',
   'claude/skills/ci-workflow/references/workflows.md',
@@ -133,6 +178,10 @@ export const GATED_PATHS: readonly string[] = [
   'claude/skills/deprecation-migration/REQUIREMENT.md',
   'claude/skills/deprecation-migration/SKILL.md',
   'claude/skills/deprecation-migration/references/adopted.md',
+  'claude/skills/design-record/REQUIREMENT.md',
+  'claude/skills/design-record/SKILL.md',
+  'claude/skills/design-record/references/design.md',
+  'claude/skills/design-record/references/folder.md',
   'claude/skills/design-taste/REQUIREMENT.md',
   'claude/skills/design-taste/SKILL.md',
   'claude/skills/design-taste/references/adopted.md',
@@ -394,6 +443,7 @@ export const GATED_PATHS: readonly string[] = [
   'wiki/',
   'README.md',
   'CONTRIBUTING.md',
+  'CLAUDE.md',
 ]
 
 /**
@@ -425,7 +475,7 @@ export function densityGates(
   gated: readonly string[] = GATED_PATHS,
   alwaysGated = true,
 ): boolean {
-  if (!inDensityScope(rel)) return false
+  if (!inDensityScope(rel) && !KEY_PATHS_SCOPE.test(rel)) return false
   if (REQUIREMENT_SCOPE.test(rel)) return gated.includes(rel)
   if (
     alwaysGated &&

package/src/markdown/structure.ts

@@ -67,7 +67,7 @@ const MARKER_WIDTH = 20
 
 export const LIST_ITEM = /^(\s*)([-*+]|\d+\.)\s+/
 export const TABLE_ROW = /^\s*\|/
-const TABLE_SEPARATOR = /^\s*\|[\s:|-]+\|\s*$/
+export const TABLE_SEPARATOR = /^\s*\|[\s:|-]+\|\s*$/
 export const BLOCKQUOTE = /^\s*>/
 
 /**

package/src/markdown/tables.ts

@@ -0,0 +1,150 @@
+import { type BodyLine, visibleText } from '@/markdown/scan'
+import { LIST_ITEM, TABLE_ROW, TABLE_SEPARATOR } from '@/markdown/structure'
+
+/** The most visible characters one table cell may hold. */
+export const TABLE_CELL = 120
+
+/** The most body rows a table may carry before it splits into groups. */
+export const TABLE_ROWS = 8
+
+/** The longest unbroken run a code span in a table cell may carry. */
+export const TABLE_TOKEN = 30
+
+export type TableKind =
+  | 'table-cell'
+  | 'table-rows'
+  | 'table-then-list'
+  | 'table-token'
+
+export interface TableFinding {
+  readonly kind: TableKind
+  /** The row holding the cell or span, the header for a row count, or the list's first item. */
+  readonly line: number
+  /** What was measured, or null for a trailing list, which is a shape rather than a count. */
+  readonly value: number | null
+  readonly limit: number | null
+}
+
+/**
+ * The body of every code span in a cell, read after link destinations are
+ * dropped, since only a link's label renders.
+ */
+export function codeSpans(cell: string): string[] {
+  return (cell.replace(/\]\([^)]*\)/g, ']').match(/`[^`]+`/g) ?? []).map(
+    (span) => span.slice(1, -1),
+  )
+}
+
+/**
+ * The longest whitespace-free run in a code span. A preview also breaks a span
+ * after a hyphen or a slash, but a run this long still splits mid-token or
+ * widens its column, so whitespace is the break this counts.
+ */
+export function unbrokenRun(span: string): number {
+  return Math.max(...span.split(/\s+/).map((part) => part.length))
+}
+
+/** Splits a row on its unescaped pipes, dropping the outer two. */
+function cellsOf(row: string): string[] {
+  return row
+    .trim()
+    .replace(/^\|/, '')
+    .replace(/(?<!\\)\|$/, '')
+    .split(/(?<!\\)\|/)
+    .map((cell) => cell.trim().replaceAll('\\|', '|'))
+}
+
+/**
+ * Every breach of the four table limits, in line order.
+ *
+ * A table is a run of pipe rows whose second row is a delimiter, the shape a
+ * renderer draws. Pipe lines with no delimiter render as paragraph text, and a
+ * fenced line is an example, so neither is measured. The limits are a
+ * 120-character cell, 8 body rows, a list as the next block, and a code span
+ * holding a run past 30 characters. Every finding reports and none gates.
+ */
+export function tableFindings(lines: readonly BodyLine[]): TableFinding[] {
+  const found: TableFinding[] = []
+  let index = 0
+
+  while (index < lines.length) {
+    const header = lines[index]
+    const delimiter = lines[index + 1]
+    if (
+      header.fenced ||
+      !TABLE_ROW.test(header.text) ||
+      delimiter === undefined ||
+      delimiter.fenced ||
+      !TABLE_SEPARATOR.test(delimiter.text)
+    ) {
+      index++
+      continue
+    }
+
+    const tableRows = [header]
+    let end = index + 2
+    while (
+      end < lines.length &&
+      !lines[end].fenced &&
+      TABLE_ROW.test(lines[end].text)
+    ) {
+      tableRows.push(lines[end])
+      end++
+    }
+
+    for (const row of tableRows) {
+      for (const cell of cellsOf(row.text)) {
+        const length = visibleText(cell).length
+        if (length > TABLE_CELL) {
+          found.push({
+            kind: 'table-cell',
+            line: row.number,
+            value: length,
+            limit: TABLE_CELL,
+          })
+        }
+        for (const span of codeSpans(cell)) {
+          const run = unbrokenRun(span)
+          if (run > TABLE_TOKEN) {
+            found.push({
+              kind: 'table-token',
+              line: row.number,
+              value: run,
+              limit: TABLE_TOKEN,
+            })
+          }
+        }
+      }
+    }
+
+    const bodyRows = tableRows.length - 1
+    if (bodyRows > TABLE_ROWS) {
+      found.push({
+        kind: 'table-rows',
+        line: header.number,
+        value: bodyRows,
+        limit: TABLE_ROWS,
+      })
+    }
+
+    let next = end
+    while (next < lines.length && lines[next].text.trim() === '') next++
+    const following = lines[next]
+    if (
+      following !== undefined &&
+      !following.fenced &&
+      LIST_ITEM.test(following.text)
+    ) {
+      found.push({
+        kind: 'table-then-list',
+        line: following.number,
+        value: null,
+        limit: null,
+      })
+    }
+
+    index = end
+  }
+
+  return found.sort((a, b) => a.line - b.line)
+}