@erclx/canon 5.30.0 → 5.32.0

package/src/cli/help.ts

@@ -58,9 +58,9 @@ export const COMMAND_GROUPS: { title: string; rows: CommandRow[] }[] = [
       ['sessions [cmd]', 'Resolve live sessions to worktree and branch'],
       ['worktrees [cmd]', 'Reclaim worktrees whose branches merged'],
       ['hooks [cmd]', 'Run the steps a git hook drives (post-merge)'],
-      ['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'],
+      ['upstream [cmd]', 'Read Claude Code releases (fetch, catalog, advance)'],
+      ['feedback', 'File toolkit feedback as a GitHub issue'],
     ],
   },
   {
@@ -74,7 +74,6 @@ export const COMMAND_GROUPS: { title: string; rows: CommandRow[] }[] = [
       ['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'],
     ],
   },
@@ -127,11 +126,11 @@ const EXAMPLES = [
   'canon secrets scan --json',
   'canon deps audit --json',
   'canon labels audit --json',
-  'canon repo metadata propose --json',
   'canon census --json',
   'canon audits run --json',
   'canon gate run --all --no-write',
   'canon upgrade --json',
+  'canon upstream fetch --since 2.1.256 --json',
 ]
 
 // The frame follows stdout's TTY state rather than `palette`, whose blank

package/src/cli.ts

@@ -37,10 +37,9 @@ import { register as gate } from '@/commands/gate'
 import { register as secrets } from '@/commands/secrets'
 import { register as deps } from '@/commands/deps'
 import { register as labels } from '@/commands/labels'
-import { register as autoship } from '@/commands/autoship'
 import { register as pr } from '@/commands/pr'
-import { register as repo } from '@/commands/repo'
 import { register as census } from '@/commands/census'
+import { register as upstream } from '@/commands/upstream'
 import { register as targets } from '@/commands/targets'
 import { register as upgrade } from '@/commands/upgrade'
 import { readInstalled, UNKNOWN_LABEL } from '@/version/installed'
@@ -98,10 +97,9 @@ hooks(program)
 secrets(program)
 deps(program)
 labels(program)
-autoship(program)
 pr(program)
-repo(program)
 census(program)
+upstream(program)
 audits(program)
 gate(program)
 upgrade(program)

package/src/commands/claude.ts

@@ -157,21 +157,17 @@ interface RoutingOptions {
   readonly json?: boolean
 }
 
