@erclx/canon 5.43.0 → 5.45.0

package/src/markdown/scope.ts

@@ -8,19 +8,28 @@ const BULLET_RUN_SCOPE = [
   /^(?:claude|\.claude)\/skills\/[^/]+\/references\/.+\.md$/,
 ]
 
+/**
+ * The requirement beside each skill. Its findings gate only on a `GATED_PATHS`
+ * entry naming the file itself, so the prefix that gates a skill's body never
+ * sweeps in a requirement the rewrite has not reached yet.
+ */
+const REQUIREMENT_SCOPE =
+  /^(?:claude|\.claude)\/skills\/[^/]+\/REQUIREMENT\.md$/
+
 /**
  * The tracked documents the density limits hold: the context entries, the docs
- * pages, the skill bodies and references of both skill trees, the tooling
- * seeds and stack references, the wiki, and the two root guides.
+ * pages, the skill bodies, references, and requirements of both skill trees,
+ * the tooling seeds and stack references, the wiki, and the two root guides.
  *
  * Rules stay out, since a rule is one imperative per bullet. So do
- * `CLAUDE.md`, the requirement and design records, a seed carrying one of
- * those three names, the changelog, the examples, and every `.canon/` record,
- * each with a shape and cap of its own. Named here and nowhere else, so the
- * audit, the gate stage reading its exit, and their tests read one scope.
+ * `CLAUDE.md`, the project requirement and design records, a seed carrying one
+ * of those three names, the changelog, the examples, and every `.canon/`
+ * record, each with a shape and cap of its own. Named here and nowhere else, so
+ * the audit, the gate stage reading its exit, and their tests read one scope.
  */
 const DENSITY_SCOPE = [
   ...BULLET_RUN_SCOPE,
+  REQUIREMENT_SCOPE,
   /^tooling\/[^/]+\/seeds\/(?:.+\/)?(?!(?:CLAUDE|REQUIREMENTS|DESIGN)\.md$)[^/]+\.md$/,
   /^tooling\/[^/]+\/reference\.md$/,
   /^wiki\/.+\.md$/,
@@ -105,35 +114,36 @@ export const GATED_PATHS: readonly string[] = [
   'claude/skills/docs-sync/references/readme.md',
   'claude/skills/document-health/SKILL.md',
   'claude/skills/document-health/references/axes.md',
-  'claude/skills/draft-and-pick/SKILL.md',
-  'claude/skills/draft-and-pick/references/live-arms.md',
-  'claude/skills/draft-doc/SKILL.md',
-  'claude/skills/draft-doc/references/context.md',
-  'claude/skills/draft-doc/references/docs.md',
-  'claude/skills/draft-doc/references/readme.md',
-  'claude/skills/draft-doc/references/readme/agent-facing.md',
-  'claude/skills/draft-doc/references/readme/application.md',
-  'claude/skills/draft-doc/references/readme/cli.md',
-  'claude/skills/draft-doc/references/readme/library.md',
-  'claude/skills/draft-doc/references/readme/plugin.md',
-  'claude/skills/draft-doc/references/requirements.md',
-  'claude/skills/draft-doc/references/wiki-kind.md',
-  'claude/skills/draft-doc/references/wiki.md',
-  'claude/skills/draft-figure/SKILL.md',
-  'claude/skills/draft-figure/references/architecture-set.md',
-  'claude/skills/draft-figure/references/figures.md',
-  'claude/skills/draft-figure/references/hand-drawn.md',
-  'claude/skills/draft-figure/references/mermaid-path.md',
-  'claude/skills/draft-figure/references/mermaid.md',
-  'claude/skills/draft-identity/SKILL.md',
-  'claude/skills/draft-identity/references/card-route.md',
-  'claude/skills/draft-ready/SKILL.md',
-  'claude/skills/draft-ready/references/assembly.md',
-  'claude/skills/draft-ready/references/ready.md',
-  'claude/skills/draft-screencast/SKILL.md',
-  'claude/skills/draft-screencast/references/beats-template.md',
-  'claude/skills/draft-slides/SKILL.md',
-  'claude/skills/draft-slides/references/deck.md',
+  'claude/skills/pick-by-eye/REQUIREMENT.md',
+  'claude/skills/pick-by-eye/SKILL.md',
+  'claude/skills/pick-by-eye/references/live-arms.md',
+  'claude/skills/write-doc/SKILL.md',
+  'claude/skills/write-doc/references/context.md',
+  'claude/skills/write-doc/references/docs.md',
+  'claude/skills/write-doc/references/readme.md',
+  'claude/skills/write-doc/references/readme/agent-facing.md',
+  'claude/skills/write-doc/references/readme/application.md',
+  'claude/skills/write-doc/references/readme/cli.md',
+  'claude/skills/write-doc/references/readme/library.md',
+  'claude/skills/write-doc/references/readme/plugin.md',
+  'claude/skills/write-doc/references/requirements.md',
+  'claude/skills/write-doc/references/wiki-kind.md',
+  'claude/skills/write-doc/references/wiki.md',
+  'claude/skills/draw-figure/SKILL.md',
+  'claude/skills/draw-figure/references/architecture-set.md',
+  'claude/skills/draw-figure/references/figures.md',
+  'claude/skills/draw-figure/references/hand-drawn.md',
+  'claude/skills/draw-figure/references/mermaid-path.md',
+  'claude/skills/draw-figure/references/mermaid.md',
+  'claude/skills/design-identity/SKILL.md',
+  'claude/skills/design-identity/references/card-route.md',
+  'claude/skills/plan-ready/SKILL.md',
+  'claude/skills/plan-ready/references/assembly.md',
+  'claude/skills/plan-ready/references/ready.md',
+  'claude/skills/script-screencast/SKILL.md',
+  'claude/skills/script-screencast/references/beats-template.md',
+  'claude/skills/make-deck/SKILL.md',
+  'claude/skills/make-deck/references/deck.md',
   'claude/skills/git-branch/SKILL.md',
   'claude/skills/git-branch/references/branch.md',
   'claude/skills/git-branch/references/slug.md',
@@ -195,6 +205,7 @@ export const GATED_PATHS: readonly string[] = [
   'claude/skills/review-ui/references/hosted-preview.md',
   'claude/skills/review-ui/references/post.md',
   'claude/skills/review-ui/references/tick.md',
+  'claude/skills/role-orchestrator/REQUIREMENT.md',
   'claude/skills/role-orchestrator/SKILL.md',
   'claude/skills/role-orchestrator/references/orchestrator-cloud-launch.md',
   'claude/skills/role-orchestrator/references/orchestrator-dispatch.md',
@@ -212,8 +223,10 @@ export const GATED_PATHS: readonly string[] = [
   'claude/skills/role-orchestrator/references/orchestrator-reviewer-launch.md',
   'claude/skills/role-orchestrator/references/orchestrator-sweep.md',
   'claude/skills/role-orchestrator/references/orchestrator-watch.md',
+  'claude/skills/role-planner/REQUIREMENT.md',
   'claude/skills/role-planner/SKILL.md',
   'claude/skills/role-reviewer/SKILL.md',
+  'claude/skills/role-worker/REQUIREMENT.md',
   'claude/skills/role-worker/SKILL.md',
   'claude/skills/search-craft/SKILL.md',
   'claude/skills/search-craft/references/adopted.md',
@@ -301,6 +314,7 @@ export function densityGates(
   gated: readonly string[] = GATED_PATHS,
 ): boolean {
   if (!inDensityScope(rel)) return false
+  if (REQUIREMENT_SCOPE.test(rel)) return gated.includes(rel)
   if (
     ALWAYS_GATED.includes(kind) &&
     BULLET_RUN_SCOPE.some((pattern) => pattern.test(rel))

package/src/migrate/record-layout.ts

@@ -346,7 +346,7 @@ function entriesOf(dir: string, isDirectory: boolean): string[] {
 }
 
 /**
- * What `draft-and-pick` Step 6 writes into the folder it archives a choice to:
+ * What `pick-by-eye` Step 6 writes into the folder it archives a choice to:
  * a capture per canvas frame, named `arm-<id>`. A design handoff marks a pick
  * folder an earlier skill wrote. A folder carrying neither is evidence.
  */

package/src/migrate/scratch-evidence.ts

@@ -34,7 +34,7 @@ import {
   slugOf,
 } from '@/migrate/evidence-ordinal'
 import { presentFolders } from '@/records/backup'
-import { recordDir, SCRATCH } from '@/roots/record'
+import { LEGACY_SCRATCH_REL, recordDir, SCRATCH } from '@/roots/record'
 
 /**
  * Every folder this promotion moves, at the name it carries under scratch.
@@ -64,9 +64,17 @@ export const PROMOTED_FOLDERS: readonly string[] = [
   'target-survey',
 ]
 
-/** Where a promoted folder sits before the move. */
+/**
+ * Where a promoted folder sits before the move: `.canon/tmp` when it holds the
+ * folder, so a target part-way through a move promotes the newer copy, and the
+ * retired scratch folder otherwise. The verb is a migration, so it reads an
+ * unmigrated target where it is.
+ */
 export function sourcePath(root: string, folder: string): string {
-  return recordDir(root, SCRATCH, folder)
+  const current = recordDir(root, SCRATCH, folder)
+  const legacy = join(root, LEGACY_SCRATCH_REL, folder)
+
+  return !existsSync(current) && existsSync(legacy) ? legacy : current
 }
 
 /** The folder a promoted one lands inside, under whichever root carries it. */
@@ -85,7 +93,7 @@ function escape(value: string): string {
  * swallowing a sibling folder whose name extends it.
  */
 const OLD_PREFIXES = [
-  '.claude/.tmp/',
+  '.claude/.tmp/', // canon-keep-record-root
   '.canon/tmp/',
   '../.tmp/',
   '../tmp/',

package/src/migrate/skill-names.ts

@@ -13,13 +13,12 @@ import { defineRenameRules, type RenameRules } from '@/migrate/rename'
  * session roles together.
  *
  * The four `canon-` rows split the same way rather than sharing one
- * replacement prefix. `canon-screencast` and `canon-slides-draft` draft a
- * document, which is what the `draft-` family already means across its other
- * members, so they join it as `draft-screencast` and `draft-slides`.
- * `canon-record` and `canon-frames-read` are not drafting anything, so each
- * takes a standalone verb-first name, `record-screencast` and `read-frames`,
- * reading in sequence with `draft-screencast` as one three-step pipeline with
- * no prefix forcing that reading.
+ * replacement prefix. `canon-screencast` and `canon-slides-draft` each make
+ * an artifact, so each takes the verb-first name of what it makes,
+ * `script-screencast` and `make-deck`. `canon-record` and `canon-frames-read`
+ * take `record-screencast` and `read-frames`, reading in sequence with
+ * `script-screencast` as one three-step pipeline with no prefix forcing that
+ * reading.
  *
  * Two rows rename a skill rather than retiring a prefix. `ui-test` became
  * `ui-checklist` when the skill stopped writing tests and shrank to the
@@ -36,15 +35,25 @@ import { defineRenameRules, type RenameRules } from '@/migrate/rename'
  * Five rows merge skills rather than rename one. `draft-docs`,
  * `draft-context`, `draft-wireframes`, `draft-readme`, and `draft-wiki` ran
  * one procedure five times over, differing only in the standard each read and
- * the catalog each checked, so they became `draft-doc`, which picks the kind
- * from where the document lands. Every retired name lands on the one skill, so
- * a target citing any of them resolves after a single sweep.
+ * the catalog each checked, so they became one skill, which picks the kind
+ * from where the document lands. Every retired name lands on that skill, so a
+ * target citing any of them resolves after a single sweep.
  *
- * `draft-diagram` merged into `draft-figure` the same way, its architecture
+ * `draft-diagram` merged into the figure skill the same way, its architecture
  * views becoming one reference the figure skill reads. `claude-diagram` is
- * retargeted onto `draft-figure` rather than left on the retired name, for the
+ * retargeted onto the figure skill rather than left on a retired name, for the
  * same reason `claude-ui-test` was.
  *
+ * The `draft-` family then dissolved. Its seven members shared a verb rather
+ * than a phase or a role, so the prefix grouped a deck, a figure, a brand
+ * identity, a pick loop, and a thin plan under one word that said nothing
+ * about which of them a skill makes. Each took a verb-first name for its
+ * output instead: `write-doc`, `draw-figure`, `design-identity`, `make-deck`,
+ * `pick-by-eye`, `plan-ready`, and `script-screencast`. Every older key that
+ * landed on a `draft-` name is retargeted straight onto its new one, so a
+ * target on the oldest spelling lands in one pass rather than two.
+ * `draft-ready` alone keys on its namespaced forms below rather than here.
+ *
  * Every name takes two words. Ten of these would have landed as a bare single
  * word under a plain strip, and a bare word such as `review` or `docs` is a
  * substring of ordinary prose with no token left for a later sweep to find.
@@ -63,7 +72,7 @@ export const SKILL_NAME_MAP: Readonly<Record<string, string>> = {
   'claude-address-review': 'review-address',
   'claude-autoship': 'auto-ship',
   'claude-design-extract': 'design-extract',
-  'claude-diagram': 'draft-figure',
+  'claude-diagram': 'draw-figure',
   'claude-docs': 'context-fold',
   'docs-fold': 'context-fold',
   'claude-feature': 'plan-feature',
@@ -87,16 +96,22 @@ export const SKILL_NAME_MAP: Readonly<Record<string, string>> = {
   'claude-ux-measure': 'ux-measure',
   'claude-worker': 'role-worker',
   'claude-worktree': 'session-worktree',
-  'canon-screencast': 'draft-screencast',
-  'canon-slides-draft': 'draft-slides',
+  'canon-screencast': 'script-screencast',
+  'canon-slides-draft': 'make-deck',
   'canon-record': 'record-screencast',
   'canon-frames-read': 'read-frames',
-  'draft-docs': 'draft-doc',
-  'draft-context': 'draft-doc',
-  'draft-wireframes': 'draft-doc',
-  'draft-readme': 'draft-doc',
-  'draft-wiki': 'draft-doc',
-  'draft-diagram': 'draft-figure',
+  'draft-docs': 'write-doc',
+  'draft-context': 'write-doc',
+  'draft-wireframes': 'write-doc',
+  'draft-readme': 'write-doc',
+  'draft-wiki': 'write-doc',
+  'draft-diagram': 'draw-figure',
+  'draft-doc': 'write-doc',
+  'draft-figure': 'draw-figure',
+  'draft-identity': 'design-identity',
+  'draft-slides': 'make-deck',
+  'draft-and-pick': 'pick-by-eye',
+  'draft-screencast': 'script-screencast',
 }
 
 /**
@@ -110,14 +125,42 @@ export const SKILL_NAME_MAP: Readonly<Record<string, string>> = {
  * guard rejects a following `-`, so a rewritten `canon:canvas-board` is not
  * matched again.
  *
+ * `draft-ready` became `plan-ready` and takes the same treatment for a
+ * different reason. It is two words, but they are ordinary prose for a pull
+ * request moving from draft to ready, and the sweep takes no scope in a
+ * target, so a bare key would rewrite that sentence in every tracked file a
+ * project wrote.
+ *
  * What this leaves behind is a prose mention of the skill by its bare name,
  * which has no token for a sweep to find and is fixed by hand.
  */
 export const SKILL_CITATION_MAP: Readonly<Record<string, string>> = {
   'canon:canvas': 'canon:canvas-board',
   'skills/canvas': 'skills/canvas-board',
+  'canon:draft-ready': 'canon:plan-ready',
+  'skills/draft-ready': 'skills/plan-ready',
 }
 
+/**
+ * The old `draft-` names that still answer as a pointer skill, each naming the
+ * skill it became.
+ *
+ * Each pointer's own files spell the old name on purpose, so the sweep must
+ * never reach them. A later run would otherwise move the stub onto the real
+ * body at the new name. Their paths join the exclusions only once the sweep
+ * that moved the real bodies has run, since excluding them first leaves each
+ * body unmoved at its old path.
+ */
+export const RENAMED_DRAFT_POINTERS: readonly string[] = [
+  'draft-doc',
+  'draft-figure',
+  'draft-identity',
+  'draft-slides',
+  'draft-and-pick',
+  'draft-ready',
+  'draft-screencast',
+]
+
 /**
  * The skill rename.
  *
@@ -159,5 +202,9 @@ export const SKILL_NAME_RULES: RenameRules = defineRenameRules({
     'CHANGELOG.md',
     'src/migrate/skill-names.ts',
     'src/migrate/skill-names.test.ts',
+    ...RENAMED_DRAFT_POINTERS.flatMap((name) => [
+      `claude/skills/${name}/SKILL.md`,
+      `claude/skills/${name}/REQUIREMENT.md`,
+    ]),
   ],
 })

package/src/pr/frames.ts

@@ -22,6 +22,9 @@ const ADD_ATTEMPTS = 3
 /** One half of a reference address. It opens on a letter or digit and holds no separator, so `..` and `/` cannot survive it. */
 const REFERENCE_PART = /^[A-Za-z0-9][A-Za-z0-9._-]*$/
 
+/** A tracked reference, `canon/design/<surface>/<name>`, whose name may carry its `.png`. The halves are validated as a canvas address's are. */
+const DESIGN_REFERENCE = /^canon\/design\/([^/]+)\/([^/]+?)(?:\.png)?$/
+
 const FOLDER_PATTERN = /^pr-(\d+)$/
 
 const DAY_MS = 86_400_000
@@ -163,20 +166,28 @@ export function frameLink(repo: string, path: string): string {
 }
 
 /**
- * The file-name slug of a `<page>/<frame>` address, or undefined when the
+ * The file-name slug of a `<page>/<frame>` address or a tracked
+ * `canon/design/<surface>/<name>` path, or undefined when the
  * address would not round-trip. Each half must open on a letter or digit and
  * hold only letters, digits, dots, underscores, and dashes, and neither may
  * carry `--`, so the joined slug reads back as the same two names and a path
  * never gains a directory or escapes the pass folder.
  */
 export function referenceSlug(address: string): string | undefined {
-  const parts = address.split('/')
+  const tracked = DESIGN_REFERENCE.exec(address)
+  const parts = tracked ? [tracked[1], tracked[2]] : address.split('/')
   if (parts.length !== 2) return undefined
   const [page, frame] = parts as [string, string]
   const valid = [page, frame].every(
     (part) => REFERENCE_PART.test(part) && !part.includes('--'),
   )
-  return valid ? `${page}--${frame}` : undefined
+  if (!valid) return undefined
+  return tracked ? `design--${page}--${frame}` : `${page}--${frame}`
+}
+
+/** Whether a reference names a tracked `canon/design/<surface>/<name>` file rather than a `<page>/<frame>` address. */
+export function isDesignReference(address: string): boolean {
+  return DESIGN_REFERENCE.test(address)
 }
 
 /**

package/src/records/backup.ts

@@ -107,9 +107,9 @@ export const EXCLUDED_ENTRIES = [
 /**
  * Whether a top-level name stays out of every push, at either root.
  *
- * `SCRATCH` is the legacy `.tmp` spelling, which a records index opened before
- * the move can still carry and which `EXCLUDED_ENTRIES` names at its `.canon`
- * spelling only.
+ * `SCRATCH` is the retired `.tmp` spelling. It is a guard rather than a lookup,
+ * keeping a stray `.tmp` out of a push, and `EXCLUDED_ENTRIES` names the
+ * `.canon` spelling only.
  */
 function isExcluded(name: string): boolean {
   return (

package/src/records/validate.ts

@@ -208,6 +208,7 @@ const PLAN_SECTIONS = [
   'Summary',
   'Constraints',
   'Files to touch',
+  'Design references',
   'Verification',
   'Risks',
   'Review focus',
@@ -226,6 +227,22 @@ const PLAN_REQUIRED: readonly PlanSection[] = [
   'Questions',
 ]
 
+/**
+ * The files whose edit changes what a person sees, the set the `ui/a11y` and
+ * `ui/keyboard` rules glob plus the other markup and style extensions a plan
+ * names. A plan touching one owes a `Design references` section, so a set too wide forces it on every
+ * plan and one too narrow lets a UI plan skip it.
+ */
+const RENDERED_SURFACE = /\.(?:tsx|jsx|astro|vue|svelte|html|css|scss)$/
+
+export function touchesRenderedSurface(entries: readonly string[]): boolean {
+  return entries.some((entry) =>
+    [...entry.matchAll(/`([^`]+)`/g)].some((span) =>
+      RENDERED_SURFACE.test(span[1]),
+    ),
+  )
+}
+
 /**
  * A line standing alone as a bold label or an H2, whatever it names. A plan is
  * free to carry a section of its own, so the split has to see one to close the
@@ -450,6 +467,20 @@ export function checkPlan(name: string, text: string): Finding[] {
     }
   }
 
+  if (
+    !sections.has('Design references') &&
+    touchesRenderedSurface(sections.get('Files to touch') ?? [])
+  ) {
+    findings.push(
+      finding(
+        'section-missing',
+        name,
+        preferredMarker('Design references'),
+        'is required when Files to touch names a rendered-surface file. Write None identified. when no reference folder governs it.',
+      ),
+    )
+  }
+
   for (const line of sections.get('Files to touch') ?? []) {
     const trimmed = line.trim()
     if (!trimmed.startsWith('- ') || trimmed === `- ${NONE_IDENTIFIED}`)

package/src/roots/record.ts

@@ -29,17 +29,22 @@ export type RecordRoot = (typeof RECORD_ROOTS)[number]
 export const CREATION_ROOT: RecordRoot = '.canon'
 
 /**
- * The deletable scratch folder, named at the spelling `.claude/` gives it.
+ * The deletable scratch folder, named at the spelling `.claude/` gave it.
  *
- * It is the one folder whose name differs by root, and callers name it at the
- * old spelling because `spell` is the only place the variant is decided. Inside
- * a dotted root the leading dot hides nothing already hidden and costs a bare
- * `ls` that omits the folder, so the move dropped it. Every other record folder
- * keeps its name, `.records.git` included, where the dot marks the mechanism
- * apart from a payload rather than hiding it.
+ * Scratch resolves at `.canon/tmp` only. The `.claude/.tmp` spelling is a
+ * migration source, named through `LEGACY_SCRATCH_REL` by the verbs that move
+ * it, and no lookup falls back to it. Callers still name the folder at this
+ * spelling because `spell` is the only place the variant is decided. Inside a
+ * dotted root the leading dot hides nothing already hidden and costs a bare
+ * `ls` that omits the folder, so the move dropped it. Every other record
+ * folder keeps its name, `.records.git` included, where the dot marks the
+ * mechanism apart from a payload rather than hiding it.
  */
 export const SCRATCH = '.tmp'
 
+/** The retired scratch location, read only as the source of a migration. */
+export const LEGACY_SCRATCH_REL = '.claude/.tmp' // canon-keep-record-root
+
 /** The scratch folder's name under `.canon/`. */
 const CANON_SCRATCH = 'tmp'
 
@@ -109,6 +114,8 @@ export function spell(root: RecordRoot, folder: string): string {
  * records it belongs to rather than at the creation default.
  */
 function rootOf(root: string, folder: string): RecordRoot {
+  if (folder === SCRATCH) return CREATION_ROOT
+
   return (
     RECORD_ROOTS.find((candidate) =>
       existsSync(join(root, candidate, spell(candidate, folder))),
@@ -147,7 +154,9 @@ export function recordDirs(
   folder: string,
   ...rest: string[]
 ): string[] {
-  return RECORD_ROOTS.map((candidate) =>
+  const candidates = folder === SCRATCH ? [CREATION_ROOT] : RECORD_ROOTS
+
+  return candidates.map((candidate) =>
     join(root, candidate, spell(candidate, folder), ...rest),
   )
 }