@erclx/canon 5.32.0 → 5.34.0

package/src/records/validate.ts

@@ -22,7 +22,6 @@ export const RECORD_KINDS = [
   'plans',
   'groundwork',
   'intake',
-  'memory',
   'standards',
   'teach',
 ] as const
@@ -60,7 +59,6 @@ export type ValidateRefusal = (typeof VALIDATE_REFUSALS)[number]
 export const FINDING_KINDS = [
   'name-malformed',
   'title-missing',
-  'title-is-slug',
   'section-missing',
   'scope-unanchored',
   'entry-unreasoned',
@@ -72,7 +70,6 @@ export const FINDING_KINDS = [
   'state-missing',
   'closing-partial',
   'item-incomplete',
-  'category-mismatch',
   'operator-call-phrasing',
   'batch-unsplit',
   'source-unquoted',
@@ -81,22 +78,12 @@ export const FINDING_KINDS = [
 
 export type FindingKind = (typeof FINDING_KINDS)[number]
 
-/**
- * The transforms `migrate.ts` carries. Most finding kinds have none, since a
- * transform is only safe where the old shape is recoverable from the file
- * itself, so this stays optional on `Finding` rather than required.
- */
-export const FINDING_REMEDIES = ['category-from-name'] as const
-
-export type FindingRemedy = (typeof FINDING_REMEDIES)[number]
-
 export interface Finding {
   readonly kind: FindingKind
   /** The record the finding sits in, relative to the validated folder. */
   readonly record: string
   readonly subject: string
   readonly message: string
-  readonly remedy?: FindingRemedy
 }
 
 export interface ValidateReport {
@@ -214,9 +201,8 @@ function finding(
   record: string,
   subject: string,
   message: string,
-  remedy?: FindingRemedy,
 ): Finding {
-  return { kind, record, subject, message, remedy }
+  return { kind, record, subject, message }
 }
 
 async function listMarkdown(dir: string): Promise<string[]> {
@@ -934,169 +920,6 @@ async function checkWorkspace(dir: string, slug: string): Promise<Finding[]> {
   ]
 }
 
-const MEMORY_INDEX = 'index.md'
-const MEMORY_FIELDS = ['title', 'description', 'category'] as const
-
-/**
- * The filename prefix and the `category` field are one fact in two spellings,
- * so the map is the whole type list and the comparison against it is what
- * catches a prefix outside the set, a field disagreeing with the prefix, and a
- * casing drift that would open a second group in the catalog.
- */
-export const CATEGORY_BY_TYPE = {
-  feedback: 'Feedback',
-  project: 'Project',
-  user: 'User',
-  reference: 'Reference',
-} as const
-
-export type MemoryType = keyof typeof CATEGORY_BY_TYPE
-
-const MEMORY_TYPES = Object.keys(CATEGORY_BY_TYPE) as readonly MemoryType[]
-
-export const MEMORY_NAME = /^([a-z]+)-[a-z0-9]+(?:-[a-z0-9]+)*\.md$/
-
-/** The two markers a rule-bearing body carries, on top of the rule line itself. */
-const MEMORY_MARKERS = ['**Why:**', '**How to apply:**'] as const
-
-export function memoryType(value: string): MemoryType | undefined {
-  return MEMORY_TYPES.find((type) => type === value)
-}
-
-/**
- * The one missing-field shape `migrate.ts` can repair: `category` alone,
- * recoverable from the same filename prefix `checkMemory` already read it
- * from. `title` and `description` are prose nobody wrote down, so a finding
- * naming either carries no remedy.
- */
-function memoryRemedy(
-  missing: readonly string[],
-  named: MemoryType | undefined,
-): FindingRemedy | undefined {
-  return named && missing.length === 1 && missing[0] === 'category'
-    ? 'category-from-name'
-    : undefined
-}
-
-export function checkMemory(name: string, text: string): Finding[] {
-  const findings: Finding[] = []
-  const match = MEMORY_NAME.exec(name)
-  const named = match ? memoryType(match[1]) : undefined
-
-  if (!named) {
-    findings.push(
-      finding(
-        'name-malformed',
-        name,
-        name,
-        `is not named <type>-<slug>.md with a type of ${MEMORY_TYPES.join(', ')}.`,
-      ),
-    )
-  }
-
-  const frontmatter = parseFrontmatter(text)
-  const missing = MEMORY_FIELDS.filter(
-    (field) => !readField(frontmatter, field),
-  )
-
-  if (missing.length > 0) {
-    findings.push(
-      finding(
-        'frontmatter-incomplete',
-        name,
-        name,
-        `carries no ${missing.join(' and no ')}.`,
-        memoryRemedy(missing, named),
-      ),
-    )
-  }
-
-  // Its own kind rather than `title-missing`, which means an absent heading on a
-  // plan. One kind covering both leaves a caller filtering the JSON unable to
-  // tell a record with no title from one whose title is its own slug.
-  if (readField(frontmatter, 'title') === name.replace(/\.md$/, '')) {
-    findings.push(
-      finding(
-        'title-is-slug',
-        name,
-        name,
-        'is titled with its own filename, so the catalog renders a slug where the rule belongs.',
-      ),
-    )
-  }
-
-  const category = readField(frontmatter, 'category')
-
-  // Reported against the prefix alone. A name the prefix rule already failed
-  // has no type to compare against, and reporting it twice names one defect as
-  // two.
-  if (named && category && category !== CATEGORY_BY_TYPE[named]) {
-    findings.push(
-      finding(
-        'category-mismatch',
-        name,
-        category,
-        `is not ${CATEGORY_BY_TYPE[named]}, which the filename prefix declares.`,
-      ),
-    )
-  }
-
-  return [
-    ...findings,
-    ...checkMemoryBody(
-      name,
-      text.slice(frontmatter?.raw.length ?? 0),
-      named ?? category,
-    ),
-  ]
-}
-
-/**
- * A `user` or `reference` entry is a single sentence by design, so the markers
- * are checked only where a rule is being stated. The type is read off the
- * prefix, falling back to the category so a misnamed file is still checked
- * against the shape it claims.
- */
-function checkMemoryBody(
-  name: string,
-  text: string,
-  claimed: string | undefined,
-): Finding[] {
-  const type = claimed && memoryType(claimed.toLowerCase())
-  if (type !== 'feedback' && type !== 'project') return []
-
-  const body = linesOutsideFences(text).filter((line) => line.trim().length > 0)
-
-  const findings: Finding[] = []
-  const opening = body[0]
-
-  if (!opening || MEMORY_MARKERS.some((marker) => opening.startsWith(marker))) {
-    findings.push(
-      finding(
-        'section-missing',
-        name,
-        'the rule line',
-        'is absent, so the entry carries a rationale with no rule to apply.',
-      ),
-    )
-  }
-
-  for (const marker of MEMORY_MARKERS) {
-    if (!body.some((line) => line.startsWith(marker))) {
-      findings.push(
-        finding(
-          'section-missing',
-          name,
-          marker,
-          `is required on a ${type} entry and the body carries no such line.`,
-        ),
-      )
-    }
-  }
-
-  return findings
-}
-
 const STANDARD_INDEX = 'index.md'
 const STANDARD_FIELDS = ['title', 'description'] as const
 
@@ -1225,7 +1048,7 @@ export function checkStandard(name: string, text: string): Finding[] {
  */
 const FOLDER_CHECK: Readonly<
   Record<
-    Exclude<RecordKind, 'plans' | 'memory' | 'standards'>,
+    Exclude<RecordKind, 'plans' | 'standards'>,
     (dir: string, slug: string) => Promise<Finding[]>
   >
 > = {
@@ -1279,15 +1102,6 @@ export async function validateRecords(
 
   if (kind === 'plans') return validateFiles(dir, kind, checkPlan)
 
-  if (kind === 'memory') {
-    return validateFiles(
-      dir,
-      kind,
-      checkMemory,
-      (file) => file === MEMORY_INDEX,
-    )
-  }
-
   // The walk stays flat, matching install and the catalog.
   if (kind === 'standards') {
     return validateFiles(

package/src/sandbox/census.ts

@@ -71,7 +71,7 @@ export function listSkills(root: string): string[] {
  *
  * `<category>-<command>` is the rule `canon/context/sandbox/coverage/census.md` states, and it
  * alone pairs 29 of 54 skills. The bare `<command>` fallback is what reaches the
- * rest: `claude/target-setup.sh` drives the `target-setup` skill, not a `claude-target-setup` that
+ * rest: `claude/target-setup.ts` drives the `target-setup` skill, not a `claude-target-setup` that
  * does not exist. Stating one spelling and shipping two is what let the audit
  * report a paired skill as unpaired.
  *

package/src/sandbox/coverage.ts

@@ -44,13 +44,9 @@ function listScenarios(sandboxDir: string): ScenarioCoverage[] {
   const scenarios: ScenarioCoverage[] = []
 
   for (const category of listCategories(sandboxDir)) {
-    // A stem in both forms counts once, and provisioning refuses it by name.
-    const { scenarios: files, ambiguous } = listScenarioFiles(
-      join(sandboxDir, category),
-    )
-    const commands = [...files.map((f) => f.command), ...ambiguous].sort()
+    const { scenarios: files } = listScenarioFiles(join(sandboxDir, category))
 
-    for (const command of commands) {
+    for (const { command } of files) {
       scenarios.push({ category, command, armed: [] })
     }
   }

package/src/sandbox/equivalence.ts

@@ -22,7 +22,6 @@ import {
   listCategories,
   listScenarioFiles,
   loadScenario,
-  type ScenarioKind,
 } from '@/sandbox/scenario'
 import { createStubRemote, readStubManifest } from '@/sandbox/stub-remote'
 
@@ -153,28 +152,6 @@ export function armKey(arm: Arm): string {
   return arm.arm === undefined ? scenario : `${scenario}/${arm.arm}`
 }
 
-/**
- * Reads the quoted arguments of `select_or_route_scenario`, joining a call that
- * continues across backslash-newline pairs. The first argument is the prompt and
- * the rest are arm names. A call this cannot see returns no arms, which the
- * coverage cross-check in `enumerateArms` turns into an error rather than a
- * smaller list.
- */
-export function parseArmNames(source: string): string[] {
-  const start = source.search(/select_or_route_scenario\b/)
-  if (start === -1) return []
-
-  const call = source
-    .slice(start)
-    .replace(/\\\n/g, ' ')
-    .split('\n')[0]
-    ?.replace(/^select_or_route_scenario/, '')
-
-  return [...(call ?? '').matchAll(/"([^"]*)"/g)]
-    .map((match) => match[1] ?? '')
-    .slice(1)
-}
-
 function matchesTarget(
   category: string,
   command: string,
@@ -199,25 +176,14 @@ function matchesArm(arm: Arm, targets: readonly string[]): boolean {
 }
 
 /**
- * Reads a scenario's arm names and anchor flag: off a bash file's source, and
- * off a TypeScript module's own keys, which is what its stage routes on.
+ * Reads a scenario's arm names and anchor flag off its module's own keys, which
+ * is what its stage routes on.
  */
 function readArms(
   file: string,
-  kind: ScenarioKind,
 ):
   | { ok: true; anchor: boolean; names: string[] }
   | { ok: false; error: string } {
-  if (kind === 'sh') {
-    const source = readFileSync(file, 'utf8')
-
-    return {
-      ok: true,
-      anchor: /^use_anchor\s*\(\)/m.test(source),
-      names: parseArmNames(source),
-    }
-  }
-
   try {
     const definition = loadScenario(file)
 
@@ -250,17 +216,12 @@ export function enumerateArms(
   const coverage = collectCoverage(root)
 
   for (const category of listCategories(sandboxDir)) {
-    const { scenarios, ambiguous } = listScenarioFiles(
-      join(sandboxDir, category),
-    )
-    for (const command of ambiguous)
-      if (matchesTarget(category, command, targets))
-        errors.push(`${category}:${command} exists as both .sh and .ts`)
+    const { scenarios } = listScenarioFiles(join(sandboxDir, category))
 
-    for (const { command, file, kind } of scenarios) {
+    for (const { command, file } of scenarios) {
       if (!matchesTarget(category, command, targets)) continue
 
-      const declared = readArms(file, kind)
+      const declared = readArms(file)
       if (!declared.ok) {
         errors.push(`${category}:${command} did not load: ${declared.error}`)
         continue
@@ -740,13 +701,16 @@ function canonVersion(): string {
 }
 
 /**
- * Adds the baseline as a detached worktree of the base ref, so it carries full
- * history for the scenarios that read it, and returns a remover that is safe to
- * call twice. `node_modules` is linked from the working checkout, since the
- * baseline runs the same CLI and carries no install of its own.
+ * Adds a detached worktree of `ref` at `path`, so it carries full history for
+ * the scenarios that read it, and returns a remover that is safe to call twice.
+ * `node_modules` is linked from the working checkout, since the copy runs the
+ * same CLI and carries no install of its own.
  */
-function addBaseline(root: string, workDir: string, ref: string): () => void {
-  const path = join(workDir, 'base')
+export function addDetachedWorktree(
+  root: string,
+  path: string,
+  ref: string,
+): () => void {
   execFileSync('git', ['worktree', 'add', '--detach', path, ref], {
     cwd: root,
     stdio: ['ignore', 'ignore', 'pipe'],
@@ -800,7 +764,11 @@ export async function runEquivalence(
 
   let removeBaseline: () => void
   try {
-    removeBaseline = addBaseline(options.root, workDir, options.base)
+    removeBaseline = addDetachedWorktree(
+      options.root,
+      join(workDir, 'base'),
+      options.base,
+    )
   } catch (error) {
     // An unknown ref must not leave an empty scratch folder behind.
     if (options.out === undefined)

package/src/sandbox/expect.ts

@@ -354,7 +354,7 @@ function checkWriteScope(
   // none, and without this the declaration vanishes from the verdict entirely:
   // no result, no skipped entry, and no contribution to the unchecked count that
   // exists to surface exactly this. The `undefined` branch above cannot stand in,
-  // since `run.sh` always passes `--writes` and `readPathList` returns `[]` for an
+  // since `canon sandbox run` always passes `--writes` and `readPathList` returns `[]` for an
   // empty file. An arm whose output escaped the snapshot reads as a clean run,
   // which is the vacuous pass the harness exists to remove.
   if (writes.length === 0) {
@@ -377,7 +377,7 @@ function checkWriteScope(
 }
 
 /**
- * `run.sh` watches two toolkit roots for a write to shared session scratch
+ * `canon sandbox run` watches two toolkit roots for a write to shared session scratch
  * during a run, and reports every one it finds as an unattributed escape with
  * no arm able to fail on it. An arm whose skill legitimately reaches outside
  * the sandbox tree declares the destinations here, and the harness asserts
@@ -388,8 +388,8 @@ function checkWriteScope(
  * nothing skips rather than passing on a fabricated zero. An escape-scope
  * declaration exists to bound a side effect nothing requires, so zero escapes
  * is the outcome a correct run produces and reports as a pass outright,
- * provided a watched root held something to watch. `run.sh`'s `snapshot_root`
- * returns an empty manifest both when a watch ran clean and when none of the
+ * provided a watched root held something to watch. `snapshotRoot` in
+ * `src/sandbox/headless/watch.ts` returns an empty manifest both when a watch ran clean and when none of the
  * four watched directories existed under a root, and the two produce the same
  * empty `escapes` list. `watched` is what tells them apart: a run that had
  * nothing to watch reports unmeasured rather than passing on a diff it never

package/src/sandbox/provision.ts

@@ -8,7 +8,6 @@ import {
   writeFileSync,
 } from 'node:fs'
 import { basename, dirname, join, relative } from 'node:path'
-import { probeScenario, stageScenario } from '@/sandbox/hooks'
 import {
   FIXTURE_SUFFIX,
   FIXTURES_DIR,
@@ -34,9 +33,8 @@ import {
 
 /**
  * Provisions one scenario into the sandbox tree, and resets or cleans that tree.
- * A bash scenario's hooks run through `sandbox-hook.sh` and a TypeScript one's
- * arm runs in process through `scenario.ts`, and everything between them runs
- * here, in the order the retired bash dispatcher held.
+ * A scenario's arm runs in process through `scenario.ts`, and everything
+ * around it runs here, in the order the retired bash dispatcher held.
  *
  * Narration is part of the contract. `canon sandbox equivalence` compares the
  * log line for line against the bash harness, so every message, its frame
@@ -403,36 +401,22 @@ interface Scenario {
 
 /**
  * Reads what a scenario declares ahead of provisioning: its config exports and
- * whether it stages from the anchor. A bash scenario answers through the probe,
- * and a TypeScript one from its module, which is also what its stage runs.
+ * whether it stages from the anchor, from its module, which is also what its
+ * stage runs.
  */
 function declareScenario(
   root: string,
   scenario: Scenario,
   env: NodeJS.ProcessEnv,
-):
-  | { kind: 'sh'; file: string; isAnchor: boolean }
-  | { kind: 'ts'; definition: ScenarioDefinition; isAnchor: boolean } {
+): { definition: ScenarioDefinition; isAnchor: boolean } {
   const name = `${scenario.category}/${scenario.command}`
   const resolved = resolveScenarioFile(
     join(root, 'sandbox'),
     scenario.category,
     scenario.command,
   )
-  if (!resolved.ok && resolved.reason === 'ambiguous')
-    fail(
-      `Sandbox script ${name} exists as both .sh and .ts. Delete the one the port replaced.`,
-    )
   if (!resolved.ok) fail(`Sandbox script not found: ${name}`)
 
-  if (resolved.kind === 'sh') {
-    const probe = probeScenario(resolved.file, env)
-    if (!probe.ok) throw new Halt(probe.status)
-    Object.assign(env, probe.exports)
-
-    return { kind: 'sh', file: resolved.file, isAnchor: probe.isAnchor }
-  }
-
   let definition: ScenarioDefinition
   try {
     definition = loadScenario(resolved.file)
@@ -443,7 +427,7 @@ function declareScenario(
   }
   Object.assign(env, scenarioExports(definition, root, env))
 
-  return { kind: 'ts', definition, isAnchor: definition.anchor === true }
+  return { definition, isAnchor: definition.anchor === true }
 }
 
 async function provisionScenario(
@@ -481,21 +465,14 @@ async function provisionScenario(
   // A scenario that execs a verb as its last step hands the run to that verb,
   // whose own frame is the last one written, so nothing follows it here. An
   // in-process arm writes its exports straight into `env`.
-  const staged =
-    declared.kind === 'sh'
-      ? stageScenario(declared.file, env)
-      : {
-          ...(await stageScenarioInProcess(declared.definition, {
-            root,
-            dir: sandbox,
-            env,
-            arm: scenario.arm,
-          })),
-          exports: {},
-        }
+  const staged = await stageScenarioInProcess(declared.definition, {
+    root,
+    dir: sandbox,
+    env,
+    arm: scenario.arm,
+  })
   if (staged.ending === 'replaced') throw new Halt(staged.status, false)
   if (staged.ending === 'exited') throw new Halt(staged.status)
-  Object.assign(env, staged.exports)
 
   const isSkipAutoCommit = (env.SANDBOX_SKIP_AUTO_COMMIT ?? '') !== ''
   const isSkipInject = (env.SANDBOX_SKIP_SKILL_INJECT ?? '') !== ''
@@ -602,7 +579,7 @@ function parseTarget(target: string): { category: string; command: string } {
 }
 
 export interface SandboxRequest {
-  /** False where a caller already opened the frame, as `run.sh` and the picker do. */
+  /** False where a caller already opened the frame, as `canon sandbox run` and the picker do. */
   readonly isHeader: boolean
   /** `<category>:<command>`, `reset`, or `clean`. */
   readonly target: string