@erclx/canon 5.33.0 → 5.35.0

package/src/gate/measures.ts

@@ -104,28 +104,6 @@ const info = (text: string): Emission => ({ kind: 'info', text })
 const warn = (text: string): Emission => ({ kind: 'warn', text })
 const output = (text: string): Emission => ({ kind: 'output', text })
 
-/**
- * Rules no stack reaches, sorted the way `canon gov list` emits them.
- * `260-shadcn` and `320-tanstack-query` are opt-in libraries a project may not
- * want.
- *
- * `130-go`, `140-php`, `335-testing-go`, and `336-testing-php` are opt-in by
- * `--add` until a Go or PHP stack ships, which `target-setup` reaches by
- * matching a detected language against each rule's description.
- *
- * All are recorded here rather than in a config file: the list is what a
- * reader compares a new arrival against, and a config file would absorb the
- * arrival silently.
- */
-export const GOV_EXPECTED_UNREFERENCED = [
-  '130-go',
-  '140-php',
-  '260-shadcn',
-  '320-tanstack-query',
-  '335-testing-go',
-  '336-testing-php',
-]
-
 /**
  * Scenarios declaring no expectation, taken from `canon sandbox coverage`
  * against a clean tree. Raising it is a deliberate edit that says which
@@ -170,16 +148,19 @@ function parseJson(payload: string): unknown {
 }
 
 /**
- * A rule no stack names is a report rather than a gate. All three standing
- * findings ship that way on purpose, so failing would fail every push over the
- * deliberate case and teach a reader to route around the stage.
+ * A rule no stack reaches arrives at a project only through `canon gov
+ * detect`, so each one needs a `governance/detect.toml` entry or nothing ever
+ * proposes it. A key naming a retired rule fails too, since it would hide from
+ * the rename sweep that keys the file by basename.
  *
- * The catalog is parsed here rather than piped through `bun --eval`, which the
- * script this replaces had to do and had to guard: that interpreter exits 0
- * when its script throws while stdin is a pipe, so a payload that is not JSON
- * printed nothing and exited clean, and empty already means every rule is
- * reached. A sentinel string carried success past that. Parsing in process
- * leaves the two states distinguishable with nothing to carry.
+ * The check replaced a fixed list of expected unreferenced rules. Once the
+ * stacks are thin, that list is most of the catalog and would be rewritten on
+ * every new rule, which is a list nobody reads.
+ *
+ * The catalog is parsed here rather than piped through `bun --eval`, whose
+ * interpreter exits 0 when its script throws while stdin is a pipe, so a
+ * payload that is not JSON would print nothing and read as every rule
+ * reached. Parsing in process keeps the two states distinguishable.
  */
 export const unreferencedRules: Measure = async (ctx) => {
   const { exitCode, stdout } = await ctx.cli(['gov', 'list', '--json'])
@@ -190,34 +171,67 @@ export const unreferencedRules: Measure = async (ctx) => {
     }
   }
 
