@erclx/canon 4.127.0 → 5.2.0

package/src/commands/upgrade.ts

@@ -1,6 +1,6 @@
 import type { Command } from 'commander'
 import { execa } from 'execa'
-import { PROJECT_ROOT } from '@/project-root'
+import { findCheckoutMismatch, PROJECT_ROOT } from '@/project-root'
 import {
   frameError,
   intro,
@@ -10,6 +10,7 @@ import {
   outro,
   select,
 } from '@/ui'
+import { compareVersions, parseVersion } from '@/version/compare'
 import { readInstalled, UNKNOWN_LABEL } from '@/version/installed'
 import { detectManager, installCommand, type Manager } from '@/version/manager'
 import {
@@ -30,7 +31,9 @@ interface UpgradeRecord {
   readonly before: string
   readonly after?: string
   readonly latest?: string
-  readonly state: 'upgraded' | 'current' | 'cancelled' | 'refused'
+  /** The version of the checkout at cwd, present only on `pending`. */
+  readonly checkout?: string
+  readonly state: 'upgraded' | 'current' | 'pending' | 'cancelled' | 'refused'
   readonly reason?: string
   /**
    * One rendered line for a caller that reports the outcome without parsing
@@ -117,7 +120,24 @@ async function runUpgrade(opts: UpgradeOptions): Promise<number> {
   logStep('Published')
   logInfo(describeSkew(skew))
 
+  const checkout = readCheckoutVersion()
+  const latest = latestOf(skew)
+
   if (skew.state === 'current') {
+    const note = pendingNote(latest, checkout)
+    if (note !== undefined && checkout !== undefined) {
+      logWarn(note)
+      outro()
+      emit(opts, {
+        ...base(before, manager, command, skew),
+        after: before,
+        checkout,
+        state: 'pending',
+        message: `CLI stays at ${before}. ${note}`,
+      })
+      return 0
+    }
+
     outro()
     emit(opts, {
       ...base(before, manager, command, skew),
@@ -128,7 +148,7 @@ async function runUpgrade(opts: UpgradeOptions): Promise<number> {
     return 0
   }
 
-  return await applyUpgrade(opts, before, skew, manager, command)
+  return await applyUpgrade(opts, before, skew, manager, command, checkout)
 }
 
 /**
@@ -147,6 +167,7 @@ async function applyUpgrade(
   skew: SkewReport,
   manager: Manager,
   command: readonly string[],
+  checkout: string | undefined,
 ): Promise<number> {
   const proceed = await select({
     message: `Run \`${command.join(' ')}\`?`,
@@ -199,15 +220,50 @@ async function applyUpgrade(
     ...base(before, manager, command, skew),
     after,
     state: 'upgraded',
-    message: upgradedMessage(before, after),
+    message: [upgradedMessage(before, after), pendingNote(after, checkout)]
+      .filter((part) => part !== undefined)
+      .join(' '),
   })
   return 0
 }
 
+/**
+ * The version of the checkout the caller stands in, read off cwd rather than
+ * off `PROJECT_ROOT`, which is the installed package a bare `canon` resolves
+ * to. A target project sits in no canon checkout, so this reads nothing there
+ * and the verb behaves as it did.
+ */
+function readCheckoutVersion(): string | undefined {
+  const dir = findCheckoutMismatch(process.cwd())
+  return dir === undefined ? undefined : readInstalled(dir).version
+}
+
+/**
+ * The clause a caller appends when the checkout carries a release npm does not
+ * serve yet. A pull lands the release commit before the publish job finishes,
+ * so for a few minutes the checkout leads the registry, and a release that
+ * never publishes keeps it leading. The wording names the served version
+ * rather than promising a publish for that reason. `undefined` covers every
+ * case with nothing to say, including a version that does not parse.
+ */
+export function pendingNote(
+  served: string | undefined,
+  checkout: string | undefined,
+): string | undefined {
+  if (served === undefined || checkout === undefined) return undefined
+
+  const local = parseVersion(checkout)
+  const published = parseVersion(served)
+  if (local === undefined || published === undefined) return undefined
+  if (compareVersions(local, published) <= 0) return undefined
+
+  return `The checkout is at ${checkout} and npm serves ${served}.`
+}
+
 export function upgradedMessage(before: string, after: string): string {
   return after === before
-    ? `Reinstalled ${after}, unchanged.`
-    : `Upgraded ${before} to ${after}.`
+    ? `CLI reinstalled ${after}, unchanged.`
+    : `CLI upgraded ${before} to ${after}.`
 }
 
 function base(

package/src/counts/catalogs.ts

@@ -3,7 +3,6 @@ import { join } from 'node:path'
 import { AUDITS } from '@/audits/catalog'
 import { listSkills } from '@/claude/skills-list'
 import { buildGovCatalog } from '@/gov/list'
-import { buildSnippetsCatalog } from '@/snippets/list'
 import { listStandards } from '@/standards/read'
 
 export interface Catalog {
@@ -39,16 +38,6 @@ function countCommands(root: string): number | undefined {
   return [...readFileSync(cli, 'utf8').matchAll(REGISTER_IMPORT)].length
 }
 
-/**
- * The distinct entries across every category, matching what `regen-hero.sh`
- * counts. A snippet reachable from two categories is one snippet, not two.
- */
-function countSnippets(root: string): number {
-  const catalog = buildSnippetsCatalog(root)
-  return new Set(catalog.categories.flatMap((category) => category.entries))
-    .size
-}
-
 /**
  * The closed set of catalogs this sweep counts a document against.
  *
@@ -75,11 +64,6 @@ export const CATALOGS: readonly Catalog[] = [
     nouns: ['standard', 'standards'],
     count: (root) => listStandards(root).length,
   },
-  {
-    id: 'snippets',
-    nouns: ['snippet', 'snippets'],
-    count: countSnippets,
-  },
   {
     id: 'commands',
     nouns: ['command', 'commands'],

package/src/counts/scan.ts

@@ -153,7 +153,7 @@ const ARTICLES = ['the', 'a', 'an']
  * either number.
  *
  * The optional word between the number and the noun is what reaches a form
- * like `installs 11 shipped snippets` without also reaching past an
+ * like `installs 11 shipped rules` without also reaching past an
  * intervening clause, since a wider gap would start pairing a number in one
  * clause with a noun in the next. Requiring the noun's own plural form to
  * double as its match narrows the corpus this reads without hand-listing

package/src/docs/read.ts

@@ -56,22 +56,22 @@ export function resolveTopic(
 }
 
 /**
- * Names every sub-area file called `<topic>.md`, across both roots. A name
- * carried by more than one folder resolves to none of them, since answering a
- * bare `overview` with whichever folder sorts first is a confident wrong answer
- * where the miss is a listing of what the caller could have typed.
+ * Names every sub-area file called `<topic>.md` in the first root whose folders
+ * carry one, so the root precedence above holds one folder down as well. A name
+ * carried by more than one folder of that root resolves to none of them, since
+ * answering a bare `overview` with whichever folder sorts first is a confident
+ * wrong answer where the miss is a listing of what the caller could have typed.
  */
 function findLeaves(root: string, topic: string): string[] {
-  const matches: string[] = []
-
   for (const dir of ROOTS) {
-    for (const folder of catalogedFolders(join(root, dir))) {
-      const rel = join(dir, folder, `${topic}.md`)
-      if (existsSync(join(root, rel))) matches.push(rel)
-    }
+    const matches = catalogedFolders(join(root, dir))
+      .map((folder) => join(dir, folder, `${topic}.md`))
+      .filter((rel) => existsSync(join(root, rel)))
+
+    if (matches.length > 0) return matches
   }
 
-  return matches
+  return []
 }
 
 /**
@@ -100,20 +100,20 @@ export function listTopics(root: string): string[] {
   const leaves = ROOTS.map((dir) => collectLeaves(root, dir))
 
   const taken = new Set(named.flat())
-  const counts = new Map<string, number>()
-  for (const name of leaves.flat()) {
-    counts.set(name, (counts.get(name) ?? 0) + 1)
-  }
-
-  const reachable = (name: string): boolean =>
-    !taken.has(name) && counts.get(name) === 1
-
-  return ROOTS.flatMap((_, position) =>
-    [
-      ...(named[position] as string[]),
-      ...(leaves[position] as string[]).filter(reachable),
-    ].sort(),
-  )
+  const claimed = new Set<string>()
+
+  return ROOTS.flatMap((_, position) => {
+    const here = leaves[position] as string[]
+    const reachable = [...new Set(here)].filter(
+      (name) =>
+        !taken.has(name) &&
+        !claimed.has(name) &&
+        here.indexOf(name) === here.lastIndexOf(name),
+    )
+    for (const name of here) claimed.add(name)
+
+    return [...(named[position] as string[]), ...reachable].sort()
+  })
 }
 
 /** The sibling files and split folders of one root, which shadow every leaf. */

package/src/gate/measures.ts

@@ -361,6 +361,58 @@ export const documentCeiling: Measure = async (ctx) => {
   }
 }
 
+/**
+ * Whether a path's stem, its basename up to the first `.`, repeats its
+ * immediate parent folder, either whole or as a `<folder>-` prefix.
+ *
+ * Exact rather than singular-aware, so `standards/standard.md` passes. A false
+ * positive on a gate stage teaches a contributor to route around it, and a
+ * widened match is cheap to add once a real echo slips through.
+ */
+export function isFolderEchoedName(path: string): boolean {
+  const segments = path.split('/')
+  if (segments.length < 2) return false
+  const folder = segments[segments.length - 2] ?? ''
+  const stem = (segments[segments.length - 1] ?? '').split('.')[0] ?? ''
+  if (folder === '' || stem === '') return false
+  return stem === folder || stem.startsWith(`${folder}-`)
+}
+
+/**
+ * Every tracked file whose name repeats the folder it sits in, which says the
+ * folder's name twice in every path that cites it.
+ *
+ * Reads paths only, so it runs over the whole tree rather than the markdown
+ * corpus. It stays out of `canon markdown audit`, which runs inside every
+ * target, where a folder-named file may be a convention the target chose.
+ */
+export const folderEchoedNames: Measure = async (ctx) => {
+  const files = await listRepositoryFiles(ctx.root)
+  if (files === undefined) {
+    return {
+      emissions: [],
+      unmeasured:
+        'The tracked file list could not be read, so no filename was checked.',
+    }
+  }
+
+  const echoed = files.filter(isFolderEchoedName)
+  if (echoed.length === 0) {
+    return {
+      emissions: [
+        info(
+          `No filename repeats its folder across ${plural(files.length, 'tracked file')}`,
+        ),
+      ],
+    }
+  }
+
+  return {
+    emissions: echoed.map((path) => warn(`${path} repeats its folder's name`)),
+    failure: `${echoed.length === 1 ? 'One tracked file repeats its' : `${echoed.length} tracked files repeat their`} folder's name: ${echoed.join(', ')}. Rename each for what it covers inside the folder, dropping the prefix the folder already states.`,
+  }
+}
+
 /**
  * A second run of the records move should rewrite nothing, and the count is
  * only knowable once the folders themselves have landed.

package/src/gate/stages.ts

@@ -4,6 +4,7 @@ import {
   captureStamps,
   clientCommandCitations,
   documentCeiling,
+  folderEchoedNames,
   markdownBans,
   type Measure,
   pluginManifests,
@@ -366,6 +367,14 @@ export const STAGES: readonly Stage[] = [
     label: 'Document ceiling',
     checks: [{ kind: 'measure', measure: documentCeiling }],
   },
+  {
+    // Unscoped, since any branch can add a file anywhere and one git ls-files
+    // costs nothing. Reads paths rather than markdown, so it sits here rather
+    // than in the markdown audit that also runs inside every target.
+    id: 'folder-echoed-names',
+    label: 'Folder-echoed filenames',
+    checks: [{ kind: 'measure', measure: folderEchoedNames }],
+  },
   {
     // A rule citing a file that moved fails silently. The consumed-copy drift
     // stage passes an authored rule and its copy that are wrong together, and

package/src/gov/restated.ts

@@ -1,5 +1,6 @@
 import { existsSync, readFileSync } from 'node:fs'
 import { join } from 'node:path'
+import { RULE_DIRS } from '@/gov/citations'
 
 /** The always-loaded file whose bullets are the subjects this sweep matches. */
 export const INSTRUCTIONS_REL = 'CLAUDE.md'
@@ -11,15 +12,26 @@ export const SEED_REL = join('tooling', 'claude', 'seeds', 'CLAUDE.md')
 export const SHIPPED_SKILLS_REL = join('claude', 'skills')
 
 /**
- * Path-scoped rules, read from the authoring root rather than the consumed
- * copy under `.claude/rules/`. A stack takes a whole rule folder, so a bullet
- * landing anywhere under here ships to every target the stack reaches, the
- * same way a bullet in the always-loaded file or the seed does. That is what
- * makes a rule an instruction surface rather than a place a rule is merely
- * quoted, and it is why a bullet moved here from the seed still belongs to
- * the corpus this sweep reads rather than leaving it.
+ * The project's own skill bodies. Here that is the toolkit's internal skills,
+ * and in a target it is that project's own, which is equally a place a rule
+ * gets restated in prose.
+ */
+export const PROJECT_SKILLS_REL = join('.claude', 'skills')
+
+/** Every root a candidate body is read from, each reported under its own path. */
+const SKILL_ROOTS: readonly string[] = [SHIPPED_SKILLS_REL, PROJECT_SKILLS_REL]
+
+/*
+ * Path-scoped rules are read from every root in `RULE_DIRS`, the authoring
+ * roots rather than the consumed copy under `.claude/rules/`. A stack takes a
+ * whole rule folder, so a bullet landing anywhere under `governance/rules/`
+ * ships to every target the stack reaches, the same way a bullet in the
+ * always-loaded file or the seed does, and `internal/rules/` loads the same
+ * way for every session in this repository. That is what makes a rule an
+ * instruction surface rather than a place a rule is merely quoted, and it is
+ * why a bullet moved into either root from the seed still belongs to the
+ * corpus this sweep reads rather than leaving it.
  */
-export const RULES_REL = join('governance', 'rules')
 
 /**
  * Path pairs whose duplication is deliberate and already recorded.
@@ -174,6 +186,22 @@ const STOPWORDS = new Set([
  */
 const PROHIBITIONS = ['never', 'do not', "don't", 'avoid', 'refuse']
 
+/**
+ * A `no` opening a clause or a comma-set phrase directly on a code span, as in
+ * `pinned to major tags, no `@latest``.
+ *
+ * `no` is admitted here and only here, since sitting on a backticked
+ * identifier it names the thing ruled out rather than qualifying a verb. The
+ * phrase boundary is what keeps description out: `returns no `jq` output` puts
+ * the marker after a verb and reports what happens.
+ *
+ * `not` and `never` stay out. Admitting them turned two agreeing pairs into
+ * contradictions, `, not `pwd`` and `, never `@latest``, because the subject
+ * each matched spelled its own negation on plain words or in a clause the
+ * anchors tied against, so the reading flipped on one side alone.
+ */
+const NEGATED_SPAN = /(?:^|[,;:(])\s*no\s+`/
+
 export type RestatedRefusal = 'no-instructions' | 'no-surfaces'
 
 export type Restatement = 'mirror' | 'repetition' | 'contradiction'
@@ -315,7 +343,10 @@ function prohibits(text: string): boolean {
     .replace(/^[^a-z]*/, '')
     .replace(/^(and|but|so|then|also|however)[\s,]+/, '')
 
-  return PROHIBITIONS.some((marker) => opening.startsWith(marker))
+  return (
+    PROHIBITIONS.some((marker) => opening.startsWith(marker)) ||
+    NEGATED_SPAN.test(opening)
+  )
 }
 
 /**
@@ -465,7 +496,10 @@ function readBullets(root: string, relative: string): Statement[] {
  * is reused per file rather than rebuilt for prose, and frontmatter is read
  * past for the same reason it is: no line there starts with `- `.
  */
-function readRuleFiles(root: string, rulesRoot: string): Statement[] {
+function readRuleFiles(root: string, rulesRel: string): Statement[] {
+  const rulesRoot = join(root, rulesRel)
+  if (!existsSync(rulesRoot)) return []
+
   const files = [
     ...new Bun.Glob('**/*.md').scanSync({ cwd: rulesRoot, onlyFiles: true }),
   ].sort()
@@ -473,13 +507,13 @@ function readRuleFiles(root: string, rulesRoot: string): Statement[] {
   return files.flatMap((file) =>
     readBullets(
       root,
-      `${RULES_REL.replaceAll('\\', '/')}/${file.replaceAll('\\', '/')}`,
+      `${rulesRel.replaceAll('\\', '/')}/${file.replaceAll('\\', '/')}`,
     ),
   )
 }
 
 /**
- * Every prose line and bullet in a shipped body.
+ * Every prose line and bullet in a skill body under one skills root.
  *
  * Wider than the bullet rule above because the motivating case was stated in a
  * body as a paragraph, so a bullet-only read would miss the one instance this
@@ -487,7 +521,10 @@ function readRuleFiles(root: string, rulesRoot: string): Statement[] {
  * heading names a section rather than stating a rule, and a fenced block is an
  * example whose words are the surrounding prose's by construction.
  */
-function readBodyLines(root: string, skillsRoot: string): Candidate[] {
+function readBodyLines(root: string, skillsRel: string): Candidate[] {
+  const skillsRoot = join(root, skillsRel)
+  if (!existsSync(skillsRoot)) return []
+
   const candidates: Candidate[] = []
 
   const files = [
@@ -500,7 +537,7 @@ function readBodyLines(root: string, skillsRoot: string): Candidate[] {
   for (const file of files) {
     const posix = file.replaceAll('\\', '/')
     const skill = posix.split('/')[0]
-    const relative = `${SHIPPED_SKILLS_REL.replaceAll('\\', '/')}/${posix}`
+    const relative = `${skillsRel.replaceAll('\\', '/')}/${posix}`
 
     const lines = readFileSync(join(root, relative), 'utf8').split('\n')
     let fenced = false
@@ -639,8 +676,9 @@ function classify(
  * defect the sweep exists for, and a recall-first reading can be narrowed from
  * real output where the reverse cannot.
  *
- * The always-loaded file and every rule each open the search as a subject, and
- * the seed, the shipped bodies, and every rule again close it as a candidate.
+ * The always-loaded file and every rule under either rule root each open the
+ * search as a subject, and the seed, the skill bodies under both skill roots,
+ * and every rule again close it as a candidate.
  * A rule sits on both sides because a stack ships a whole rule folder, so a
  * bullet duplicated between two rules reaches a target exactly as a bullet
  * duplicated between the always-loaded file and a rule does, and neither shape
@@ -660,14 +698,14 @@ export function readRestated(root: string): RestatedReport {
     kind: 'seed' as const,
   }))
 
-  const skillsRoot = join(root, SHIPPED_SKILLS_REL)
-  const bodies = existsSync(skillsRoot) ? readBodyLines(root, skillsRoot) : []
+  const bodies = SKILL_ROOTS.flatMap((skillsRel) =>
+    readBodyLines(root, skillsRel),
+  )
   const bodyFiles = new Set(bodies.map((candidate) => candidate.file)).size
 
-  const rulesRoot = join(root, RULES_REL)
-  const ruleStatements = existsSync(rulesRoot)
-    ? readRuleFiles(root, rulesRoot)
-    : []
+  const ruleStatements = RULE_DIRS.flatMap((rulesRel) =>
+    readRuleFiles(root, rulesRel),
+  )
   const rules: Candidate[] = ruleStatements.map((statement) => ({
     ...statement,
     kind: 'rule' as const,

package/src/help.ts

@@ -26,7 +26,6 @@ export const COMMAND_GROUPS: { title: string; rows: CommandRow[] }[] = [
     rows: [
       ['gov [cmd]', 'Governance rules (install, sync, list)'],
       ['standards [cmd]', 'Standards (install, sync, list, <name>)'],
-      ['snippets [cmd]', 'Prompt snippets (create, list)'],
       ['tooling [cmd]', 'Tooling stacks (sync, ref, create)'],
       ['claude [cmd]', 'Claude workflow (init, sync, setup)'],
       ['wiki [cmd]', 'Wiki pages (init)'],
@@ -93,7 +92,6 @@ const EXAMPLES = [
   'canon gov sync ../my-app',
   'canon gov restated --json',
   'canon standards markdown',
-  'canon snippets list',
   'canon init ../my-app',
   'canon tooling sync base',
   'canon tooling create',

package/src/init/steps.ts

@@ -5,7 +5,7 @@ import type { DomainStep } from '@/init/run'
 export type RunFactory = (args: readonly string[]) => () => Promise<boolean>
 
 /**
- * States the same fact as `docs/target/target-migrations.md`'s backup section in its
+ * States the same fact as `docs/target/migrations.md`'s backup section in its
  * own words. Keep the two in step by hand; nothing compares them.
  */
 const RECORDS_SETUP_NOTICE =

package/src/migrate/skill-names.ts

@@ -93,11 +93,10 @@ export const SKILL_NAME_MAP: Readonly<Record<string, string>> = {
  * one destination, so the ordering is asserted directly.
  *
  * It matches whole tokens. A skill name is a complete name rather than a word
- * stem, and the corpus holds one word that opens with a name and means
- * something else: `wiki/claude/claude-worktrees.md` documents the harness
- * feature, not the skill, and every sibling in that folder is named
- * `claude-<topic>.md` for a Claude Code concept. Sixteen occurrences of it
- * would have moved to a name the folder's own convention contradicts.
+ * stem, and a word can open with a name and mean something else: a filename
+ * such as `claude-worktrees.md` names the harness feature, not the skill, and
+ * a stem matching by prefix would move it to a name that no longer describes
+ * what the file documents.
  *
  * No article fixup travels with it. `auto-ship` is the one destination opening
  * on a vowel sound, and the corpus spells an article before it once, which is

package/src/secrets/shipped.ts

@@ -13,8 +13,8 @@ import { join } from 'node:path'
  *
  * What it does not cover is the plugin, which a marketplace install reads live
  * from `claude/` rather than from a tarball. That folder is a `files` entry
- * too, and its `standards` and `snippets` symlinks resolve into trees the field
- * lists in their own right, so both routes land inside the same corpus.
+ * too, and its `standards` symlink resolves into a tree the field lists in its
+ * own right, so both routes land inside the same corpus.
  */
 export type ShipEntries =
   /** The field declares a corpus, which is what this check reads. */

package/src/serve/static.ts

@@ -186,8 +186,7 @@ export function resolveWithin(
  * Re-tests containment after following symlinks. `resolveWithin` is lexical
  * and `resolve` does not follow a link, so a link inside the root clears that
  * test while the file it points at sits outside. This repository is a live
- * instance, since `claude/standards` and `claude/snippets` are links out of
- * `claude/`.
+ * instance, since `claude/standards` is a link out of `claude/`.
  *
  * Only a path that exists is checked, because a link can be followed only once
  * there is something on the other end, and a path that resolves to nothing is

package/src/shipped/references.ts

@@ -10,8 +10,8 @@ import { isMarked } from '@/exempt-marker'
  * on purpose rather than by omission. What decides membership here is whether
  * anything serves the file to a reader who does not hold this repository: a
  * skill body loads into a session, a docs page is read through `canon docs`, a
- * standard through `canon standards`, a rule through a glob match, a snippet
- * through an `@` expansion, and a seed through an install. A `src/` doc comment
+ * standard through `canon standards`, a rule through a glob match, and a seed
+ * through an install. A `src/` doc comment
  * is read by someone working on the toolkit, in this checkout, where every
  * number resolves.
  *
@@ -20,17 +20,16 @@ import { isMarked } from '@/exempt-marker'
  * `#191512`, which no width or boundary rule separates from a pull request
  * number, so telling them apart would need the line's syntactic position.
  *
- * `claude/standards` and `claude/snippets` are symlinks into two of the roots
- * below, and a walk that followed them would read those two corpora twice and
- * report every finding in them under two paths. Nothing is lost by not
- * following, since both are corpora here in their own right.
+ * `claude/standards` is a symlink into one of the roots below, and a walk that
+ * followed it would read that corpus twice and report every finding in it
+ * under two paths. Nothing is lost by not following, since it is a corpus here
+ * in its own right.
  */
 export const SHIPPED_CORPORA = [
   'claude',
   'docs',
   'governance',
   'scripts',
-  'snippets',
   'standards',
   'tooling',
 ] as const
@@ -142,7 +141,7 @@ const SAME_REPOSITORY =
  * `canon/context/` carries no equivalent pattern. The same resolution test
  * cannot separate a path every scaffolded project holds, such as
  * `canon/context/index.md`, from this repository's own domain entry, such
- * as `canon/context/indexes.md`, since both resolve here and only the
+ * as `canon/context/context-model/indexes.md`, since both resolve here and only the
  * second is a defect. That is a semantic read no pattern makes, so it stays
  * with the rule and the review checklist rather than joining this reader.
  */

package/src/sync/engine.ts

@@ -129,11 +129,11 @@ export type NonInteractivePolicy =
 /**
  * The two holes every domain sync leaves open: where a destination file's
  * source lives, and what counts as a change beyond a plain content diff.
- * Everything else in a sync is identical across gov, snippets, and standards,
+ * Everything else in a sync is identical across domains,
  * so it lives in the engine.
  *
  * The optional members exist because one adapter needed each of them. Leaving
- * all three unset reproduces the behavior gov and snippets already had.
+ * all three unset reproduces the behavior gov already had.
  */
 export interface SyncAdapter {
   readonly banner: string

package/standards/context.md

@@ -111,6 +111,8 @@ Only the `development` entry carries this section. It is not a general-purpose h
 - Retire a decision or gotcha once its subject is gone, rewriting the bullet to state the current design rather than leaving the narration of what it replaced beside it. A rejected alternative is not a retired one, so what was tried and why it lost stays whatever its age. The rule above protects content whose subject is live, and this one releases content whose subject is not.
 - Rewrite a decision a later one replaced rather than appending the replacement beside it. The subject is still live, so the rule above does not reach it, and two bullets on one subject leave a reader to work out which of them is current. State the design that stands and keep the superseded reasoning only where it is the alternative that lost.
 - Split into a folder (`canon/context/<domain>/<sub-area>.md`) when a domain has three or more sub-areas that do not fit cleanly in one file. That split is the natural ceiling.
+- Group whole single-file entries of two or more small domains into one folder when they share a kind, such as small feature domains that each own a verb. Each entry still covers one domain, and the folder's generated `index.md` carries a `subtitle` naming the kind. It names an entry to start with only when that entry frames the others. A grouping folder is not a split, so no entry inside it is a sub-area of another.
+- Name an entry inside a split or grouping folder per the `codebase-layout` skill, which never repeats the folder's name as the entry's stem or prefix.
 - Keep a split domain's `index.md` generated. The catalog body is rewritten on every regen, so the domain's own overview and layout belong in a sibling file rather than in it, and the `subtitle` is what names the file to start with.
 - Author a catalog that grows a row per shipped thing as a bullet list, never a markdown table. A table pads its columns to a shared width, so one row outgrowing its column reflows every row and turns a one-line edit into a whole-file rewrite that conflicts with any sibling branch. This is what forced the split above.
 

package/standards/docs.md

@@ -72,6 +72,7 @@ A page failing these is non-conforming even when it satisfies every shape rule b
 - Move every page carrying that value. A shelf split across two depths is harder to scan than either arrangement taken whole.
 - Give the subfolder a catalog page of its own, so the parent lists one entry where it listed several. The parent lists a subfolder as a folder rather than as a member of the shelf it replaced, so nothing on that page restores the grouping.
 - Retarget every link into a moved page in the same change. A link resolving nowhere is what the move costs, and nothing else reports it.
+- Name a moved page per the `codebase-layout` skill, which drops the prefix the subfolder now states.
 
 ## Template
 

package/standards/index.md

@@ -34,7 +34,6 @@ Reference docs for consistent authoring across the toolkit and target projects.
 - [Skill requirement reference](skill-requirement.md): Shape and content rules for the REQUIREMENT.md beside a skill
 - [Claude skill reference](skill.md): Claude skill structure and authoring rules
 - [Slug reference](slug.md): Transform from a git branch name to a slug, and the three responses to an empty result
-- [Snippet reference](snippets.md): Snippet reference and authoring conventions
 - [Standard reference](standard.md): Shape and content rules for authoring a standard
 - [Tasks reference](tasks.md): Folder layout, filename convention, file format, origin lines, and archiving for task files under .canon/tasks/
 - [Teach reference](teach.md): Workspace layout, ordinal naming, frontmatter, and the mission and learning-record formats for a learning workspace