@erclx/canon 5.14.1 → 5.16.0

package/src/commands/sandbox.ts

@@ -13,6 +13,11 @@ import {
   coveragePercent,
   type CoverageReport,
 } from '@/sandbox/coverage'
+import {
+  equivalenceExitCode,
+  runEquivalence as collectEquivalence,
+  type EquivalenceRecord,
+} from '@/sandbox/equivalence'
 import {
   expectFilePath,
   parseTarget,
@@ -338,6 +343,71 @@ function runCoverage(options: CoverageOptions): void {
   process.exitCode = wrongExemption || rolloutIncomplete ? 1 : 0
 }
 
+interface EquivalenceOptions {
+  readonly base: string
+  readonly includeAnchor?: boolean
+  readonly out?: string
+  readonly masks: boolean
+  readonly json?: boolean
+}
+
+/**
+ * Provisions every arm on a base ref and on this checkout, then names what
+ * differs. The record is the only thing on stdout, and a red arm that is red the
+ * same way on both sides is reported without failing the run, since it proves
+ * nothing either way.
+ */
+async function runEquivalence(
+  targets: string[],
+  options: EquivalenceOptions,
+): Promise<void> {
+  if (reportAbsentScenarioTree()) return
+
+  intro('canon sandbox equivalence')
+
+  let record: EquivalenceRecord
+  try {
+    record = await collectEquivalence({
+      root: PROJECT_ROOT,
+      targets,
+      base: options.base,
+      includeAnchor: options.includeAnchor === true,
+      useMasks: options.masks,
+      out: options.out,
+    })
+  } catch (error) {
+    const reason = error instanceof Error ? error.message : String(error)
+    logError(`Cannot provision the baseline ${options.base}: ${reason}`)
+    outro()
+    process.exitCode = 1
+
+    return
+  }
+
+  logStep(`Base ${record.base} (${record.baseCommit.slice(0, 8)})`)
+  logInfo(`canon ${record.canonVersion}`)
+
+  for (const arm of record.arms) {
+    if (arm.state === 'identical' || arm.state === 'skipped-anchor') continue
+    const detail = arm.differs.length > 0 ? `: ${arm.differs.join(', ')}` : ''
+    if (arm.state === 'differs') logRemove(`${arm.arm} differs${detail}`)
+    else logWarn(`${arm.arm} is ${arm.state}`)
+  }
+  for (const line of record.masksApplied) logInfo(`masked ${line}`)
+  for (const error of record.errors) logError(error)
+
+  const { counts } = record
+  logStep('Equivalence')
+  const summary = `${counts.identical} identical, ${counts.differs} differs, ${counts['red-on-base']} red-on-base, ${counts['skipped-anchor']} skipped-anchor`
+  if (equivalenceExitCode(record) === 0) logInfo(summary)
+  else logWarn(summary)
+
+  if (options.json === true) process.stdout.write(`${JSON.stringify(record)}\n`)
+
+  outro()
+  process.exitCode = equivalenceExitCode(record)
+}
+
 function runCheck(
   target: string,
   arm: string | undefined,
@@ -482,4 +552,42 @@ export function register(program: Command): void {
     .action((options: CoverageOptions) => {
       runCoverage(options)
     })
+
+  sandbox
+    .command('equivalence')
+    .description(
+      'Provision every arm on a base ref and on this checkout, and diff the trees',
+    )
+    .argument(
+      '[target...]',
+      'Category or <category>:<command>, defaulting to every category',
+    )
+    .helpOption('-h, --help', 'Show this help message')
+    .option('--base <ref>', 'Ref the baseline is provisioned from', 'main')
+    .option(
+      '--include-anchor',
+      'Also run the arms that push to the shared GitHub anchor, one at a time (attended)',
+    )
+    .option('--out <dir>', 'Keep the provisioned trees and logs in this folder')
+    .option(
+      '--no-masks',
+      'Compare every path, listing what each mask would hide',
+    )
+    .option('--json', 'Emit the record as JSON on stdout')
+    .addHelpText(
+      'after',
+      [
+        '',
+        'Examples:',
+        '  canon sandbox equivalence claude --json',
+        '  canon sandbox equivalence claude:plan-feature --base origin/main',
+        '',
+        'Provisions offline only and never runs sandbox/run.sh or a claude binary.',
+        'Exit codes: 0 when every compared arm is identical or red the same way',
+        'on both sides, 1 on any difference, exit mismatch, or enumeration error.',
+      ].join('\n'),
+    )
+    .action((targets: string[], options: EquivalenceOptions) =>
+      runEquivalence(targets, options),
+    )
 }

package/src/context/classify/prompts.ts

@@ -20,7 +20,7 @@ File types and what they hold:
 Verdicts (pick exactly one):
 - KEEP: states current design, a rule, copy, a decision with its rejected alternative, or a live gotcha, on the right surface.
 - REPLACE: restates a fact or figure the existing section already carries ("moved again", "now", "the count moved", a newer number appended after an older one). The old statement should be rewritten in place, not appended to.
-- HISTORY: narrates how things got here: which branch/PR changed what, "closed on", "did not survive", review-pass stories, pick-by-pick rounds. The current state is what belongs; the trail goes to the PR or a decision log.
+- HISTORY: narrates how things got here: which branch/PR changed what, "closed on", "did not survive", review-pass stories, pick-by-pick rounds. The current state is what belongs; the trail goes to the PR.
 - MOVE: correct content on the wrong surface (domain mechanism in ARCHITECTURE.md, implementation detail in a wireframe).
 
 Return only JSON: {"verdict": "...", "quote": "<the shortest added phrase that decided it>", "reason": "<one sentence>"}

package/src/context/folders.ts

@@ -19,7 +19,6 @@ import { SURFACE_ROOTS } from '@/surface-root'
  */
 export const DEFAULT_FOLDERS: readonly string[] = [
   'context',
-  'decisions',
   'diagrams',
   'wireframes',
 ]

package/src/demo/compile.ts

@@ -134,8 +134,8 @@ export function compilePlan(draft: Draft, options: CompileOptions): DemoPlan {
     url: '',
     viewport: VIEWPORT,
     output: {
-      video: `${options.outDir}/${options.slug}.webm`,
-      still: `${options.outDir}/${options.slug}.png`,
+      video: `${options.outDir}/${options.slug}/take/${options.slug}.webm`,
+      still: `${options.outDir}/${options.slug}/take/${options.slug}.png`,
     },
     pointer: { travelMs: POINTER_TRAVEL_MS, typeDelayMs: TYPE_DELAY_MS },
     annotations: ANNOTATIONS,
@@ -252,8 +252,12 @@ export function parsePlan(text: string): PlanParse {
       },
       ...(colorScheme.value && { colorScheme: colorScheme.value }),
       output: {
-        video: asText(output.video) || `demos/${slug || 'demo'}.webm`,
-        still: asText(output.still) || `demos/${slug || 'demo'}.png`,
+        video:
+          asText(output.video) ||
+          `demos/${slug || 'demo'}/take/${slug || 'demo'}.webm`,
+        still:
+          asText(output.still) ||
+          `demos/${slug || 'demo'}/take/${slug || 'demo'}.png`,
       },
       pointer: {
         travelMs: asNumber(pointer.travelMs, POINTER_TRAVEL_MS),

package/src/demo/container.ts

@@ -135,7 +135,7 @@ export async function convertToGif(
 
 /**
  * Written beside the video by default, so frames fall under the same
- * `demos/*.png` gitignore entry the still already uses with no new rule
+ * `take` folder gitignore entry the still already uses with no new rule
  * needed. One frame a second by default, matched to the seconds-to-tens-of-
  * seconds length a tuned recording runs, without a smarter sampling strategy
  * nobody has asked for.

package/src/gov/renames.ts

@@ -34,8 +34,9 @@ export function loadRenames(root: string): Renames {
 
 /**
  * Follows a declared rename to the name the toolkit ships the rule under now,
- * through every later rename of that name. The ledger is never pruned, so a
- * target several releases behind still reaches the current name.
+ * through every later rename of that name. The ledger is pruned only once a
+ * rule is retired, so a target several releases behind still reaches the
+ * current name of every rule that still ships.
  *
  * Returns nothing when the chain ends on a name with no source, or loops,
  * since installing a guess is worse than the retire the caller falls back to.

package/src/help.ts

@@ -45,6 +45,7 @@ export const COMMAND_GROUPS: { title: string; rows: CommandRow[] }[] = [
       ['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)'],
+      ['canvas [cmd]', 'Local canvas of pages and frames (serve, list)'],
     ],
   },
   {

package/src/migrate/rename.ts

@@ -168,10 +168,11 @@ const AITK_ARTICLE = /\b([Aa])n(\s+`?)(canon|CANON|Canon)(?![A-Za-z])/g
 /**
  * The `aitk` to `canon` rename.
  *
- * `aitk-sandbox` is a separate repository that is not being renamed. It has to
- * win against the bare token, and it also has to win against the owner-scoped
- * spelling, since `erclx/aitk-sandbox` would otherwise rewrite to
- * `erclx/canon-sandbox` and name a repository that does not exist.
+ * `aitk-sandbox` is the retired spelling of a repository that was later renamed
+ * `canon-sandbox`, and GitHub still resolves the old name through a redirect.
+ * It has to win against the bare token, and it also has to win against the
+ * owner-scoped spelling, so a consumer's text naming `erclx/aitk-sandbox` keeps
+ * the form that resolves rather than being rewritten.
  *
  * Case is carried in the map rather than derived, because the uppercase form
  * is an environment variable prefix and the title-case form is a heading word,

package/src/record-root.ts

@@ -64,6 +64,7 @@ export const RECORD_ENTRIES: readonly string[] = [
   '.records.git',
   SCRATCH,
   'README.md',
+  'canvas',
   'diagrams',
   'evidence',
   'feedback',