@erclx/canon 5.30.0 → 5.32.0

package/src/commands/feedback.ts

@@ -1,18 +1,13 @@
-import { existsSync, mkdirSync, writeFileSync } from 'node:fs'
-import { join } from 'node:path'
-import type { Command } from 'commander'
+import { Option, type Command } from 'commander'
 import {
   deriveDomainLabels,
-  deriveSlug,
   deriveTitle,
   missingField,
   missingFieldMessage,
 } from '@/feedback/body'
-import { checkoutMismatchWarning, PROJECT_ROOT } from '@/roots/project'
-import { creationRel } from '@/roots/record'
 import { createGithubIssue } from '@/feedback/github'
 import { issueFailureMessage } from '@/feedback/github-format'
-import { frameError, frameSuccess, logWarn, palette } from '@/cli/ui'
+import { frameError, frameSuccess } from '@/cli/ui'
 
 function readStdin(): Promise<string> {
   return new Promise((resolveStream, rejectStream) => {
@@ -25,62 +20,17 @@ function readStdin(): Promise<string> {
   })
 }
 
-function timestamp(): string {
-  const d = new Date()
-  const pad = (n: number): string => n.toString().padStart(2, '0')
-  return `${d.getFullYear()}${pad(d.getMonth() + 1)}${pad(d.getDate())}-${pad(d.getHours())}${pad(d.getMinutes())}${pad(d.getSeconds())}`
-}
-
-/**
- * A registry install ships no `.claude/`, so a local write would land inside
- * `node_modules/` and report a project-relative path the operator cannot find.
- * The toolkit source is the only root where local scratch reaches a maintainer.
- */
-function isToolkitSource(): boolean {
-  return existsSync(join(PROJECT_ROOT, '.claude'))
-}
-
-/**
- * One producer, one record folder. Feedback is not a review, so it writes
- * under a root folder of its own rather than inside `review/`, and `canon
- * records push` backs it with no list edit, since it carries every `.canon/`
- * entry it does not exclude.
- */
-function writeLocal(body: string, mismatch: string | undefined): string {
-  // Resolved against the same root the write joins onto. `creationRel` reads
-  // whichever root already carries a `feedback/` folder and falls back to the
-  // creation root when neither does.
-  const relativeDir = creationRel(PROJECT_ROOT, 'feedback')
-  const feedbackDir = join(PROJECT_ROOT, relativeDir)
-  mkdirSync(feedbackDir, { recursive: true })
-  const filename = `feedback-${deriveSlug(body)}-${timestamp()}.md`
-  const filePath = join(feedbackDir, filename)
-  writeFileSync(filePath, `${body}\n`, 'utf8')
-
-  // Manual frame rather than `frameSuccess`, since the mismatch warning is a
-  // frame-interior line landing between the opener and the command title,
-  // matching the convention `#1587` set at its other six sites.
-  const { GREEN, GREY, NC, WHITE } = palette(process.stderr)
-  process.stderr.write(`${GREY}┌${NC}\n`)
-  if (mismatch !== undefined) logWarn(mismatch)
-  process.stderr.write(
-    `${GREY}│${NC} ${WHITE}canon feedback${NC}\n${GREY}│${NC}\n${GREY}│${NC} ${GREEN}✓${NC} ${join(relativeDir, filename)}\n${GREY}└${NC}\n`,
-  )
-  return filePath
-}
-
 export function register(program: Command): void {
   program
     .command('feedback')
     .helpOption('-h, --help', 'Show this help message')
     .description(
-      'Write toolkit feedback from stdin to .canon/feedback/, or open a GitHub issue with --github',
-    )
-    .option(
-      '--github',
-      'Open a GitHub issue on the toolkit repo instead of writing local scratch',
+      'Open a GitHub issue on the toolkit repo from a feedback block on stdin',
     )
-    .action(async (opts: { github?: boolean }) => {
+    // A cached plugin still pipes `--github`, and commander rejects an unknown
+    // option, so the flag stays accepted and hidden for one release.
+    .addOption(new Option('--github').hideHelp())
+    .action(async () => {
       if (process.stdin.isTTY) {
         frameError(
           'No feedback on stdin. Pipe a markdown block: pbpaste | canon feedback',
@@ -95,8 +45,8 @@ export function register(program: Command): void {
         return
       }
 
-      // Both write paths, not `--github` alone. A report missing its surface is
-      // no more useful sitting in the triage queue on disk than in the tracker.
+      // A report missing its surface is no more useful in the tracker than
+      // anywhere else, so validation runs before any `gh` call.
       const absent = missingField(body)
       if (absent) {
         frameError(missingFieldMessage(absent))
@@ -104,39 +54,20 @@ export function register(program: Command): void {
         return
       }
 
-      if (opts.github) {
-        const result = await createGithubIssue({
-          title: deriveTitle(body),
-          body,
-          labels: ['feedback', ...deriveDomainLabels(body)],
-        })
-        if (result.ok) {
-          frameSuccess('canon feedback', result.url)
-          process.stdout.write(`${result.url}\n`)
-          return
-        }
-        const reason = issueFailureMessage(result)
-        if (!isToolkitSource()) {
-          frameError(reason)
-          process.exitCode = 1
-          return
-        }
-        const { NC, YELLOW } = palette(process.stderr)
-        process.stderr.write(
-          `${YELLOW}! ${reason} Wrote local scratch instead.${NC}\n`,
-        )
-      }
-
-      if (!isToolkitSource()) {
-        frameError(
-          'Local scratch needs the toolkit source. Re-run with --github to open an issue instead.',
-        )
-        process.exitCode = 1
+      const result = await createGithubIssue({
+        title: deriveTitle(body),
+        body,
+        labels: ['feedback', ...deriveDomainLabels(body)],
+      })
+      if (result.ok) {
+        frameSuccess('canon feedback', result.url)
+        process.stdout.write(`${result.url}\n`)
         return
       }
-
-      const mismatch = checkoutMismatchWarning(process.cwd())
-      const filePath = writeLocal(body, mismatch)
-      process.stdout.write(`${filePath}\n`)
+      // The block goes to stdout so the session can paste it where the issue
+      // would have gone, and the reason frames on stderr.
+      frameError(issueFailureMessage(result))
+      process.stdout.write(`${body}\n`)
+      process.exitCode = 1
     })
 }

package/src/commands/gov.ts

@@ -239,8 +239,8 @@ export function register(program: Command): void {
       'after',
       [
         '',
-        'Measures the rule in .claude/rules/canon/claude/567-planning.md that asks for',
-        'the test before the code. It reports and never gates, because pairing',
+        'Measures the test-first order the test-first skill and auto-ship hold: the',
+        'test before the code. It reports and never gates, because pairing',
         'a test to an implementation is a judgment.',
         '',
         'Coverage:',

package/src/commands/records.ts

@@ -57,6 +57,7 @@ import {
   plural,
 } from '@/cli/ui'
 import { currentWorktreeRoot, mainWorktreeRoot } from '@/git/worktree'
+import { readLivePlans, stackFindings } from '@/tasks/stack'
 
 /** Returned when a record carries a finding, which is the gating result. */
 const EXIT_FINDINGS = 2
@@ -299,10 +300,10 @@ export function register(program: Command): void {
         'Entries are ordered due first, then those citing a missing path, then the',
         'longest unreviewed, then by name, so a review takes the first N as a batch.',
         '',
-        'canonical: reads REQUIREMENTS.md and ARCHITECTURE.md at whichever surface',
-        'root carries each, in the current worktree since both are tracked. Each',
-        'reports its reviewed date and the release tags merged into HEAD after that',
-        'day, or never when it carries no date. --days does not apply.',
+        'canonical: reads REQUIREMENTS.md at whichever surface root carries it,',
+        'in the current worktree since it is tracked. It reports its reviewed date',
+        'and the release tags merged into HEAD after that day, or never when it',
+        'carries no date. --days does not apply.',
         '',
         'Exit codes:',
         '  0  the reading completed, whatever it found',
@@ -644,7 +645,7 @@ async function runStaleCanonical(
   logStep('Canonical')
 
   if (outcome.docs.length === 0) {
-    logInfo('neither REQUIREMENTS.md nor ARCHITECTURE.md exists')
+    logInfo('REQUIREMENTS.md does not exist')
   } else {
     for (const doc of outcome.docs) logInfo(describeCanonical(doc, outcome))
   }
@@ -911,7 +912,24 @@ async function runValidate(
 
   const root = opts.root ?? (await defaultRoot(kind))
 
-  return report(await validateRecords(root, kind), emitJson, root)
+  return report(await validateWithStacks(root, kind), emitJson, root)
+}
+
+/**
+ * Appends the one plans finding that reads across files. It sits in the command
+ * layer because `src/records/` sits below `src/tasks/`, and `migrate` iterates
+ * `validateRecords` alone, so it never meets a finding with no safe repair.
+ */
+async function validateWithStacks(
+  root: string,
+  kind: RecordKind,
+): Promise<ValidateOutcome> {
+  const outcome = await validateRecords(root, kind)
+  if (!outcome.ok || kind !== 'plans') return outcome
+
+  const stacked = stackFindings(await readLivePlans(root))
+
+  return { ...outcome, findings: [...outcome.findings, ...stacked] }
 }
 
 function report(

package/src/commands/sync.ts

@@ -282,7 +282,7 @@ function renderTooling(report: CheckReport): void {
 /**
  * Seeds print their own section because no sync command applies them. A `stale`
  * seed is safe to take whole and a `drifted` one holds edits, which is the split
- * `seed-sync` reads to decide what needs a section-level merge.
+ * that decides what needs a hand merge.
  */
 function renderSeeds(report: CheckReport): void {
   const notable = report.seeds.entries.filter(
@@ -300,7 +300,9 @@ function renderSeeds(report: CheckReport): void {
     logWarn(`${entry.rel} (${entry.state})`)
   }
 
-  logInfo('Run /canon:seed-sync to reconcile these section by section.')
+  logInfo(
+    'A stale seed is safe to take whole. Merge a drifted one by hand against the toolkit copy.',
+  )
 }
 
 /**
@@ -401,7 +403,7 @@ async function runSync(target: string): Promise<number> {
 
   if (existsSync(join(resolved, '.claude'))) {
     process.stderr.write(
-      `${GREY}Tip: run \`/seed-sync\` to audit seed drift per section, preserving local customizations.${NC}\n`,
+      `${GREY}Tip: merge a drifted seed by hand against the toolkit copy, and take a stale one whole.${NC}\n`,
     )
   }
 

package/src/commands/upstream.ts

@@ -0,0 +1,430 @@
+import { resolve } from 'node:path'
+import { $ } from 'bun'
+import type { Command } from 'commander'
+import { intro, logInfo, logStep, logWarn, outro, plural } from '@/cli/ui'
+import { currentWorktreeRoot, mainWorktreeRoot } from '@/git/worktree'
+import { buildCatalog, renderCatalog } from '@/upstream/catalog'
+import {
+  advanceCursor,
+  compareVersions,
+  llmsDifference,
+  readCursor,
+  readLastLlms,
+} from '@/upstream/cursor'
+import { buildDigest } from '@/upstream/digest'
+import {
+  decideDue,
+  passesVocabulary,
+  readDueCache,
+  writeDueCache,
+  type DueReason,
+  type Gap,
+} from '@/upstream/due'
+import {
+  githubPageFetcher,
+  grepHint,
+  keepLines,
+  walkReleases,
+  type FetchFailure,
+} from '@/upstream/releases'
+
+const LLMS_URL = 'https://code.claude.com/docs/llms.txt'
+const VERSION = /^\d+(\.\d+)*$/
+const READ_BUDGET_MS = 5000
+
+interface RootOption {
+  readonly root?: string
+  readonly json?: boolean
+}
+
+interface FetchOptions extends RootOption {
+  readonly since?: string
+}
+
+interface AdvanceOptions extends RootOption {
+  readonly intake: string
+  readonly llms: boolean
+}
+
+type Refusal =
+  | 'no-cursor'
+  | 'bad-since'
+  | 'cursor-missing'
+  | FetchFailure
+  | 'older-than-cursor'
+  | 'invalid-version'
+
+const REFUSALS: Record<Refusal, string> = {
+  'no-cursor':
+    'No cursor is stored, so there is no range to read. Pass --since <version> with the last version a digest covered.',
+  'bad-since': 'The --since value is not a dotted version such as 2.1.256.',
+  'cursor-missing':
+    'The releases feed ran out before reaching a release at or below the cursor, so the range cannot be bounded. Pass --since with a more recent version.',
+  'rate-limited':
+    'GitHub refused the request. Set GH_TOKEN or GITHUB_TOKEN to lift the hourly limit.',
+  network: 'The releases feed could not be reached.',
+  http: 'GitHub answered with an error for the releases feed.',
+  'older-than-cursor':
+    'The version is older than the stored cursor, and the cursor never moves back.',
+  'invalid-version': 'The version is not a dotted number such as 2.1.289.',
+}
+
+export function register(program: Command): void {
+  const upstream = program
+    .command('upstream')
+    .description(
+      'Read Claude Code releases against the toolkit (fetch, catalog, advance)',
+    )
+    .helpOption('-h, --help', 'Show this help message')
+    .addHelpText(
+      'after',
+      [
+        '',
+        'Ships in the published CLI as `canon gate` and `canon sandbox` do, but',
+        'only the toolkit repository has the skill that drives it, so a target',
+        'has no use for these verbs.',
+        '',
+      ].join('\n'),
+    )
+
+  upstream
+    .command('fetch')
+    .description(
+      'List the release lines since the cursor, with the mechanical noise dropped',
+    )
+    .helpOption('-h, --help', 'Show this help message')
+    .option('--since <version>', 'Read from this version instead of the cursor')
+    .option('--root <path>', 'Repository to read, defaulting to the cwd')
+    .option('--json', 'Add a machine-readable record on stdout')
+    .addHelpText(
+      'after',
+      [
+        '',
+        'Writes nothing. The cursor moves only through `upstream advance`, so a',
+        'run that dies midway reads the same range next time.',
+        '',
+        'Exit codes:',
+        '  0  the range was read, possibly empty',
+        '  1  refused, with the reason on stderr or in the JSON record',
+        '',
+        'Examples:',
+        '  canon upstream fetch --json',
+        '  canon upstream fetch --since 2.1.256 --json',
+        '',
+      ].join('\n'),
+    )
+    .action(async (opts: FetchOptions) => {
+      process.exitCode = await runFetch(opts)
+    })
+
+  upstream
+    .command('catalog')
+    .description("List the toolkit's own mechanisms, one line each")
+    .helpOption('-h, --help', 'Show this help message')
+    .option('--root <path>', 'Repository to read, defaulting to the cwd')
+    .option('--json', 'Emit the sections as a JSON record instead of text')
+    .addHelpText(
+      'after',
+      [
+        '',
+        'Writes nothing. Skills, verbs, hooks, and gate stages are read from the',
+        'tree, so the list cannot drift from it. A row that exists but cannot be',
+        'described is named under Gaps.',
+        '',
+        'Examples:',
+        '  canon upstream catalog',
+        '  canon upstream catalog --json',
+        '',
+      ].join('\n'),
+    )
+    .action(async (opts: RootOption) => {
+      process.exitCode = await runCatalog(opts)
+    })
+
+  upstream
+    .command('due')
+    .description('Say whether a digest is due, from the cursor and the install')
+    .helpOption('-h, --help', 'Show this help message')
+    .option('--root <path>', 'Repository to read, defaulting to the main root')
+    .option('--json', 'Add a machine-readable record on stdout')
+    .addHelpText(
+      'after',
+      [
+        '',
+        'Due when the cursor is a week old and the installed version is ahead of',
+        'it, or sooner when an Added line in the gap names a canon surface. The',
+        'gap is read from GitHub at most once a day and cached under the scratch',
+        'folder, and a failed read is held for the day as well.',
+        '',
+        'Exit codes:',
+        '  0  answered, whether or not a digest is due',
+        '',
+        'Examples:',
+        '  canon upstream due --json',
+        '',
+      ].join('\n'),
+    )
+    .action(async (opts: RootOption) => {
+      process.exitCode = await runDue(opts)
+    })
+
+  upstream
+    .command('advance')
+    .description('Move the cursor to a version once its digest is filed')
+    .helpOption('-h, --help', 'Show this help message')
+    .argument('<version>', 'Last version the digest covered')
+    .requiredOption('--intake <slug>', 'Intake folder the digest was filed in')
+    .option('--no-llms', 'Keep the stored llms.txt rather than fetching it')
+    .option('--root <path>', 'Repository to write, defaulting to the cwd')
+    .option('--json', 'Add a machine-readable record on stdout')
+    .addHelpText(
+      'after',
+      [
+        '',
+        'Writes the cursor and the current llms.txt under the upstream record',
+        'folder through a temp file and a rename. It refuses a version older than',
+        'the stored cursor.',
+        '',
+        'Exit codes:',
+        '  0  the cursor moved',
+        '  1  refused, with the reason on stderr or in the JSON record',
+        '',
+        'Examples:',
+        '  canon upstream advance 2.1.289 --intake claude-code-2-1-257-to-2-1-289',
+        '',
+      ].join('\n'),
+    )
+    .action(async (version: string, opts: AdvanceOptions) => {
+      process.exitCode = await runAdvance(version, opts)
+    })
+}
+
+function refuse(
+  reason: Refusal,
+  extra: Record<string, unknown>,
+  emitJson: boolean,
+): number {
+  logStep('Refused')
+  logWarn(REFUSALS[reason])
+  outro()
+
+  if (emitJson) {
+    process.stdout.write(
+      `${JSON.stringify({ ...extra, reason, message: REFUSALS[reason] })}\n`,
+    )
+  }
+
+  return 1
+}
+
+async function fetchLlms(): Promise<string | null> {
+  try {
+    const response = await fetch(LLMS_URL)
+
+    return response.ok ? await response.text() : null
+  } catch {
+    return null
+  }
+}
+
+async function runFetch(opts: FetchOptions): Promise<number> {
+  const emitJson = opts.json ?? false
+  const cursorRoot = opts.root ? resolve(opts.root) : await mainWorktreeRoot()
+  const readRoot = opts.root ? resolve(opts.root) : await currentWorktreeRoot()
+
+  intro('canon upstream fetch')
+
+  if (opts.since !== undefined && !VERSION.test(opts.since)) {
+    return refuse('bad-since', { since: opts.since }, emitJson)
+  }
+  const cursor = opts.since ?? readCursor(cursorRoot)?.version
+  if (!cursor) return refuse('no-cursor', {}, emitJson)
+
+  const digest = await buildDigest(cursor, githubPageFetcher(), (name) =>
+    grepHint(readRoot, name),
+  )
+  if (digest.kind === 'failed') {
+    return refuse(digest.reason, {}, emitJson)
+  }
+  if (digest.kind === 'cursor-missing') {
+    return refuse('cursor-missing', { cursor: digest.cursor }, emitJson)
+  }
+
+  const llms = await fetchLlms()
+  const difference =
+    llms === null ? null : llmsDifference(readLastLlms(cursorRoot), llms)
+
+  logStep('Range')
+  logInfo(
+    `${digest.from} to ${digest.to}, ${plural(digest.releases, 'release')}, ${plural(digest.lines.length, 'line')} kept`,
+  )
+  if (difference === null) logWarn('llms.txt could not be fetched')
+  outro()
+
+  if (!emitJson) {
+    for (const line of digest.lines) {
+      process.stdout.write(`${line.version}\t${line.text}\n`)
+    }
+  } else {
+    process.stdout.write(
+      `${JSON.stringify({
+        from: digest.from,
+        to: digest.to,
+        releases: digest.releases,
+        lines: digest.lines,
+        llms: difference,
+      })}\n`,
+    )
+  }
+
+  return 0
+}
+
+const DUE_TEXT: Record<DueReason, string> = {
+  'no-cursor': 'No digest has been run, so there is no cursor.',
+  week: 'A week has passed since the last digest.',
+  vocabulary: 'A release since the last digest added something canon may use.',
+  current: 'The installed version is at or below the cursor.',
+  recent:
+    'The last digest is under a week old and nothing in the gap stands out.',
+  'unknown-version': 'The installed version could not be read.',
+}
+
+async function installedVersion(): Promise<string | null> {
+  try {
+    const result = await $`claude --version`.quiet().nothrow()
+    const match = /^\d+(\.\d+)*/.exec(result.stdout.toString().trim())
+
+    return match ? match[0] : null
+  } catch {
+    return null
+  }
+}
+
+// A failed read is stored as a null gap, so a rate limit hit by one session of
+// a wave is not retried by the nineteen after it.
+async function readGap(
+  root: string,
+  installed: string,
+  cursor: string,
+  now: Date,
+): Promise<Gap | null> {
+  const cached = readDueCache(root, installed, cursor, now)
+  if (cached) return cached.gap
+
+  // The hook that calls this has a 10 second timeout, and a network that drops
+  // packets would otherwise hold every session start to it with nothing cached.
+  const walk = await walkReleases(
+    cursor,
+    githubPageFetcher(process.env, AbortSignal.timeout(READ_BUDGET_MS)),
+  )
+  const gap: Gap | null =
+    walk.kind === 'reached'
+      ? {
+          releases: walk.releases.length,
+          lines: walk.releases
+            .flatMap(keepLines)
+            .map((line) => line.text)
+            .filter(passesVocabulary),
+        }
+      : null
+
+  try {
+    await writeDueCache(root, {
+      checkedAt: now.toISOString(),
+      installed,
+      cursor,
+      gap,
+    })
+  } catch {
+    // A cache that cannot be written costs a request, not a wrong answer.
+  }
+
+  return gap
+}
+
+async function runDue(opts: RootOption): Promise<number> {
+  const root = opts.root ? resolve(opts.root) : await mainWorktreeRoot()
+  const now = new Date()
+  const cursor = readCursor(root)
+  const installed = await installedVersion()
+  const isAhead =
+    cursor !== null &&
+    installed !== null &&
+    compareVersions(installed, cursor.version) > 0
+  const gap = isAhead
+    ? await readGap(root, installed, cursor.version, now)
+    : null
+  const result = decideDue({ installed, cursor, gap, now })
+
+  intro('canon upstream due')
+  logStep(result.due ? 'Due' : 'Not due')
+  logInfo(DUE_TEXT[result.reason])
+  outro()
+
+  if (opts.json) {
+    process.stdout.write(
+      `${JSON.stringify({
+        ...result,
+        installed,
+        cursor: cursor?.version ?? null,
+      })}\n`,
+    )
+  }
+
+  return 0
+}
+
+async function runCatalog(opts: RootOption): Promise<number> {
+  const root = opts.root ? resolve(opts.root) : await currentWorktreeRoot()
+  const catalog = buildCatalog(root)
+
+  if (opts.json) {
+    process.stdout.write(`${JSON.stringify(catalog)}\n`)
+  } else {
+    process.stdout.write(`${renderCatalog(catalog)}\n`)
+  }
+
+  return 0
+}
+
+async function runAdvance(
+  version: string,
+  opts: AdvanceOptions,
+): Promise<number> {
+  const emitJson = opts.json ?? false
+  const root = opts.root ? resolve(opts.root) : await mainWorktreeRoot()
+
+  intro('canon upstream advance')
+
+  const llms = opts.llms ? await fetchLlms() : null
+  const outcome = await advanceCursor(root, {
+    version,
+    intake: opts.intake,
+    today: new Date().toISOString().slice(0, 10),
+    llms,
+  })
+  if (outcome.kind === 'refused') {
+    return refuse(outcome.reason, { version }, emitJson)
+  }
+
+  logStep('Cursor')
+  logInfo(`Moved to ${version}, filed as ${opts.intake}`)
+  if (opts.llms && llms === null) {
+    logWarn('llms.txt could not be fetched, so the stored copy is unchanged')
+  }
+  outro()
+
+  if (emitJson) {
+    process.stdout.write(
+      `${JSON.stringify({
+        version,
+        intake: opts.intake,
+        advanced: true,
+        llms: llms === null ? 'kept' : 'stored',
+      })}\n`,
+    )
+  }
+
+  return 0
+}