@erclx/canon 5.42.0 → 5.44.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,35 @@ 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/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',
@@ -301,6 +310,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/session-defaults.ts

@@ -0,0 +1,138 @@
+/**
+ * Adds the session defaults the seeded `.claude/settings.json` carries to a
+ * target that was seeded before them.
+ *
+ * `canon claude init` copies a seed only when the file is absent, so a target
+ * holding its own settings never sees a later seed change. This verb adds each
+ * default only where the key is absent: a deny entry is never removed, and a
+ * person's `autoMemoryEnabled: true` is never overwritten.
+ */
+
+import { existsSync } from 'node:fs'
+import { join } from 'node:path'
+import {
+  readSettings,
+  type SettingsKey,
+  type SettingsRecord,
+  serializeSettings,
+  writeSettings,
+} from '@/claude/settings'
+
+/** Both names, since `Task` is the tool's name before Claude Code renamed it. */
+export const DENIED_TOOLS: readonly string[] = ['Agent', 'Task']
+
+export interface SessionDefaultsPlan {
+  readonly keys: readonly SettingsKey[]
+  readonly next: SettingsRecord
+  readonly changed: boolean
+  /**
+   * True when the file holds no default at all. A file holding either one has
+   * been through the seed or this verb, so a missing deny there was removed
+   * on purpose, which is how an operator opts back into subagents.
+   */
+  readonly predates: boolean
+}
+
+export type SessionDefaultsRead =
+  | { readonly kind: 'refused'; readonly reason: string }
+  | { readonly kind: 'absent'; readonly path: string }
+  | {
+      readonly kind: 'planned'
+      readonly path: string
+      readonly indent: string
+      readonly plan: SessionDefaultsPlan
+    }
+
+export function settingsPath(root: string): string {
+  return join(root, '.claude', 'settings.json')
+}
+
+function isRecord(value: unknown): value is SettingsRecord {
+  return typeof value === 'object' && value !== null && !Array.isArray(value)
+}
+
+/**
+ * Appends the denied tools a list lacks, keeping the list's own order, so the
+ * diff a person reads is the added entries alone.
+ */
+export function planSessionDefaults(
+  current: SettingsRecord,
+): SessionDefaultsPlan {
+  const next: SettingsRecord = { ...current }
+  const permissions = isRecord(current.permissions) ? current.permissions : {}
+  const deny = Array.isArray(permissions.deny) ? permissions.deny : []
+
+  const missing = DENIED_TOOLS.filter((tool) => !deny.includes(tool))
+  if (missing.length > 0) {
+    next.permissions = { ...permissions, deny: [...deny, ...missing] }
+  }
+
+  const memoryAbsent = !('autoMemoryEnabled' in current)
+  if (memoryAbsent) next.autoMemoryEnabled = false
+
+  const keys: SettingsKey[] = [
+    { label: 'permissions.deny', changed: missing.length > 0 },
+    { label: 'autoMemoryEnabled', changed: memoryAbsent },
+  ]
+  return {
+    keys,
+    next,
+    changed: keys.some((key) => key.changed),
+    predates: memoryAbsent && missing.length === DENIED_TOOLS.length,
+  }
+}
+
+/**
+ * Refuses rather than plans whenever a write could replace something the
+ * person owns: the toolkit's own settings, a file `JSON.parse` cannot read,
+ * or a `permissions` or `deny` value of an unexpected shape.
+ */
+export async function readSessionDefaults(
+  root: string,
+  protectedRoot: string,
+): Promise<SessionDefaultsRead> {
+  if (root === protectedRoot) {
+    return {
+      kind: 'refused',
+      reason:
+        'Cannot run against toolkit root. Files here are the source of truth.',
+    }
+  }
+
+  const path = settingsPath(root)
+  if (!existsSync(path)) return { kind: 'absent', path }
+
+  let read: Awaited<ReturnType<typeof readSettings>>
+  try {
+    read = await readSettings(path)
+  } catch (error) {
+    return {
+      kind: 'refused',
+      reason: error instanceof Error ? error.message : String(error),
+    }
+  }
+
+  const { permissions } = read.value
+  if (permissions !== undefined && !isRecord(permissions)) {
+    return { kind: 'refused', reason: `${path}: permissions is not an object` }
+  }
+  if (permissions?.deny !== undefined && !Array.isArray(permissions.deny)) {
+    return {
+      kind: 'refused',
+      reason: `${path}: permissions.deny is not a list`,
+    }
+  }
+
+  return {
+    kind: 'planned',
+    path,
+    indent: read.indent,
+    plan: planSessionDefaults(read.value),
+  }
+}
+
+export async function applySessionDefaults(
+  read: Extract<SessionDefaultsRead, { kind: 'planned' }>,
+): Promise<void> {
+  await writeSettings(read.path, serializeSettings(read.plan.next, read.indent))
+}

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/pr/local.ts

@@ -1,26 +1,11 @@
+import { belongsTo } from '@/listeners/belongs'
+import type { ListenerReader } from '@/listeners/machine'
 import { readAddresses } from '@/pr/evidence'
 
