@erclx/canon 5.30.0 → 5.32.0

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/tasks/validate.ts

@@ -18,7 +18,7 @@ const ORDERING_FILE = 'priority.md'
 const BACKLOG_FILE = 'backlog.md'
 
 /**
- * The readiness headings `standards/board.md` fixes. The names are the
+ * The readiness headings `claude/skills/task-board/references/board.md` fixes. The names are the
  * contract rather than a suggestion, so a board grouping under names of its own
  * reads as carrying no group at all and the run refuses instead of reporting a
  * clean board it never parsed.

package/src/teach/workspace.ts

@@ -30,7 +30,7 @@ export interface TeachRefused {
   readonly detail: readonly string[]
 }
 
-/** The files and folders `standards/teach.md` fixes for a workspace. */
+/** The files and folders `claude/skills/teach-workspace/references/teach.md` fixes for a workspace. */
 export const TEACH_MISSION = 'MISSION.md'
 export const TEACH_RESOURCES = 'RESOURCES.md'
 export const TEACH_GLOSSARY = 'GLOSSARY.md'

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.
+export 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)),
+  }
+}

package/src/upstream/digest.ts

@@ -0,0 +1,75 @@
+import {
+  extractIdentifiers,
+  keepLines,
+  versionOf,
+  walkReleases,
+  type FetchFailure,
+  type PageFetcher,
+  type ReleaseLine,
+} from '@/upstream/releases'
+
+const FILE_HINTS = 3
+
+export interface NamedIdentifier {
+  readonly name: string
+  readonly files: string[]
+}
+
+export interface DigestLine extends ReleaseLine {
+  readonly identifiers: NamedIdentifier[]
+}
+
+export type Digest =
+  | {
+      readonly kind: 'digest'
+      readonly from: string
+      readonly to: string
+      readonly releases: number
+      readonly lines: DigestLine[]
+    }
+  | { readonly kind: 'cursor-missing'; readonly cursor: string }
+  | {
+      readonly kind: 'failed'
+      readonly reason: FetchFailure
+      readonly message: string
+    }
+
+/** Files naming an identifier, supplied so a test needs no repository. */
+export type Grep = (identifier: string) => Promise<string[]>
+
+export async function buildDigest(
+  cursor: string,
+  fetchPage: PageFetcher,
+  grep: Grep,
+): Promise<Digest> {
+  const walk = await walkReleases(cursor, fetchPage)
+  if (walk.kind !== 'reached') return walk
+
+  const oldestFirst = [...walk.releases].reverse()
+  const lines = await Promise.all(
+    oldestFirst.flatMap(keepLines).map(async (line) => ({
+      ...line,
+      identifiers: await hintsFor(line.text, grep),
+    })),
+  )
+  const newest = walk.releases[0]
+
+  return {
+    kind: 'digest',
+    from: cursor,
+    to: newest ? versionOf(newest.tag_name) : cursor,
+    releases: walk.releases.length,
+    lines,
+  }
+}
+
+async function hintsFor(text: string, grep: Grep): Promise<NamedIdentifier[]> {
+  const found = await Promise.all(
+    extractIdentifiers(text).map(async (name) => ({
+      name,
+      files: (await grep(name)).slice(0, FILE_HINTS),
+    })),
+  )
+
+  return found.filter((entry) => entry.files.length > 0)
+}

package/src/upstream/due.ts