-const SEEDED_FILES: readonly string[] = [
-  'ARCHITECTURE.md',
-  'REQUIREMENTS.md',
-  'DESIGN.md',
-]
-const SEEDED_DIRS: readonly string[] = ['memory', 'tasks', 'wireframes']
+const SEEDED_FILES: readonly string[] = ['REQUIREMENTS.md', 'DESIGN.md']
+const SEEDED_DIRS: readonly string[] = ['tasks']
 
 /**
  * Where a `SEEDED_DIRS` entry resolves for the sync presence check.
  *
- * `wireframes` is a tracked surface entry, resolved under `canon/` ahead of
- * `.claude/`, while `memory` and `tasks` are session records resolved under
- * `.canon/` ahead of `.claude/`. Routing every name through `recordDir`
- * reported a migrated target's `canon/wireframes/` as missing, since that
- * resolver never checks `canon/`.
+ * A tracked surface entry resolves under `canon/` ahead of `.claude/`, while
+ * `tasks` is a session record resolved under `.canon/` ahead of
+ * `.claude/`. Routing every name through `recordDir` would report a migrated
+ * target's surface folder as missing, since that resolver never checks
+ * `canon/`.
  */
 export function seededDirPath(resolved: string, name: string): string {
   return SURFACE_ENTRIES.includes(name)
@@ -296,7 +292,7 @@ export function register(program: Command): void {
         '  1  refused, with the reason on stderr',
         '',
         'Reports rather than gates. Whether a bullet belongs in a rule is the',
-        'judgment 592-claude-md states, and naming a path is evidence for it',
+        'judgment canon/context/context-model/overview.md states, and naming a path is evidence for it',
         'rather than the answer.',
         '',
         'Examples:',
@@ -615,9 +611,7 @@ async function runSync(target: string): Promise<number> {
 
   // A record folder resolves at either root, so a migrated target is reported as
   // seeded rather than sent to `canon claude init` to re-create records it
-  // already holds. `wireframes` is a tracked surface entry instead, resolved
-  // through `surfaceDir`, since a migrated target holds it at `canon/` rather
-  // than under either record root.
+  // already holds.
   logStep('Seeded')
   for (const name of SEEDED_FILES) {
     if (existsSync(join(resolved, '.claude', name))) logInfo(name)

package/src/commands/context.ts

@@ -18,18 +18,6 @@ import {
   requiredSections,
   type SectionFinding,
 } from '@/context/audit'
-import {
-  architectureRel,
-  type ArchitectureReport,
-  coveredCount,
-  isOverCount,
-  isOverLength,
-  isOverRisks,
-  measureArchitecture,
-  missingRevisit,
-  overWords,
-  testableCount,
-} from '@/context/architecture'
 import { auditCitations, type CitationReport } from '@/context/citations'
 import {
   CANONICAL_DOC_TYPES,
@@ -65,10 +53,6 @@ import {
   type RequirementsReport,
 } from '@/context/requirements'
 import { auditIndexes, type FolderDrift } from '@/context/index-drift'
-import {
-  measureWireframeFolder,
-  type WireframeStatesReport,
-} from '@/context/wireframe-states'
 import { RENDER_WIDTH } from '@/markdown/structure'
 import {
   frameError,
@@ -104,7 +88,7 @@ export function register(program: Command): void {
   context
     .command('audit')
     .description(
-      'Report required sections, entry length, citations, reference form, catalog tables, provenance, index drift, the architecture record against its own ceiling, entry cap, word cap, and risk cap, the requirements record against its own word cap, and wireframe states against their evidence folders',
+      'Report required sections, entry length, citations, reference form, catalog tables, provenance, index drift, and the requirements record against its own word cap',
     )
     .argument('[path]', 'Project root, defaulting to the current directory')
     .helpOption('-h, --help', 'Show this help message')
@@ -127,21 +111,14 @@ export function register(program: Command): void {
         '  1  refused, with the reason on stderr',
         '  2  a gating finding is present',
         '',
-        'An unresolved citation always gates. An architecture record that',
-        'states its own line allowances gates when it is past the ceiling',
-        'those derive, on any run except --citations-only, which never',
-        'measures it. A record stating an entry cap gates the same way when',
-        'it holds more decisions than the cap, and a record stating that',
-        'every decision closes with a revisit sentence gates when one lacks',
-        'it. A record stating a word cap a decision or a risk bullet cap',
-        'gates past either, and a requirements record stating a word cap',
-        'gates past it. A record stating none of these is reported and',
-        'never gated. --gate widens the gate to the other two',
-        'findings that are facts rather than judgments: a missing required',
-        'section and index drift. A context entry requires Overview and',
-        'Layout, and a wireframe requires Regions, States, Copy, and Not on',
-        'this surface. Entry length, reference form, table, provenance, and the',
-        'record claim classification are judgments under both.',
+        'An unresolved citation always gates. A requirements record',
+        'stating a word cap gates past it, on any run except',
+        '--citations-only, which never measures it. A record stating no',
+        'cap is reported and never gated. --gate widens the gate to the',
+        'other two findings that are facts rather than judgments: a',
+        'missing required section and index drift. A context entry',
+        'requires Overview and Layout. Entry length, reference form,',
+        'table, and provenance are judgments under both.',
         '',
         'Depth and bullet weight are stated over every markdown file rather',
         'than over a context entry, so `canon markdown audit` measures them.',
@@ -177,7 +154,7 @@ export function register(program: Command): void {
     .option('--base <ref>', 'Far side of the range, defaulting to the trunk')
     .option(
       '--doc-types <list>',
-      `Comma-separated canonical doc types (default: all five: ${CANONICAL_DOC_TYPES.join(', ')})`,
+      `Comma-separated canonical doc types (default: all three: ${CANONICAL_DOC_TYPES.join(', ')})`,
     )
     .option(
       '--backend <name>',
@@ -201,7 +178,7 @@ export function register(program: Command): void {
         'Examples:',
         '  canon context classify diff',
         '  canon context classify diff --base origin/main --json',
-        '  canon context classify diff --doc-types context,wireframes',
+        '  canon context classify diff --doc-types context',
         '',
       ].join('\n'),
     )
@@ -212,13 +189,13 @@ export function register(program: Command): void {
   classify
     .command('sweep')
     .description(
-      'Classify every section of the five canonical doc types, split at H3',
+      'Classify every section of the three canonical doc types, split at H3',
     )
     .argument('[path]', 'Project root, defaulting to the current directory')
     .helpOption('-h, --help', 'Show this help message')
     .option(
       '--doc-types <list>',
-      `Comma-separated canonical doc types (default: all five: ${CANONICAL_DOC_TYPES.join(', ')})`,
+      `Comma-separated canonical doc types (default: all three: ${CANONICAL_DOC_TYPES.join(', ')})`,
     )
     .option(
       '--backend <name>',
@@ -612,7 +589,7 @@ async function runAudit(
     return refuse('bad-folder-list', names, gateOnly, root, opts.json ?? false)
   }
 
-  // The root base is opt-in. A target carrying a root `wireframes/` would
+  // The root base is opt-in. A target carrying a root folder of its own would
   // otherwise be audited against a standard it never adopted, on a bare run
   // that named nothing.
   const named = opts.folder !== undefined
@@ -667,17 +644,7 @@ async function runAudit(
   // Absent under `--citations-only` and null when the project carries no
   // record. A run that never looked and a project with nothing to look at are
   // different answers, and one value for both reports the second as the first.
-  const record = gateOnly ? undefined : await measureArchitecture(root)
   const requirements = gateOnly ? undefined : await measureRequirements(root)
-  const wireframes = gateOnly
-    ? []
-    : (
-        await Promise.all(
-          folders
-            .filter((folder) => folder.name === 'wireframes')
-            .map((folder) => measureWireframeFolder(root, folder)),
-        )
-      ).flat()
 
   if (gateOnly) {
     reportGate(citations)
@@ -691,9 +658,7 @@ async function runAudit(
     reportTables(entries)
     reportProvenance(entries, folders)
     reportDrift(drift)
-    reportRecord(record, root)
     reportRequirements(requirements, root)
-    reportWireframeStates(wireframes)
     outro()
   }
 
@@ -730,22 +695,15 @@ async function runAudit(
         // Null says the run opened the project and found no record, which a
         // target that never wrote one is entitled to. Absent says the run
         // never looked, which is `--citations-only`.
-        architecture: gateOnly ? undefined : (record ?? null),
-        // The same three states for the requirements record.
         requirements: gateOnly ? undefined : (requirements ?? null),
-        // Absent under `--citations-only`, for the same reason as above. An
-        // empty array under the ordinary run says the project carries no
-        // wireframes folder or no entry carrying a States table, which is a
-        // fact rather than an unmeasured run.
-        wireframes: gateOnly ? undefined : wireframes,
         checkpoints: {
           lines: LENGTH_CHECKPOINT,
           renderWidth: RENDER_WIDTH,
           provenanceFolder: PROVENANCE_FOLDER,
           requiredSections: REQUIRED_SECTIONS,
           // Keyed on the audited folder name. The flat key above stays for a
-          // caller that read it before wireframes owed a section, since turning
-          // it into this map would break that caller without an error.
+          // caller that read it first, since removing it would break that
+          // caller without an error.
           requiredSectionsByFolder: REQUIRED_SECTIONS_BY_FOLDER,
         },
       })}\n`,
@@ -754,17 +712,10 @@ async function runAudit(
 
   const gating = isGating({
     unresolvedCitations: citations.unresolved.length,
-    recordOverLength: record !== undefined && isOverLength(record),
-    recordOverCount: record !== undefined && isOverCount(record),
-    recordMissingRevisit:
-      record !== undefined && missingRevisit(record).length > 0,
-    recordOverWords: record !== undefined && overWords(record).length > 0,
-    recordOverRisks: record !== undefined && isOverRisks(record),
     requirementsOverWords:
       requirements !== undefined && isOverWordCap(requirements),
     sections,
     drift,
-    wireframes,
     widened,
   })
 
@@ -945,8 +896,7 @@ function reportReferenceForm(
 
 /**
  * Names the path each finding belongs to, which is an entry in the folder named
- * under `.claude/`, the folder itself in a domain split across one, and the
- * file in any wireframe folder. States
+ * under `.claude/`, and the folder itself in a domain split across one. States
  * the reach on every run for the reason the provenance report does.
  *
  * This prints ahead of the four readability measures because a missing section
@@ -983,7 +933,7 @@ function reportSections(
     )
   }
   logInfo(
-    'A heading at any level counts. Each entry answers for itself, except in a context domain split across a folder, where a sibling answers for the rest. A wireframe answers for itself in every folder.',
+    'A heading at any level counts. Each entry answers for itself, except in a context domain split across a folder, where a sibling answers for the rest.',
   )
 
   if (missing.length === 0) {
@@ -1136,178 +1086,6 @@ function reportProvenance(
   )
 }
 
-/** How each classification reads in the report. */
-const CLAIM_LABEL: Record<string, string> = {
-  countable: 'countable claim',
-  invariant: 'structural invariant',
-  neither: 'reasoning only',
-}
-
-/**
- * Reports the architecture record against the ceiling it states for itself and
- * against what a machine could test in it.
- *
- * The length reading is a fact and gates. Everything below it names candidates
- * a reader adjudicates, because deciding whether a sentence states a claim is a
- * judgment no parser settles, and a stored verdict would age the way the
- * anchors it sits beside already do. Nothing is stored: every run reclassifies,
- * so an entry rewritten tomorrow is read as it stands then.
- */
-function reportRecord(
-  report: ArchitectureReport | undefined,
-  root: string,
-): void {
-  logStep('Architecture record')
-
-  if (report === undefined) {
-    logInfo(
-      `Out of scope. The project carries no ${architectureRel(root)}, so there was no record to measure.`,
-    )
-    return
-  }
-
-  const decisions = report.decisions.length
-  const { allowances } = report
-
-  logInfo(
-    `${plural(report.words, 'word')} across ${plural(report.lines, 'line')}. The whole file's count never gates.`,
-  )
-  if (report.risksWords !== undefined) {
-    logInfo(
-      `\`## Risks / open questions\` holds ${plural(report.risksWords, 'word')}.`,
-    )
-  }
-
-  const longDecisions = overWords(report)
-  if (report.wordCap === undefined) {
-    logInfo(
-      'No word cap a decision stated, so each decision word count is reported and never gated.',
-    )
-  } else if (longDecisions.length > 0) {
-    for (const entry of longDecisions) {
-      logError(
-        `"${entry.heading}" holds ${entry.words} words against a cap of ${report.wordCap} a decision.`,
-      )
-    }
-  } else {
-    logInfo(
-      `Every decision fits the cap of ${report.wordCap} words a decision.`,
-    )
-  }
-
-  if (report.riskCap === undefined) {
-    logInfo('No risk bullet cap stated, so the Risks section is never gated.')
-  } else if (report.risksBullets === undefined) {
-    logWarn(
-      `The record states a cap of ${report.riskCap} risk bullets and carries no \`## Risks / open questions\` section to count.`,
-    )
-  } else if (isOverRisks(report)) {
-    logError(
-      `${plural(report.risksBullets, 'risk bullet')} against a cap of ${report.riskCap}, nested bullets counted.`,
-    )
-  } else {
-    logInfo(
-      `${plural(report.risksBullets, 'risk bullet')} against a cap of ${report.riskCap}, nested bullets counted.`,
-    )
-  }
-
-  if (allowances === undefined) {
-    logInfo(
-      `Covers ${report.rel} alone. No standard sets a length rule for it and this record states none, so its ${plural(report.lines, 'line')} across ${plural(decisions, 'decision')} are reported and nothing is gated.`,
-    )
-    logInfo(
-      'A record declaring an allowance for its frame and one a decision is measured against the ceiling those two derive. That rule belongs to whichever record writes it, never to the toolkit.',
-    )
-  } else {
-    logInfo(
-      `Covers ${report.rel} alone, which states its own allowance of ${plural(allowances.frame, 'line')} for the frame and ${allowances.perDecision} a decision.`,
-    )
-    if (isOverLength(report)) {
-      logError(
-        `${report.lines} lines against a ceiling of ${report.ceiling} from ${plural(decisions, 'decision')}`,
-      )
-    } else {
-      logInfo(
-        `${report.lines} lines against a ceiling of ${report.ceiling} from ${plural(decisions, 'decision')}.`,
-      )
-    }
-    logInfo(
-      `The ceiling rises with the decision count, so adding a decision buys ${allowances.perDecision} lines and the check passes exactly when the file grew.`,
-    )
-  }
-
-  if (report.entryCap === undefined) {
-    logInfo(
-      `${plural(decisions, 'decision')} and no entry cap stated, so the count is reported and never gated.`,
-    )
-  } else if (isOverCount(report)) {
-    logError(
-      `${plural(decisions, 'decision')} against a cap of ${report.entryCap}. Merge two or retire one, never compress.`,
-    )
-  } else {
-    logInfo(
-      `${plural(decisions, 'decision')} against a cap of ${report.entryCap}.`,
-    )
-  }
-
-  const revisited = report.decisions.filter((entry) => entry.revisit).length
-  const lackingRevisit = missingRevisit(report)
-  if (!report.revisitRequired) {
-    logInfo(
-      `${revisited} of ${plural(decisions, 'decision')} close with a revisit sentence, and the record states no revisit clause, so this is reported and never gated.`,
-    )
-  } else if (lackingRevisit.length > 0) {
-    for (const heading of lackingRevisit) {
-      logError(
-        `"${heading}" carries no sentence opening "Revisit when", which the record requires of every decision.`,
-      )
-    }
-  } else {
-    logInfo(
-      `Every one of ${plural(decisions, 'decision')} closes with the revisit sentence the record requires.`,
-    )
-  }
-
-  if (decisions === 0) {
-    logWarn('The record declares no decision, so nothing was classified.')
-    return
-  }
-
-  const testable = testableCount(report)
-  const covered = coveredCount(report)
-
-  logInfo(
-    'A countable claim carries a figure a run could recompute and an invariant quantifies over a named tree a walk could falsify. Both are candidates a reader settles, and neither gates.',
-  )
-  logInfo(
-    'A figure spelled in words reads as uncounted, since a cardinal in prose is pronominal more often than measured. Entries are counted by heading, so a heading carrying several decisions counts once and the total reads low by however many it holds.',
-  )
-  const line = `${testable} of ${decisions} carry a claim a machine could test, ${covered} of which name a check that exists`
-  // A record whose every testable claim names a check has nothing to act on,
-  // and so does one carrying no testable claim at all. Warning on both is how
-  // a section becomes one nobody reads after the second run.
-  if (testable > covered) logWarn(line)
-  else logInfo(`${line}.`)
-  logInfo(
-    'Coverage reads the entry rather than the tree, so a claim some check happens to cover without the entry naming it reads as unchecked.',
-  )
-
-  pipeOutput(
-    report.decisions
-      .map((entry) => {
-        const kind = CLAIM_LABEL[entry.claim] ?? entry.claim
-        const evidence =
-          entry.figures.length > 0 ? `  ${entry.figures.join(' ')}` : ''
-        const checks =
-          entry.checks.length > 0
-            ? `\n  checked by ${entry.checks.join(', ')}`
-            : ''
-        return `${report.rel}:${entry.line}  ${kind}${evidence}  ${plural(entry.words, 'word')}\n  ${entry.heading}${checks}`
-      })
-      .join('\n'),
-  )
-}
-
 /** Reports the requirements record against the word cap it states, if any. */
 function reportRequirements(
   report: RequirementsReport | undefined,
@@ -1353,43 +1131,3 @@ function reportDrift(drift: readonly FolderDrift[]): void {
   logWarn(plural(lines.length, 'disagreement'))
   pipeOutput(lines.join('\n'))
 }
-
-function reportWireframeStates(
-  wireframes: readonly WireframeStatesReport[],
-): void {
-  logStep('Wireframe states')
-
-  const withRows = wireframes.filter((entry) => entry.rows.length > 0)
-  if (withRows.length === 0) {
-    logInfo(
-      'No wireframe carries a States table, so nothing was checked against its evidence folders.',
-    )
-    return
-  }
-
-  const lines = withRows.flatMap((entry) => [
-    ...entry.missingFolders.map(
-      (finding) =>
-        `${entry.rel}:${finding.line}  ${finding.state}  no folder at ${finding.path}`,
-    ),
-    ...entry.unlistedFolders.map(
-      (finding) =>
-        `${entry.rel}  ${finding.root}/${finding.folder}  named in no row`,
-    ),
-    ...(entry.sketchWithEvidence
-      ? [
-          `${entry.rel}:${entry.sketchLine}  a plaintext sketch sits beside evidence that already exists`,
-        ]
-      : []),
-  ])
-
-  if (lines.length === 0) {
-    logInfo(
-      `${plural(withRows.length, 'wireframe')} checked, every state matched one-to-one with its evidence folder.`,
-    )
-    return
-  }
-
-  logWarn(plural(lines.length, 'finding'))
-  pipeOutput(lines.join('\n'))
-}