@erclx/canon 5.8.0 → 5.10.0

package/src/commands/pr.ts

@@ -26,6 +26,7 @@ import {
   withMergeState,
 } from '@/pr/checks'
 import {
+  findEvidenceCaseCount,
   findEvidenceChecklist,
   findEvidenceCommentId,
   findEvidenceLocal,
@@ -173,20 +174,21 @@ const PULL_REFUSALS: Record<PullRefusal | HeadRefusal, string> = {
 type EvidenceRefusal =
   | 'gh-failed'
   | 'no-base'
-  | 'unreadable-tree'
   | 'unreadable-changes'
   | 'unreadable-checklist'
+  | 'would-empty'
 
 const EVIDENCE_REFUSALS: Record<EvidenceRefusal, string> = {
   'gh-failed':
     'gh could not answer for this repository. Name the pull request number.',
   'unreadable-checklist':
     'The file named by --checklist could not be read, or holds nothing. Rendering without it would drop the only copy, since the caller deletes the handoff once a post reports success.',
-  'no-base': 'No base resolves against the trunk. Fetch origin and re-run.',
-  'unreadable-tree':
-    'git could not read the tree at the base commit, so no path could be judged added or changed.',
+  'no-base':
+    'GitHub reported no merge base for this pull request, so no path could be judged added or changed.',
   'unreadable-changes':
-    'git could not list what this branch changed, so the set is unknown.',
+    'GitHub could not list what this pull request changed, so the set is unknown.',
+  'would-empty':
+    'This render holds no cases and the marked comment holds some, so posting it would replace a comparison with an empty one. Edit the comment by hand if every case was removed on purpose.',
 }
 
 /** Why the read produced no comparison, ahead of the ones the compare owns. */
@@ -427,11 +429,13 @@ export function register(program: Command): void {
       'after',
       [
         '',
-        'Compares the merge base with the trunk against the current head, never',
-        'the previous push against the new one, so the comment never claims more',
-        'than the branch currently shows. A path counts as evidence when one of',
-        'its segments is literally `evidence` and the filename carries an image',
-        'extension (png, jpg, jpeg, gif, webp, avif, svg). A README, a capture',
+        "Compares the pull request's merge base against its head, both read over",
+        'the API for the number named, so the record is the same from any',
+        'checkout. It never compares the previous push against the new one, so',
+        'the comment never claims more than the pull request currently shows.',
+        'A path counts as evidence when one of its segments is literally',
+        '`evidence` and the filename carries an image extension (png, jpg,',
+        'jpeg, gif, webp, avif, svg). A README, a capture',
         'script, or a raw data file kept beside the images is left out rather',
         'than rendered as a broken embed.',
         '',
@@ -440,6 +444,8 @@ export function register(program: Command): void {
         '               comment already exists and should be edited in place',
         '  no-evidence  nothing in the diff carries an evidence/ segment, which',
         '               is an ordinary, silent no-op rather than a refusal',
+        '  would-empty  the render holds no cases and the marked comment holds',
+        '               some, so no body is printed and a person edits the comment',
         '',
         "--preview puts the address on the body's first line. With no evidence",
         'in the diff, the body is that line and the marker alone, reported as',
@@ -1346,21 +1352,63 @@ async function runReviewState(
 }
 
 /**
- * Every path `git ls-tree` reports for `ref`, or undefined when the read
- * failed. One call for the whole tree rather than one `cat-file -e` per
- * evidence path, since existence at base is checked once per changed path and
- * a batch read is one round trip instead of many.
+ * The paths a pull request changed that still exist at its head, each tagged
+ * with whether the pull request added it, read through the paginated files
+ * endpoint so the set is the same from any checkout and never capped at the
+ * first view. `renamed` and `copied` count as added, since the new path has no
+ * counterpart at the merge base. Returns undefined when the read fails, which
+ * refuses rather than rendering a short set.
  */
-async function listTreePaths(
-  root: string,
-  ref: string,
-): Promise<Set<string> | undefined> {
-  const result = await $`git -C ${root} ls-tree -r --name-only ${ref}`
-    .env(gitEnv())
-    .quiet()
-    .nothrow()
-  if (result.exitCode !== 0) return undefined
-  return new Set(result.text().split('\n').filter(Boolean))
+async function listPullFiles(
+  cwd: string,
+  number: number,
+): Promise<ReadonlyMap<string, boolean> | undefined> {
+  const stdout = await gh(cwd, [
+    'api',
+    '--paginate',
+    `repos/{owner}/{repo}/pulls/${number}/files`,
+    '--jq',
+    '.[] | [.status, .filename] | @tsv',
+  ])
+  if (stdout === null) return undefined
+  const files = new Map<string, boolean>()
+  for (const line of stdout.split('\n').filter(Boolean)) {
+    const [status, path] = line.split('\t')
+    if (status === undefined || path === undefined || status === 'removed') {
+      continue
+    }
+    files.set(path, status !== 'modified' && status !== 'changed')
+  }
+  return files
+}
+
+/**
+ * The commit the pull request diverged from its base at, from the compare
+ * endpoint, since a checkout on another branch resolves its own trunk tip
+ * instead and the base image links would then describe the wrong commit.
+ */
+async function readPullMergeBase(
+  cwd: string,
+  number: number,
+  head: string,
+): Promise<string | undefined> {
+  const baseRef = await gh(cwd, [
+    'pr',
+    'view',
+    String(number),
+    '--json',
+    'baseRefName',
+    '--jq',
+    '.baseRefName',
+  ])
+  if (baseRef === null || baseRef.trim() === '') return undefined
+  const sha = await gh(cwd, [
+    'api',
+    `repos/{owner}/{repo}/compare/${baseRef.trim()}...${head}`,
+    '--jq',
+    '.merge_base_commit.sha',
+  ])
+  return sha === null || sha.trim() === '' ? undefined : sha.trim()
 }
 
 async function runEvidence(
@@ -1404,16 +1452,20 @@ async function runEvidence(
     )
   }
 
-  const base = await resolveBaseRef(root)
-  if (base === undefined) {
-    return refuseWith('no-base', EVIDENCE_REFUSALS['no-base'], emitJson, root)
+  if (identity.number === undefined) {
+    return refuseWith(
+      'gh-failed',
+      EVIDENCE_REFUSALS['gh-failed'],
+      emitJson,
+      root,
+    )
   }
 
-  const [changed, baseTree] = await Promise.all([
-    listChangedFiles(root, base),
-    listTreePaths(root, base),
+  const [pullFiles, base] = await Promise.all([
+    listPullFiles(root, identity.number),
+    readPullMergeBase(root, identity.number, identity.head),
   ])
-  if (changed === undefined) {
+  if (pullFiles === undefined) {
     return refuseWith(
       'unreadable-changes',
       EVIDENCE_REFUSALS['unreadable-changes'],
@@ -1421,61 +1473,57 @@ async function runEvidence(
       root,
     )
   }
-  if (baseTree === undefined) {
-    return refuseWith(
-      'unreadable-tree',
-      EVIDENCE_REFUSALS['unreadable-tree'],
-      emitJson,
-      root,
-    )
+  if (base === undefined) {
+    return refuseWith('no-base', EVIDENCE_REFUSALS['no-base'], emitJson, root)
   }
 
-  const grouped = await groupEvidence(changed, async (path) =>
-    baseTree.has(path),
+  const grouped = await groupEvidence(
+    [...pullFiles.keys()],
+    async (path) => pullFiles.get(path) === false,
   )
 
+  let existingCases = 0
   let commentId: number | undefined
   let carriedPreview: string | undefined
   let carriedChecklist: string | undefined
   let carriedLocal: string | undefined
-  if (identity.number !== undefined) {
-    const commentsRow = await gh(root, [
-      'pr',
-      'view',
-      String(identity.number),
-      '--json',
-      'comments',
-    ])
-    // An unread thread refuses rather than rendering, since a body built
-    // without it knows neither the comment to edit nor the preview address
-    // to carry, and posting it would duplicate the comment and drop the link.
-    // It refuses ahead of no-evidence too, so that record never reports an
-    // absent field it did not read.
-    let comments: readonly { url?: string; body: string }[] | undefined
-    if (commentsRow !== null) {
-      try {
-        comments = (
-          JSON.parse(commentsRow) as {
-            comments?: readonly { url?: string; body: string }[]
-          }
-        ).comments
-      } catch {
-        comments = undefined
-      }
-    }
-    if (comments === undefined) {
-      return refuseWith(
-        'gh-failed',
-        EVIDENCE_REFUSALS['gh-failed'],
-        emitJson,
-        root,
-      )
+  const commentsRow = await gh(root, [
+    'pr',
+    'view',
+    String(identity.number),
+    '--json',
+    'comments',
+  ])
+  // An unread thread refuses rather than rendering, since a body built
+  // without it knows neither the comment to edit nor the preview address
+  // to carry, and posting it would duplicate the comment and drop the link.
+  // It refuses ahead of no-evidence too, so that record never reports an
+  // absent field it did not read.
+  let comments: readonly { url?: string; body: string }[] | undefined
+  if (commentsRow !== null) {
+    try {
+      comments = (
+        JSON.parse(commentsRow) as {
+          comments?: readonly { url?: string; body: string }[]
+        }
+      ).comments
+    } catch {
+      comments = undefined
     }
-    commentId = findEvidenceCommentId(comments)
-    carriedPreview = findEvidencePreview(comments)
-    carriedChecklist = findEvidenceChecklist(comments)
-    carriedLocal = findEvidenceLocal(comments)
   }
+  if (comments === undefined) {
+    return refuseWith(
+      'gh-failed',
+      EVIDENCE_REFUSALS['gh-failed'],
+      emitJson,
+      root,
+    )
+  }
+  commentId = findEvidenceCommentId(comments)
+  existingCases = findEvidenceCaseCount(comments)
+  carriedPreview = findEvidencePreview(comments)
+  carriedChecklist = findEvidenceChecklist(comments)
+  carriedLocal = findEvidenceLocal(comments)
 
   // What the marked comment already shows a reviewer, kept apart from the
   // flags this call passed so a reader learns what is posted.
@@ -1543,6 +1591,28 @@ async function runEvidence(
 
   const caseCount = states.reduce((n, s) => n + s.items.length, 0)
 
+  // A render with no cases cannot tell a removal from a short read, so it
+  // never replaces a comment that carries some. The record keeps the comment
+  // id and the carried fields so the caller can still edit by hand.
+  if (caseCount === 0 && existingCases > 0) {
+    logStep('Refused')
+    logWarn(EVIDENCE_REFUSALS['would-empty'])
+    outro()
+    if (emitJson) {
+      process.stdout.write(
+        `${JSON.stringify({
+          root,
+          number: identity.number,
+          reason: 'would-empty',
+          message: EVIDENCE_REFUSALS['would-empty'],
+          ...(commentId !== undefined && { commentId }),
+          ...carried,
+        })}\n`,
+      )
+    }
+    return 1
+  }
+
   logStep('Scope')
   logInfo(
     `${plural(caseCount, 'case')} across ${plural(states.length, 'state')}`,

package/src/commands/standards.ts

@@ -1,11 +1,11 @@
 import { resolve } from 'node:path'
 import type { Command } from 'commander'
-import { registerPassThroughVerbs } from '@/commands/pass-through'
 import {
   auditExitCode,
   auditStandards,
   type StandardsAudit,
 } from '@/standards/audit'
+import { listStandardEntries } from '@/standards/list'
 import { listStandards, readStandard, resolveStandard } from '@/standards/read'
 import {
   frameError,
@@ -19,6 +19,10 @@ import {
   plural,
 } from '@/ui'
 
+interface StandardsListOptions {
+  readonly json?: boolean
+}
+
 interface StandardsAuditOptions {
   readonly json?: boolean
   readonly arrivalsOnly?: boolean
@@ -57,7 +61,14 @@ export function register(program: Command): void {
       process.exitCode = print(name)
     })
 
-  registerPassThroughVerbs(standards, 'standards', ['list'])
+  standards
+    .command('list')
+    .description('List the standards with their descriptions and jurisdiction')
+    .helpOption('-h, --help', 'Show this help message')
+    .option('--json', 'Emit machine-readable JSON')
+    .action((opts: StandardsListOptions) => {
+      process.exitCode = runStandardsList(opts)
+    })
 
   standards
     .command('audit')
@@ -95,6 +106,26 @@ export function register(program: Command): void {
     })
 }
 
+/**
+ * Reads the working root first, the way `canon standards <name>` does, so a
+ * project's own standards list beside the package corpus. The `--json` record
+ * is the one thing on stdout and the frame opens only on the text path.
+ */
+function runStandardsList(opts: StandardsListOptions): number {
+  const standards = listStandardEntries(process.cwd())
+
+  if (opts.json) {
+    process.stdout.write(`${JSON.stringify({ standards })}\n`)
+    return 0
+  }
+
+  intro('canon standards')
+  logStep('Standards')
+  for (const each of standards) logInfo(`${each.name} : ${each.description}`)
+  outro()
+  return 0
+}
+
 /**
  * Writes the standard to stdout and every frame line to stderr, so a caller
  * capturing the output with `$(...)` receives the document alone.

package/src/commands/tasks.ts

@@ -10,9 +10,11 @@ import {
   type CitationOutcome,
   type DeclineOutcome,
   declineTask,
+  type InboundRelink,
   type PlanCitations,
   type PlanMove,
   planCitations,
+  type RelinkFailure,
 } from '@/tasks/archive'
 import {
   type LabelOutcome,
@@ -112,6 +114,7 @@ interface PullRequestCommandOptions {
 }
 
 interface PlanLinkCommandOptions {
+  readonly add?: boolean
   readonly json?: boolean
   readonly root?: string
 }
@@ -452,6 +455,10 @@ export function register(program: Command): void {
     .argument('<task>', 'Task filename stem, as in v28.1-trigger-escalation')
     .argument('<plan>', 'Plan path or its slug, as in dispatch-answer-gate')
     .helpOption('-h, --help', 'Show this help message')
+    .option(
+      '--add',
+      'Append the plan to the line, for a task sliced over plans',
+    )
     .option('--json', 'Emit a machine-readable record on stdout')
     .option('--root <path>', 'Board root, defaulting to the main worktree')
     .addHelpText(
@@ -459,7 +466,7 @@ export function register(program: Command): void {
       [
         '',
         'Exit codes:',
-        '  0  the line was added, corrected, or already correct',
+        '  0  the line was added, appended to, corrected, or already correct',
         '  1  refused, including several-plans for a line linking more than one',
         '     plan, with the reason on stderr or in the JSON record',
         '',
@@ -469,8 +476,13 @@ export function register(program: Command): void {
         'tasks plan-answers does. Safe from a linked worktree, since it',
         'resolves the board root in-process.',
         '',
+        'With --add it keeps every link in order and appends the plan, so a',
+        'sliced task links one plan per slice. It reports unchanged when the',
+        'plan is already listed and is allowed on a line holding several.',
+        '',
         'Examples:',
         '  canon tasks plan-link v28.1-trigger-escalation dispatch-answer-gate',
+        '  canon tasks plan-link v28.1-trigger-escalation second-slice --add',
         '  canon tasks plan-link v28.1-trigger-escalation .canon/plans/feature-dispatch-answer-gate.md --json',
         '',
       ].join('\n'),
@@ -723,7 +735,7 @@ async function runPlanLink(
 ): Promise<number> {
   const emitJson = opts.json ?? false
   const root = opts.root ?? (await mainWorktreeRoot())
-  const outcome = await recordPlan(root, task, plan)
+  const outcome = await recordPlan(root, task, plan, opts.add ?? false)
 
   return reportPlanLink(outcome, emitJson, root)
 }
@@ -1493,6 +1505,7 @@ function report(
     logInfo('retargeted the Ready: line')
   }
   if (outcome.priorityRowRemoved) logInfo('cleared the ordering row')
+  logRelinked(outcome.relinked, outcome.relinkFailed, root)
   if (outcome.indexRegenerated) logInfo('regenerated index.md')
   if (outcome.cut > 0) logInfo(`${outcome.cut} outcome(s) cut`)
   outro()
@@ -1508,6 +1521,43 @@ function logPlanMoves(plans: readonly PlanMove[], root: string): void {
   if (plans.length > 0) logInfo('retargeted the Plan: line')
 }
 
+function logRelinked(
+  relinked: readonly InboundRelink[],
+  failed: readonly RelinkFailure[],
+  root: string,
+): void {
+  if (relinked.length > 0) {
+    const links = relinked.reduce((sum, entry) => sum + entry.links, 0)
+    logInfo(`repointed ${links} link(s) in ${relinked.length} file(s)`)
+  }
+
+  for (const failure of failed) {
+    logWarn(
+      `could not repoint ${relative(root, failure.file)}: ${failure.message}`,
+    )
+  }
+}
+
+function relinkFailedFor(
+  failed: readonly RelinkFailure[],
+  root: string,
+): readonly { readonly file: string; readonly message: string }[] {
+  return failed.map((failure) => ({
+    file: relative(root, failure.file),
+    message: failure.message,
+  }))
+}
+
+function relinkedFor(
+  relinked: readonly InboundRelink[],
+  root: string,
+): readonly { readonly file: string; readonly links: number }[] {
+  return relinked.map((entry) => ({
+    file: relative(root, entry.file),
+    links: entry.links,
+  }))
+}
+
 function planMovesFor(
   plans: readonly PlanMove[],
   root: string,
@@ -1547,6 +1597,8 @@ function recordFor(
       : null,
     closed: outcome.closed,
     cut: outcome.cut,
+    relinked: relinkedFor(outcome.relinked, root),
+    relinkFailed: relinkFailedFor(outcome.relinkFailed, root),
   }
 }
 
@@ -1639,6 +1691,7 @@ function reportDecline(
   logPlanMoves(outcome.plans, root)
   if (outcome.priorityRowRemoved) logInfo('cleared the ordering row')
   if (outcome.backlogRowRemoved) logInfo('cleared the backlog row')
+  logRelinked(outcome.relinked, outcome.relinkFailed, root)
   if (outcome.indexRegenerated) logInfo('regenerated index.md')
   outro()
 
@@ -1667,5 +1720,7 @@ function declineRecordFor(
     backlogRowRemoved: outcome.backlogRowRemoved,
     indexRegenerated: outcome.indexRegenerated,
     plans: planMovesFor(outcome.plans, root),
+    relinked: relinkedFor(outcome.relinked, root),
+    relinkFailed: relinkFailedFor(outcome.relinkFailed, root),
   }
 }

package/src/commands/tooling.ts

@@ -19,7 +19,7 @@ import {
 } from '@/tooling/manifest'
 import { readReference, resolveReference } from '@/tooling/read'
 import { scan, type ScanResult } from '@/tooling/scan'
-import { recordToolingChain } from '@/tooling/stamp'
+import { recordedStacks, recordToolingChain } from '@/tooling/stamp'
 import { subfolderPath } from '@/tooling/subfolder'
 import {
   intro,
@@ -34,7 +34,7 @@ import {
   select,
 } from '@/ui'
 
-const PASS_THROUGH_VERBS = ['create', 'verify'] as const
+const PASS_THROUGH_VERBS = ['verify'] as const
 
 interface SyncOptions {
   readonly skip?: string
@@ -71,7 +71,7 @@ type Prepared =
 export function register(program: Command): void {
   const tooling = program
     .command('tooling')
-    .description('Manage tooling stacks (sync, reference, create)')
+    .description('Manage tooling stacks (sync, reference)')
     .helpOption('-h, --help', 'Show this help message')
 
   tooling
@@ -228,7 +228,7 @@ export function register(program: Command): void {
  *
  * The frame opens after the `--json` return. The bash emitted a closing `└`
  * from its EXIT trap with no `┌` above it, because the hand-rolled
- * pass-through loop below skips the `intro` the shared helper carries.
+ * pass-through loop below opens no frame before it runs the script.
  */
 function runList(opts: ListOptions): number {
   // The warning is a frame-interior line, so it goes out after `intro` on the
@@ -485,7 +485,7 @@ async function stampChain(chain: Manifest[], target: string): Promise<void> {
   )
 
   if (recorded) {
-    logInfo(`Recorded chain: ${chain.map((entry) => entry.name).join(' < ')}`)
+    logInfo(`Recorded chain: ${recordedStacks(chain).join(' < ')}`)
     return
   }
 

package/src/commands/upgrade.ts

@@ -37,7 +37,7 @@ interface UpgradeRecord {
   readonly reason?: string
   /**
    * One rendered line for a caller that reports the outcome without parsing
-   * the rest of the record, such as `.husky/post-merge`. `current` reuses
+   * the rest of the record, such as the base stack's post-merge hook. `current` reuses
    * `describeSkew` verbatim so its wording never drifts from the line `canon
    * sync --check` and `canon claude skills drift` already report.
    */
@@ -312,7 +312,8 @@ function emit(opts: UpgradeOptions, record: UpgradeRecord): void {
 /**
  * `message` is the one field carrying arbitrary text: `describeSkew`'s
  * `unknown` branch embeds a registry error verbatim, and a registry answering
- * with HTML produces one already carrying a double quote. `.husky/post-merge`
+ * with HTML produces one already carrying a double quote. The base stack's
+ * post-merge hook, and any hook installed before `canon hooks post-merge`,
  * reads this field with a pattern rather than a parser, so a quote makes it
  * through `JSON.stringify` as an escaped `\"` that the pattern stops at,
  * truncating the line it prints. Collapsing whitespace and swapping the quote

package/src/commands/worktrees.ts

@@ -35,10 +35,11 @@ interface ReclaimCommandOptions {
 /**
  * What a caller reads instead of the frame.
  *
- * `.husky/post-merge` is the first caller that is not a person, and it branches
+ * The post-merge hooks are the callers that are not a person, and they branch
  * on a parsed field rather than on the exit code, since a shell profile
- * wrapping `canon` in a function flattens every status to zero. It reads the
- * record with a pattern rather than a parser, so every field it branches on is
+ * wrapping `canon` in a function flattens every status to zero. The base
+ * stack's hook, and any hook installed before `canon hooks post-merge`, reads
+ * the record with a pattern rather than a parser, so every field it branches on is
  * a number or a fixed word, and `outcomes` sits last so a greedy pattern
  * anchored on a scalar never reaches into it.
  */

package/src/counts/catalogs.ts

@@ -25,14 +25,14 @@ const REGISTER_IMPORT = /^import \{ register as /gm
 /**
  * Every top-level `canon` command, read off the CLI entry point rather than a
  * catalog verb, because a command carries no `--json` listing of its own
- * siblings. `regen-hero.sh` reads its own `COMMAND_COUNT` through `gov counts`
+ * siblings. `regen-hero.ts` imports this reader for its `COMMAND_COUNT`
  * rather than a second regex on `src/cli.ts`, so this is the one place that
  * pattern is written.
  *
  * This is the one catalog with no meaning outside this repository, the way
- * `regen-hero.sh` documents itself as clone-only for the same reason.
+ * `regen-hero.ts` documents itself as clone-only for the same reason.
  */
-function countCommands(root: string): number | undefined {
+export function countCommands(root: string): number | undefined {
   const cli = join(root, 'src', 'cli.ts')
   if (!existsSync(cli)) return undefined
   return [...readFileSync(cli, 'utf8').matchAll(REGISTER_IMPORT)].length

package/src/design/tokens.ts

@@ -99,7 +99,7 @@ export const TOKENS: DesignTokens = {
     '',
     'The values below are the system rather than a reading of one. Until 2026-09-01 this record transcribed two surfaces and agreed with nothing else, which is what made a change to it reach nobody. The slide theme, the token preview, and a teach workspace stylesheet now read the module this file is rendered from, so a value changed there changes what all three render.',
     '',
-    'The two rendered captures read it as well. `scripts/core/regen-hero.sh` fills `assets/captures/hero.html.tmpl` and `assets/captures/install.html.tmpl` with what `canon design css --no-components` emits, so both frames now carry the custom properties rather than their own copies of the hex, and a value moved here moves what the next capture renders.',
+    'The two rendered captures read it as well. `scripts/core/regen-hero.ts` fills `assets/captures/hero.html.tmpl` and `assets/captures/install.html.tmpl` with what `canon design css --no-components` emits, so both frames now carry the custom properties rather than their own copies of the hex, and a value moved here moves what the next capture renders.',
     '',
     'The terminal framing is the one surface left holding its own values, and that is a decision rather than a gap. `scripts/lib/ui.sh` and `src/ui.ts` each spell six escape constants, and `canon/context/scripts/framing.md` records one color source per language with a check behind each, so generating a third spelling from here would break the rule those two checks enforce. What the record is still incomplete about is the other half of those six: `WHITE` and `GREY` name no role below, so the terminal palette is described here in part rather than in whole.',
   ].join('\n'),