@erclx/canon 5.49.0 → 5.50.0

package/src/markdown/scope.ts

@@ -1,4 +1,9 @@
-import type { DensityKind } from '@/markdown/density'
+import {
+  type DensityFinding,
+  type DensityKind,
+  densityFindings,
+} from '@/markdown/density'
+import type { BodyLine } from '@/markdown/scan'
 
 /** The surfaces the retired bullet-stacks stage held, per `ALWAYS_GATED`. */
 const BULLET_RUN_SCOPE = [
@@ -21,11 +26,12 @@ const REQUIREMENT_SCOPE =
  * 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 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.
+ * Rules stay out, since a rule is one imperative per bullet, and so does every
+ * `CLAUDE.md` section but Key paths, which `KEY_PATHS_SCOPE` holds. So do 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,
@@ -36,10 +42,49 @@ const DENSITY_SCOPE = [
   /^(?:README|CONTRIBUTING)\.md$/,
 ]
 
+/**
+ * The root `CLAUDE.md` and its seed, measured inside `## Key paths` alone. That
+ * section is a catalog rather than rules, so it takes the run limit and the H3
+ * opening a grouped catalog needs, and nothing else a rule would breach.
+ */
+const KEY_PATHS_SCOPE = /^(?:tooling\/claude\/seeds\/)?CLAUDE\.md$/
+const KEY_PATHS_HEADING = /^## Key paths\s*$/
+const KEY_PATHS_KINDS: readonly DensityKind[] = ['bullet-run', 'h3-opening']
+
+/** The lines under `## Key paths` up to the next H1 or H2, keeping their numbers. */
+function keyPathsSection(lines: readonly BodyLine[]): readonly BodyLine[] {
+  const start = lines.findIndex(
+    (line) => !line.fenced && KEY_PATHS_HEADING.test(line.text),
+  )
+  if (start === -1) return []
+  const rest = lines.slice(start + 1)
+  const end = rest.findIndex(
+    (line) => !line.fenced && /^#{1,2}\s/.test(line.text),
+  )
+  return end === -1 ? rest : rest.slice(0, end)
+}
+
+/**
+ * The density findings a path takes, being every finding on a density-scope
+ * file and the Key paths findings on a `CLAUDE.md`. The audit, the init probe,
+ * and `canon claude sync` all read this, so the three agree on what counts.
+ */
+export function scopedDensityFindings(
+  rel: string,
+  lines: readonly BodyLine[],
+): DensityFinding[] {
+  if (inDensityScope(rel)) return densityFindings(lines)
+  if (!KEY_PATHS_SCOPE.test(rel)) return []
+  return densityFindings(keyPathsSection(lines)).filter((finding) =>
+    KEY_PATHS_KINDS.includes(finding.kind),
+  )
+}
+
 /**
  * The roots `canon init` gates in a new project when each passes at init time:
- * every density surface a target authors itself, leaving out the toolkit's own
- * `claude/skills/` and `tooling/` trees.
+ * every density surface a target authors itself and the Key paths of its
+ * `CLAUDE.md`, leaving out the toolkit's own `claude/skills/` and `tooling/`
+ * trees.
  */
 export const GATED_SCOPE_ROOTS: readonly string[] = [
   'canon/context/',
@@ -48,6 +93,7 @@ export const GATED_SCOPE_ROOTS: readonly string[] = [
   'wiki/',
   'README.md',
   'CONTRIBUTING.md',
+  'CLAUDE.md',
 ]
 
 /**
@@ -93,7 +139,6 @@ export const GATED_PATHS: readonly string[] = [
   'claude/skills/canvas-board/REQUIREMENT.md',
   'claude/skills/canvas-board/SKILL.md',
   'claude/skills/canvas-board/references/canvas.md',
-  'claude/skills/canvas-board/references/design.md',
   'claude/skills/ci-workflow/REQUIREMENT.md',
   'claude/skills/ci-workflow/SKILL.md',
   'claude/skills/ci-workflow/references/workflows.md',
@@ -133,6 +178,10 @@ export const GATED_PATHS: readonly string[] = [
   'claude/skills/deprecation-migration/REQUIREMENT.md',
   'claude/skills/deprecation-migration/SKILL.md',
   'claude/skills/deprecation-migration/references/adopted.md',
+  'claude/skills/design-record/REQUIREMENT.md',
+  'claude/skills/design-record/SKILL.md',
+  'claude/skills/design-record/references/design.md',
+  'claude/skills/design-record/references/folder.md',
   'claude/skills/design-taste/REQUIREMENT.md',
   'claude/skills/design-taste/SKILL.md',
   'claude/skills/design-taste/references/adopted.md',
@@ -394,6 +443,7 @@ export const GATED_PATHS: readonly string[] = [
   'wiki/',
   'README.md',
   'CONTRIBUTING.md',
+  'CLAUDE.md',
 ]
 
 /**
@@ -425,7 +475,7 @@ export function densityGates(
   gated: readonly string[] = GATED_PATHS,
   alwaysGated = true,
 ): boolean {
-  if (!inDensityScope(rel)) return false
+  if (!inDensityScope(rel) && !KEY_PATHS_SCOPE.test(rel)) return false
   if (REQUIREMENT_SCOPE.test(rel)) return gated.includes(rel)
   if (
     alwaysGated &&

package/src/markdown/structure.ts

@@ -67,7 +67,7 @@ const MARKER_WIDTH = 20
 
 export const LIST_ITEM = /^(\s*)([-*+]|\d+\.)\s+/
 export const TABLE_ROW = /^\s*\|/
-const TABLE_SEPARATOR = /^\s*\|[\s:|-]+\|\s*$/
+export const TABLE_SEPARATOR = /^\s*\|[\s:|-]+\|\s*$/
 export const BLOCKQUOTE = /^\s*>/
 
 /**

package/src/markdown/tables.ts

@@ -0,0 +1,150 @@
+import { type BodyLine, visibleText } from '@/markdown/scan'
+import { LIST_ITEM, TABLE_ROW, TABLE_SEPARATOR } from '@/markdown/structure'
+
+/** The most visible characters one table cell may hold. */
+export const TABLE_CELL = 120
+
+/** The most body rows a table may carry before it splits into groups. */
+export const TABLE_ROWS = 8
+
+/** The longest unbroken run a code span in a table cell may carry. */
+export const TABLE_TOKEN = 30
+
+export type TableKind =
+  | 'table-cell'
+  | 'table-rows'
+  | 'table-then-list'
+  | 'table-token'
+
+export interface TableFinding {
+  readonly kind: TableKind
+  /** The row holding the cell or span, the header for a row count, or the list's first item. */
+  readonly line: number
+  /** What was measured, or null for a trailing list, which is a shape rather than a count. */
+  readonly value: number | null
+  readonly limit: number | null
+}
+
+/**
+ * The body of every code span in a cell, read after link destinations are
+ * dropped, since only a link's label renders.
+ */
+export function codeSpans(cell: string): string[] {
+  return (cell.replace(/\]\([^)]*\)/g, ']').match(/`[^`]+`/g) ?? []).map(
+    (span) => span.slice(1, -1),
+  )
+}
+
+/**
+ * The longest whitespace-free run in a code span. A preview also breaks a span
+ * after a hyphen or a slash, but a run this long still splits mid-token or
+ * widens its column, so whitespace is the break this counts.
+ */
+export function unbrokenRun(span: string): number {
+  return Math.max(...span.split(/\s+/).map((part) => part.length))
+}
+
+/** Splits a row on its unescaped pipes, dropping the outer two. */
+function cellsOf(row: string): string[] {
+  return row
+    .trim()
+    .replace(/^\|/, '')
+    .replace(/(?<!\\)\|$/, '')
+    .split(/(?<!\\)\|/)
+    .map((cell) => cell.trim().replaceAll('\\|', '|'))
+}
+
+/**
+ * Every breach of the four table limits, in line order.
+ *
+ * A table is a run of pipe rows whose second row is a delimiter, the shape a
+ * renderer draws. Pipe lines with no delimiter render as paragraph text, and a
+ * fenced line is an example, so neither is measured. The limits are a
+ * 120-character cell, 8 body rows, a list as the next block, and a code span
+ * holding a run past 30 characters. Every finding reports and none gates.
+ */
+export function tableFindings(lines: readonly BodyLine[]): TableFinding[] {
+  const found: TableFinding[] = []
+  let index = 0
+
+  while (index < lines.length) {
+    const header = lines[index]
+    const delimiter = lines[index + 1]
+    if (
+      header.fenced ||
+      !TABLE_ROW.test(header.text) ||
+      delimiter === undefined ||
+      delimiter.fenced ||
+      !TABLE_SEPARATOR.test(delimiter.text)
+    ) {
+      index++
+      continue
+    }
+
+    const tableRows = [header]
+    let end = index + 2
+    while (
+      end < lines.length &&
+      !lines[end].fenced &&
+      TABLE_ROW.test(lines[end].text)
+    ) {
+      tableRows.push(lines[end])
+      end++
+    }
+
+    for (const row of tableRows) {
+      for (const cell of cellsOf(row.text)) {
+        const length = visibleText(cell).length
+        if (length > TABLE_CELL) {
+          found.push({
+            kind: 'table-cell',
+            line: row.number,
+            value: length,
+            limit: TABLE_CELL,
+          })
+        }
+        for (const span of codeSpans(cell)) {
+          const run = unbrokenRun(span)
+          if (run > TABLE_TOKEN) {
+            found.push({
+              kind: 'table-token',
+              line: row.number,
+              value: run,
+              limit: TABLE_TOKEN,
+            })
+          }
+        }
+      }
+    }
+
+    const bodyRows = tableRows.length - 1
+    if (bodyRows > TABLE_ROWS) {
+      found.push({
+        kind: 'table-rows',
+        line: header.number,
+        value: bodyRows,
+        limit: TABLE_ROWS,
+      })
+    }
+
+    let next = end
+    while (next < lines.length && lines[next].text.trim() === '') next++
+    const following = lines[next]
+    if (
+      following !== undefined &&
+      !following.fenced &&
+      LIST_ITEM.test(following.text)
+    ) {
+      found.push({
+        kind: 'table-then-list',
+        line: following.number,
+        value: null,
+        limit: null,
+      })
+    }
+
+    index = end
+  }
+
+  return found.sort((a, b) => a.line - b.line)
+}

package/src/tasks/validate.ts

@@ -1,6 +1,7 @@
 import { existsSync, statSync } from 'node:fs'
 import { readdir, readFile } from 'node:fs/promises'
 import { join, resolve } from 'node:path'
+import { codeSpans, unbrokenRun } from '@/markdown/tables'
 import {
   archiveDir,
   declinedDir,
@@ -1084,28 +1085,30 @@ function checkFolderClaims(
 /**
  * The widest the longest unbroken run in a code span may be before a table
  * scrolls in the preview pane. A 57-character span fit and a 78-character one
- * did not, so the limit sits at the nearest round number above the first.
+ * did not, so the limit sits at the nearest round number above the first. It
+ * is still too high: a 36-character path with no hyphen widened a board column
+ * until the next one ran off the pane, which is why a table cell reads the same
+ * measure at 30. The board keeps 60 until its own report is revisited.
  */
 const WIDE_LIMIT = 60
 
 /**
- * Reports a code span a table cell cannot wrap. A span breaks only at
- * whitespace, so the longest whitespace-free run is what is measured, and a
- * link target is stripped first because only its label renders. Every group is
- * scanned, since the overflow this exists for happened under `## Up next`,
- * where the folder-claim scan would not have looked. Prose breaks at spaces
- * and bare words at hyphens, so only a span is read.
+ * Reports a code span a table cell cannot wrap, measured by `unbrokenRun`,
+ * which `canon markdown audit` reads for a table too. A rendered preview breaks
+ * a span at whitespace and after a hyphen or a slash, so a long run either
+ * widens its column or splits mid-token. Every group is scanned, since the
+ * overflow this exists for happened under `## Up next`, where the folder-claim
+ * scan would not have looked. Prose breaks at spaces and bare words at hyphens,
+ * so only a span is read.
  */
 function checkWideTokens(rows: readonly BoardRow[]): WideToken[] {
   const wide: WideToken[] = []
 
   for (const row of rows) {
     for (const cell of row.cells) {
-      const spans = cell.replace(/\]\([^)]*\)/g, ']').match(/`[^`]+`/g) ?? []
-
-      for (const span of spans) {
-        const text = span.slice(1, -1)
-        const run = Math.max(...text.split(/\s+/).map((part) => part.length))
+      for (const text of codeSpans(cell)) {
+        const span = `\`${text}\``
+        const run = unbrokenRun(text)
 
         if (/\{[^}]*,[^}]*\}/.test(text)) {
           wide.push({

package/tooling/claude/reference.md

@@ -57,6 +57,7 @@ A project installed before the board became a folder still holds `.claude/TASKS.
 
 - Fill in the seed's placeholder project name, description, and key paths after init
 - Keep its sections `Context`, `Commands`, and `Key paths`, since skills detect, extend, or skip by heading
+- Group `Key paths` under H3s, each opening on a lead sentence, before it runs past 5 bullets. `canon markdown audit` and `canon claude sync` both report a longer run.
 - Keep the `Context` section to one line pointing at the state docs, since `plan-feature` does the parallel read when invoked
 
 ## Seed docs

package/tooling/claude/seeds/.claude/hooks/standards-audit.sh

@@ -81,6 +81,11 @@ colons=$(printf '%s' "$record" |
 density=$(printf '%s' "$record" |
   jq -r '.entries[]?.density[]? | ":\(.line)  \(.kind)  " + (if .limit == null then "opens with neither a paragraph nor a table" else "\(.value) past \(.limit)" end) + (if .gating then "  gating" else "" end)' 2>/dev/null)
 
+# Table findings report and never gate, so each kind is handed back with the
+# fix its shape takes rather than the seam a density finding splits at.
+tables=$(printf '%s' "$record" |
+  jq -r '.entries[]?.tables[]? | ":\(.line)  \(.kind)  " + (if .limit == null then "a list follows the table with no lead sentence" else "\(.value) past \(.limit)" end)' 2>/dev/null)
+
 # A page marked `kind: reference` carries reference shape findings, handed back
 # whole the same way, since a gated one fails the push like a density finding.
 shape=$(printf '%s' "$record" |
@@ -92,7 +97,7 @@ shape=$(printf '%s' "$record" |
 empty=$(printf '%s' "$record" |
   jq -r '[.bans.emptySets[]?] | join(", ")' 2>/dev/null)
 
-[ -z "$hits" ] && [ -z "$headings" ] && [ -z "$colons" ] && [ -z "$density" ] && [ -z "$shape" ] && [ -z "$unread" ] && [ -z "$empty" ] && exit 0
+[ -z "$hits" ] && [ -z "$headings" ] && [ -z "$colons" ] && [ -z "$density" ] && [ -z "$tables" ] && [ -z "$shape" ] && [ -z "$unread" ] && [ -z "$empty" ] && exit 0
 
 nl=$'\n'
 msg=""
@@ -125,6 +130,11 @@ if [ -n "$density" ]; then
   msg="${msg:+$msg$nl}$found"
 fi
 
+if [ -n "$tables" ]; then
+  found=$(printf 'Standards-audit: %s breaks the markdown table limits, being a 120-character cell, 8 body rows, a list directly after a table, and a code span holding a run past 30 characters. These report and never fail a push. Move a long cell into a bullet under the table'"'"'s lead, split a long table into groups each under a lead sentence, give a trailing list its own lead sentence, and move a wide token out of the table.\n%s' "$file" "$tables")
+  msg="${msg:+$msg$nl}$found"
+fi
+
 if [ -n "$shape" ]; then
   found=$(printf 'Standards-audit: %s is marked kind: reference and breaks its shape, being an opening, then Output, Refusals, and See also, each at most once and in that order, no H3, and no flag table. Point at the command'"'"'s own --help for flags. A finding marked gating fails the push.\n%s' "$file" "$shape")
   msg="${msg:+$msg$nl}$found"

package/tooling/claude/seeds/CLAUDE.md

@@ -15,5 +15,14 @@
 
 ## Key paths
 
+### Code
+
+[One sentence on what the code paths below hold]
+
 - `src/`: [description]
+
+### Content
+
+[One sentence on what the content paths below hold]
+
 - `canon/DESIGN.md`: visual intent, pointing at the stylesheet that holds the values