@erclx/canon 4.127.0 → 5.1.0

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

package/standards/skill.md

@@ -17,7 +17,6 @@ Does not govern:
 
 - What a `REQUIREMENT.md` must answer, its sections, and its template: `skill-requirement.md`
 - Path-scoped coding rules, which load on a file match rather than on a request match: `rule.md`
-- Single-purpose chat prompts carrying no frontmatter, references, or scripts: `snippets.md`
 - Voice, rhythm, and sentence construction in a skill body: the `write-human` skill
 - Punctuation, formatting, and word choice in a skill body: `markdown.md`
 - The transform from a branch name to a slug a skill carries in a filename: `slug.md`
@@ -128,7 +127,7 @@ allowed-tools: <tools required>
 
 - Avoid flags that dispatch between alternate flows. The model misreads them and runs the vanilla path. Dry-run-style toggles are fine. For alternate flows, prefer a separate skill or manual invocation of two skills in sequence.
 - When a skill should fire from multiple callers, rely on description matching with strong trigger phrases. Do not hardcode `Skill` calls in sibling skills that could trigger it naturally.
-- Before collapsing a manual multi-step flow into a skill, ask what the manual pauses do. Where a pause carries external timing, error-surfacing, or judgment weight, prefer a snippet or explicit per-step confirmation.
+- Before collapsing a manual multi-step flow into a skill, ask what the manual pauses do. Where a pause carries external timing, error-surfacing, or judgment weight, prefer explicit per-step confirmation.
 
 ### Output and tuning
 

package/standards/wiki.md

@@ -37,7 +37,8 @@ A page failing either is non-conforming even when it satisfies every shape rule
 
 ## Naming
 
-- Name a page with a `claude-` prefix before the kebab subject.
+- Name a page by its kebab subject alone. The vendor folder it sits in already names the vendor, so a prefix repeats the folder.
+- The `codebase-layout` skill carries the same rule for every folder in a project, beyond the wiki.
 
 ## Sourcing
 

package/tooling/base/reference.md

@@ -4,7 +4,7 @@
 
 The base layer covers every project the toolkit scaffolds, whatever language sits on top. It ships formatting, spelling, shell linting, conventional commits, git hooks, CI, and one maintenance script. Every other stack extends it, so a decision made here is one every stack inherits.
 
-A repository with several language roots layers this stack once at the root and skips it per subtree, since git honors only one `core.hooksPath` and a re-dropped husky silently breaks. `canon docs target-scenarios` carries the recipe.
+A repository with several language roots layers this stack once at the root and skips it per subtree, since git honors only one `core.hooksPath` and a re-dropped husky silently breaks. `canon docs scenarios` carries the recipe.
 
 ## What ships as golden configs
 
@@ -97,4 +97,4 @@ Sticky negative knowledge. Do not relearn.
 
 `bun run check` repairs a checkout rather than gating one. It runs `format` first to auto-fix drifted code, then asserts only what the formatters could not fix. The pull request workflow calls `check:format`, `check:spell`, and `check:shell` directly, and those three are the gate.
 
-`scripts/verify.sh`'s `Markdown bans` stage is the exception: it gates rather than repairs. It runs `canon markdown audit` over every tracked markdown file except `CHANGELOG.md`, since a generated changelog carries commit subjects nobody wrote against the ban set, and exits `2` on a finding or `3` on a shipped-empty ban set, failing `bun run check` and the `pre-push` hook that calls it. A refusal to measure exits `1` and is logged as a skip rather than a failure, as does a corpus with no file left to check once `CHANGELOG.md` is set aside. The stage needs `canon` on PATH. `canon docs target-projects` names the install command. Without it, the stage is skipped and logged, and coverage falls back to the three checks above.
+`scripts/verify.sh`'s `Markdown bans` stage is the exception: it gates rather than repairs. It runs `canon markdown audit` over every tracked markdown file except `CHANGELOG.md`, since a generated changelog carries commit subjects nobody wrote against the ban set, and exits `2` on a finding or `3` on a shipped-empty ban set, failing `bun run check` and the `pre-push` hook that calls it. A refusal to measure exits `1` and is logged as a skip rather than a failure, as does a corpus with no file left to check once `CHANGELOG.md` is set aside. The stage needs `canon` on PATH. `canon docs projects` names the install command. Without it, the stage is skipped and logged, and coverage falls back to the three checks above.

package/tooling/claude/reference.md

@@ -82,7 +82,7 @@ The first entry covers the whole record root, so a record folder added later nee
 ## CLAUDE.md
 
 - Ships as a seed with placeholder project name, description, and key paths. Fill these in after init.
