@erclx/canon 5.39.0 → 5.41.0

package/src/commands/upstream.ts

@@ -103,6 +103,14 @@ export function register(program: Command): void {
         'Writes nothing. The cursor moves only through `upstream advance`, so a',
         'run that dies midway reads the same range next time.',
         '',
+        'Reasons:',
+        '  no-cursor         no cursor is stored and no --since was given',
+        '  bad-since         --since is not a dotted version',
+        '  cursor-missing    every release the feed returned is newer than the cursor',
+        '  rate-limited      GitHub refused the request, so set GH_TOKEN or GITHUB_TOKEN',
+        '  network           the feed could not be reached',
+        '  http              GitHub answered with an error status',
+        '',
         'Exit codes:',
         '  0  the range was read, possibly empty',
         '  1  refused, with the reason on stderr or in the JSON record',
@@ -154,7 +162,19 @@ export function register(program: Command): void {
         'Due when the cursor is a week old and the installed version is ahead of',
         'it, or sooner when an Added line in the gap names a canon surface. The',
         'gap is read from GitHub at most once a day and cached under the scratch',
-        'folder, and a failed read is held for the day as well.',
+        'folder, and a failed read is held for the day as well. The record',
+        'carries due, reason, releases, installed, and cursor, and releases is',
+        'null when the feed was not read.',
+        '',
+        'Reasons:',
+        '  Due, by reason:',
+        '    no-cursor       no digest has been run',
+        '    week            the cursor is seven or more days old and the install is ahead',
+        '    vocabulary      an Added line in the gap names a plugin, skill, hook, or worktree',
+        '  Not due, by reason:',
+        '    current         the install is at or below the cursor, as after a downgrade',
+        '    recent          the cursor is under a week old and no line in the gap matches',
+        '    unknown-version claude --version could not be read',
         '',
         'Exit codes:',
         '  0  answered, whether or not a digest is due',
@@ -185,6 +205,10 @@ export function register(program: Command): void {
         'folder through a temp file and a rename. It refuses a version older than',
         'the stored cursor.',
         '',
+        'Reasons:',
+        '  invalid-version    the version is not a dotted number',
+        '  older-than-cursor  the version is older than the stored cursor',
+        '',
         'Exit codes:',
         '  0  the cursor moved',
         '  1  refused, with the reason on stderr or in the JSON record',

package/src/commands/worktrees.ts

@@ -119,6 +119,11 @@ const CONDITIONS = [
   'command is running in, since git removes the directory a caller stands',
   'in and every later call scoped to it then fails.',
   '',
+  'A "refusals" entry is one of these reasons:',
+  ...Object.entries(REFUSALS).map(
+    ([reason, meaning]) => `  ${reason.padEnd(24)}${meaning}`,
+  ),
+  '',
   'An unreadable input refuses the whole reading rather than reporting',
   'every worktree as not reclaimable, since an absent merge state and a',
   'branch with no merged pull request produce the same empty answer.',

package/src/context/audit.ts

@@ -104,6 +104,19 @@ export const LAYOUT_PARAGRAPH_CAP = 1
 /** The one Layout H3 not titled with a path, holding the trivial folders. */
 export const OTHER_FOLDERS = 'Other folders'
 
+/** The run-command table H3 only the development entry carries under `Layout`. */
+export const SCRIPTS_HEADING = 'Scripts'
+
+/**
+ * Whether an entry path is the development entry, being the flat entry, the
+ * overview of a split one a target may still carry, or this repository's
+ * `local-loop` entry. The standard exempts the
+ * `Scripts` H3 for that entry alone, so the path is what tells.
+ */
+function isDevelopmentEntry(rel: string): boolean {
+  return /(?:^|\/)development(?:\/(?:overview|local-loop))?\.md$/.test(rel)
+}
+
 /**
  * The context standard's list, kept as its own export because the audit record
  * has published it flat under `checkpoints.requiredSections` since before any
@@ -584,13 +597,18 @@ interface FolderHeading {
  * A cap reports once per section or folder heading however far past it the
  * count runs, since the fix is one cut either way. `Other folders` is exempt
  * from both folder caps, its one-line bullets being held by the bullet run
- * limit `canon markdown audit` already gates.
+ * limit `canon markdown audit` already gates. The development entry's `Scripts`
+ * H3 is exempt from the heading rule and both caps the same way, its table
+ * being a run-command surface rather than a folder.
  */
 function shapeIssues(
+  rel: string,
   lines: readonly BodyLine[],
   retired: readonly string[],
 ): ShapeIssue[] {
   const issues: ShapeIssue[] = []
+  const exempt = new Set([OTHER_FOLDERS])
+  if (isDevelopmentEntry(rel)) exempt.add(SCRIPTS_HEADING)
   let section: string | undefined
   let gotchas: { line: number; bullets: number } | undefined
   let folder: FolderHeading | undefined
@@ -599,7 +617,7 @@ function shapeIssues(
   let afterBlank = false
 
   const closeFolder = (): void => {
-    if (folder && folder.text !== OTHER_FOLDERS) {
+    if (folder && !exempt.has(folder.text)) {
       if (folder.paragraphs > LAYOUT_PARAGRAPH_CAP) {
         issues.push({
           line: folder.line,
@@ -659,7 +677,7 @@ function shapeIssues(
       } else if (section === 'Layout' && level === 3) {
         closeFolder()
         folder = { line: line.number, text, bullets: 0, paragraphs: 0 }
-        if (!FOLDER_TITLE.test(text) && text !== OTHER_FOLDERS) {
+        if (!FOLDER_TITLE.test(text) && !exempt.has(text)) {
           issues.push({ line: line.number, kind: 'layout-heading', text })
         }
       } else if (section === 'Layout') {
@@ -780,7 +798,7 @@ export function measureEntry(
     bareReferences: bareReferences(lines, siblings),
     sections: declaredSections(lines, required),
     otherSections: otherSections(lines, allowed, retired),
-    shape: governsContent ? shapeIssues(lines, retired) : [],
+    shape: governsContent ? shapeIssues(rel, lines, retired) : [],
     stub: isStubSeed(source),
     governed: governsContent,
   }

package/src/context/folders.ts

@@ -56,7 +56,7 @@ export interface AuditedFolder {
    * The requested folder name this was resolved under, which is what says
    * which standard governs the entries. A nested split folder carries the name
    * of the folder it sits beneath rather than its own, so
-   * `canon/context/claude-plugin` is governed as `context`.
+   * `canon/context/<domain>` is governed as `context`.
    */
   readonly name: string
   /**

package/src/context/shape-gated.ts

@@ -15,8 +15,11 @@
  */
 export const SHAPE_GATED_FOLDERS: readonly string[] = [
   'canon/context/context-model.md',
-  'canon/context/design.md',
-  'canon/context/web.md',
+  'canon/context/development/',
+  'canon/context/features/',
+  'canon/context/surfaces/',
+  'canon/context/workflow/',
+  'tooling/base/seeds/',
 ]
 
 /** Whether a repository-relative entry path sits under a gated prefix. */

package/src/counts/scan.ts

@@ -80,7 +80,7 @@ function sentencesOf(line: string): string[] {
  * the 290 showed removing all of them while keeping that one.
  *
  * `authors` joined the list on a corpus measurement rather than on the shape
- * argument above. `canon/context/development/regeneration.md` states `the
+ * argument above. A context entry asserting `the
  * toolkit authors 69 rules under governance/rules/`, which is the assertion
  * shape this list was built for with a verb the list did not carry, and the
  * word costs one further sentence across the whole corpus and no finding.

package/src/design/components.ts

@@ -250,7 +250,7 @@ const TEACH_CHROME: Component = {
     'navigation shared by every teach page. Recovered from two gitignored',
     'course.css files that predate a regression that dropped this layer from the',
     "generator, and rewritten onto this module's tokens rather than the",
-    'incompatible palette they carried. See canon/context/features/teach/chrome.md',
+    'incompatible palette they carried. See canon/context/features/teach.md',
     'for the shape.',
   ].join('\n   '),
   reads: [

package/src/design/document.ts

@@ -95,7 +95,7 @@ function borderRows(tokens: readonly BorderToken[]): string[][] {
  */
 const LEAD = [
   'Authoring guidance: `claude/skills/canvas-board/references/design.md`. Rendered from `src/design/tokens.ts` by `canon design regen`, so edit the module and never this file.',
-  'Why each value was chosen lives in `canon/context/design.md`.',
+  'Why each value was chosen lives in `canon/context/features/design.md`.',
 ].join(' ')
 
 function bullets(rules: readonly string[]): string {

package/src/design/tokens.ts

@@ -59,7 +59,7 @@ export interface BorderToken {
 /**
  * Every prose slot is a list of one-line rules rather than a string, so a
  * bullet is the unit the renderer emits and the prose budget counts, and a
- * value needing a paragraph of why goes to `canon/context/design.md`.
+ * value needing a paragraph of why goes to `canon/context/features/design.md`.
  */
 export interface DesignTokens {
   readonly personality: string

package/src/gate/boundaries.ts

@@ -211,7 +211,7 @@ function collectCommands(value: unknown, into: string[] = []): string[] {
 /**
  * A hook, a workflow, or a husky script reaching one side of the seed or config
  * boundary and not the other is a capability withheld with no recorded reason,
- * per the criterion in `canon/context/tooling/seeds.md`.
+ * per the criterion in `canon/context/surfaces/tooling.md`.
  *
  * Presence on either side clears a name, and a `canon-no-seed:` comment in the
  * file is the recorded reason. The same marker on a destination clears a
@@ -434,6 +434,9 @@ function grepLines(
  * seed itself installs, so every other spelling reports. No seed root, or roots
  * carrying no markdown, is unmeasured rather than a pass, which agrees with
  * `seedStandards` on the no-root case.
+ *
+ * The token matches as a substring, so `canonical` reports as `canon` does. The
+ * walk covers the seed roots alone, so a shipped rule citing the CLI passes.
  */
 export const seedIndependence: Measure = async (ctx) => {
   if (!isDirectory(join(ctx.root, 'tooling'))) {

package/src/gate/measures.ts

@@ -1401,7 +1401,7 @@ export const pluginManifests: Measure = async (ctx) => {
     return {
       emissions: [],
       unmeasured:
-        'claude is on PATH and claude --version fails, so the install brought down no platform-native binary and no manifest was read. Raise or lower the pinned version at the Install Plugin CLI step in .github/workflows/verify.yml, and record the move in canon/context/ci/checks.md.',
+        'claude is on PATH and claude --version fails, so the install brought down no platform-native binary and no manifest was read. Raise or lower the pinned version at the Install Plugin CLI step in .github/workflows/verify.yml, then test the raised pin as `canon/context/development/ci.md` states.',
     }
   }
 

package/src/gate/stages.ts

@@ -92,12 +92,12 @@ export interface Stage {
 }
 
 /**
- * Corpora a `src/` test asserts over from outside `src/`, censused in
- * `canon/context/development/tests.md`. This list and that census are
- * two copies of one set with nothing comparing them, so a corpus joining the
- * census joins this list in the same change. The first four are directory
- * prefixes because their tests walk the tree whole, which is what reaches a
- * rule or a skill a branch adds rather than edits.
+ * Corpora a `src/` test asserts over from outside `src/`. Nothing compares
+ * this list to the tests reading those paths, so a test that starts reading a
+ * new corpus joins it here in the same change, or a branch touching only that
+ * corpus skips the Tests stage. The first four are directory prefixes because
+ * their tests walk the tree whole, which is what reaches a rule or a skill a
+ * branch adds rather than edits.
  */
 export const TEST_CORPORA_PATTERNS = [
   '^claude/skills/',
@@ -302,7 +302,7 @@ export const STAGES: readonly Stage[] = [
   {
     // A hook, a workflow, or a husky script reaching one side of the seed or
     // config boundary and not the other is a capability withheld with no
-    // recorded reason, per the criterion in canon/context/tooling/seeds.md.
+    // recorded reason, per the criterion in canon/context/surfaces/tooling.md.
     id: 'capability-seeding',
     label: 'Capability seeding',
     checks: [{ kind: 'measure', measure: capabilitySeeding }],

package/src/git/env.ts

@@ -26,6 +26,12 @@ const RESOLUTION_VARS = [
  * Read per call rather than captured at module load. A long-lived process can
  * have these set after import, and a snapshot would then hand git the very
  * variables this exists to strip.
+ *
+ * Hooks export `GIT_DIR`, `GIT_WORK_TREE`, `GIT_INDEX_FILE`, and `GIT_PREFIX`,
+ * which beat `-C`. Under pre-push an inherited `GIT_DIR` made a `-C src` read
+ * resolve against the whole repository, and in a fixture it let a config write
+ * overwrite the real repository's committer identity, so route every shelled
+ * call through this, fixtures included.
  */
 export function gitEnv(): Record<string, string> {
   return Object.fromEntries(

package/src/markdown/scope.ts

@@ -35,16 +35,11 @@ const DENSITY_SCOPE = [
  * corpus, which is why the audit reads it only inside a canon checkout.
  */
 export const GATED_PATHS: readonly string[] = [
-  'canon/context/claude-plugin/',
-  'canon/context/claude-internal/',
+  'canon/context/surfaces/',
+  'canon/context/workflow/',
+  'canon/context/development/',
   'canon/context/features/',
-  'canon/context/cli/',
-  'canon/context/sandbox/',
-  'canon/context/governance/',
-  'canon/context/tooling/',
-  'canon/context/web.md',
   'canon/context/context-model.md',
-  'canon/context/design.md',
   'canon/context/index.md',
   'claude/skills/api-design/SKILL.md',
   'claude/skills/auto-ship/SKILL.md',
@@ -76,6 +71,7 @@ export const GATED_PATHS: readonly string[] = [
   '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/git-branch/SKILL.md',
   'claude/skills/git-commit/SKILL.md',
   'claude/skills/git-followup/SKILL.md',
@@ -130,16 +126,12 @@ export const GATED_PATHS: readonly string[] = [
   'claude/skills/video-craft/SKILL.md',
   'claude/skills/write-human/SKILL.md',
   'claude/skills/youtube-transcripts/SKILL.md',
-  'docs/agents/indexes.md',
-  'docs/agents/install-and-sync.md',
-  'docs/agents/migrate.md',
-  'docs/agents/output-shape.md',
-  'docs/agents/overview.md',
-  'docs/agents/targets.md',
-  'canon/context/development/',
-  'canon/context/ci/',
-  'canon/context/scripts/',
   '.claude/skills/internal-',
+  'docs/',
+  'tooling/',
+  'wiki/',
+  'README.md',
+  'CONTRIBUTING.md',
 ]
 
 /**
@@ -148,8 +140,8 @@ export const GATED_PATHS: readonly string[] = [
  * entries, the docs pages, and the skill bodies and references through a stage
  * of its own before this measure existed, and waiting on `GATED_PATHS` would
  * reopen that hole. The seeds, the stack references, the wiki, and the root
- * guides were never held to it, and seven runs in the stack references would
- * fail the push on the day this lands, so those wait for their batch.
+ * guides were never held to it, so they joined `GATED_PATHS` only once their
+ * rewrite brought them to zero.
  */
 const ALWAYS_GATED: readonly DensityKind[] = ['bullet-run']
 

package/src/pr/frames.ts

@@ -19,6 +19,9 @@ const PASS_PATTERN = /^\d{8}T\d{6}Z$/
 /** How many times an add rebuilds on a tip another writer moved. */
 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._-]*$/
+
 const FOLDER_PATTERN = /^pr-(\d+)$/
 
 const DAY_MS = 86_400_000
@@ -77,7 +80,8 @@ export interface FrameInput {
   readonly number: number
   readonly head: string
   readonly pass: string
-  readonly box: number
+  readonly box?: number
+  readonly reference?: string
   readonly theme?: FrameTheme
   readonly bytes: Uint8Array
 }
@@ -158,6 +162,39 @@ export function frameLink(repo: string, path: string): string {
   return `https://github.com/${repo}/blob/${FRAMES_BRANCH}/${path}?raw=true`
 }
 
+/**
+ * The file-name slug of a `<page>/<frame>` address, 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('/')
+  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
+}
+
+/**
+ * Where a design reference capture lands, beside the evidence frames of one
+ * pass. The slug repeats for one reference, so a second capture in a pass
+ * overwrites only itself. Undefined when the address has no valid slug.
+ */
+export function referencePath(
+  number: number,
+  head: string,
+  pass: string,
+  address: string,
+): string | undefined {
+  const slug = referenceSlug(address)
+  if (slug === undefined) return undefined
+  return `pr-${number}/${head.slice(0, SHORT_HEAD_LENGTH)}/${pass}/ref-${slug}.png`
+}
+
 /** The frame's bytes, or undefined when the file is absent, empty, or not a PNG. */
 export async function readFrame(path: string): Promise<Uint8Array | undefined> {
   const bytes = await readFile(path).catch(() => undefined)
@@ -179,17 +216,24 @@ export async function pushFrame(
   api: FramesApi,
   input: FrameInput,
 ): Promise<PushResult> {
-  const path = framePath(
-    input.number,
-    input.head,
-    input.pass,
-    input.box,
-    input.theme,
-  )
+  const path =
+    input.reference === undefined
+      ? framePath(
+          input.number,
+          input.head,
+          input.pass,
+          input.box ?? 0,
+          input.theme,
+        )
+      : referencePath(input.number, input.head, input.pass, input.reference)
+  if (path === undefined) return { kind: 'refused', reason: 'push-failed' }
   const blob = await api.createBlob(Buffer.from(input.bytes).toString('base64'))
   if (blob === undefined) return { kind: 'refused', reason: 'push-failed' }
   const entry: TreeEntry = { path, mode: '100644', type: 'blob', sha: blob }
-  const message = `chore(frames): add box ${input.box} of #${input.number}`
+  const message =
+    input.reference === undefined
+      ? `chore(frames): add box ${input.box} of #${input.number}`
+      : `chore(frames): add reference ${input.reference} of #${input.number}`
 
   for (let attempt = 0; attempt < ADD_ATTEMPTS; attempt += 1) {
     const tip = await api.readTip()