@erclx/canon 4.115.0 → 4.117.0

package/src/teach/components/paragraph.tsx

@@ -4,9 +4,26 @@ import type { Child, Element } from '@/teach/html/jsx-runtime'
 export interface ParagraphProps {
   /** The lesson's dek, read back by `extractLessonMeta` in `@/teach/nav`. */
   readonly lede?: boolean
+  /** Reference numbers, each linking to the `Refs` item carrying that id. */
+  readonly cites?: readonly number[]
   readonly children: Child
 }
 
-export function Paragraph({ lede, children }: ParagraphProps): Element {
-  return lede ? <p class="lede">{children}</p> : <p>{children}</p>
+export function Paragraph({ lede, cites, children }: ParagraphProps): Element {
+  const markers = (cites ?? []).map((cite) => (
+    <sup class="cite">
+      <a href={`#r${cite}`}>{cite}</a>
+    </sup>
+  ))
+  return lede ? (
+    <p class="lede">
+      {children}
+      {markers}
+    </p>
+  ) : (
+    <p>
+      {children}
+      {markers}
+    </p>
+  )
 }

package/src/teach/components/refs.tsx

@@ -0,0 +1,28 @@
+/** @jsxImportSource ../html */
+import type { Element } from '@/teach/html/jsx-runtime'
+
+export interface Reference {
+  readonly title: string
+  readonly url?: string
+  readonly note?: string
+}
+
+export interface RefsProps {
+  readonly items: readonly Reference[]
+}
+
+/**
+ * Numbers each item from 1 so its `id` matches the `#r<n>` a cited
+ * `Paragraph` links to. The caller has already checked every `url` parses as
+ * http or https, since attribute escaping does not stop a `javascript:` href.
+ */
+export function Refs({ items }: RefsProps): Element {
+  const rendered = items.map(({ title, url, note }, index) => (
+    <li id={`r${index + 1}`}>
+      <cite>{title}</cite>
+      {note === undefined ? null : `. ${note}`}
+      {url === undefined ? null : [' ', <a href={url}>{new URL(url).host}</a>]}
+    </li>
+  ))
+  return <ol class="refs">{rendered}</ol>
+}

package/src/teach/cross-references.ts

@@ -0,0 +1,78 @@
+export interface LessonReferencesLinked {
+  readonly html: string
+  /** Four-digit numbers naming no lesson, each once, in first-seen order. */
+  readonly unresolved: readonly string[]
+}
+
+/**
+ * A mention a learner would read as pointing at another lesson. The whitespace
+ * is captured rather than normalized, since a prettier-wrapped lesson can break
+ * a mention across a line.
+ */
+const MENTION = /\b(lesson|Lesson)(\s+)(\d{4})\b/g
+
+/**
+ * A link nav wrote on an earlier run, and the only kind it may rewrite. The
+ * close tag allows whitespace before its `>`, which is how prettier wraps it.
+ */
+const OWNED_LINK = /<a\s[^>]*\bdata-lesson-ref\b[^>]*>([\s\S]*?)<\/a\s*>/g
+
+/**
+ * A comment, a raw-text element taken whole so a `<` inside a script never
+ * reads as a tag, any other tag, or the text between tags.
+ */
+const TOKEN =
+  /<!--[\s\S]*?-->|<(script|style)\b[\s\S]*?<\/\1\s*>|<\/?[a-zA-Z][^>]*>|[^<]+|</g
+
+const TAG_NAME = /^<(\/?)([a-zA-Z][a-zA-Z0-9-]*)/
+
+/**
+ * Elements whose text stays plain. A link inside a quiz `label` navigates on
+ * the click meant to pick an option, and one inside `summary` fights the
+ * toggle.
+ */
+const SKIPPED = new Set(['a', 'code', 'pre', 'label', 'summary'])
+
+/**
+ * Links every "lesson NNNN" mention in a lesson's authored region to the
+ * sibling file carrying that number, and reports the numbers naming no lesson.
+ * A link carrying `data-lesson-ref` is nav's own, so it is unwrapped and
+ * resolved again from its text, which re-points it after a slug rename and
+ * drops it once its target is gone. An author's own `<a>` is never touched.
+ */
+export function linkLessonReferences(
+  html: string,
+  targets: ReadonlyMap<string, string>,
+  current: string,
+): LessonReferencesLinked {
+  const unresolved: string[] = []
+  let depth = 0
+
+  const linkText = (text: string): string =>
+    text.replace(MENTION, (mention, word, space, number: string) => {
+      const target = targets.get(number)
+      if (target === current) return mention
+      if (target === undefined) {
+        if (!unresolved.includes(number)) unresolved.push(number)
+        return mention
+      }
+      return `<a href="${target}" data-lesson-ref>${word}${space}${number}</a>`
+    })
+
+  const unwrapped = html.replace(OWNED_LINK, (_link, text: string) => text)
+
+  const rewritten = unwrapped.replace(TOKEN, (token) => {
+    if (!token.startsWith('<') || token === '<') {
+      return depth === 0 ? linkText(token) : token
+    }
+
+    const tag = TAG_NAME.exec(token)
+    if (tag === null || !SKIPPED.has(tag[2].toLowerCase())) return token
+
+    if (tag[1] === '/') depth = Math.max(0, depth - 1)
+    else if (!token.endsWith('/>')) depth += 1
+    return token
+  })
+
+  return { html: rewritten, unresolved }
+}

package/src/teach/lesson.ts

@@ -13,7 +13,7 @@ import {
 const LESSON_WIDTH = 4
 
 /** The ordinal a lesson filename opens with, which fixes its read order. */
-const LESSON_NUMBER = /^(\d{4})-/
+export const LESSON_NUMBER = /^(\d{4})-/
 
 const LESSON_SLUG = /^[a-z0-9]+(-[a-z0-9]+)*$/
 

package/src/teach/nav.ts

@@ -10,7 +10,9 @@ import { FAVICON_COLORS, faviconLink, renderFavicon } from '@/design/favicon'
 import { stripFrontmatter } from '@/frontmatter'
 import { parseFrontmatter, readField } from '@/indexes/frontmatter'
 import { PROJECT_ROOT } from '@/project-root'
+import { linkLessonReferences } from '@/teach/cross-references'
 import { TEACH_FONT_FACES } from '@/teach/fonts'
+import { LESSON_NUMBER } from '@/teach/lesson'
 import {
   listWorkspaces,
   readWorkspace,
@@ -1306,6 +1308,7 @@ function spliceRegion(
 interface LessonRewritten {
   readonly ok: true
   readonly file: string
+  readonly unresolved: readonly string[]
 }
 
 interface LessonRefused {
@@ -1334,15 +1337,57 @@ const FOOTNAV_OPEN = '<!-- canon:teach:footnav -->'
  * alone, which keeps a second run byte-identical.
  */
 function wrapMain(html: string): string {
+  const bounds = authoredBounds(html)
+  if (bounds === undefined) return html
+
+  const body = html.slice(bounds.start, bounds.end)
+  if (/<main[\s>]/.test(body)) return html
+
+  return `${html.slice(0, bounds.start)}\n<main>\n${body.trim()}\n</main>\n${html.slice(bounds.end)}`
+}
+
+function authoredBounds(
+  html: string,
+): { readonly start: number; readonly end: number } | undefined {
   const start = html.indexOf(HEADER_CLOSE)
   const end = html.indexOf(FOOTNAV_OPEN, start)
-  if (start === -1 || end === -1) return html
+  if (start === -1 || end === -1) return undefined
+  return { start: start + HEADER_CLOSE.length, end }
+}
 
-  const bodyStart = start + HEADER_CLOSE.length
-  const body = html.slice(bodyStart, end)
-  if (/<main[\s>]/.test(body)) return html
+/** Each lesson number to the file carrying it, the first in filename order. */
+function lessonTargets(
+  lessonFiles: readonly string[],
+): ReadonlyMap<string, string> {
+  const targets = new Map<string, string>()
+  for (const file of [...lessonFiles].sort()) {
+    const number = LESSON_NUMBER.exec(file)?.[1]
+    if (number !== undefined && !targets.has(number)) targets.set(number, file)
+  }
+  return targets
+}
+
+/**
+ * Links the "lesson NNNN" mentions in the authored region, the one rewrite nav
+ * makes between the header and footnav markers besides the `<main>` wrap.
+ */
+function linkAuthoredRegion(
+  html: string,
+  targets: ReadonlyMap<string, string>,
+  file: string,
+): { readonly html: string; readonly unresolved: readonly string[] } {
+  const bounds = authoredBounds(html)
+  if (bounds === undefined) return { html, unresolved: [] }
 
-  return `${html.slice(0, bodyStart)}\n<main>\n${body.trim()}\n</main>\n${html.slice(end)}`
+  const linked = linkLessonReferences(
+    html.slice(bounds.start, bounds.end),
+    targets,
+    file,
+  )
+  return {
+    html: `${html.slice(0, bounds.start)}${linked.html}${html.slice(bounds.end)}`,
+    unresolved: linked.unresolved,
+  }
 }
 
 /**
@@ -1359,6 +1404,7 @@ async function rewriteLesson(
   metas: readonly LessonMeta[],
   workspaces: readonly WorkspaceSummary[],
   css: string,
+  targets: ReadonlyMap<string, string>,
 ): Promise<LessonRewritten | LessonRefused> {
   const file = metas[index].file
   const path = join(root, detail.path, TEACH_LESSONS, file)
@@ -1439,8 +1485,9 @@ async function rewriteLesson(
     html = spliced
   }
 
-  await writeFile(path, wrapMain(html))
-  return { ok: true, file }
+  const linked = linkAuthoredRegion(wrapMain(html), targets, file)
+  await writeFile(path, linked.html)
+  return { ok: true, file, unresolved: linked.unresolved }
 }
 
 export interface LessonSkipped {
@@ -1461,6 +1508,17 @@ export interface NavGenerated {
    * reference page left unrendered on a Bun carrying no markdown renderer.
    */
   readonly skipped: readonly LessonSkipped[]
+  /**
+   * A "lesson NNNN" mention naming no lesson in its workspace, one per distinct
+   * number per lesson. The lesson still rewrote, so it counts in `lessons`.
+   */
+  readonly unresolved: readonly LessonReferenceUnresolved[]
+}
+
+export interface LessonReferenceUnresolved {
+  /** Relative to the root, the way a `skipped` entry is. */
+  readonly file: string
+  readonly lesson: string
 }
 
 const MARKDOWN_RENDERER = 'Bun.markdown'
@@ -1512,6 +1570,7 @@ export async function generateNav(
 
   const contents: string[] = []
   const skipped: LessonSkipped[] = []
+  const unresolved: LessonReferenceUnresolved[] = []
   let lessons = 0
   let reference = 0
   const canRenderMarkdown = hasMarkdownRenderer()
@@ -1555,6 +1614,7 @@ export async function generateNav(
     await removeOrphanReferencePages(root, detail)
 
     const css = stripImports(await readFile(cssPath, 'utf8'))
+    const targets = lessonTargets(detail.lessonFiles)
 
     for (let index = 0; index < metas.length; index += 1) {
       const outcome = await rewriteLesson(
@@ -1564,10 +1624,17 @@ export async function generateNav(
         metas,
         listed.workspaces,
         css,
+        targets,
       )
 
       if (outcome.ok) {
         lessons += 1
+        for (const lesson of outcome.unresolved) {
+          unresolved.push({
+            file: join(detail.path, TEACH_LESSONS, outcome.file),
+            lesson,
+          })
+        }
       } else {
         skipped.push({
           file: join(detail.path, TEACH_LESSONS, outcome.file),
@@ -1584,5 +1651,6 @@ export async function generateNav(
     lessons,
     reference,
     skipped,
+    unresolved,
   }
 }

package/src/teach/render.ts

@@ -1,6 +1,7 @@
 import { Heading } from '@/teach/components/heading'
 import { List } from '@/teach/components/list'
 import { Paragraph } from '@/teach/components/paragraph'
+import { type Reference, Refs } from '@/teach/components/refs'
 import { render } from '@/teach/html/jsx-runtime'
 import type { TeachRefused } from '@/teach/workspace'
 
@@ -10,12 +11,14 @@ export type LessonBlock =
       readonly type: 'paragraph'
       readonly text: string
       readonly lede?: boolean
+      readonly cites?: readonly number[]
     }
   | {
       readonly type: 'list'
       readonly items: readonly string[]
       readonly ordered?: boolean
     }
+  | { readonly type: 'refs'; readonly items: readonly Reference[] }
   | { readonly type: 'raw'; readonly html: string }
 
 export interface RenderRendered {
@@ -25,7 +28,9 @@ export interface RenderRendered {
 
 export type RenderOutcome = RenderRendered | TeachRefused
 
-const BLOCK_TYPES = ['heading', 'paragraph', 'list', 'raw'] as const
+const BLOCK_TYPES = ['heading', 'paragraph', 'list', 'refs', 'raw'] as const
+
+const LINK_PROTOCOLS = new Set(['http:', 'https:'])
 
 function isBlockType(value: unknown): value is LessonBlock['type'] {
   return (BLOCK_TYPES as readonly string[]).includes(value as string)
@@ -48,10 +53,46 @@ function isStringArray(value: unknown): value is readonly string[] {
   return Array.isArray(value) && value.every(isString)
 }
 
+function isCiteArray(value: unknown): value is readonly number[] {
+  return (
+    Array.isArray(value) &&
+    value.length > 0 &&
+    value.every((cite) => Number.isInteger(cite) && cite > 0)
+  )
+}
+
+function isLinkUrl(value: string): boolean {
+  if (!URL.canParse(value)) return false
+  return LINK_PROTOCOLS.has(new URL(value).protocol)
+}
+
+function readReference(item: unknown, position: number): Reference | string {
+  if (typeof item !== 'object' || item === null) {
+    return `reference ${position} is not an object`
+  }
+  const { title, url, note } = item as Record<string, unknown>
+  if (!isString(title) || title === '') {
+    return `reference ${position} needs a non-empty string title`
+  }
+  if (note !== undefined && !isString(note)) {
+    return `reference ${position} note must be a string`
+  }
+  if (url !== undefined && !(isString(url) && isLinkUrl(url))) {
+    return `reference ${position} url must be an http or https URL`
+  }
+  return { title, url, note }
+}
+
+interface RenderedBlock {
+  readonly html: string
+  readonly cites?: readonly number[]
+  readonly referenceCount?: number
+}
+
 function renderBlock(
   block: unknown,
   index: number,
-): { readonly html: string } | TeachRefused {
+): RenderedBlock | TeachRefused {
   if (typeof block !== 'object' || block === null || !('type' in block)) {
     return badBlock(index, 'not an object carrying a type')
   }
@@ -83,8 +124,24 @@ function renderBlock(
       if (fields.lede !== undefined && typeof fields.lede !== 'boolean') {
         return badBlock(index, 'paragraph lede must be a boolean')
       }
+      if (fields.cites !== undefined && !isCiteArray(fields.cites)) {
+        return badBlock(
+          index,
+          'paragraph cites must be a non-empty array of positive integers',
+        )
+      }
+      if (fields.lede === true && fields.cites !== undefined) {
+        return badBlock(index, 'a lede paragraph cannot carry cites')
+      }
       return {
-        html: render(Paragraph({ lede: fields.lede, children: fields.text })),
+        html: render(
+          Paragraph({
+            lede: fields.lede,
+            cites: fields.cites,
+            children: fields.text,
+          }),
+        ),
+        cites: fields.cites,
       }
     }
     case 'list': {
@@ -98,6 +155,21 @@ function renderBlock(
         html: render(List({ ordered: fields.ordered, items: fields.items })),
       }
     }
+    case 'refs': {
+      if (!Array.isArray(fields.items) || fields.items.length === 0) {
+        return badBlock(index, 'refs needs a non-empty items array')
+      }
+      const items: Reference[] = []
+      for (const [position, item] of fields.items.entries()) {
+        const reference = readReference(item, position + 1)
+        if (isString(reference)) return badBlock(index, reference)
+        items.push(reference)
+      }
+      return {
+        html: render(Refs({ items })),
+        referenceCount: items.length,
+      }
+    }
     case 'raw': {
       if (!isString(fields.html)) {
         return badBlock(index, 'raw needs a string html')
@@ -112,15 +184,31 @@ function renderBlock(
  * `lesson.test.tsx` composes as JSX, so a real lesson and the component test
  * share one rendering mechanism. Every block past the first refusal
  * goes unread, matching how a malformed JSON parse refuses the whole call.
+ * Citations resolve across blocks once every block has rendered, so a marker
+ * with no reference refuses rather than leaving a dead anchor.
  */
 export function renderLessonBody(blocks: readonly unknown[]): RenderOutcome {
-  const rendered: string[] = []
+  const rendered: RenderedBlock[] = []
+  let referenceCount = 0
 
   for (const [index, block] of blocks.entries()) {
     const result = renderBlock(block, index)
     if ('ok' in result) return result
-    rendered.push(result.html)
+    if (result.referenceCount !== undefined) {
+      if (referenceCount > 0) {
+        return badBlock(index, 'a lesson carries one refs block')
+      }
+      referenceCount = result.referenceCount
+    }
+    rendered.push(result)
+  }
+
+  for (const [index, block] of rendered.entries()) {
+    const dangling = block.cites?.find((cite) => cite > referenceCount)
+    if (dangling !== undefined) {
+      return badBlock(index, `cite ${dangling} resolves to no reference`)
+    }
   }
 
-  return { ok: true, html: rendered.join('\n') }
+  return { ok: true, html: rendered.map((block) => block.html).join('\n') }
 }

package/src/tooling/inject.ts

@@ -6,7 +6,12 @@ import { copyPreservingMode } from '@/copy'
 import { rewritesOnInstall, stripSeedMarker } from '@/seed-marker'
 import { resolveSurfacePath } from '@/surface-root'
 import { mergeSections, pruneSections } from '@/tooling/gitignore'
-import { ancestorsFirst, listFiles, type Manifest } from '@/tooling/manifest'
+import {
+  ancestorsFirst,
+  configPaths,
+  listFiles,
+  type Manifest,
+} from '@/tooling/manifest'
 import {
   applyScripts,
   collectDeps,
@@ -97,9 +102,14 @@ export async function injectSeeds(
   target: string,
 ): Promise<string[]> {
   const applied: string[] = []
+  const isSubfolder = isSubfolderTarget(target)
+  const shadowed = configPaths(chain)
 
   for (const manifest of ancestorsFirst(chain)) {
-    const files = listFiles(manifest.seedsDir)
+    const files = listFiles(manifest.seedsDir).filter(
+      (rel) =>
+        !shadowed.has(rel) && !(isSubfolder && isWithheldInSubfolder(rel)),
+    )
     if (files.length === 0) continue
 
     logStep(`Applying ${manifest.name} seeds`)
@@ -111,9 +121,7 @@ export async function injectSeeds(
     }
   }
 
-  const spellConfig = isSubfolderTarget(target)
-    ? subfolderSpellConfig(chain)
-    : undefined
+  const spellConfig = isSubfolder ? subfolderSpellConfig(chain) : undefined
   if (spellConfig !== undefined && !hasSpellConfig(target)) {
     logStep('Applying subfolder spell config')
     await writeFile(join(target, SUBFOLDER_SPELL_CONFIG), spellConfig)

package/src/tooling/manifest.ts

@@ -44,6 +44,15 @@ export function listFiles(dir: string): string[] {
   ].sort()
 }
 
+/**
+ * Every path any stack in the chain ships as a config. A seed at one of these
+ * paths is shadowed, since the config overwrites it on every sync. `scan` and
+ * `injectSeeds` both read this, so the report and the write cannot disagree.
+ */
+export function configPaths(chain: readonly Manifest[]): Set<string> {
+  return new Set(chain.flatMap((manifest) => listFiles(manifest.configsDir)))
+}
+
 /**
  * Reverses a chain so the furthest ancestor is applied first and nearer
  * stacks overwrite it.

package/src/tooling/scan.ts

@@ -2,7 +2,12 @@ import { existsSync, readFileSync } from 'node:fs'
 import { join } from 'node:path'
 import { resolveSurfacePath } from '@/surface-root'
 import { mergeSections } from '@/tooling/gitignore'
-import { ancestorsFirst, listFiles, type Manifest } from '@/tooling/manifest'
+import {
+  ancestorsFirst,
+  configPaths,
+  listFiles,
+  type Manifest,
+} from '@/tooling/manifest'
 import {
   collectDeps,
   collectScripts,
@@ -63,10 +68,13 @@ function isIdentical(a: string, b: string): boolean {
  * stack first, while dependencies and gitignore entries resolve from the
  * furthest ancestor inward.
  *
- * A target below its git toplevel is scanned as a subfolder: a path GitHub
- * reads only at the root moves to `withheld` and counts as no change, and the
- * nested spell config joins the seeds. The scope is read here so every caller
- * of `scan` agrees without passing a flag.
+ * A seed at a path the chain also ships as a config is left to the config,
+ * so the path is reported once.
+ *
+ * A target below its git toplevel is scanned as a subfolder: a config or seed
+ * GitHub reads only at the root moves to `withheld` and counts as no change,
+ * and the nested spell config joins the seeds. The scope is read here so every
+ * caller of `scan` agrees without passing a flag.
  */
 export function scan(chain: readonly Manifest[], target: string): ScanResult {
   const isSubfolder = isSubfolderTarget(target)
@@ -98,13 +106,22 @@ export function scan(chain: readonly Manifest[], target: string): ScanResult {
   }
 
   const seeds: SeedState[] = []
-  const seenSeeds = new Set<string>()
+  const seenSeeds = configPaths(chain)
 
   for (const manifest of chain) {
     for (const rel of listFiles(manifest.seedsDir)) {
       if (seenSeeds.has(rel)) continue
       seenSeeds.add(rel)
 
+      if (isSubfolder && isWithheldInSubfolder(rel)) {
+        withheld.push({
+          rel,
+          stack: manifest.name,
+          present: existsSync(join(target, rel)),
+        })
+        continue
+      }
+
       seeds.push({
         rel,
         state: existsSync(resolveSurfacePath(target, rel))

package/src/tooling/subfolder.ts

@@ -50,9 +50,9 @@ export function subfolderPath(target: string): string | undefined {
 
 /**
  * GitHub reads workflows only at the repository root, so a `.github/` copied
- * into a subfolder is a file nothing runs. `scan` and `injectConfigs` both
- * read this, so the set the diff withholds and the set the sync skips cannot
- * disagree.
+ * into a subfolder is a file nothing runs. `scan`, `injectConfigs`, and
+ * `injectSeeds` all read this, so the set the diff withholds and the set the
+ * sync skips cannot disagree, whether the path ships as a config or a seed.
  */
 export function isWithheldInSubfolder(rel: string): boolean {
   return rel.startsWith(WITHHELD_PREFIX)

package/standards/context.md

@@ -105,8 +105,8 @@ Only the `development` entry carries this section. It is not a general-purpose h
 
 ## Length
 
-- Aim for one entry per domain. There is no hard cap. Length is a symptom, not the defect.
-- Past roughly 150 rendered lines, check three things before adding more: whether the entry still covers a single domain, whether it has filled with content `ls` or `--help` reproduces, and whether it has accumulated the history of its own changes. Fix whichever is true rather than trimming to hit a number. Rendered lines count as `markdown.md` defines them.
+- Aim for one entry per domain. Length is a symptom, not the defect, and the one hard cap is the whole-document ceiling `markdown.md` states.
+- Past roughly 150 rendered lines, check three things before adding more: whether the entry still covers a single domain, whether it has filled with content `ls` or `--help` reproduces, and whether it has accumulated the history of its own changes. Fix whichever is true rather than trimming to hit a number. The 150 is a diagnostic checkpoint and never gates. Rendered lines count as `markdown.md` defines them.
 - Never cut a `## Decisions` or `## Gotchas` entry to shorten a file. Cut a `## Layout` or `## CLI` section instead.
 - 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.

package/standards/markdown.md

@@ -32,6 +32,8 @@ Does not govern:
 - Proper nouns and product names retain their casing in headings
 - Past roughly 40 rendered lines with no heading of any level breaking them, add a subheading at the seam. Measure the longest such run rather than everything under one `##`, and exclude fenced code blocks. The number is a checkpoint, not a cap.
 - Count rendered lines rather than source lines, wrapping each source line at 80 columns and summing the heights. Source lines undercount a file authored one line per bullet, where a block of fifteen paragraph-bullets occupies fifteen lines and renders past sixty. A checkpoint another standard states counts the same unit, so a file measured one way never sits beside a run measured another.
+- Keep a whole document at or under 300 rendered lines, counted over the full source with frontmatter and fenced blocks included, since a session pays for every line it loads. This one is a ceiling rather than a checkpoint. `canon markdown audit` lists every document past it without failing the run, and a gate stage reads the same number, so whether a push fails on it is the project's gate to decide. Split the document at a seam rather than compressing it.
+- Exempt a file named `CHANGELOG.md`, which a release tool rewrites, and a document carrying `<!-- canon-length-exempt: <reason> -->` on a line of its own outside a fenced block. A marker naming no reason exempts nothing.
 - Exempt a block whose lines are all list items at one level averaging under roughly 130 characters. A flat list of short peers is already navigable, and a subheading dropped into it splits a set that belongs together. Bullet count says nothing on its own, since a catalog of one-liners and a stack of paragraphs reach the same count and read nothing alike, so weight is what decides.
 - Mixing prose with that list, or nesting levels inside it, ends the exemption at any weight.
 - Exempt a block whose lines are all table rows, at any length. The peer list above is exempt because it is already navigable, and a table because the remedy does not exist: a subheading dropped inside one splits the table rather than the run, so no edit short of rewriting it as a list clears the checkpoint.

package/standards/skill.md

@@ -180,6 +180,7 @@ Without this skill, a session <observed failure>, <observed failure>.
 - Contain only behavioral rules (what to do, what not to do) and pointers to reference docs. Narrative descriptions of what files are or how the system works belong in `docs/`, not in the skill body.
 - State rules, not inventories. Reference docs for lists that change, and phrase a rule as a ban on the forbidden shape rather than an enumeration of allowed options, so it stays stable as categories change.
 - Cut any rule that resists crisp one-line phrasing. Vague guidance is worse than none.
+- State the current rule only, in the body and in every file under `references/`. The incident and the date that earned a rule go in `REQUIREMENT.md` under `Gap`, or stay in git. A date inside a fence or a code span is example data and stays. `canon claude skills audit` names every other ISO date.
 - Group bullets under H2 headings by domain concern. Keep dos and don'ts together under the topic they belong to rather than splitting them into flat rules and constraints sections.
 - One actionable constraint per bullet. Prefer the `X over Y` form for preferences.
 - Do not include code examples unless a one to three line inline snippet captures a pattern the model cannot infer.

package/tooling/base/reference.md

@@ -15,8 +15,6 @@ Golden config files live in `tooling/base/configs/` and are copied into the targ
 - `.editorconfig`: `root = true`, with an `[*.sh]` block setting `indent_style = space` and `indent_size = 2`.
 - `commitlint.config.js`: ESM default export extending `@commitlint/config-conventional`. Rules are `header-max-length: 72`, `scope-case: lower-case`, `subject-full-stop: never`, and `subject-case` disabled.
 - `.husky/`: `pre-commit`, `commit-msg`, `pre-push`, `post-merge`, `post-rewrite`.
-- `.github/workflows/verify.yml`: runs on pull requests targeting `main` and on `workflow_dispatch`.
-- `.github/pull_request_template.md`: `## Summary`, `## Key Changes`, `## Technical Context`, `## Testing`.
 - `.vscode/extensions.json` and `.vscode/settings.json`: editor wiring for Prettier, cspell, shfmt, and shellcheck.
 - `scripts/verify.sh`: the maintenance entry point behind `check`.
 
@@ -28,6 +26,8 @@ Seeds live in `tooling/base/seeds/`. Sync drops each once on first install and n
 - `.cspell/project-terms.txt` and `.cspell/tech-stack.txt`: one word per line, sorted alphabetically.
 - `.lintstagedrc`: the glob map below.
 - `.prettierignore`: created empty. Projects add their own entries.
+- `.github/workflows/verify.yml`: runs on pull requests targeting `main` and on `workflow_dispatch`. A project with more than one language root adds its own jobs here.
+- `.github/pull_request_template.md`: `## Summary`, `## Key Changes`, `## Technical Context`, `## Testing`. A project adds the checklist lines its own review needs.
 - `canon/context/`: extend the `ci` and `development` entries with project-specific commands, workflows, or deploy steps. Canonical rationale stays in this reference.
 
 ## Tool pairing