-- Section layout: `Context`, `Indexes`, `Markdown`, `Key paths`, `Spelling`, `Snippets`, `Tasks`, `Memory`. Each section groups rules that share a surface so skills can detect, extend, or skip by heading.
+- Section layout: `Context`, `Indexes`, `Markdown`, `Key paths`, `Spelling`, `Tasks`, `Memory`. Each section groups rules that share a surface so skills can detect, extend, or skip by heading.
 - The memory rules favor signal over volume. Saving only after a second occurrence or an explicit user correction keeps entries focused on patterns worth preventing, not first-occurrence slips. The 3-line cap stops the built-in auto-memory from drifting into narrative writeups that bury the rule underneath the recovery story.
 - The `Context` section points at `.claude/` state docs one line. `plan-feature` does the parallel read when invoked. The seed intentionally does not re-list every file.
 

package/claude/skills/create-snippet/REQUIREMENT.md

@@ -1,39 +0,0 @@
----
-name: create-snippet
-description: Why a snippet needs its shape read from the reference and its write surface resolved before anything is drafted
----
-
-# Create snippet requirement
-
-## Gap
-
-Without this skill, a snippet is drafted the way any other markdown file is drafted, so it arrives carrying frontmatter, headings, and a fill-in placeholder. None of the invocation channels strip those. Typing `>slug` in a chat inserts the scaffolding verbatim, and the file that was meant to be one instruction reads as a document.
-
-The write surface is the second failure. The toolkit authors at `snippets/` and a target project may still hold a stale `.claude/snippets/` copy from before that domain's install channel retired, so a session picks whichever folder it noticed first. A toolkit snippet written into the consumed copy fails the drift assertion that regenerates that folder. A snippet written there in a target project is correct and looks identical, which is why the surface has to be resolved from what the project has rather than guessed.
-
-Inside the project surface, a third failure sits one level deeper. A project-authored snippet sharing a name with a toolkit one used to be indistinguishable from it, back when `canon snippets sync` walked that folder and could not tell which side owned the file. That verb retired with the domain's install channel, so nothing reads ownership by location there any more, but the `project/` subfolder still separates the two by eye, which is worth keeping even with no sync left to protect from.
-
-## Must
-
-- Read the bundled snippet reference before drafting, since the shape rules are what the invocation channels depend on
-- Resolve the write surface from which snippet folder the project has, rather than from whichever one the session noticed first
-- On the project surface, write under its `project/` subfolder, keeping a project-authored file visually apart from a toolkit-installed one
-- Confirm the slug and the full body with the user before writing
-- Emit the written path in full, so the terminal can resolve it
-- State what the resolved surface implies after writing, since a root file needs the consumed copy regenerated and a project-local one needs copying to the toolkit to ship
-
-## Must not
-
-- Restate the snippet authoring conventions in the body, which the bundled reference owns and which would drift from it
-- Write a standard, which answers to a different authoring contract
-
-## Guards
-
-- Neither snippet folder exists: stop, since there is nowhere for the snippet to live
-
-## Out of scope
-
-- Editing a snippet that already exists
-- A standard, which `create-standard` owns
-- Installing and syncing the snippets the toolkit ships, which the `canon snippets` commands own
-- What a snippet is and how it is invoked, which the bundled snippet reference states

package/claude/skills/create-snippet/SKILL.md

@@ -1,30 +0,0 @@
----
-name: create-snippet
-description: Creates a new snippet file in `snippets/` or `.claude/snippets/`. Use when asked to "create a snippet", add a snippet, write a reusable prompt, or make a new snippet. Do NOT use to edit an existing snippet.
----
-
-# Create snippet
-
-Creates one snippet file. Read these files in parallel:
-
-- `${CLAUDE_SKILL_DIR}/../../standards/markdown.md`: punctuation and formatting for all generated text
-- The `write-human` skill: voice, rhythm, and sentence construction for all generated text
-- `${CLAUDE_SKILL_DIR}/../../standards/snippets.md`: authoring conventions, invocation channels, use patterns
-
-## Guards
-
-- If neither `snippets/` nor `.claude/snippets/` exists, stop: `❌ No snippets/ or .claude/snippets/ directory found.`
-
-## Steps
-
-1. Resolve the write surface: `snippets/` at the root if present, which is the toolkit's own authoring source. Otherwise `.claude/snippets/`, a stale copy a target project holds from before its install channel retired.
-2. Draft the content from the user's description. The snippet reference governs structure, invocation, and authoring conventions.
-3. Confirm the slug and full content with the user before writing
-4. Write the file. On the root surface: `<surface>/<category>/<slug>.md`, or `<surface>/<slug>.md` when the snippet takes no category. On the `.claude/` surface: the same shape nested one level deeper under `project/`, a convention kept for its own sake now that nothing syncs that folder.
-
-## After writing
-
-Emit the full path on its own line.
-
-- Root surface: this is the toolkit's authoring source. Remind the user to run `bun run check` to regenerate the consumed copy under `.claude/`.
-- `.claude/` surface: the file is project-local, under `.claude/snippets/project/`. Remind the user to copy it to the toolkit repo, under `snippets/<category>/<name>.md`, if it should ship to every project.