-  const record = parseJson(stdout) as { unreferenced?: unknown } | undefined
-  if (!Array.isArray(record?.unreferenced)) {
+  const record = parseJson(stdout) as
+    | { unreferenced?: unknown; rules?: unknown; staleDetect?: unknown }
+    | undefined
+  if (
+    !Array.isArray(record?.unreferenced) ||
+    !Array.isArray(record?.rules) ||
+    !Array.isArray(record?.staleDetect)
+  ) {
     return {
       emissions: [],
       unmeasured:
-        'The governance catalog carried no readable unreferenced list.',
+        'The governance catalog carried no readable unreferenced, rules, or staleDetect list.',
     }
   }
 
+  const detected = new Set(
+    record.rules
+      .filter(
+        (rule): rule is { name: string; detect: unknown } =>
+          typeof rule === 'object' &&
+          rule !== null &&
+          typeof (rule as { name?: unknown }).name === 'string',
+      )
+      .filter((rule) => rule.detect !== null && rule.detect !== undefined)
+      .map((rule) => rule.name),
+  )
   const unreferenced = record.unreferenced.map(String)
-  if (unreferenced.length === 0) {
-    return { emissions: [info('Every rule is reached by a stack')] }
+  const undetected = unreferenced.filter((rule) => !detected.has(rule))
+  const stale = record.staleDetect.map(String)
+
+  const emissions: Emission[] = []
+  if (undetected.length > 0) {
+    emissions.push(
+      warn(
+        `Reached by no stack and proposed by nothing: ${undetected.join(' ')}`,
+      ),
+      warn(
+        'Name each in a stack, or add a table to governance/detect.toml with the deps or files that mark a project as wanting it.',
+      ),
+    )
+  }
+  if (stale.length > 0) {
+    emissions.push(
+      warn(`governance/detect.toml names no live rule: ${stale.join(' ')}`),
+      warn('Rename the key to the rule it became, or delete the table.'),
+    )
   }
 
-  const listed = unreferenced.join(' ')
-  if (listed === GOV_EXPECTED_UNREFERENCED.join(' ')) {
+  if (emissions.length > 0) {
     return {
-      emissions: [
-        info(`Reached by no stack: ${listed} (each recorded above with why)`),
-      ],
+      emissions,
+      failure: 'An opt-in rule has no route to a project',
     }
   }
 
   return {
     emissions: [
-      warn(`Reached by no stack: ${listed}`),
-      warn(
-        `Expected: ${GOV_EXPECTED_UNREFERENCED.join(' ')}. Name the new rule in a stack, or update GOV_EXPECTED_UNREFERENCED in src/gate/measures.ts and say why it reaches no stack.`,
+      info(
+        unreferenced.length === 0
+          ? 'Every rule is reached by a stack'
+          : `${plural(unreferenced.length, 'rule')} reached by no stack, each proposed by governance/detect.toml`,
       ),
     ],
   }
@@ -491,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.
  */
@@ -757,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.
@@ -790,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.
  */
@@ -827,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':
@@ -889,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 }],

package/src/gate/stages.ts

@@ -25,7 +25,6 @@ import {
   skillFamily,
   skillPracticeShape,
   skillProvenance,
-  standardCriteria,
   unreferencedRules,
   visualPathGlobs,
 } from '@/gate/measures'
@@ -328,10 +327,9 @@ export const STAGES: readonly Stage[] = [
     success: 'Capability seeding clean',
   },
   {
-    // A stack entry naming a rule folder takes every rule in it, which is what
-    // stops a new rule from needing a second edit to reach a target. The
-    // failure it leaves open is a rule authored into a folder no stack names,
-    // which `canon gov install` never reaches on its own.
+    // A rule no stack names reaches a target only when `canon gov detect`
+    // proposes it, so every such rule needs a governance/detect.toml entry,
+    // and every key there has to name a live rule.
     id: 'unreferenced-rules',
     label: 'Unreferenced rules',
     checks: [{ kind: 'measure', measure: unreferencedRules }],
@@ -503,11 +501,6 @@ export const STAGES: readonly Stage[] = [
     label: 'Skill family',
     checks: [{ kind: 'measure', measure: skillFamily }],
   },
-  {
-    id: 'standard-criteria',
-    label: 'Standard success criteria',
-    checks: [{ kind: 'measure', measure: standardCriteria }],
-  },
   {
     id: 'sandbox-coverage',
     label: 'Sandbox coverage',
@@ -523,18 +516,6 @@ export const STAGES: readonly Stage[] = [
     label: 'Plugin manifests',
     checks: [{ kind: 'measure', measure: pluginManifests }],
   },
-  {
-    id: 'spelling',
-    label: 'Spelling',
-    checks: [
-      {
-        kind: 'command',
-        argv: ['bun', 'run', 'check:spell'],
-        failure: 'Spell check failed',
-      },
-    ],
-    success: 'Spell check passed',
-  },
   {
     id: 'shell',
     label: 'Shell',

package/src/gov/citations.ts

@@ -6,7 +6,6 @@ import { isMarked } from '@/sweep/exempt-marker'
 import { gitEnv } from '@/git/env'
 import { listRuleFiles } from '@/gov/payload'
 import { parseFrontmatter } from '@/indexes/frontmatter'
-import { movedStandardPath } from '@/standards/read'
 import { findBacktickSpans } from '@/markdown/backticks'
 
 /**
@@ -42,14 +41,14 @@ export const RULE_DIRS: readonly string[] = [
 export const GLOB_CORPUS = join('internal', 'rules')
 
 /**
- * How the citation was written, kept on the finding because the three resolve
+ * How the citation was written, kept on the finding because the two resolve
  * against different roots and a reader repairing one needs to know which.
  *
- * `standard` is the live form, carried by 20 rules. `path` is a backticked
- * repository path. `sibling` is a rule naming another rule by filename alone,
- * which resolves inside the folder the citing rule sits in.
+ * `path` is a backticked repository path. `sibling` is a rule naming another
+ * rule by filename alone, which resolves inside the folder the citing rule
+ * sits in.
  */
-export type CitationForm = 'path' | 'standard' | 'sibling'
+export type CitationForm = 'path' | 'sibling'
 
 /**
  * What the sweep decided about one citation.
@@ -116,13 +115,6 @@ const FENCE = /^\s*(?:```|~~~)/
 
 const FRONTMATTER_DELIMITER = /^---\s*$/
 
-/**
- * The verb form, with the name captured. A leading letter or digit is required,
- * which is what leaves `canon standards <name>` unmatched: that line teaches the
- * form rather than citing a standard, and it is the only one in either corpus.
- */
-const STANDARD_CALL = /canon standards ([A-Za-z0-9][A-Za-z0-9._-]*)/g
-
 /** A rule filename, which is how a rule names a sibling with no folder around it. */
 const SIBLING_RULE = /^\d{3}-[a-z0-9-]+\.md$/
 
@@ -146,8 +138,8 @@ function isNotRepositoryPath(span: string): boolean {
  * This is what separates a citation from the folder and module conventions the
  * corpus is full of. `next/font`, `try/except`, `react-hooks/set-state-in-effect`,
  * and `oven-sh/setup-bun@v2` all carry a slash and name no file, and a trailing
- * slash is a folder rather than a document. The cost is that `claude/standards`
- * is a real path this declines to check, which is the bound the report states.
+ * slash is a folder rather than a document. The cost is that a real folder path
+ * goes unchecked, which is the bound the report states.
  */
 function namesAFile(span: string): boolean {
   if (span.endsWith('/')) return false
@@ -160,10 +152,10 @@ function namesAFile(span: string): boolean {
  * sweep can resolve.
  *
  * The whole span is classified rather than a trailing pattern inside it.
- * Extracting `standards/tooling-reference.md` out of
- * `internal/standards/tooling-reference.md` and resolving that against the
- * standards root manufactures a dead citation out of a file that exists, which
- * a session measuring this corpus did before the check was written.
+ * Extracting a trailing `<folder>/<name>.md` out of a longer path and resolving
+ * that against another root manufactures a dead citation out of a file that
+ * exists, which a session measuring this corpus did before the check was
+ * written.
  */
 export function classifySpan(span: string): CitationForm | undefined {
   if (isNotRepositoryPath(span)) return undefined
@@ -176,15 +168,6 @@ export function classifySpan(span: string): CitationForm | undefined {
  * Where a citation could answer, which is wherever the reader's own tools look
  * and nowhere else.
  *
- * A standard name takes the authoring root alone, matching `standardRoots` in
- * `@/standards/read`, which reads `standards/` at the working root and then the
- * package corpus, plus the skill reference a retired name moved to. This verb
- * refuses a tree holding no rule corpus, so it runs only where those two roots
- * are one directory. `internal/standards/` is
- * deliberately absent: `canon standards <name>` never reaches it, so admitting it
- * here would pass a citation that refuses for the session opening it, which is a
- * gate failing open.
- *
  * A sibling resolves inside the folder the citing rule sits in, since that is
  * the only place a bare rule filename means anything.
  */
@@ -193,11 +176,6 @@ function candidatesFor(
   cited: string,
   ruleFile: string,
 ): string[] {
-  if (form === 'standard') {
-    const moved = movedStandardPath(cited)
-
-    return [join('standards', `${cited}.md`), ...(moved ? [moved] : [])]
-  }
   if (form === 'sibling') return [join(dirname(ruleFile), cited)]
   return [cited]
 }
@@ -244,16 +222,6 @@ export function collectCitations(text: string): RawCitation[] {
         : trimmed
     const marked = isMarked(lines, index, CITATION_MARKER)
 
-    for (const match of line.matchAll(STANDARD_CALL)) {
-      found.push({
-        line: index + 1,
-        form: 'standard',
-        cited: match[1] ?? '',
-        preview,
-        marked,
-      })
-    }
-
     // A backticked span is the only carrier a rule writes a citation in. No
     // rule in either corpus uses a markdown link, and matching running prose
     // would report every sentence that happens to name a file.