@erclx/canon 4.35.0 → 4.36.1

package/claude/.claude-plugin/plugin.json

@@ -1,7 +1,7 @@
 {
   "name": "canon",
   "description": "Automated governance, versioning, and discovery tools for Claude Code.",
-  "version": "4.35.0",
+  "version": "4.36.1",
   "author": {
     "name": "Eric Le",
     "url": "https://github.com/erclx"

package/claude/skills/draft-and-pick/SKILL.md

@@ -16,7 +16,7 @@ Some decisions are settled by looking rather than by reasoning, and no draft is
 ## Step 1: name the decision and the arms
 
 1. State the decision in one sentence, naming what changes between arms and what stays fixed.
-2. Derive a kebab slug from that sentence. Every file this run writes goes to `.canon/tmp/<slug>/`, per `.claude/rules/core/055-scratch.md`.
+2. Derive a kebab slug from that sentence. Every file this run writes goes to `.canon/tmp/<slug>/`, per `.claude/rules/canon/core/055-scratch.md`.
 3. Write one arm per candidate, each carrying an id, a label, and what the arm costs. An arm with no stated cost is not an option.
 4. Make the current state arm `0`, so the baseline is a candidate rather than an absence. A decision with nothing shipped yet says so and starts at arm `1`.
 5. Stop at three to five arms. Two is a comparison the operator can hold in prose, and past five the pick stops being a look and becomes a sort.
@@ -47,7 +47,7 @@ canon capture .canon/tmp/<slug>/candidates.html --selector <element>
 
 ## Step 4: take the pick
 
-Put the choice to the operator through the structured question surface, per `.claude/rules/core/005-behavior.md`.
+Put the choice to the operator through the structured question surface, per `.claude/rules/canon/core/005-behavior.md`.
 
 - One option per arm, labeled with the arm's id and carrying its cost as the description.
 - Rank the recommendation first and mark it `(Recommended)`.

package/claude/skills/migration-standards-drop/SKILL.md

@@ -86,7 +86,7 @@ Print the blocks below, omitting any that is empty.
 ## Citations to repoint
 
 - `CLAUDE.md:42` → `canon standards markdown`
-- `.claude/rules/core/<n>-<slug>.md:8` → `canon standards skill`
+- `.claude/rules/canon/core/<n>-<slug>.md:8` → `canon standards skill`
 
 ## You supply
 

package/docs/agents/commands.md

@@ -149,7 +149,7 @@ Common patterns:
 
 `migrate records` moves a project's session records from `.claude/` to `.canon/` and rewrites every tracked file that cites one. It reports until `--write` is passed, and refuses outright when the project does not already ignore `.canon/`, since every folder it relocates is ignored where it stands and landing one under a tracked root commits the memory pen. Take the ignore entry with `canon tooling sync --write` first.
 
-A record folder already present at the destination is a refusal rather than a merge, and a line carrying `canon-keep-record-root`, or the line below it, keeps the old spelling for prose that dates a decision. The records themselves are never swept: everything under `.canon/` and every `.claude/` record folder is passed over and reported as a count on its own line, which is what keeps the run that follows the ignore collapse touching the same files as one before it. Running it twice rewrites nothing, which is the check that the exclusions, the markers, and that skip all fired.
+A record folder already present at the destination is a refusal rather than a merge, and a line carrying `canon-keep-record-root`, or the nearest non-blank line below it, keeps the old spelling for prose that dates a decision. The records themselves are never swept: everything under `.canon/` and every `.claude/` record folder is passed over and reported as a count on its own line, which is what keeps the run that follows the ignore collapse touching the same files as one before it. Running it twice rewrites nothing, which is the check that the exclusions, the markers, and that skip all fired.
 
 `migrate record-tree` is what reaches the records the sweep above passes over, and the two share no scope. That one enumerates through git, so it sees every tracked file and none of the records, which are gitignored by construction. This one walks `.canon/` itself and is scoped to the folders a session still follows a path into: `diagrams`, `memory`, `plans`, `proposals`, `review`, `tasks`, and `teach`, each minus its own `archive/` subtree. A closed groundwork or intake trail, the scratch folder, and the backup history are reported as counts and never rewritten, because a path inside a closed trail sits in a sentence about work that already ended. Run it after the move, since there is no new root to walk before one.
 

package/docs/agents/install-and-sync.md

@@ -9,22 +9,25 @@ The behavior notes behind the verbs listed in `commands.md`. Each one records wh
 
 ## Domain sync
 
-`canon gov sync` updates only rules already present under `.claude/rules/` and
-never adds new ones. A rule the toolkit does not ship is left alone, which is
-how project-authored rules survive, and one under `.claude/rules/project/`
-is left alone regardless of its name, since that subfolder is project-authored
-by location. It also removes a stale `.claude/GOV.md`
-from the retired build. Use `canon gov install` to add rules.
-
-A rule the toolkit finds no source for, sitting in a shared subdirectory rather
-than under `.claude/rules/project/`, is reported with the path under that
-subfolder it would take. The offer is conditional on the project having written
-the rule, since a rule the toolkit shipped and later renamed reaches the same
-line, and moving one there would mark it the project's for good. Nothing is
-moved either way, because a rule's installed path is one the project's own
-rules, skills, and docs may cite. `canon standards rule` carries the reserved
-number bands behind that placement, where `900-999` is the range a
-project-authored rule takes and everything below it belongs to the toolkit.
+`canon gov sync` updates only rules already present under
+`.claude/rules/canon/` and never adds new ones. That wrapper marks the
+toolkit-owned half of the tree, and it is the whole of what the walk reaches:
+`.claude/rules/project/` sits outside it by location and is never read,
+matched, or reported on, which is how project-authored rules survive. It also
+removes a stale `.claude/GOV.md` from the retired build. Use
+`canon gov install` to add rules.
+
+A rule under `.claude/rules/canon/` that the toolkit finds no source for is
+reported orphaned with no destination offered. The toolkit cannot tell a rule
+a project dropped there from one it shipped and later renamed, and a
+destination nested inside `canon/` would be wrong for the first case
+regardless, since that folder is replaced wholesale on sync.
+
+Nothing is moved either way, because a rule's installed path is one the
+project's own rules, skills, and docs may cite. `canon standards rule` carries
+the reserved number bands behind the three-way split, where `900-999` under
+`.claude/rules/project/` is what a project-authored rule takes and everything
+under `.claude/rules/canon/` belongs to the toolkit.
 
 `canon sync --check` does not report an orphaned entry. It skips every one, so
 the destination reaches `canon gov sync` alone among the two per-file domain
@@ -52,8 +55,8 @@ without governance has yet to install what every project carries, while one
 without design chose that.
 
 When the target's install recorded a stack, `canon gov sync` also reports a
-rule that stack lists and `.claude/rules/` does not hold, as a `missing` entry
-carrying no change. This is what makes a target whose recorded sync point
+rule that stack lists and `.claude/rules/canon/` does not hold, as a `missing`
+entry carrying no change. This is what makes a target whose recorded sync point
 postdates a rule joining its stack still see that rule: the report reads the
 target's current entitlement against its current tree rather than diffing
 from an anchor a later sync could advance past the rule's own commit. A
@@ -109,9 +112,12 @@ runs the verb again for that name.
 
 `canon gov regen` is the one governance verb that runs against the toolkit root,
 because the `.claude/rules/` it writes there is produced output rather than an
-operator's working copy. It reads the stack recorded in `internal/governance.toml`,
-installs it alongside anything under `internal/rules/`, and clears the
-destination first so a rule the record stopped naming disappears.
+operator's working copy. It reads the stack recorded in `internal/governance.toml`
+into `.claude/rules/canon/`, installs anything under `internal/rules/` into a
+separate `.claude/rules/internal/`, and clears both destinations first so a
+rule the record stopped naming disappears. `internal/` is what this repository
+alone carries: no `canon gov install` or `canon gov sync` target ever writes it,
+since a target has no rule source of its own that ships nowhere.
 
 It takes `--root <path>` and defaults to the toolkit root, prints nothing on success, and
 reports the reason on stderr with exit 1 when the record names a stack or rule

package/docs/agents/routing.md

@@ -5,7 +5,7 @@ description: Reading per CLAUDE.md section how many bullets name a path, what co
 
 # Routing report
 
-`canon claude routing` reports, per `CLAUDE.md` section, how many top-level bullets name a path and how many of those a path-scoped rule already covers. It answers the firing axis of the tier test in `.claude/rules/claude/592-claude-md.md`, whether a fact applies every session or fires on one path, and which until this verb existed was a judgment nothing counted. `.claude/ARCHITECTURE.md` names two further axes, conditional presence and updatability, that this verb does not check.
+`canon claude routing` reports, per `CLAUDE.md` section, how many top-level bullets name a path and how many of those a path-scoped rule already covers. It answers the firing axis of the tier test in `.claude/rules/canon/claude/592-claude-md.md`, whether a fact applies every session or fires on one path, and which until this verb existed was a judgment nothing counted. `.claude/ARCHITECTURE.md` names two further axes, conditional presence and updatability, that this verb does not check.
 
 ```bash
 canon claude routing

package/docs/agents/test-order.md

@@ -5,7 +5,7 @@ description: Reading where an implementation reached history ahead of its test,
 
 # Test order
 
-`canon gov test-order` reports where an implementation reached a commit ahead of the test covering the same behavior. It answers the rule in `.claude/rules/core/070-planning.md` that asks for the test first, which until this verb existed was prose loaded on a glob match with nothing measuring it.
+`canon gov test-order` reports where an implementation reached a commit ahead of the test covering the same behavior. It answers the rule in `.claude/rules/canon/core/070-planning.md` that asks for the test first, which until this verb existed was prose loaded on a glob match with nothing measuring it.
 
 ```bash
 canon gov test-order

package/docs/target-projects.md

@@ -142,7 +142,7 @@ Order matters between the first line and the two under it. The sync prunes the t
 
 Read the `ok` field out of the `--json` record rather than the exit code. A shell profile that wraps `canon` in a function takes its status from whatever the function runs last, so an absent subcommand and a clean run can both exit 0, and a reader watching the exit alone concludes the move happened.
 
-A tracked file that names an old record path on purpose, such as prose dating a decision, keeps it by carrying `canon-keep-record-root` on that line or the one above. The report pass prints every file it would rewrite, which is where to catch one before `--write` runs.
+A tracked file that names an old record path on purpose, such as prose dating a decision, keeps it by carrying `canon-keep-record-root` on that line or the nearest non-blank line above. The report pass prints every file it would rewrite, which is where to catch one before `--write` runs.
 
 Until the move runs, the project is exposed. The shipped ignore set no longer names the old record paths, so a project holding records at `.claude/` stops ignoring them on its next `canon tooling sync`, and the first sign is a memory file or a task board appearing in a commit. Every command reads either root, so nothing else breaks in the meantime, and running the move is what closes it.
 

package/governance/rules/lib/305-e2e-reliability.md

@@ -31,4 +31,4 @@ paths:
 
 ## Authority
 
-- Follow `.claude/rules/lib/300-testing-ts.md` for framework choice, file placement, and test naming.
+- Follow `.claude/rules/canon/lib/300-testing-ts.md` for framework choice, file placement, and test naming.

package/governance/rules/lib/306-test-scope.md

@@ -21,5 +21,5 @@ paths:
 
 - Answer a question about the running page with a script against the dev server rather than with the suite.
 - Do not enable `fullyParallel` in `playwright.config.ts`.
-- Follow `.claude/rules/ui/440-surface-capture.md` for capture scope.
-- Follow `.claude/rules/lib/305-e2e-reliability.md` for waits and guards.
+- Follow `.claude/rules/canon/ui/440-surface-capture.md` for capture scope.
+- Follow `.claude/rules/canon/lib/305-e2e-reliability.md` for waits and guards.

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@erclx/canon",
   "type": "module",
-  "version": "4.35.0",
+  "version": "4.36.1",
   "description": "Infrastructure and quality tooling for developer workflows",
   "license": "MIT",
   "bin": {

package/scripts/core/install-check.sh

@@ -97,7 +97,7 @@ log_step "Assert scaffold"
 # folder-whole entry the same way it does `core` and `claude`.
 for path in "CLAUDE.md" ".claude/wiki/index.md" ".claude" ".claude/context/index.md" ".claude/wireframes/index.md" ".canon/diagrams/index.md" \
   ".prettierrc" ".editorconfig" ".lintstagedrc" ".husky/pre-commit" ".github/workflows/verify.yml" "scripts/verify.sh" \
-  ".claude/rules/core/000-constitution.md" ".claude/rules/snippets/505-at-references.md"; do
+  ".claude/rules/canon/core/000-constitution.md" ".claude/rules/canon/snippets/600-at-references.md"; do
   if [ ! -e "$TARGET_DIR/$path" ]; then
     log_error "Missing after canon init: $path"
   fi

package/src/commands/feedback.ts

@@ -106,7 +106,7 @@ export function register(program: Command): void {
         }
         const reason = issueFailureMessage(result)
         if (!isToolkitSource()) {
-          frameError(`${reason} No toolkit source to fall back to.`)
+          frameError(reason)
           process.exitCode = 1
           return
         }

package/src/commands/gov.ts

@@ -78,6 +78,7 @@ function payloadRel(root: string): string {
   return creationRel(root, SCRATCH, 'gov', 'rules.md')
 }
 const RULES_REL = join('.claude', 'rules')
+const CANON_RULES_REL = join('.claude', 'rules', 'canon')
 
 interface InstallOptions {
   readonly add?: string
@@ -139,7 +140,7 @@ export function register(program: Command): void {
 
   gov
     .command('install')
-    .description('Install a governance stack into .claude/rules/')
+    .description('Install a governance stack into .claude/rules/canon/')
     .argument('[stack]', 'Stack name (e.g. base, node, react)')
     .argument('[target]', 'Target directory', '.')
     .helpOption('-h, --help', 'Show this help message')
@@ -167,7 +168,7 @@ export function register(program: Command): void {
 
   gov
     .command('sync')
-    .description('Update rules already installed under .claude/rules/')
+    .description('Update rules already installed under .claude/rules/canon/')
     .argument('[target]', 'Target directory', '.')
     .helpOption('-h, --help', 'Show this help message')
     .action(async (target: string) => {
@@ -230,7 +231,7 @@ export function register(program: Command): void {
       'after',
       [
         '',
-        'Measures the rule in .claude/rules/core/070-planning.md that asks for',
+        'Measures the rule in .claude/rules/canon/core/070-planning.md that asks for',
         'the test before the code. It reports and never gates, because pairing',
         'a test to an implementation is a judgment.',
         '',
@@ -1191,7 +1192,7 @@ async function runInstall(
   for (const source of found) logInfo(source.rule)
 
   const shouldInstall = await select({
-    message: `Install ${found.length} rules to ${displayPath(target, RULES_REL)}?`,
+    message: `Install ${found.length} rules to ${displayPath(target, CANON_RULES_REL)}?`,
     options: [
       { value: true, label: 'Yes' },
       { value: false, label: 'No' },

package/src/commands/migrate.ts

@@ -435,8 +435,9 @@ export function register(program: Command): void {
         'this relocates is ignored where it stands, and landing one under a root',
         'the project tracks publishes the memory pen into the next commit.',
         '',
-        'A line carrying canon-keep-record-root, or the line below it, keeps the',
-        'old root. Prose that dates a decision needs it; a live path does not.',
+        'A line carrying canon-keep-record-root, or the nearest non-blank line',
+        'below it, keeps the old root. Prose that dates a decision needs it; a',
+        'live path does not.',
         '',
         'The records themselves are never swept. Everything under .canon/ and',
         'every .claude/ record folder is left alone and reported as a count, so',
@@ -487,8 +488,9 @@ export function register(program: Command): void {
         'The records are untracked and unbacked, so a wrong rewrite has no undo',
         'and the report is what a reader judges before passing --write.',
         '',
-        'A line carrying canon-keep-record-root, or the line below it, keeps the',
-        'old root. Prose that dates a decision needs it; a live path does not.',
+        'A line carrying canon-keep-record-root, or the nearest non-blank line',
+        'below it, keeps the old root. Prose that dates a decision needs it; a',
+        'live path does not.',
         '',
         'Examples:',
         '  canon migrate record-tree',

package/src/gate/measures.ts

@@ -85,7 +85,7 @@ const output = (text: string): Emission => ({ kind: 'output', text })
 /**
  * Rules no stack reaches, sorted the way `canon gov list` emits them.
  * `260-shadcn` and `320-tanstack-query` are opt-in libraries a project may not
- * want. `505-at-references` used to sit here too, shipping with no stack on
+ * want. `600-at-references` used to sit here too, shipping with no stack on
  * purpose since a rule under `claude/` would reach every base consumer through
  * the folder-whole entry there. Its own install channel, `canon snippets
  * install`, retired with nothing left to deliver it, so `base` now carries

package/src/github-format.ts

@@ -25,13 +25,15 @@ export interface IssueSuccess {
 
 export type CreateIssueResult = IssueSuccess | IssueFailure
 
-const ISSUE_URL = 'https://github.com/erclx/canon/issues/new'
+const REPO = 'erclx/canon'
+const ISSUE_URL = `https://github.com/${REPO}/issues/new`
 
 export function buildIssueArgs(opts: CreateIssueOptions): string[] {
   const args = ['issue', 'create', '--title', opts.title, '--body', opts.body]
   for (const label of opts.labels ?? []) {
     args.push('--label', label)
   }
+  args.push('--repo', REPO)
   return args
 }
 
@@ -71,5 +73,5 @@ export function issueFailureMessage(failure: IssueFailure): string {
   if (failure.reason === 'missing-binary') {
     return `gh is not installed, so no issue was filed. Install gh, or file it at ${ISSUE_URL}`
   }
-  return `gh could not file the issue: ${failure.detail ?? 'no diagnostic on stderr'}`
+  return `gh could not file the issue: ${failure.detail ?? 'no diagnostic on stderr'}. File it manually at ${ISSUE_URL} instead.`
 }

package/src/gov/adapter.ts

@@ -1,5 +1,6 @@
 import { existsSync } from 'node:fs'
 import { basename, join, relative, resolve } from 'node:path'
+import { canonRulesDir } from '@/gov/install'
 import { resolveMissingRules } from '@/gov/stacks'
 import type { InstalledFile, RetiredSurface, SyncAdapter } from '@/sync/engine'
 import { readStamp, stampedChain } from '@/sync/stamp'
@@ -42,6 +43,13 @@ export function indexSourceRules(root: string): Map<string, string> {
  * Matches installed rules to sources by rule name rather than by relative
  * path, so a rule that moved between subdirectories in the toolkit still
  * syncs into the subdirectory the target already uses.
+ *
+ * Declares no `projectSubdir`. That exemption existed to keep a project's
+ * `.claude/rules/project/` folder out of the walk by location before any
+ * name lookup ran, and `installedRoot` narrowing to `.claude/rules/canon/`
+ * already leaves `project/` outside the walked root, so a second exemption
+ * computing a stale `canon/project/` destination would be wrong rather than
+ * merely redundant.
  */
 export function createGovAdapter(root: string): SyncAdapter {
   const index = indexSourceRules(root)
@@ -52,12 +60,11 @@ export function createGovAdapter(root: string): SyncAdapter {
     missingMessage:
       "No governance surfaces found in target. Run 'canon gov install' first.",
     unit: 'changes',
-    installedRoot: (target: string) => join(target, '.claude', 'rules'),
+    installedRoot: canonRulesDir,
     locateSource: (file: InstalledFile) =>
       index.get(basename(file.path, '.md')),
     collectRetired: (target: string) => collectRetiredGov(target),
     collectMissing: (target: string) => collectMissingGov(root, target),
-    projectSubdir: 'project',
     stamp: { domain: 'governance', toolkitRoot: root },
   }
 }
@@ -72,13 +79,7 @@ function collectMissingGov(root: string, target: string): RetiredSurface[] {
   const chain = stampedChain(readStamp(target), 'governance')
 
   return resolveMissingRules(root, target, chain).map((source) => {
-    const dest = join(
-      target,
-      '.claude',
-      'rules',
-      source.subdir,
-      `${source.rule}.md`,
-    )
+    const dest = join(canonRulesDir(target), source.subdir, `${source.rule}.md`)
     const rel = relative(target, dest)
     return {
       path: dest,

package/src/gov/consumed.ts

@@ -2,8 +2,9 @@ import { existsSync, readFileSync } from 'node:fs'
 import { rm } from 'node:fs/promises'
 import { basename, join } from 'node:path'
 import {
+  canonRulesDir,
+  installedInternalRulesDir,
   installRules,
-  installedRulesDir,
   lookupRules,
   type RuleSource,
   ruleSubdir,
@@ -117,12 +118,15 @@ export async function regenConsumedRules(
 
   // Clearing first is what makes a rule the record stopped naming disappear.
   // Copying over the destination would leave it behind as an unsourced file,
-  // which is the state this producer exists to end.
-  await rm(installedRulesDir(root), { recursive: true, force: true })
+  // which is the state this producer exists to end. Each subtree clears on
+  // its own rather than through the shared `.claude/rules/` parent, so a
+  // `project/` folder landing beside them later is never in the blast radius.
+  await rm(canonRulesDir(root), { recursive: true, force: true })
+  await rm(installedInternalRulesDir(root), { recursive: true, force: true })
 
   const installed = [
-    ...(await installRules(found, root)),
-    ...(await installRules(internal, root)),
+    ...(await installRules(found, root, 'canon')),
+    ...(await installRules(internal, root, 'internal')),
   ]
 
   return { ok: true, installed: installed.sort() }

package/src/gov/install.ts

@@ -21,13 +21,26 @@ export function installedRulesDir(target: string): string {
   return join(target, '.claude', 'rules')
 }
 
+/** Toolkit-shipped stack rules, wrapped so their source reads from location. */
+export function canonRulesDir(target: string): string {
+  return join(installedRulesDir(target), 'canon')
+}
+
+/**
+ * This repository's own toolkit-only rules, installed beside `canon/` rather
+ * than interleaved into its bands. No target ever holds this folder.
+ */
+export function installedInternalRulesDir(target: string): string {
+  return join(installedRulesDir(target), 'internal')
+}
+
 /**
- * Rule names a target already holds, read off the installed tree by basename
- * rather than off a recorded stack, since a target may hold rules `--add`
- * layered on that no stack lists.
+ * Rule names a target already holds, read off the installed `canon/` tree by
+ * basename rather than off a recorded stack, since a target may hold rules
+ * `--add` layered on that no stack lists.
  */
 export function installedRuleNames(target: string): Set<string> {
-  const dir = installedRulesDir(target)
+  const dir = canonRulesDir(target)
   const names = new Set<string>()
   if (!existsSync(dir)) return names
 
@@ -114,12 +127,20 @@ export function lookupRules(
  * Copies each rule into the subdirectory it was authored in, so the installed
  * tree keeps the band structure `governance/rules/` carries. Returns the
  * target-relative paths the timeline prints.
+ *
+ * `destSubdir` picks which wrapper the rule lands under: `canon` for every
+ * target-facing install, and `internal` only for this repository's own
+ * toolkit-only rules, which `regenConsumedRules` installs separately.
  */
 export async function installRules(
   sources: readonly RuleSource[],
   target: string,
+  destSubdir: 'canon' | 'internal' = 'canon',
 ): Promise<string[]> {
-  const rulesDir = installedRulesDir(target)
+  const rulesDir =
+    destSubdir === 'canon'
+      ? canonRulesDir(target)
+      : installedInternalRulesDir(target)
   const installed: string[] = []
 
   for (const source of sources) {

package/src/gov/restated.ts

@@ -699,7 +699,7 @@ export function readRestated(root: string): RestatedReport {
   // Every candidate's rare set is invariant across the subject loop, so it is
   // built once here rather than per pair. The corpora multiply out to hundreds
   // of thousands of pairings, and rebuilding a set inside that is the shape
-  // `.claude/rules/core/040-performance.md` names.
+  // `.claude/rules/canon/core/040-performance.md` names.
   const rareCandidates = candidates.map((candidate) => ({
     ...candidate,
     rare: distinctive(candidate.analysis),

package/src/migrate/records.ts

@@ -134,7 +134,7 @@ export const RECORD_ONLY_ROOTS: readonly RecordRoot[] = RECORD_ROOTS.filter(
  *
  * The asymmetry is the point. A whole-root prefix is correct for the new root
  * and wrong for the old one, which is mixed: this repository tracks 163 files
- * under `.claude/`, and a target's installed `.claude/rules/core/035-tasks.md`
+ * under `.claude/`, and a target's installed `.claude/rules/canon/core/035-tasks.md`
  * is the file the sweep exists to repoint, so a bare `.claude/` prefix strands
  * it silently. The old root is therefore entry-scoped, through `spell` so the
  * one naming variant stays decided in `record-root.ts`.
@@ -180,14 +180,21 @@ export function isRecordArtifact(path: string): boolean {
  * Prose that dates a decision, records where a defect landed, or names the
  * fallback a target still resolves through all have to keep saying `.claude/`,
  * and a sweep cannot tell those from a live path. The marker sits on the line
- * itself or on the one above it, which is the placement `canon-keep-retired`
- * and `canon-allow-superseded` already use here.
+ * itself or on the nearest non-blank line above it, walking past a run of
+ * blank markdown lines to reach a marker written on its own line above the
+ * paragraph it protects. `canon-keep-retired` and `canon-allow-superseded`
+ * mark code instead, where no blank line ever falls between the marker and
+ * the line it protects, so neither needs the walk.
  */
 const KEEP_MARKER = 'canon-keep-record-root'
 
 function isKept(lines: readonly string[], index: number): boolean {
   if (lines[index]?.includes(KEEP_MARKER)) return true
-  return index > 0 && (lines[index - 1]?.includes(KEEP_MARKER) ?? false)
+
+  let above = index - 1
+  while (above >= 0 && lines[above]?.trim() === '') above -= 1
+
+  return above >= 0 && (lines[above]?.includes(KEEP_MARKER) ?? false)
 }
 
 /** Rewrites every unmarked citation into a moved entry. */

package/src/slides/layouts.ts

@@ -30,6 +30,11 @@ export const LAYOUTS: LayoutInfo[] = [
   { name: 'stat-callout', description: 'Row of large stats with captions' },
   { name: 'grid', description: 'Two-by-two cards, each a term and detail' },
   { name: 'quote', description: 'Large pull quote with attribution' },
+  {
+    name: 'freeform',
+    description:
+      'Explicit shapes at a declared position and size, for a figure the other layouts cannot draw',
+  },
 ]
 
 const LAYOUT_NAMES = new Set(LAYOUTS.map((layout) => layout.name))
@@ -55,6 +60,7 @@ const RENDERERS: Record<
   'stat-callout': renderStatCallout,
   grid: renderGrid,
   quote: renderQuote,
+  freeform: renderFreeform,
 }
 
 export function renderDeckSlide(
@@ -346,6 +352,81 @@ function renderQuote(s: PptxSlide, slide: Slide, theme: Theme): void {
   }
 }
 
+const SHAPE_KEYS = new Set(['x', 'y', 'w', 'h', 'color'])
+const COLOR_ROLES: (keyof Theme)[] = [
+  'background',
+  'surface',
+  'ink',
+  'muted',
+  'accent',
+]
+
+function renderFreeform(s: PptxSlide, slide: Slide, theme: Theme): void {
+  addTitle(s, slide.title, theme)
+  for (const line of slide.content) {
+    if (!line.trim().startsWith('-')) throw malformedShape(slide.title, line)
+    renderShapeLine(s, line, slide.title, theme)
+  }
+}
+
+function malformedShape(title: string, line: string): Error {
+  return new Error(
+    `Malformed freeform shape on slide "${title}": ${line.trim()}`,
+  )
+}
+
+function renderShapeLine(
+  s: PptxSlide,
+  line: string,
+  title: string,
+  theme: Theme,
+): void {
+  const stripped = line.replace(/^\s*-\s*/, '')
+  const colonIndex = stripped.indexOf(':')
+  const head = (
+    colonIndex === -1 ? stripped : stripped.slice(0, colonIndex)
+  ).trim()
+  const text = colonIndex === -1 ? '' : stripped.slice(colonIndex + 1).trim()
+
+  const tokens = head.split(/\s+/).filter(Boolean)
+  const kind = tokens.shift()
+  if (kind !== 'text' && kind !== 'rect') throw malformedShape(title, line)
+  if (kind === 'text' && colonIndex === -1) throw malformedShape(title, line)
+
+  const attrs: Record<string, string> = {}
+  for (const token of tokens) {
+    const match = token.match(/^(\w+)=(.+)$/)
+    if (!match) throw malformedShape(title, line)
+    if (!SHAPE_KEYS.has(match[1])) throw malformedShape(title, line)
+    attrs[match[1]] = match[2]
+  }
+
+  const x = Number(attrs.x)
+  const y = Number(attrs.y)
+  const w = Number(attrs.w)
+  const h = Number(attrs.h)
+  if (![x, y, w, h].every(Number.isFinite)) throw malformedShape(title, line)
+
+  const role = attrs.color as keyof Theme
+  if (!COLOR_ROLES.includes(role)) throw malformedShape(title, line)
+  const color = theme[role]
+
+  if (kind === 'text') {
+    s.addText(clean(text), {
+      x,
+      y,
+      w,
+      h,
+      fontFace: FONTS.body,
+      fontSize: TYPE.body,
+      color,
+      valign: 'top',
+    })
+  } else {
+    s.addShape('rect', { x, y, w, h, fill: { color } })
+  }
+}
+
 function addTitle(s: PptxSlide, title: string, theme: Theme): void {
   if (!title) return
   s.addText(clean(title), {

package/src/sync/check.ts

@@ -67,7 +67,7 @@ const ADAPTERS: Record<ScannedDomain, (root: string) => SyncAdapter> = {
 }
 
 const INSTALL_MARKERS: Record<ScannedDomain, readonly string[]> = {
-  governance: ['.claude', 'rules'],
+  governance: ['.claude', 'rules', 'canon'],
   design: DESIGN_INSTALL_DIR.split(sep),
 }
 

package/standards/publish.md

@@ -40,7 +40,9 @@ This check is one of the two the destination rule above scopes. The reader insid
 
 A phase label is one way text names the board, and a path under a record root is the other. Both resolve for a reader holding this checkout and neither resolves for anyone else, so this check is the second one the destination rule scopes.
 
-Two shapes get past a reader scanning for a bare label. A code span quoting a label is still the label, so read a span whose whole content is one as a hit and leave a longer token inside a span alone, which is a fixture name rather than a reference. The second shape is a path under a record root, gitignored and therefore absent from every clone, so `.canon/review/feedback/` names a folder the remote's reader cannot open. Under `.claude/`'s own tracked folders there is no hit, since `.claude/rules/core/005-behavior.md` resolves everywhere. `.canon/` carries no such carve-out: one ignore line covers the root whole, so every path beneath it is a hit regardless of which folder names it.
+Two shapes get past a reader scanning for a bare label. A code span quoting a label is still the label, so read a span whose whole content is one as a hit and leave a longer token inside a span alone, which is a fixture name rather than a reference. The second shape is a path under a record root, gitignored and therefore absent from every clone, so `.canon/review/feedback/` names a folder the remote's reader cannot open.
+
+Under `.claude/`'s own tracked folders there is no hit, since `.claude/context/governance/rules.md` resolves everywhere. `.canon/` carries no such carve-out: one ignore line covers the root whole, so every path beneath it is a hit regardless of which folder names it.
 
 Rewrite a hit to name what the reader can reach rather than deleting it. A row's subject stated plainly replaces its label, and what a record folder holds, said in a sentence, replaces its path.
 

package/standards/rule.md

@@ -31,27 +31,32 @@ Write both when both apply. A rule stating the directive and a skill stating how
 
 ## Location
 
-- Rules live at `.claude/rules/<subdirectory>/<n>-<slug>.md`
+- A toolkit-shipped rule lives at `.claude/rules/canon/<subdirectory>/<n>-<slug>.md`. The wrapper marks the file as toolkit-owned and replaced on sync, so a reader unfamiliar with the numbering convention still knows not to edit it.
 - Subdirectories group by domain: `core/`, `lang/`, `framework/`, `lib/`, `ui/`, `claude/`, `snippets/`, `ci/`
 - `<n>` is a number from the band reserved for the rule's source and `<slug>` is a one-to-three-word kebab topic
-- A rule the project authored itself lives at `.claude/rules/project/<subdirectory>/<n>-<slug>.md`, keeping the same subdirectory names
+- A rule the project authored itself lives at `.claude/rules/project/<subdirectory>/<n>-<slug>.md`, a sibling of `canon/` rather than nested inside it, keeping the same subdirectory names
+- This repository's own toolkit-only rules, which never ship to a target, live at `.claude/rules/internal/<subdirectory>/<n>-<slug>.md`, a second sibling of `canon/`. See "Two sources numbering into one folder" below.
 - Give every rule a numeric prefix. A bare-word filename reads as a folder name where a stack names its rules, so a rule without one is unreachable from a stack entry.
 
 ## Reserved numbers
 
-`000-899` is reserved for a rule set that ships to targets. `000-599` is what the first six subdirectories above already divide, at 100 per subdirectory. `ci/` was the first to draw from the headroom past that, taking `700-799`, and `600-699` with `800-899` is what remains for a subdirectory a shipped set has not added yet.
+`000-899` is reserved for a rule set that ships to targets. `000-599` is what the first six subdirectories above already divide, at 100 per subdirectory. `ci/` was the first to draw from the headroom past that, taking `700-799`.
+
+`snippets/` holds one rule rather than a subdirectory's worth of them, and draws a single number, `600`, from the nearer overflow band rather than claiming a hundred for one file. The rest of `600-699`, along with `800-899`, is what remains for a subdirectory a shipped set has not added yet.
 
 A project-authored rule takes `900-999`, one sequence across every subdirectory under `.claude/rules/project/`. Scanning for a free number instead is what fails, because a shipped set fills its own band release by release, so what reads as free today is what a later release lands on. One target authored `claude/561-self-check.md` on a day nothing shipped at 561, met `claude/561-teach.md` on its next install, and now reads two numbers differently from everywhere else.
 
 The cost is that a project-authored rule's leading digit stops naming its domain. Its subdirectory names it instead, and install preserves that either way. What a shared band costs is worse: a session that loads two rules reading as one number, with nothing in the folder to say which is which.
 
-`canon gov sync` reports a rule it finds no toolkit source for, outside `.claude/rules/project/`, and offers the path under it. The offer is conditional on the project having authored the rule, because a rule the toolkit shipped and later renamed looks identical from the outside and moving one there would mark it the project's for good. Nothing is moved either way, since a rule's installed path is one the project's own rules, skills, and docs may cite.
+`canon gov sync` walks only `.claude/rules/canon/`, so `.claude/rules/project/` sits outside the walk by location and is never matched, read, or reported on. A file under `.claude/rules/canon/` itself that no toolkit source names is still reported orphaned, but with no destination offered: the toolkit cannot tell a rule the project dropped there from one it shipped and later renamed, and a destination nested inside `canon/` would be wrong for the first case regardless, since that folder is toolkit-owned and replaced on sync. Nothing is moved either way, since a rule's installed path is one the project's own rules, skills, and docs may cite.
 
 ## Two sources numbering into one folder
 
-The reservation above divides one pair, being a shipped set against the rules a project wrote for itself. A third source numbering into the same folder needs its own division, which is the case for a rule set held back from targets and installed only where it was authored. Divide by source rather than by topic: one source takes the top of each subdirectory's band and the other takes the gaps between the tens.
+The reservation above divides one pair, being a shipped set against the rules a project wrote for itself. A third source, a rule set held back from targets and installed only where it was authored, needs its own division too. This repository is the one place all three sources exist at once, and it divides the third pair two ways at once rather than one: `canon/` and `internal/` separate a shipped rule from an internal one by location, the same way `project/` separates a project-authored one, and within each subdirectory the numbering still divides by source as well, one source taking the top of the band and the other the gaps between the tens.
+
+The numbering half stays because location alone does not carry to a reader who only sees the number, such as one comparing `core/070-planning.md` against a citation written before the rules moved into `canon/`.
 
-The collision this prevents is silent. Two rules that resolve to the same `<n>-<slug>` path leave one file in the installed folder, and neither the install nor the session that reads it reports which source lost. Nothing checks a division outside the reserved bands, so it holds only while both sources follow it.
+The collision this prevents is silent. Two rules that resolve to the same `<n>-<slug>` path leave one file in the installed folder, and neither the install nor the session that reads it reports which source lost. Nothing checks a division outside the reserved bands, so it holds only while both sources follow it. Separating `canon/` from `internal/` by folder removes the filename-collision case specifically, since the two no longer install to the same directory, but the number still carries the source signal for a reader who has only the number in view.
 
 State that division where the rule sources are described, not inside the rules it divides. A rule states its own topic, and a numbering convention spanning two sources belongs to whatever documents the pair.
 

package/tooling/claude/seeds/.claude/hooks/scratch-guard.sh

@@ -57,5 +57,5 @@ marker="$marker_dir/$key"
 mkdir -p "$marker_dir"
 : >"$marker"
 
-msg='Temporary file write outside the project scratch folder. Write temp files to .canon/tmp/<slug>/ in the project root, or .claude/.tmp/<slug>/ where the project carries no .canon/ root, not system temp. See the Scratch rule at .claude/rules/core/055-scratch.md.'
+msg='Temporary file write outside the project scratch folder. Write temp files to .canon/tmp/<slug>/ in the project root, or .claude/.tmp/<slug>/ where the project carries no .canon/ root, not system temp. See the Scratch rule (055-scratch, under core/ in your installed governance rules).'
 jq -nc --arg msg "$msg" '{hookSpecificOutput:{hookEventName:"PreToolUse",additionalContext:$msg}}'