-/**
- * The folder linked worktrees sit under. A listener there belongs to another
- * branch even though its cwd sits inside the main checkout's toplevel.
- */
-const LINKED_WORKTREES = '.claude/worktrees'
-
-/** The state `/proc/net/tcp` writes for a socket in LISTEN. */
-const PROC_LISTEN_STATE = '0A'
-
 export type LocalRefusal = 'no-server' | 'no-listener-reader'
 
-export interface Listener {
-  readonly port: number
-  readonly pid: number
-}
-
-/** The machine reads a detection makes, injected so it can be driven without binding a socket. */
-export interface LocalRunner {
-  /** Every TCP socket in LISTEN with its owning pid, or undefined when this machine offers no way to read them. */
-  listListeners(): Promise<readonly Listener[] | undefined>
-  cwdOf(pid: number): Promise<string | undefined>
+/** The listener reads a detection makes plus an HTML probe, injected so it can be driven without binding a socket. */
+export interface LocalRunner extends ListenerReader {
   /** Whether the port serves an HTML page at its root inside the runner's timeout. */
   probe(port: number): Promise<boolean>
 }
@@ -29,22 +14,6 @@ export type LocalResult =
   | { readonly kind: 'found'; readonly port: number; readonly url: string }
   | { readonly kind: 'refused'; readonly reason: LocalRefusal }
 
-function isInside(path: string, root: string): boolean {
-  return path === root || path.startsWith(`${root}/`)
-}
-
-/**
- * Whether a process running in `cwd` serves this worktree. A tool that
- * changes into a subfolder before listening still counts, while a sibling
- * worktree nested under the main checkout's `.claude/worktrees/` does not.
- */
-function belongsTo(cwd: string, worktreeRoot: string): boolean {
-  return (
-    isInside(cwd, worktreeRoot) &&
-    !isInside(cwd, `${worktreeRoot}/${LINKED_WORKTREES}`)
-  )
-}
-
 /**
  * Finds the server this worktree is running: the lowest port whose listening
  * process runs inside the worktree and answers an HTTP probe. A port rather
@@ -76,40 +45,6 @@ export async function findLocalServer(
   return { kind: 'refused', reason: 'no-server' }
 }
 
-/** Reads `lsof -nP -iTCP -sTCP:LISTEN -Fpn` output, where a `p` line opens a process and each `n` line names one of its sockets. */
-export function parseLsofListeners(text: string): Listener[] {
-  const listeners: Listener[] = []
-  let pid: number | undefined
-  for (const line of text.split('\n')) {
-    if (line.startsWith('p')) pid = Number(line.slice(1))
-    if (!line.startsWith('n') || pid === undefined) continue
-    const port = Number(line.slice(line.lastIndexOf(':') + 1))
-    if (Number.isInteger(port) && port > 0) listeners.push({ pid, port })
-  }
-  return listeners
-}
-
-export interface ProcSocket {
-  readonly port: number
-  readonly inode: string
-}
-
-/** Reads `/proc/net/tcp` or `tcp6`, keeping each listening socket's port and inode for matching against `/proc/<pid>/fd`. */
-export function parseProcNetTcp(text: string): ProcSocket[] {
-  const sockets: ProcSocket[] = []
-  for (const line of text.split('\n').slice(1)) {
-    const fields = line.trim().split(/\s+/)
-    const local = fields[1]
-    const state = fields[3]
-    const inode = fields[9]
-    if (local === undefined || inode === undefined) continue
-    if (state !== PROC_LISTEN_STATE) continue
-    const port = Number.parseInt(local.slice(local.lastIndexOf(':') + 1), 16)
-    if (Number.isInteger(port) && port > 0) sockets.push({ port, inode })
-  }
-  return sockets
-}
-
 /**
  * Drops the address line of a marked body, hosted and local segments alike,
  * since the close that runs this also deletes the branch's preview

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` rule
+ * globs 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/sync/check.ts

@@ -38,6 +38,7 @@ import {
   resolveChain,
 } from '@/tooling/manifest'
 import { scan } from '@/tooling/scan'
+import { isAddOn } from '@/tooling/stamp'
 import { readSkew, type SkewReport } from '@/version/skew'
 
 /**
@@ -302,6 +303,20 @@ export function buildToolingReport(
 function resolveRecorded(
   toolkitRoot: string,
   recorded: readonly string[],
+): Manifest[] {
+  const addOns = recorded
+    .map((name) => loadManifest(toolkitRoot, name))
+    .filter((manifest) => manifest !== undefined)
+    .filter(isAddOn)
+  const addOnNames = new Set(addOns.map((manifest) => manifest.name))
+  const core = recorded.filter((name) => !addOnNames.has(name))
+
+  return [...resolveCore(toolkitRoot, core), ...addOns]
+}
+
+function resolveCore(
+  toolkitRoot: string,
+  recorded: readonly string[],
 ): Manifest[] {
   const loaded = recorded
     .map((name) => loadManifest(toolkitRoot, name))