@erclx/canon 4.108.0 → 4.110.0

package/scripts/core/regen-hero.sh

@@ -96,11 +96,8 @@ GOV_JSON="$(catalog gov list)"
 STANDARDS_JSON="$(catalog standards list)"
 SNIPPETS_JSON="$(catalog snippets list)"
 TOOLING_JSON="$(catalog tooling list)"
-# The catalog ledger names three commands, and the registered set is only
-# readable from the root help, which lists one per line under `Commands:`.
-COMMANDS_HELP="$(cd "$PROJECT_ROOT" && CANON_NON_INTERACTIVE=1 bun src/cli.ts --help 2>/dev/null)"
 
-for payload in "$COUNTS_JSON" "$SKILLS_JSON" "$GOV_JSON" "$STANDARDS_JSON" "$SNIPPETS_JSON" "$TOOLING_JSON" "$COMMANDS_HELP"; do
+for payload in "$COUNTS_JSON" "$SKILLS_JSON" "$GOV_JSON" "$STANDARDS_JSON" "$SNIPPETS_JSON" "$TOOLING_JSON"; do
   if [ -z "$payload" ]; then
     echo "regen-hero: a catalog returned nothing, refusing to write a zeroed hero" >&2
     exit 1
@@ -120,7 +117,6 @@ printf '%s' "$GOV_JSON" >"$PAYLOAD_DIR/gov.json"
 printf '%s' "$STANDARDS_JSON" >"$PAYLOAD_DIR/standards.json"
 printf '%s' "$SNIPPETS_JSON" >"$PAYLOAD_DIR/snippets.json"
 printf '%s' "$TOOLING_JSON" >"$PAYLOAD_DIR/tooling.json"
-printf '%s' "$COMMANDS_HELP" >"$PAYLOAD_DIR/commands-help.txt"
 printf '%s' "$TOKEN_CSS" >"$PAYLOAD_DIR/tokens.css"
 
 export PAYLOAD_DIR
@@ -349,36 +345,8 @@ for (const [label, rows] of [
   }
 }
 