@@ -0,0 +1,128 @@
+import { existsSync, readFileSync } from 'node:fs'
+import { recordDir, SCRATCH } from '@/roots/record'
+import { compareVersions, writeAtomic, type Cursor } from '@/upstream/cursor'
+
+const DAY_MS = 86_400_000
+const DUE_AFTER_DAYS = 7
+
+// Ported from the groundwork's pre-filter script. It names canon's own surfaces,
+// so an Added line matching it is one a digest would act on.
+const VOCABULARY =
+  /plugin|skill|hook|SendMessage|ListAgents|agent view|agents view|worktree|subagent|background|routine|schedule|Monitor|mod\b|mods\b|CLAUDE\.md|rules|memory|permission|auto mode|stream-json|--bg|headless|-p\b|marketplace|session/i
+const ADDED = /^Added/
+const CACHE_MAX_AGE_MS = DAY_MS
+
+/** What the gap between the cursor and the installed version holds. */
+export interface Gap {
+  readonly releases: number
+  readonly lines: readonly string[]
+}
+
+export interface DueInput {
+  /** The installed Claude Code version, or null when it could not be read. */
+  readonly installed: string | null
+  readonly cursor: Cursor | null
+  /** Null when the feed was not read, so only the age path can decide. */
+  readonly gap: Gap | null
+  readonly now: Date
+}
+
+export type DueReason =
+  | 'no-cursor'
+  | 'week'
+  | 'vocabulary'
+  | 'current'
+  | 'recent'
+  | 'unknown-version'
+
+export interface DueResult {
+  readonly due: boolean
+  readonly reason: DueReason
+  /** Releases in the gap, or null when it was not read. */
+  readonly releases: number | null
+}
+
+export function passesVocabulary(line: string): boolean {
+  return ADDED.test(line) && VOCABULARY.test(line)
+}
+
+// A cursor date is a calendar day with no time, read at UTC midnight. An
+// unreadable one gives NaN, which fails the age test and leaves the vocabulary
+// path to decide.
+function ageInDays(date: string, now: Date): number {
+  return (now.getTime() - Date.parse(`${date}T00:00:00Z`)) / DAY_MS
+}
+
+/**
+ * Decides whether a digest is due.
+ *
+ * The age boundary is inclusive: a cursor exactly seven days old is due, since
+ * a week has passed. An installed version at or below the cursor is never due,
+ * which covers a downgrade as well as a run straight after a digest.
+ */
+export function decideDue(input: DueInput): DueResult {
+  const { installed, cursor, gap, now } = input
+  const releases = gap?.releases ?? null
+
+  if (cursor === null) return { due: true, reason: 'no-cursor', releases }
+  if (installed === null) {
+    return { due: false, reason: 'unknown-version', releases }
+  }
+  if (compareVersions(installed, cursor.version) <= 0) {
+    return { due: false, reason: 'current', releases }
+  }
+  if (ageInDays(cursor.date, now) >= DUE_AFTER_DAYS) {
+    return { due: true, reason: 'week', releases }
+  }
+  if (gap?.lines.some(passesVocabulary)) {
+    return { due: true, reason: 'vocabulary', releases }
+  }
+
+  return { due: false, reason: 'recent', releases }
+}
+
+/**
+ * One reading of the feed, kept so a wave of sessions starting together spends
+ * one request rather than one each.
+ */
+export interface DueCache {
+  readonly checkedAt: string
+  readonly installed: string
+  readonly cursor: string
+  /** Null when the read failed, so a failure is held for the day too. */
+  readonly gap: Gap | null
+}
+
+// Scratch rather than the upstream record folder, which a records push backs
+// whole. A file rewritten daily would add a commit to the history each time.
+const cachePath = (root: string): string =>
+  recordDir(root, SCRATCH, 'upstream-due', 'check.json')
+
+/** The stored reading when it is fresh and answers for this pair of versions. */
+export function readDueCache(
+  root: string,
+  installed: string,
+  cursor: string,
+  now: Date,
+): DueCache | null {
+  const path = cachePath(root)
+  if (!existsSync(path)) return null
+
+  try {
+    const cache = JSON.parse(readFileSync(path, 'utf8')) as DueCache
+    const age = now.getTime() - Date.parse(cache.checkedAt)
+    const isFresh = age >= 0 && age < CACHE_MAX_AGE_MS
+    const isSamePair = cache.installed === installed && cache.cursor === cursor
+
+    return isFresh && isSamePair ? cache : null
+  } catch {
+    return null
+  }
+}
+
+export async function writeDueCache(
+  root: string,
+  cache: DueCache,
+): Promise<void> {
+  await writeAtomic(cachePath(root), `${JSON.stringify(cache)}\n`)
+}