@erclx/canon 5.34.0 → 5.36.0

package/src/commands/markdown.ts

@@ -3,9 +3,14 @@ import { readFile } from 'node:fs/promises'
 import { dirname, relative, resolve } from 'node:path'
 import type { Command } from 'commander'
 import { BAN_SETS, emptyBanSets } from '@/markdown/bans'
-import { lengthExemption } from '@/markdown/ceiling'
+import { isChangelog, lengthExemption } from '@/markdown/ceiling'
+import { type ColonFinding, findColons } from '@/markdown/colons'
 import { type MarkdownAuditRefusal, resolveMarkdown } from '@/markdown/files'
 import { isGating } from '@/markdown/gate'
+import {
+  findHeadingCase,
+  type HeadingCaseFinding,
+} from '@/markdown/heading-case'
 import { decodePath, findBrokenLinks, type LinkFinding } from '@/markdown/links'
 import {
   type BanFinding,
@@ -52,6 +57,8 @@ interface FileReport {
   readonly rel: string
   readonly bans: readonly BanFinding[]
   readonly links: readonly LinkFinding[]
+  readonly colons: readonly ColonFinding[]
+  readonly headingCase: readonly HeadingCaseFinding[]
   readonly structure: StructureReport
   readonly renderedLines: number
   /** The stated reason, or null where the document is not exempt. */
@@ -90,6 +97,10 @@ export function register(program: Command): void {
         'Bullet, paragraph, and depth weight are judgments a reader settles,',
         'so all three report and none of them fails a run.',
         '',
+        'A mid-sentence colon and a heading with a capital after its first word',
+        'report the same way. A proper noun is the one case the second cannot',
+        'tell from title case, and the first is sometimes right.',
+        '',
         'Length reports a whole document past the ceiling and never exits 2.',
         'The Document ceiling gate stage owns that verdict, since this audit also',
         'runs on a record kept out of version control, where a long plan is not',
@@ -100,7 +111,7 @@ export function register(program: Command): void {
         'it correctly and a flat paragraph there is not a defect.',
         '',
         'Rewrite the sentence carrying a hit rather than swapping the token for',
-        'a near-synonym. A code span clears the report and is the answer only',
+        'a near-synonym or a colon or a comma. A code span clears the report and is the answer only',
         'where the token is genuinely an identifier under discussion, which is',
         'what markdown.md reserves the span for.',
         '',
@@ -160,9 +171,13 @@ async function runAudit(
       const abs = resolve(root, rel)
       const source = await readFile(abs, 'utf8')
       const lines = bodyLines(source)
+      // The release tool writes a changelog, so neither advisory reads it.
+      const advisory = !isChangelog(rel)
       return {
         rel,
         bans: scanBans(lines, bans),
+        colons: advisory ? findColons(lines) : [],
+        headingCase: advisory ? findHeadingCase(source) : [],
         links: findBrokenLinks(lines, (path) =>
           existsSync(resolve(dirname(abs), path)),
         ),
@@ -177,6 +192,8 @@ async function runAudit(
   reportScope(scope.files, scope.unmatched)
   reportBans(reports, bans, empty)
   reportLinks(reports, root)
+  reportColons(reports)
+  reportHeadingCase(reports)
   reportBullets(reports, checkpoints)
   reportParagraphs(reports, checkpoints)
   reportCadence(reports, checkpoints)
@@ -210,6 +227,8 @@ async function runAudit(
           path: report.rel,
           bans: report.bans,
           links: report.links,
+          colons: report.colons,
+          headingCase: report.headingCase,
           longestRun: report.structure.longestRun,
           longestRunLine: report.structure.longestRunLine,
           heavyBullets: report.structure.heavyBullets,
@@ -230,6 +249,8 @@ async function runAudit(
     bans: reports.flatMap((report) => report.bans),
     links: reports.flatMap((report) => report.links),
     structure: reports.map((report) => report.structure),
+    colons: reports.flatMap((report) => report.colons),
+    headingCase: reports.flatMap((report) => report.headingCase),
   })
 
   return gating ? EXIT_GATE : 0
@@ -310,7 +331,7 @@ function reportBans(
   logWarn(`${plural(total, 'hit')} across ${plural(carrying.length, 'file')}`)
   logWarn('This fails the run. Every other check below reports.')
   logInfo(
-    'Rewrite the sentence rather than swapping the token for a near-synonym.',
+    "Rewrite the sentence rather than swapping the token for a near-synonym, or a colon or a comma in the dash's place. That is the same sentence.",
   )
   logInfo(
     'A code span clears the report and is the answer only where the token is genuinely an identifier under discussion, which is what markdown.md reserves the span for.',
@@ -383,6 +404,78 @@ function reportLinks(reports: readonly FileReport[], root: string): void {
   )
 }
 
+function reportColons(reports: readonly FileReport[]): void {
+  logStep('Colons')
+  logInfo(
+    'A colon followed by more text in a prose line, outside a label, a code span, and a link.',
+  )
+  logInfo(
+    'A heading, a table row, a fenced block, and a line-final colon are excluded. This never fails a run.',
+  )
+
+  const carrying = reports
+    .filter((report) => report.colons.length > 0)
+    .sort((a, b) => b.colons.length - a.colons.length)
+
+  if (carrying.length === 0) {
+    logInfo('No colon joining two clauses.')
+    return
+  }
+
+  const total = carrying.reduce((sum, report) => sum + report.colons.length, 0)
+  logWarn(`${plural(total, 'colon')} across ${plural(carrying.length, 'file')}`)
+  logInfo(
+    'Split the sentence or rewrite it. A colon belongs after a label or at the end of a line introducing a list.',
+  )
+  pipeOutput(
+    carrying
+      .map(
+        (report) =>
+          `${report.rel}  ${plural(report.colons.length, 'colon')}\n${report.colons
+            .map((found) => `  :${found.line}:${found.column + 1}`)
+            .join('\n')}`,
+      )
+      .join('\n'),
+  )
+}
+
+function reportHeadingCase(reports: readonly FileReport[]): void {
+  logStep('Heading case')
+  logInfo(
+    'A heading or frontmatter title with a capitalized word after its first, outside code spans and all-caps tokens.',
+  )
+  logInfo(
+    'A proper noun reports too and is left as it is. This never fails a run.',
+  )
+
+  const carrying = reports
+    .filter((report) => report.headingCase.length > 0)
+    .sort((a, b) => b.headingCase.length - a.headingCase.length)
+
+  if (carrying.length === 0) {
+    logInfo('No heading carrying a capital after its first word.')
+    return
+  }
+
+  const total = carrying.reduce(
+    (sum, report) => sum + report.headingCase.length,
+    0,
+  )
+  logWarn(
+    `${plural(total, 'heading')} across ${plural(carrying.length, 'file')}`,
+  )
+  pipeOutput(
+    carrying
+      .map(
+        (report) =>
+          `${report.rel}  ${plural(report.headingCase.length, 'heading')}\n${report.headingCase
+            .map((found) => `  :${found.line}  ${found.text}`)
+            .join('\n')}`,
+      )
+      .join('\n'),
+  )
+}
+
 function reportBullets(
   reports: readonly FileReport[],
   checkpoints: Checkpoints,

package/src/commands/migrate.ts

@@ -1124,7 +1124,7 @@ export function register(program: Command): void {
         'repoints every citation that names one, live or archived.',
         '',
         'A promoted folder is one a durable record cites and no source file',
-        'under claude/, scripts/, src/, governance/, or standards/ names by',
+        'under claude/, scripts/, src/, or governance/ names by',
         'path. A folder a script still writes into stays in scratch, since',
         'moving it needs a code change first.',
         '',

package/src/commands/records.ts

@@ -29,7 +29,6 @@ import {
 import {
   type Finding,
   isRecordKind,
-  isSharedScratch,
   RECORD_KINDS,
   type RecordKind,
   type ValidateOutcome,
@@ -82,7 +81,7 @@ export function register(program: Command): void {
   const records = program
     .command('records')
     .description(
-      'Check a governed corpus against its standard, and back up the session records under .claude/',
+      'Check a governed corpus against its standard, and back up the session records under .canon/',
     )
     .helpOption('-h, --help', 'Show this help message')
 
@@ -92,10 +91,7 @@ export function register(program: Command): void {
     .argument('<kind>', `Record folder: ${RECORD_KINDS.join(', ')}`)
     .helpOption('-h, --help', 'Show this help message')
     .option('--json', 'Add a machine-readable record on stdout')
-    .option(
-      '--root <path>',
-      'Project root, defaulting to the main worktree except on standards',
-    )
+    .option('--root <path>', 'Project root, defaulting to the main worktree')
     .addHelpText(
       'after',
       [
@@ -104,8 +100,6 @@ export function register(program: Command): void {
         '  plans       filename, required sections, and the suggested-and-answer contract',
         '  groundwork  README and current-state files, numbering, dating, and a half-closed track',
         '  intake      overview file, numbering, dating, and the four bullets every item carries',
-        '  standards   frontmatter, the scope section and its handoff list, and a filename',
-        '              derived from the governed path',
         '',
         'Exit codes:',
         '  0  every check passed',
@@ -113,12 +107,11 @@ export function register(program: Command): void {
         '  2  at least one record carries a finding',
         '',
         'It reports and never writes, so a session fixes what the report names. A',
-        'session record has no history to undo a wrong repair from, and a standard',
-        'is installed and cited everywhere, so a rename is larger than a file move.',
+        'session record has no history to undo a wrong repair from.',
         '',
         'Examples:',
         '  canon records validate plans',
-        '  canon records validate standards',
+        '  canon records validate teach',
         '  canon records validate intake --json',
         '',
       ].join('\n'),
@@ -718,15 +711,6 @@ function reportRefusal(
   return 1
 }
 
-/**
- * A shared-scratch kind reads the main worktree root, so a linked worktree
- * validates the records every other session reads. A tracked corpus reads the
- * checkout the caller stands in, which is the copy that session has edited.
- */
-function defaultRoot(kind: RecordKind): Promise<string> {
-  return isSharedScratch(kind) ? mainWorktreeRoot() : currentWorktreeRoot()
-}
-
 async function runValidate(
   kind: string,
   opts: ValidateCommandOptions,
@@ -745,7 +729,7 @@ async function runValidate(
     )
   }
 
-  const root = opts.root ?? (await defaultRoot(kind))
+  const root = opts.root ?? (await mainWorktreeRoot())
 
   return report(await validateWithStacks(root, kind), emitJson, root)
 }

package/src/commands/sync.ts

@@ -57,6 +57,17 @@ export function register(program: Command): void {
     .addHelpText(
       'after',
       [
+        '',
+        'Runs `canon gov sync`, `canon design sync`, and `canon claude sync`',
+        'on each domain installed, so each carries its own replace behavior:',
+        'governance replaces an edited rule and deletes a retired one, design',
+        'replaces its shipped files, and claude writes .gitignore alone.',
+        'Tooling is not synced. Refuses a dirty working tree.',
+        '',
+        'Exit codes:',
+        '  0  synced, no domain installed, or --check without --exit-code',
+        '  1  the target or a dirty tree was refused, opening the pull request',
+        '     failed, or --check --exit-code found drift',
         '',
         'Examples:',
         '  canon sync',

package/src/commands/tooling.ts

@@ -99,14 +99,21 @@ export function register(program: Command): void {
         '  canon tooling sync vite-react web --skip base',
         '',
         'A target below its git root syncs as a subfolder. It withholds',
-        '.github/, which GitHub reads only at the root, and writes a nested',
-        'cspell.json registering the stack word lists.',
+        '.github/, which GitHub reads only at the root.',
         '',
         'To gate CI on tooling drift, run headlessly with neither flag. That',
         'exits 1 when a file would be replaced and 0 when none would, which is',
         'what `canon sync --check --exit-code` spells with a flag. Pass --check',
         'to report the same list and always exit 0.',
         '',
+        '--write replaces every golden config that differs from the stack.',
+        'Seeds are copy-once, so a seed the target already holds is left alone.',
+        '',
+        'Exit codes:',
+        '  0  synced, up to date, cancelled, or run with --check',
+        '  1  refused, or run headlessly with neither flag while a file would',
+        '     be replaced',
+        '',
       ].join('\n'),
     )
     .action(
@@ -276,8 +283,7 @@ function runList(opts: ListOptions): number {
 
 /**
  * Writes the reference to stdout and every frame line to stderr, so a caller
- * capturing the output with `$(...)` receives the document alone. Mirrors
- * `print` in `src/commands/standards.ts`.
+ * capturing the output with `$(...)` receives the document alone.
  */
 function printReference(stack: string): number {
   intro('canon tooling reference')

package/src/counts/catalogs.ts

@@ -3,7 +3,6 @@ import { join } from 'node:path'
 import { AUDITS } from '@/audits/catalog'
 import { listSkills } from '@/claude/skills-list'
 import { buildGovCatalog } from '@/gov/list'
-import { listStandards } from '@/standards/read'
 
 export interface Catalog {
   readonly id: string
@@ -59,11 +58,6 @@ export const CATALOGS: readonly Catalog[] = [
     nouns: ['rule', 'rules'],
     count: (root) => buildGovCatalog(root).rules.length,
   },
-  {
-    id: 'standards',
-    nouns: ['standard', 'standards'],
-    count: (root) => listStandards(root).length,
-  },
   {
     id: 'commands',
     nouns: ['command', 'commands'],

package/src/design/budget.ts

@@ -1,3 +1,5 @@
+import { canonicalHeading } from '@/design/parse'
+
 /**
  * The prose budget `claude/skills/canvas-board/references/design.md` sets for a design record, and the
  * counter the `design` gate stage reads it through.
@@ -11,21 +13,23 @@
  * `<` is dropped the way `prose()` drops it, and so is a fenced block or an
  * HTML comment spanning several lines, which `prose()` would read in part. A
  * `###` subsection counts toward the `##` section holding it, since the
- * standard fixes the sections and a subheading is no way past the cap.
+ * standard fixes the sections and a subheading is no way past the cap. A
+ * legacy `## Personality` takes the Overview cap through the parser's alias,
+ * and a finding names the heading as the record wrote it.
  */
 export const DESIGN_BUDGET = {
   /** Words before the first `##` section, the title excluded. */
   leadWords: 40,
-  /** Words in `## Personality`, held to one paragraph. */
-  personalityWords: 60,
-  personalityParagraphs: 1,
+  /** Words in `## Overview`, held to one paragraph. */
+  overviewWords: 60,
+  overviewParagraphs: 1,
   /** Bullets or paragraphs in any other section, beside its table. */
   rules: 3,
   /** Words in one of those rules, the proxy for one line. */
   ruleWords: 25,
 } as const
 
-const PERSONALITY = 'Personality'
+const OVERVIEW = 'Overview'
 
 /** A list item at any depth, which starts a rule of its own. */
 const BULLET = /^\s*(?:[-*+]|\d+[.)])\s+/
@@ -52,15 +56,15 @@ export function measureDesignProse(source: string): string[] {
           `The lead holds ${total} words against a cap of ${DESIGN_BUDGET.leadWords}`,
         )
       }
-    } else if (section.heading === PERSONALITY) {
-      if (rules.length > DESIGN_BUDGET.personalityParagraphs) {
+    } else if (canonicalHeading(section.heading) === OVERVIEW) {
+      if (rules.length > DESIGN_BUDGET.overviewParagraphs) {
         findings.push(
-          `${PERSONALITY} holds ${rules.length} paragraphs against a cap of ${DESIGN_BUDGET.personalityParagraphs}`,
+          `${section.heading} holds ${rules.length} paragraphs against a cap of ${DESIGN_BUDGET.overviewParagraphs}`,
         )
       }
-      if (total > DESIGN_BUDGET.personalityWords) {
+      if (total > DESIGN_BUDGET.overviewWords) {
         findings.push(
-          `${PERSONALITY} holds ${total} words against a cap of ${DESIGN_BUDGET.personalityWords}`,
+          `${section.heading} holds ${total} words against a cap of ${DESIGN_BUDGET.overviewWords}`,
         )
       }
     } else {

package/src/design/document.ts

@@ -114,10 +114,10 @@ export function renderDesignDocument(tokens: DesignTokens = TOKENS): string {
     '',
     LEAD,
     '',
-    section('Personality', tokens.personality),
+    section('Overview', tokens.personality),
     '',
     section(
-      'Color',
+      'Colors',
       bullets(tokens.colorRules),
       formatTable(['Role', 'Intent', 'Value'], colorRows(tokens.color)),
     ),
@@ -137,8 +137,10 @@ export function renderDesignDocument(tokens: DesignTokens = TOKENS): string {
       formatTable(['Step', 'Multiplier', 'Value'], spaceRows(tokens.spacing)),
     ),
     '',
+    section('Layout', bullets(tokens.layout)),
+    '',
     section(
-      'Borders',
+      'Shapes',
       bullets(tokens.bordersRules),
       formatTable(
         ['Role', 'Radius', 'Width', 'When used'],
@@ -146,8 +148,6 @@ export function renderDesignDocument(tokens: DesignTokens = TOKENS): string {
       ),
     ),
     '',
-    section('Layout', bullets(tokens.layout)),
-    '',
     section('Motion', bullets(tokens.motion)),
     '',
     section('Iconography', bullets(tokens.iconography)),

package/src/design/parse.ts

@@ -25,6 +25,23 @@ export interface DesignDoc {
   iconography: string
 }
 
+/**
+ * The three headings the standard renamed toward Google's DESIGN.md, each read
+ * as the section it became. Records the seed and `canvas-board` wrote before
+ * the rename sit in targets and will not rename themselves, and an unmatched
+ * heading parses to nothing without saying so. The field names on `DesignDoc`
+ * keep the old words, since the preview reading them is retired separately.
+ */
+export const LEGACY_HEADINGS: Readonly<Record<string, string>> = {
+  Personality: 'Overview',
+  Color: 'Colors',
+  Borders: 'Shapes',
+}
+
+export function canonicalHeading(heading: string): string {
+  return LEGACY_HEADINGS[heading] ?? heading
+}
+
 const VERIFY_TAG = /\s*\?\s*verify\s*$/
 
 /** A cell whose whole content is one balanced code span and nothing else. */
@@ -34,11 +51,11 @@ export function parseDesignDoc(path: string): DesignDoc {
   const raw = readFileSync(path, 'utf8')
   const sections = splitSections(raw)
   return {
-    personality: prose(sections['Personality']),
-    color: table(sections['Color']),
+    personality: prose(sections['Overview']),
+    color: table(sections['Colors']),
     typography: table(sections['Typography']),
     spacing: table(sections['Spacing']),
-    borders: table(sections['Borders']),
+    borders: table(sections['Shapes']),
     motion: prose(sections['Motion']),
     iconography: prose(sections['Iconography']),
   }
@@ -53,7 +70,7 @@ function splitSections(raw: string): Record<string, string> {
     const match = line.match(/^##\s+(.+?)\s*$/)
     if (match) {
       if (current) out[current] = buffer.join('\n')
-      current = match[1]
+      current = canonicalHeading(match[1])
       buffer = []
     } else if (current) {
       buffer.push(line)

package/src/design/render.ts

@@ -268,7 +268,7 @@ ${sections.join('\n')}
 
 function sectionPersonality(text: string): string {
   if (!text) return ''
-  return `<h2>Personality</h2>\n<p>${escape(text)}</p>`
+  return `<h2>Overview</h2>\n<p>${escape(text)}</p>`
 }
 
 function sectionColor(rows: Row[]): string {
@@ -283,7 +283,7 @@ function sectionColor(rows: Row[]): string {
       return `<tr><td>${swatch}${cellText(r, 'Role')}</td><td>${cellText(r, 'Intent')}</td><td><code>${shown}</code>${mark(r, 'Value')}</td></tr>`
     })
     .join('\n')
-  return `<h2>Color</h2>\n<table><thead><tr><th>Role</th><th>Intent</th><th>Value</th></tr></thead><tbody>${body}</tbody></table>`
+  return `<h2>Colors</h2>\n<table><thead><tr><th>Role</th><th>Intent</th><th>Value</th></tr></thead><tbody>${body}</tbody></table>`
 }
 
 function sectionTypography(rows: Row[]): string {
@@ -325,7 +325,7 @@ function sectionBorders(rows: Row[]): string {
       return `<tr><td>${cellText(r, 'Role')}</td><td><code>${escape(radius)}</code>${mark(r, 'Radius')}</td><td><code>${escape(width)}</code>${mark(r, 'Width')}</td><td>${cellText(r, 'When used')}</td><td>${sample}</td></tr>`
     })
     .join('\n')
-  return `<h2>Borders</h2>\n<table><thead><tr><th>Role</th><th>Radius</th><th>Width</th><th>When used</th><th>Sample</th></tr></thead><tbody>${body}</tbody></table>`
+  return `<h2>Shapes</h2>\n<table><thead><tr><th>Role</th><th>Radius</th><th>Width</th><th>When used</th><th>Sample</th></tr></thead><tbody>${body}</tbody></table>`
 }
 
 /** A section the record writes as one-line rules draws them as a list. */

package/src/gate/boundaries.ts

@@ -337,8 +337,8 @@ export const capabilitySeeding: Measure = async (ctx) => {
  * Every file under `claude/` resolved through its symlinks and rejected when it
  * lands under `internal/`.
  *
- * The plugin reaches `standards/` through a symlink, which an installer
- * dereferences with no code in the path to filter. Walking with symlinks
+ * An installer dereferences any symlink under the plugin root with no code in
+ * the path to filter, so a link added there ships whatever it points at. Walking with symlinks
  * followed is what an install copies, so this is the only place the boundary
  * can be measured. The walk tracks the real directories on its current descent
  * and does not enter one a second time, the way `find -L` stops on a loop.

package/src/gate/measures.ts

@@ -505,7 +505,7 @@ export const documentCeiling: Measure = async (ctx) => {
  * Whether a path's stem, its basename up to the first `.`, repeats its
  * immediate parent folder, either whole or as a `<folder>-` prefix.
  *
- * Exact rather than singular-aware, so `standards/standard.md` passes. A false
+ * Exact rather than singular-aware, so `skills/skill.md` passes. A false
  * positive on a gate stage teaches a contributor to route around it, and a
  * widened match is cheap to add once a real echo slips through.
  */
@@ -659,7 +659,7 @@ export const markdownBans: Measure = async (ctx) => {
     return {
       emissions: [output(frame.all)],
       failure:
-        'Markdown prose carries a banned character, or a relative link resolves to nothing on disk. Rewrite the sentence or fix the link, and reach for a code span only where the token is genuinely an identifier under discussion.',
+        'Markdown prose carries a banned character, or a relative link resolves to nothing on disk. Rewrite the sentence, since a colon or a comma standing where the em dash was is the same sentence, or fix the link, and reach for a code span only where the token is genuinely an identifier under discussion.',
     }
   }
 
@@ -771,28 +771,6 @@ export function seedEntryCount(payload: string): number {
   )
 }
 
-/**
- * Scoped to arrival rather than the corpus, since `standards/standard.md`
- * forbids writing a criterion into an existing standard outside the change that
- * exercises it. Gating the known gaps would fail every push until someone
- * closed them all, which is the sweep that rule exists to prevent.
- */
-export const standardCriteria: Measure = async (ctx) => {
-  const run = await ctx.cli(['standards', 'audit', '--arrivals-only'])
-
-  if (run.exitCode === 0) {
-    return { emissions: [info('Arriving standards carry a success criterion')] }
-  }
-
-  return {
-    emissions: [output(run.all)],
-    failure:
-      run.exitCode === 2
-        ? 'A standard new to this branch carries no success-criterion section. Run bun src/cli.ts standards audit.'
-        : 'canon standards audit could not read which standards arrived on this branch. Run bun src/cli.ts standards audit --json to see why.',
-  }
-}
-
 /**
  * Every file in the gated corpus, walked from `ctx.root` rather than from the
  * changed set.
@@ -804,7 +782,7 @@ export const standardCriteria: Measure = async (ctx) => {
  * nothing it would notice.
  *
  * `dot` is what reaches the seeds, which is half of what `tooling/` ships. Every
- * seeded `.claude/` tree, `.cspell/` list, and `.husky/` hook sits behind a
+ * seeded `.claude/` tree, `.github/` workflow, and `.husky/` hook sits behind a
  * dotted segment, so the default scan walks `tooling/` and returns none of the
  * files a scaffolded project actually receives.
  */
@@ -841,8 +819,8 @@ function describeShippedReference(reference: ShippedReference): string {
       return 'a pull request number that resolves elsewhere for a reader in a target'
     case 'docs-path':
       return 'a path into this repository that a registry install never carries'
-    case 'standards-path':
-      return 'a bare standards/ path that has nothing to expand it in an installed plugin cache'
+    case 'retired-verb':
+      return 'a call to canon standards, a verb no installed CLI carries'
     case 'phase-label':
       return 'a phase label that names a board no target holds'
     case 'rule-path':
@@ -903,8 +881,8 @@ export const shippedReferences: Measure = async (ctx) => {
     ),
     failure:
       found.length === 1
-        ? `One reference in the shipped corpora resolves wrong for a reader in a target. Qualify a cross-repository citation as owner/repo#123 or owner/repo@abc1234, cite a docs page through canon docs <name>, rewrite a bare standards/ path under claude/skills/ as \${CLAUDE_SKILL_DIR}/../../standards/<name>.md, state a same-repository citation or a phase label as a fact instead and relocate the evidence to the owning canon/context/ entry, state the fact a shipped skill body's cited rule enforces instead of its path, or mark the line ${REFERENCE_MARKER}: <reason> where the bare form is the point.`
-        : `${found.length} references in the shipped corpora resolve wrong for a reader in a target. Qualify a cross-repository citation as owner/repo#123 or owner/repo@abc1234, cite a docs page through canon docs <name>, rewrite a bare standards/ path under claude/skills/ as \${CLAUDE_SKILL_DIR}/../../standards/<name>.md, state a same-repository citation or a phase label as a fact instead and relocate the evidence to the owning canon/context/ entry, state the fact a shipped skill body's cited rule enforces instead of its path, or mark each line ${REFERENCE_MARKER}: <reason> where the bare form is the point.`,
+        ? `One reference in the shipped corpora resolves wrong for a reader in a target. Qualify a cross-repository citation as owner/repo#123 or owner/repo@abc1234, cite a docs page through canon docs <name>, cite the owner skill's reference in place of a canon standards call, state a same-repository citation or a phase label as a fact instead and relocate the evidence to the owning canon/context/ entry, state the fact a shipped skill body's cited rule enforces instead of its path, or mark the line ${REFERENCE_MARKER}: <reason> where the bare form is the point.`
+        : `${found.length} references in the shipped corpora resolve wrong for a reader in a target. Qualify a cross-repository citation as owner/repo#123 or owner/repo@abc1234, cite a docs page through canon docs <name>, cite the owner skill's reference in place of a canon standards call, state a same-repository citation or a phase label as a fact instead and relocate the evidence to the owning canon/context/ entry, state the fact a shipped skill body's cited rule enforces instead of its path, or mark each line ${REFERENCE_MARKER}: <reason> where the bare form is the point.`,
   }
 }
 

package/src/gate/sequencer.ts

@@ -50,6 +50,45 @@ export interface LoadReading {
   /** The 1-minute load average. */
   readonly loadAverage: number
   readonly cores: number
+  /**
+   * The `some avg10` stall share per resource from `/proc/pressure`, which the
+   * load average folds into one number. Absent where the kernel has no PSI.
+   */
+  readonly pressure?: PressureReading
+}
+
+export interface PressureReading {
+  readonly cpu: number
+  readonly memory: number
+  readonly io: number
+}
+
+/**
+ * Reads the `some avg10` percentage from one `/proc/pressure/<resource>` file.
+ * A file that does not parse answers `undefined`, which drops the clause.
+ */
+export function parsePressure(text: string): number | undefined {
+  const match = /^some\b.*\bavg10=(\d+(?:\.\d+)?)\b/m.exec(text)
+  if (match === null) return undefined
+  const value = Number.parseFloat(match[1])
+  return Number.isFinite(value) ? value : undefined
+}
+
+function readPressure(): PressureReading | undefined {
+  try {
+    const read = (name: string) =>
+      parsePressure(readFileSync(`/proc/pressure/${name}`, 'utf8'))
+    const cpu = read('cpu')
+    const memory = read('memory')
+    const io = read('io')
+    if (cpu === undefined || memory === undefined || io === undefined) {
+      return undefined
+    }
+    return { cpu, memory, io }
+  } catch {
+    // PSI off or absent: the files may exist and still fail with EOPNOTSUPP.
+    return undefined
+  }
 }
 
 /**
@@ -62,7 +101,12 @@ export function readProcLoad(): LoadReading | undefined {
     const first = readFileSync('/proc/loadavg', 'utf8').split(' ')[0]
     const loadAverage = Number.parseFloat(first)
     if (!Number.isFinite(loadAverage)) return undefined
-    return { loadAverage, cores: availableParallelism() }
+    const pressure = readPressure()
+    return {
+      loadAverage,
+      cores: availableParallelism(),
+      ...(pressure === undefined ? {} : { pressure }),
+    }
   } catch {
     return undefined
   }
@@ -252,7 +296,12 @@ function withLoadLine(
   const reading = (ctx.readLoad ?? readProcLoad)()
   if (reading === undefined) return outcome
 
-  const text = `Load average ${reading.loadAverage} on ${reading.cores} cores when the ${stage.label} stage failed`
+  const { pressure } = reading
+  const stalls =
+    pressure === undefined
+      ? ''
+      : `, pressure cpu ${pressure.cpu.toFixed(1)}% memory ${pressure.memory.toFixed(1)}% io ${pressure.io.toFixed(1)}% over 10s,`
+  const text = `Load average ${reading.loadAverage} on ${reading.cores} cores${stalls} when the ${stage.label} stage failed`
   return {
     ...outcome,
     emissions: [...outcome.emissions, { kind: 'info', text }],