-// The ledger names a few real entries per domain. Chosen by hand for the same
-// reason FEATURED_SKILLS is, and asserted against the catalog so a rename fails
-// the run rather than leaving a name the repository no longer ships.
-const commandNames = readFileSync(PAYLOAD_DIR + "/commands-help.txt", "utf8")
-  .split("\n")
-  .map((line) => line.match(/^[│\s]{2,}(?<name>[a-z][a-z-]*)\s/)?.groups?.name)
-  .filter(Boolean)
-const LEDGER = [
-  ["skills", skills.length, ["plan-feature", "role-orchestrator", "review-pr"], skills],
-  ["rules", rules.length, ["behavior", "memory", "testing"], rules],
-  ["standards", standards.length, ["markdown", "plan", "teach"], standards],
-  ["commands", commandCount, ["gov", "tasks", "design"], commandNames],
-  ["stacks", toolingStacks.length, ["astro", "python", "web"], toolingStacks.map((stack) => stack.name)],
-]
-for (const [domain, , chosen, names] of LEDGER) {
-  const known = new Set(names)
-  const missing = chosen.filter((name) => !known.has(name))
-  if (missing.length > 0) {
-    console.error(`regen-hero: ledger ${domain} names missing from the catalog: ${missing.join(", ")}`)
-    process.exit(1)
-  }
-}
-const ledgerRows = LEDGER.map(
-  ([domain, count, chosen]) =>
-    `      <div class="row"><span class="count">${count}</span><span class="domain">${domain}</span><span class="names">${escape(chosen.join(", "))}</span></div>`,
-).join("\n")
-
 const values = {
   TOKENS: tokenCss,
-  LEDGER_ROWS: ledgerRows,
   GOV_STACK_ROWS: govStackRows,
   GOV_RULE_ROWS: govRuleRows,
   STANDARD_ROWS: standardRows,
@@ -417,7 +385,7 @@ if (templates.length === 0) {
 // same template with the plain roles pointed at the light ones rather than a
 // second copy of any hex value. The hero is a landing-page frame no README
 // shows, so it stays dark.
-const LIGHT_TEMPLATES = new Set(["catalog.html.tmpl", "install.html.tmpl"])
+const LIGHT_TEMPLATES = new Set(["install.html.tmpl"])
 
 const lightRoles = [...tokenCss.matchAll(/--color-light-([a-z-]+):/g)].map((match) => match[1])
 if (lightRoles.length === 0) {

package/src/claude/cases/authoring.ts

@@ -61,6 +61,11 @@ export const AUTHORING_CASES: readonly SkillCase[] = [
       'Draft a wireframe for the settings panel, nothing under canon/wireframes covers that surface yet.',
     expect: 'draft-wireframes',
   },
+  {
+    prompt:
+      'Write a wiki reference page for Claude Code output styles, no page covers that subject yet.',
+    expect: 'draft-wiki',
+  },
   {
     prompt: 'Say what that dense answer actually means in plain terms.',
     expect: 'restate-plainly',

package/src/claude/cases/setup.ts

@@ -64,7 +64,7 @@ export const SETUP_CASES: readonly SkillCase[] = [
   {
     prompt:
       'Something about the toolkit itself is broken, write it up and send it back to the maintainers.',
-    expect: 'canon-feedback-file',
+    expect: 'canon-feedback',
   },
   {
     prompt:

package/src/cli.ts

@@ -43,169 +43,10 @@ import { register as census } from '@/commands/census'
 import { register as targets } from '@/commands/targets'
 import { register as upgrade } from '@/commands/upgrade'
 import { readInstalled, UNKNOWN_LABEL } from '@/version/installed'
-import { palette } from '@/ui'
-
-const HELP_WIDTH = 80
-const SIGNATURE_WIDTH = 19
-const ROW_INDENT = '│    '.length
-
-type CommandRow = [signature: string, description: string]
-
-// The grouping mirrors the README's domain table and has no other source, so a
-// command added to the program needs a row here or help-option.test.ts fails.
-const COMMAND_GROUPS: { title: string; rows: CommandRow[] }[] = [
-  {
-    title: 'Project',
-    rows: [
-      ['init [path]', 'Bootstrap a project with toolkit domains'],
-      ['sync [path]', 'Sync all installed domains in a project'],
-      ['upgrade', 'Reinstall the CLI with the manager that installed it'],
-      ['migrate [cmd]', 'Move a project off a retired name or layout'],
-      ['targets [cmd]', 'Projects this toolkit installed into (list, pulls)'],
-    ],
-  },
-  {
-    title: 'Domains',
-    rows: [
-      ['gov [cmd]', 'Governance rules (install, sync, list)'],
-      ['standards [cmd]', 'Standards (install, sync, list, <name>)'],
-      ['snippets [cmd]', 'Prompt snippets (create, list)'],
-      ['tooling [cmd]', 'Tooling stacks (sync, ref, create)'],
-      ['claude [cmd]', 'Claude workflow (init, sync, setup)'],
-      ['wiki [cmd]', 'Wiki pages (init)'],
-      ['indexes [cmd]', 'Regenerate index.md files (regen)'],
-      ['docs [cmd|topic]', 'Emit toolkit reference docs (list, <topic>)'],
-    ],
-  },
-  {
-    title: 'Author and render',
-    rows: [
-      ['design [cmd]', 'Design system (render, board)'],
-      ['slides [cmd]', 'Slide decks (render, list)'],
-      ['capture [source]', 'Render HTML capture sources to PNG'],
-      ['serve [dir]', 'Serve a directory on localhost, print the link'],
-      ['demo [cmd]', 'Record a running app (compile, run)'],
-      ['inventory [subj]', 'Report one computed property across every route'],
-      ['drive <url> <run>', 'Walk a page through interactions, measure each'],
-      ['transcripts <url>', 'Fetch a YouTube transcript with frontmatter'],
-      ['teach [cmd]', 'Learning workspaces (list, open, resource, glossary)'],
-    ],
-  },
-  {
-    title: 'Session and ship',
-    rows: [
-      ['sandbox [cat:cmd]', 'Provision and run sandbox scenarios'],
-      ['tasks [cmd]', 'Task board (validate, archive)'],
-      ['intake [cmd]', 'Intake folders under .canon/intake/ (list, answer)'],
-      ['records [cmd]', 'Session records (validate, size, push, pull)'],
-      ['sessions [cmd]', 'Resolve live sessions to worktree and branch'],
-      ['worktrees [cmd]', 'Reclaim worktrees whose branches merged'],
-      ['autoship [cmd]', 'Decide whether a changed set needs review'],
-      ['pr [cmd]', 'Read a pull request (key-changes, head, checks)'],
-      ['feedback', 'Write toolkit feedback from stdin'],
-    ],
-  },
-  {
-    title: 'Repo reports',
-    rows: [
-      ['audits [cmd]', 'Run every health check as one set (run, list)'],
-      ['gate [cmd]', 'Run the merge gate stage by stage (run)'],
-      ['secrets [cmd]', 'Scan the shipped tree for credentials (scan)'],
-      ['deps [cmd]', 'Read the dependency set for advisories (audit)'],
-      ['labels [cmd]', 'Read a changed set against the label map (audit)'],
-      ['comments [cmd]', 'Measure comment density and trend (scan)'],
-      ['context [cmd]', 'Report context folder health (audit)'],
-      ['markdown [cmd]', 'Report markdown against the standards (audit)'],
-      ['repo [cmd]', 'Remote metadata (metadata propose, apply)'],
-      ['census [path]', 'Report file count, extensions, and line totals'],
-    ],
-  },
-]
-
-// A row past the width is cut rather than wrapped, since a wrapped row breaks
-// the alignment the grouping exists to buy.
-function commandRow(signature: string, description: string): string {
-  const { GREY, NC } = palette(process.stdout)
-  const room = HELP_WIDTH - ROW_INDENT - SIGNATURE_WIDTH - '# '.length
-  const text =
-    description.length > room
-      ? `${description.slice(0, room - 1)}…`
-      : description
-  return `${GREY}│${NC}    ${signature.padEnd(SIGNATURE_WIDTH)}${GREY}# ${text}${NC}`
-}
+import { renderHelp } from '@/help'
 
 function showHelp(): void {
-  // The help text is the one framed surface written to stdout, so it asks
-  // about that stream rather than the stderr every other writer here uses.
-  const { GREY, NC, WHITE } = palette(process.stdout)
-  const lines = [
-    `${GREY}┌${NC}`,
-    `${GREY}├${NC} ${WHITE}Usage:${NC} canon [command]`,
-    `${GREY}│${NC}`,
-    `${GREY}│${NC}  ${WHITE}Commands:${NC}`,
-    ...COMMAND_GROUPS.flatMap((group) => [
-      `${GREY}│${NC}`,
-      `${GREY}│${NC}  ${WHITE}${group.title}${NC}`,
-      ...group.rows.map(([signature, description]) =>
-        commandRow(signature, description),
-      ),
-    ]),
-    `${GREY}│${NC}`,
-    `${GREY}│${NC}  ${WHITE}Sandbox:${NC}`,
-    `${GREY}│${NC}    canon sandbox             ${GREY}# Interactive scenario picker${NC}`,
-    `${GREY}│${NC}    canon sandbox git:commit  ${GREY}# Run specific scenario${NC}`,
-    `${GREY}│${NC}    canon sandbox reset       ${GREY}# Reset sandbox to baseline${NC}`,
-    `${GREY}│${NC}    canon sandbox clean       ${GREY}# Wipe the sandbox${NC}`,
-    `${GREY}│${NC}`,
-    `${GREY}│${NC}  ${WHITE}Examples:${NC}`,
-    `${GREY}│${NC}    canon sync ../my-app`,
-    `${GREY}│${NC}    canon sandbox git:commit`,
-    `${GREY}│${NC}    canon gov install react`,
-    `${GREY}│${NC}    canon gov sync ../my-app`,
-    `${GREY}│${NC}    canon gov restated --json`,
-    `${GREY}│${NC}    canon standards markdown`,
-    `${GREY}│${NC}    canon snippets list`,
-    `${GREY}│${NC}    canon init ../my-app`,
-    `${GREY}│${NC}    canon tooling sync base`,
-    `${GREY}│${NC}    canon tooling create`,
-    `${GREY}│${NC}    canon claude init`,
-    `${GREY}│${NC}    canon indexes regen`,
-    `${GREY}│${NC}    canon indexes regen --dry-run --json`,
-    `${GREY}│${NC}    canon docs list --json`,
-    `${GREY}│${NC}    canon docs agents`,
-    `${GREY}│${NC}    canon design render`,
-    `${GREY}│${NC}    canon design board`,
-    `${GREY}│${NC}    canon slides render`,
-    `${GREY}│${NC}    canon slides list --json`,
-    `${GREY}│${NC}    canon capture assets/captures/install.html --selector .window --out assets/evidence`,
-    `${GREY}│${NC}    canon serve .canon/teach`,
-    `${GREY}│${NC}    canon inventory focus --json`,
-    `${GREY}│${NC}    canon drive http://localhost:4173 run.json --json`,
-    `${GREY}│${NC}    pbpaste | canon feedback`,
-    `${GREY}│${NC}    canon transcripts https://youtu.be/VIDEO_ID`,
-    `${GREY}│${NC}    canon tasks archive --pull-request 673 --json`,
-    `${GREY}│${NC}    canon intake list toolkit-overview --unread --json`,
-    `${GREY}│${NC}    canon teach list --json`,
-    `${GREY}│${NC}    canon comments scan src --json`,
-    `${GREY}│${NC}    canon context audit --json`,
-    `${GREY}│${NC}    canon markdown audit .claude/rules --json`,
-    `${GREY}│${NC}    canon records validate plans`,
-    `${GREY}│${NC}    canon records size --json`,
-    `${GREY}│${NC}    canon records push --json`,
-    `${GREY}│${NC}    canon sessions list --json`,
-    `${GREY}│${NC}    canon worktrees list --json`,
-    `${GREY}│${NC}    canon worktrees reclaim --dry-run`,
-    `${GREY}│${NC}    canon secrets scan --json`,
-    `${GREY}│${NC}    canon deps audit --json`,
-    `${GREY}│${NC}    canon labels audit --json`,
-    `${GREY}│${NC}    canon repo metadata propose --json`,
-    `${GREY}│${NC}    canon census --json`,
-    `${GREY}│${NC}    canon audits run --json`,
-    `${GREY}│${NC}    canon gate run --all --no-write`,
-    `${GREY}│${NC}    canon upgrade --json`,
-    `${GREY}└${NC}`,
-  ]
-  console.log(lines.join('\n'))
+  console.log(renderHelp(process.stdout))
 }
 
 const program = new Command()

package/src/commands/pr.ts

@@ -20,7 +20,11 @@ import {
   compareKeyChanges,
   treeRoots,
 } from '@/pr/bijection'
-import { type CheckRunListing, collapseChecks } from '@/pr/checks'
+import {
+  type CheckRunListing,
+  collapseChecks,
+  withMergeState,
+} from '@/pr/checks'
 import {
   findEvidenceChecklist,
   findEvidenceCommentId,
@@ -307,6 +311,11 @@ export function register(program: Command): void {
         'an empty row list, and reading that as passing is the false green the',
         'sha key alone does not close.',
         '',
+        'A branch conflicting with its base gets no merge ref, so no run ever',
+        'starts for it and the state stays pending. The record carries',
+        '`conflicted: true` beside it when `mergeStateStatus` reads DIRTY and no',
+        'run belongs to the tip, and a caller stops waiting and rebases.',
+        '',
         'Exit codes:',
         '  0  the runs for the tip were read, whatever they say',
         '  1  refused, with the reason on stderr or in the JSON record',
@@ -865,6 +874,7 @@ interface PullIdentity {
   readonly number: number | undefined
   readonly branch: string
   readonly head?: string
+  readonly mergeState?: string
 }
 
 type IdentityRead =
@@ -911,12 +921,17 @@ async function readIdentity(
 
   const args = ['pr', 'view']
   if (number !== undefined) args.push(number)
-  args.push('--json', 'number,headRefName,headRefOid')
+  args.push('--json', 'number,headRefName,headRefOid,mergeStateStatus')
 
   const stdout = await gh(cwd, args)
   if (stdout === null) return { kind: 'refused', reason: 'gh-failed' }
 
-  let row: { number?: number; headRefName?: string; headRefOid?: string }
+  let row: {
+    number?: number
+    headRefName?: string
+    headRefOid?: string
+    mergeStateStatus?: string
+  }
   try {
     row = JSON.parse(stdout)
   } catch {
@@ -933,6 +948,9 @@ async function readIdentity(
       number: row.number,
       branch: row.headRefName,
       ...(row.headRefOid !== undefined && { head: row.headRefOid }),
+      ...(row.mergeStateStatus !== undefined && {
+        mergeState: row.mergeStateStatus,
+      }),
     },
   }
 }
@@ -1071,7 +1089,10 @@ async function runChecks(
     )
   }
 
-  const reading = collapseChecks(resolved.tip, listing)
+  const reading = withMergeState(
+    identity.mergeState,
+    collapseChecks(resolved.tip, listing),
+  )
 
   logStep('Scope')
   logInfo(
@@ -1101,6 +1122,10 @@ async function runChecks(
     logInfo('every run on the tip completed and none failed')
   } else if (reading.state === 'failing') {
     logWarn('a run on the tip failed, which no run still going can clear')
+  } else if (reading.conflicted) {
+    logWarn(
+      'the branch conflicts with its base, so no run will start for the tip. Rebase onto the base rather than waiting.',
+    )
   } else if (reading.matched === 0) {
     logInfo(
       `no run belongs to the tip yet${reading.reported > 0 ? `, against a reported count of ${reading.reported}` : ''}. That is unread rather than clean.`,

package/src/commands/tasks.ts

@@ -13,7 +13,12 @@ import {
   type PlanCitations,
   planCitations,
 } from '@/tasks/archive'
-import { type LabelOutcome, nextLabel } from '@/tasks/label'
+import {
+  type LabelOutcome,
+  type LabelRefused,
+  claimLabel,
+  nextLabel,
+} from '@/tasks/label'
 import { listTasks } from '@/tasks/list'
 import {
   type Claim,
@@ -122,6 +127,7 @@ interface ListCommandOptions {
 
 interface NextLabelCommandOptions {
   readonly json?: boolean
+  readonly claim?: boolean
   readonly root?: string
 }
 
@@ -503,6 +509,7 @@ export function register(program: Command): void {
     )
     .helpOption('-h, --help', 'Show this help message')
     .option('--json', 'Emit a machine-readable record on stdout')
+    .option('--claim', 'Reserve the label so a second claim gets another')
     .option('--root <path>', 'Board root, defaulting to the main worktree')
     .addHelpText(
       'after',
@@ -515,14 +522,18 @@ export function register(program: Command): void {
         'Exit codes:',
         '  0  the label is derived',
         '  1  refused with no-board',
+        '  2  refused with label-contended, on --claim only',
         '',
-        'It reports and never writes. Two sessions calling it in the same',
-        'second can still take the same answer, since the board is',
-        'gitignored files rather than a store with a lock.',
+        'Bare, it reports and never writes, so two sessions calling it in the',
+        'same second can take the same answer. --claim reserves the label',
+        'under .canon/ordinal-locks/ and counts every reservation in the',
+        'scan, so two claims return different labels. A dead claim leaves a',
+        'gap, which standards/versioning.md permits.',
         '',
         'Examples:',
         '  canon tasks next-label',
         '  canon tasks next-label --json',
+        '  canon tasks next-label --claim --json',
         '',
       ].join('\n'),
     )
@@ -864,11 +875,15 @@ async function runList(opts: ListCommandOptions): Promise<number> {
 
 async function runNextLabel(opts: NextLabelCommandOptions): Promise<number> {
   const root = opts.root ?? (await mainWorktreeRoot())
-  const outcome = await nextLabel(root)
+  const outcome = opts.claim ? await claimLabel(root) : await nextLabel(root)
 
   return reportNextLabel(outcome, opts.json ?? false, root)
 }
 
+function refusalExit(outcome: LabelRefused): number {
+  return outcome.reason === 'label-contended' ? 2 : 1
+}
+
 function reportNextLabel(
   outcome: LabelOutcome,
   emitJson: boolean,
@@ -879,14 +894,14 @@ function reportNextLabel(
       process.stdout.write(
         `${JSON.stringify({ ok: false, reason: outcome.reason, message: outcome.message })}\n`,
       )
-      return 1
+      return refusalExit(outcome)
     }
 
     intro('canon tasks next-label')
     logStep('Refused')
     logError(outcome.message)
     outro()
-    return 1
+    return refusalExit(outcome)
   }
 
   if (emitJson) {