@erclx/canon 5.29.0 → 5.31.0

package/src/markdown/structure.ts

@@ -92,7 +92,7 @@ const SENTENCE_END = /[.!?]["'’”)\]]*(?=\s+(?:["'“(\[]*[A-Z]|`)|\s*$)/g
  * Checkpoints the structural measures run against.
  *
  * These are the definition rather than a fallback. Reading each number out of
- * the sentence `standards/markdown.md` states it in was the alternative, and it
+ * the sentence `claude/skills/markdown-craft/references/markdown.md` states it in was the alternative, and it
  * put a parser contract on a document authored for people, where a rewording
  * degraded a number and the report had to carry a legend saying which one. The
  * standard still states every number for a reader, and moving one is an edit to

package/src/records/backup.ts

@@ -47,6 +47,7 @@ export const BACKED_FOLDERS = [
   'tasks',
   'teach',
   'transcripts',
+  'upstream',
   'walkthroughs',
 ] as const
 

package/src/records/validate.ts

@@ -75,6 +75,8 @@ export const FINDING_KINDS = [
   'category-mismatch',
   'operator-call-phrasing',
   'batch-unsplit',
+  'source-unquoted',
+  'stack-foldable',
 ] as const
 
 export type FindingKind = (typeof FINDING_KINDS)[number]
@@ -276,6 +278,7 @@ const PLAN_SECTIONS = [
   'Risks',
   'Review focus',
   'Questions',
+  'Sources',
 ] as const
 
 type PlanSection = (typeof PLAN_SECTIONS)[number]
@@ -425,6 +428,57 @@ function checkQuestionContract(name: string, lines: string[]): Finding[] {
   return findings
 }
 
+const SOURCE_LINK = /\[[^\]]+\]\(https?:\/\/[^)\s]+\)|https?:\/\/\S+/
+const SOURCE_QUOTE = /["“][^"“”]+["”]/
+const SOURCE_UNVERIFIED = /\bunverified\b/i
+
+/**
+ * A bullet opens an entry only at the section's shallowest indent, so a nested
+ * bullet and a wrapped line both belong to the entry above. Joining them first
+ * lets a passage wrap across lines and still count as quoted.
+ */
+function readSourceEntries(lines: readonly string[]): string[] {
+  const entries: string[] = []
+  let depth: number | undefined
+
+  for (const line of lines) {
+    const trimmed = line.trim()
+    if (trimmed === '') continue
+
+    const indent = line.length - line.trimStart().length
+    const opensEntry =
+      trimmed.startsWith('- ') && (depth === undefined || indent <= depth)
+
+    if (opensEntry) {
+      depth = indent
+      entries.push(trimmed)
+      continue
+    }
+
+    if (entries.length > 0) entries[entries.length - 1] += ` ${trimmed}`
+  }
+
+  return entries
+}
+
+function checkSources(name: string, lines: readonly string[]): Finding[] {
+  return readSourceEntries(lines)
+    .filter((entry) => entry !== `- ${NONE_IDENTIFIED}`)
+    .filter(
+      (entry) =>
+        !SOURCE_LINK.test(entry) ||
+        !(SOURCE_QUOTE.test(entry) || SOURCE_UNVERIFIED.test(entry)),
+    )
+    .map((entry) =>
+      finding(
+        'source-unquoted',
+        name,
+        shorten(entry),
+        'carries no link, or a link with neither a double-quoted passage nor the word unverified.',
+      ),
+    )
+}
+
 export function checkPlan(name: string, text: string): Finding[] {
   const findings: Finding[] = []
 
@@ -480,6 +534,7 @@ export function checkPlan(name: string, text: string): Finding[] {
   }
 
   findings.push(...checkQuestionContract(name, sections.get('Questions') ?? []))
+  findings.push(...checkSources(name, sections.get('Sources') ?? []))
 
   if (hasStagedBatches(text)) {
     const staged = linesOutsideFences(text).find((line) =>

package/src/roots/record.ts

@@ -80,6 +80,7 @@ export const RECORD_ENTRIES: readonly string[] = [
   'tasks',
   'teach',
   'transcripts',
+  'upstream',
   'walkthroughs',
 ]
 

package/src/standards/read.ts

@@ -53,6 +53,15 @@ export function standardRoots(root: string): StandardRoot[] {
   ]
 }
 
+/**
+ * Standards retired into the skill reference that took them, keyed by name with
+ * a path relative to the package root. Each retirement adds one line, and the
+ * map goes with the verb in the last slice of the retirement.
+ */
+const MOVED_STANDARDS: Readonly<Record<string, string>> = {
+  markdown: 'claude/skills/markdown-craft/references/markdown.md',
+}
+
 function filename(name: string): string {
   return name.endsWith('.md') ? name : `${name}.md`
 }
@@ -69,7 +78,16 @@ export function resolveStandard(
     if (existsSync(path)) return { path, source: join(label, file) }
   }
 
-  return undefined
+  const movedName = basename(file, '.md')
+  if (!Object.hasOwn(MOVED_STANDARDS, movedName)) return undefined
+
+  const moved = MOVED_STANDARDS[movedName]
+  if (!moved) return undefined
+
+  const path = join(PROJECT_ROOT, moved)
+  if (!existsSync(path)) return undefined
+
+  return { path, source: join(PACKAGE_LABEL, moved) }
 }
 
 /**
@@ -92,6 +110,8 @@ export function listStandards(root: string): string[] {
     }
   }
 
+  for (const name of Object.keys(MOVED_STANDARDS)) names.add(name)
+
   return [...names].sort()
 }
 

package/src/tasks/answers.ts

@@ -1,7 +1,8 @@
 import { existsSync } from 'node:fs'
 import { readFile } from 'node:fs/promises'
-import { isAbsolute, relative, resolve } from 'node:path'
+import { basename, isAbsolute, relative, resolve } from 'node:path'
 import { isUnder } from '@/tasks/paths'
+import { JUDGED_APART_REMEDY, readLivePlans, stackPairs } from '@/tasks/stack'
 import { recordDir, recordDirs } from '@/roots/record'
 import {
   hasStagedBatches,
@@ -231,6 +232,18 @@ export async function planAnswers(
     })
   }
 
+  const stem = basename(resolved.path, '.md')
+  const pairs = stackPairs(await readLivePlans(root))
+
+  for (const { child, parent, shared } of pairs) {
+    if (child !== stem) continue
+
+    open.push({
+      label: 'Stacked sibling',
+      why: `stacks on \`${parent}\` and shares ${shared} declared files with it. ${JUDGED_APART_REMEDY}`,
+    })
+  }
+
   return {
     ok: true,
     plan: resolved.plan,

package/src/tasks/stack.ts

@@ -0,0 +1,176 @@
+import { existsSync } from 'node:fs'
+import { readdir, readFile } from 'node:fs/promises'
+import { basename, join } from 'node:path'
+import { recordDir } from '@/roots/record'
+import type { Finding } from '@/records/validate'
+import { splitPlanSections } from '@/records/validate'
+import { readDeclarations } from '@/tasks/reach'
+
+/**
+ * The fold thresholds, calibrated over 1,043 live and archived plans in which
+ * 87 stack pairs name a parent. At these values 15 report: the inspector,
+ * canvas, slides, and evidence chains, plus one sandbox contract split that
+ * carries a `Judged apart from` line. The ceiling drops one pair of 24 files.
+ * The per-PR cost was never measured as a number, so these are calibrated
+ * against the corpus and not derived.
+ */
+export const MIN_SHARED = 3
+export const MIN_OVERLAP = 0.6
+export const MAX_UNION = 20
+
+const STACK_PARENT =
+  /(?:stacks? on|builds? on|branch(?:es)? from)\s+(?:(?:the|batch|plan|slice)\s+)*`(feature-[a-z0-9-]+)`/gi
+
+const JUDGED_APART = /^judged apart from\s+`(feature-[a-z0-9-]+)`:\s*\S/i
+
+const BULLET = /^[-*]\s+/
+
+export interface StackPlan {
+  readonly stem: string
+  readonly text: string
+}
+
+export interface StackPair {
+  readonly child: string
+  readonly parent: string
+  readonly shared: number
+  readonly union: number
+}
+
+/**
+ * One string per `**Constraints:**` bullet, with a wrapped continuation line
+ * joined to the bullet it belongs to.
+ */
+function constraintBullets(text: string): string[] {
+  const bullets: string[] = []
+
+  for (const line of splitPlanSections(text).get('Constraints') ?? []) {
+    const trimmed = line.trim()
+    if (trimmed.length === 0) continue
+
+    if (BULLET.test(trimmed)) bullets.push(trimmed.replace(BULLET, ''))
+    else if (bullets.length > 0) bullets[bullets.length - 1] += ` ${trimmed}`
+  }
+
+  return bullets
+}
+
+/**
+ * The plan stems a plan says it stacks on, in the order written.
+ *
+ * Only the slug standing directly after the phrase counts, with at most a
+ * filler word between. A line like "`feature-x` stacks on this slice, not on
+ * `feature-y`" names a parent for `feature-y`'s plan and none for this one, and
+ * reading every slug on a stack-worded line would hand it the wrong parent.
+ */
+export function readStackParents(text: string): string[] {
+  const parents: string[] = []
+
+  for (const bullet of constraintBullets(text)) {
+    for (const match of bullet.matchAll(STACK_PARENT)) {
+      const parent = match[1]
+      if (parent !== undefined) parents.push(parent.toLowerCase())
+    }
+  }
+
+  return [...new Set(parents)]
+}
+
+function isJudgedApart(text: string, parent: string): boolean {
+  return constraintBullets(text).some(
+    (bullet) => JUDGED_APART.exec(bullet)?.[1]?.toLowerCase() === parent,
+  )
+}
+
+/** Whether two declarations name the same file or one folder holding the other. */
+function overlaps(a: string, b: string): boolean {
+  return a === b || a.startsWith(`${b}/`) || b.startsWith(`${a}/`)
+}
+
+function countShared(from: readonly string[], to: readonly string[]): number {
+  return from.filter((entry) => to.some((other) => overlaps(entry, other)))
+    .length
+}
+
+/**
+ * Every live plan that stacks on a live sibling it mostly shares files with and
+ * has not written down why the two are judged apart.
+ *
+ * A parent absent from `plans` is never reported, which is how an archived
+ * parent stays clear: the caller hands over the live folder only, so a merged
+ * parent cannot be folded into. When two plans each name the other, the pair is
+ * reported once, on the child sorting second.
+ *
+ * A folder declaration counts as sharing the files under it, taking the larger
+ * of the two directions and capping at the smaller set, so a folder and the
+ * files beneath it are not undercounted as distinct strings.
+ */
+export function stackPairs(plans: readonly StackPlan[]): StackPair[] {
+  const byStem = new Map(plans.map((plan) => [plan.stem, plan]))
+  const pairs: StackPair[] = []
+
+  for (const child of plans) {
+    for (const parentStem of readStackParents(child.text)) {
+      const parent = byStem.get(parentStem)
+      if (parent === undefined || parent.stem === child.stem) continue
+
+      const mutual = readStackParents(parent.text).includes(child.stem)
+      if (mutual && child.stem < parent.stem) continue
+
+      if (isJudgedApart(child.text, parentStem)) continue
+
+      const own = readDeclarations(child.text)
+      const theirs = readDeclarations(parent.text)
+      const smaller = Math.min(own.length, theirs.length)
+      if (smaller === 0) continue
+
+      const shared = Math.min(
+        smaller,
+        Math.max(countShared(own, theirs), countShared(theirs, own)),
+      )
+      const union = new Set([...own, ...theirs]).size
+
+      if (
+        shared >= MIN_SHARED &&
+        shared / smaller >= MIN_OVERLAP &&
+        union <= MAX_UNION
+      ) {
+        pairs.push({ child: child.stem, parent: parentStem, shared, union })
+      }
+    }
+  }
+
+  return pairs
+}
+
+/** The `Judged apart from` remedy, worded once for the finding and the gate. */
+export const JUDGED_APART_REMEDY =
+  'Fold the batch into its parent as contiguous commits on one branch, or write `Judged apart from `feature-<parent>`: <reason>` in its constraints.'
+
+export function stackFindings(plans: readonly StackPlan[]): Finding[] {
+  return stackPairs(plans).map(({ child, parent, shared, union }) => ({
+    kind: 'stack-foldable',
+    record: `${child}.md`,
+    subject: parent,
+    message: `stacks on \`${parent}\` and shares ${shared} declared files with it, ${union} between the two. ${JUDGED_APART_REMEDY}`,
+  }))
+}
+
+/**
+ * The live plans folder as stem and text pairs. The archive is a folder below
+ * this one and is never walked, so a merged parent is absent and stays clear.
+ */
+export async function readLivePlans(root: string): Promise<StackPlan[]> {
+  const dir = recordDir(root, 'plans')
+  if (!existsSync(dir)) return []
+
+  const names = (await readdir(dir)).filter((name) => name.endsWith('.md'))
+  names.sort()
+
+  return Promise.all(
+    names.map(async (name) => ({
+      stem: basename(name, '.md'),
+      text: await readFile(join(dir, name), 'utf8'),
+    })),
+  )
+}

package/src/teach/nav.ts

@@ -1,4 +1,4 @@
-import { existsSync, readFileSync } from 'node:fs'
+import { existsSync } from 'node:fs'
 import { readdir, readFile, rm } from 'node:fs/promises'
 import { join, posix, relative } from 'node:path'
 import {
@@ -6,10 +6,10 @@ import {
   TEACH_STYLESHEET_COMPONENTS,
 } from '@/design/components'
 import { buildDesignCss } from '@/design/css'
-import { FAVICON_COLORS, faviconLink, renderFavicon } from '@/design/favicon'
+import { brandFavicon } from '@/design/brand-favicon'
+import { faviconLink } from '@/design/favicon'
 import { stripFrontmatter } from '@/markdown/frontmatter'
 import { parseFrontmatter, readField } from '@/indexes/frontmatter'
-import { PROJECT_ROOT } from '@/roots/project'
 import { compileScript } from '@/teach/browser/compile'
 import { dismiss } from '@/teach/browser/dismiss'
 import { focusLine } from '@/teach/browser/focus-line'
@@ -39,8 +39,6 @@ import {
 } from '@/teach/workspace'
 import { writeIfChanged } from '@/teach/write-if-changed'
 
-const BRAND_MARK = 'assets/brand/mark.svg'
-
 /**
  * The link `teach-workspace` once had a session write by hand into every page.
  * A lesson keeps whatever sits outside its marked regions, so the old icon
@@ -68,14 +66,9 @@ function dropHandWrittenHead(html: string): string {
   )
 }
 
-/**
- * Built from the brand mark and the favicon's own pair, the same two inputs
- * `web/public/favicon.svg` is generated from, so every teach page carries the
- * icon the landing page does rather than a copy of its own.
- */
+/** Every teach page carries the icon the landing page does rather than a copy of its own. */
 function teachFavicon(): string {
-  const mark = readFileSync(join(PROJECT_ROOT, BRAND_MARK), 'utf8')
-  return faviconLink(renderFavicon(mark, FAVICON_COLORS))
+  return faviconLink(brandFavicon())
 }
 
 /**

package/src/upstream/catalog.ts

@@ -0,0 +1,112 @@
+import { existsSync, readdirSync, readFileSync } from 'node:fs'
+import { join } from 'node:path'
+import { COMMAND_GROUPS } from '@/cli/help'
+import { listSkillsAt } from '@/claude/skills-list'
+import { STAGES } from '@/gate/stages'
+
+const MAX_TEXT = 140
+const PLUGIN_SKILLS = 'claude/skills'
+const INTERNAL_SKILLS = '.claude/skills'
+
+export interface CatalogEntry {
+  readonly name: string
+  readonly text: string
+}
+
+export interface Catalog {
+  readonly skills: CatalogEntry[]
+  readonly internalSkills: CatalogEntry[]
+  readonly verbs: CatalogEntry[]
+  readonly hooks: CatalogEntry[]
+  readonly gate: CatalogEntry[]
+  /** Rows that exist but could not be described, so none drops out silently. */
+  readonly gaps: string[]
+}
+
+const firstSentence = (text: string): string =>
+  text.split(/\.\s/)[0]?.replace(/\.$/, '').slice(0, MAX_TEXT) ?? ''
+
+function skillsAt(
+  root: string,
+  corpus: string,
+  gaps: string[],
+): CatalogEntry[] {
+  const dir = join(root, corpus)
+  if (!existsSync(dir)) return []
+
+  const listed = listSkillsAt(dir)
+  const named = new Set(listed.map((skill) => skill.name))
+  const folders = readdirSync(dir, { withFileTypes: true })
+    .filter((entry) => entry.isDirectory())
+    .map((entry) => entry.name)
+
+  for (const folder of folders) {
+    if (!named.has(folder)) gaps.push(`${corpus}/${folder}: no SKILL.md`)
+  }
+  for (const skill of listed) {
+    if (!skill.description) gaps.push(`${corpus}/${skill.name}: no description`)
+  }
+
+  return listed.map((skill) => ({
+    name: skill.name,
+    text: firstSentence(skill.description),
+  }))
+}
+
+function hooksAt(root: string): CatalogEntry[] {
+  const dir = join(root, '.claude', 'hooks')
+  if (!existsSync(dir)) return []
+
+  return readdirSync(dir)
+    .filter((file) => file.endsWith('.sh'))
+    .sort()
+    .map((file) => {
+      const comment = readFileSync(join(dir, file), 'utf8')
+        .split('\n')
+        .find((line) => /^#\s*\S/.test(line) && !line.startsWith('#!'))
+
+      return {
+        name: file,
+        text: (comment ?? '').replace(/^#\s*/, '').slice(0, MAX_TEXT),
+      }
+    })
+}
+
+export function buildCatalog(root: string): Catalog {
+  const gaps: string[] = []
+
+  return {
+    skills: skillsAt(root, PLUGIN_SKILLS, gaps),
+    internalSkills: skillsAt(root, INTERNAL_SKILLS, gaps),
+    verbs: COMMAND_GROUPS.flatMap((group) => group.rows).map(
+      ([signature, description]) => ({
+        name: `canon ${signature}`,
+        text: description,
+      }),
+    ),
+    hooks: hooksAt(root),
+    gate: STAGES.map((stage) => ({ name: stage.id, text: stage.label })),
+    gaps,
+  }
+}
+
+const section = (title: string, entries: readonly CatalogEntry[]): string[] => [
+  `### ${title}`,
+  ...entries.map((entry) =>
+    entry.text ? `- ${entry.name}: ${entry.text}` : `- ${entry.name}`,
+  ),
+  '',
+]
+
+export function renderCatalog(catalog: Catalog): string {
+  return [
+    ...section('Plugin skills (claude/skills/)', catalog.skills),
+    ...section('Internal skills (.claude/skills/)', catalog.internalSkills),
+    ...section('CLI verbs', catalog.verbs),
+    ...section('Hooks (.claude/hooks/)', catalog.hooks),
+    ...section('Gate stages (canon gate run)', catalog.gate),
+    ...(catalog.gaps.length > 0
+      ? ['### Gaps', ...catalog.gaps.map((gap) => `- ${gap}`), '']
+      : []),
+  ].join('\n')
+}

package/src/upstream/cursor.ts

@@ -0,0 +1,120 @@
+import {
+  existsSync,
+  mkdirSync,
+  readFileSync,
+  renameSync,
+  writeFileSync,
+} from 'node:fs'
+import { dirname } from 'node:path'
+import { recordDir } from '@/roots/record'
+
+const FOLDER = 'upstream'
+const VERSION = /^\d+(\.\d+)*$/
+
+export interface Cursor {
+  readonly version: string
+  readonly date: string
+  readonly intake: string
+}
+
+export interface AdvanceInput {
+  readonly version: string
+  readonly intake: string
+  readonly today: string
+  /** The current `llms.txt`, or null to keep the copy already stored. */
+  readonly llms: string | null
+}
+
+export type AdvanceOutcome =
+  | { readonly kind: 'advanced' }
+  | {
+      readonly kind: 'refused'
+      readonly reason: 'older-than-cursor' | 'invalid-version'
+    }
+
+export interface LlmsDifference {
+  readonly added: string[]
+  readonly removed: string[]
+}
+
+const cursorPath = (root: string): string =>
+  recordDir(root, FOLDER, 'cursor.json')
+
+const llmsPath = (root: string): string => recordDir(root, FOLDER, 'llms.txt')
+
+export function readCursor(root: string): Cursor | null {
+  const path = cursorPath(root)
+  if (!existsSync(path)) return null
+
+  try {
+    return JSON.parse(readFileSync(path, 'utf8')) as Cursor
+  } catch {
+    return null
+  }
+}
+
+export function readLastLlms(root: string): string | null {
+  const path = llmsPath(root)
+
+  return existsSync(path) ? readFileSync(path, 'utf8') : null
+}
+
+export function compareVersions(a: string, b: string): number {
+  const left = a.split('.').map(Number)
+  const right = b.split('.').map(Number)
+
+  for (let i = 0; i < Math.max(left.length, right.length); i++) {
+    const diff = (left[i] ?? 0) - (right[i] ?? 0)
+    if (diff !== 0) return diff
+  }
+
+  return 0
+}
+
+// `fetch` reads this file, so a write that half-lands would leave a reader on a
+// truncated cursor. A rename within one folder is atomic.
+async function writeAtomic(path: string, body: string): Promise<void> {
+  mkdirSync(dirname(path), { recursive: true })
+  const temp = `${path}.${process.pid}.tmp`
+  writeFileSync(temp, body)
+  renameSync(temp, path)
+}
+
+export async function advanceCursor(
+  root: string,
+  input: AdvanceInput,
+): Promise<AdvanceOutcome> {
+  if (!VERSION.test(input.version)) {
+    return { kind: 'refused', reason: 'invalid-version' }
+  }
+
+  const stored = readCursor(root)
+  if (stored && compareVersions(input.version, stored.version) < 0) {
+    return { kind: 'refused', reason: 'older-than-cursor' }
+  }
+
+  if (input.llms !== null) await writeAtomic(llmsPath(root), input.llms)
+  const next: Cursor = {
+    version: input.version,
+    date: input.today,
+    intake: input.intake,
+  }
+  await writeAtomic(cursorPath(root), `${JSON.stringify(next, null, 2)}\n`)
+
+  return { kind: 'advanced' }
+}
+
+const lines = (text: string): string[] => text.split('\n').filter(Boolean)
+
+export function llmsDifference(
+  last: string | null,
+  current: string,
+): LlmsDifference {
+  const before = new Set(lines(last ?? ''))
+  const after = new Set(lines(current))
+
+  return {
+    added: [...after].filter((line) => !before.has(line)),
+    removed: [...before].filter((line) => !after.has(line)),
+  }
+}