@erclx/canon 5.32.0 → 5.33.0

package/src/design/render.ts

@@ -105,7 +105,7 @@ interface Confidence {
 }
 
 /**
- * The columns the confidence ratio reads, fixed by `standards/design.md`. The
+ * The columns the confidence ratio reads, fixed by `claude/skills/canvas-board/references/design.md`. The
  * first column of each table names its row, and `Multiplier` and `When used`
  * restate what the row already carries, so none of them is something a source
  * could anchor and none belongs in the denominator.

package/src/gate/measures.ts

@@ -317,7 +317,7 @@ export const designProse: Measure = async (ctx) => {
   if (failures.length > 0) {
     return {
       emissions: [],
-      failure: `${failures.join(' ')} Cut to the budget in standards/design.md, moving the why to the context entry.`,
+      failure: `${failures.join(' ')} Cut to the budget in claude/skills/canvas-board/references/design.md, moving the why to the context entry.`,
     }
   }
   if (emissions.length === 0)

package/src/gate/sequencer.ts

@@ -1,3 +1,5 @@
+import { readFileSync } from 'node:fs'
+import { availableParallelism } from 'node:os'
 import { join } from 'node:path'
 import { execa } from 'execa'
 import type {
@@ -44,6 +46,28 @@ export interface StageResult {
   readonly queuedMs?: number
 }
 
+export interface LoadReading {
+  /** The 1-minute load average. */
+  readonly loadAverage: number
+  readonly cores: number
+}
+
+/**
+ * Reads the 1-minute load average from `/proc/loadavg`. A platform without
+ * it, as macOS, has no reading to give, so this answers `undefined` rather
+ * than throwing into a stage that has already failed.
+ */
+export function readProcLoad(): LoadReading | undefined {
+  try {
+    const first = readFileSync('/proc/loadavg', 'utf8').split(' ')[0]
+    const loadAverage = Number.parseFloat(first)
+    if (!Number.isFinite(loadAverage)) return undefined
+    return { loadAverage, cores: availableParallelism() }
+  } catch {
+    return undefined
+  }
+}
+
 export interface GateContext extends MeasureContext {
   /** Whether the format stage writes or checks. */
   readonly write: boolean
@@ -58,6 +82,11 @@ export interface GateContext extends MeasureContext {
    * wait and reads as a hung suite.
    */
   readonly onQueue?: (label: string, holder: LockHolder) => void
+  /**
+   * Reads the machine load a failed locked stage ran under. Defaults to
+   * `/proc/loadavg`, and answers `undefined` where there is none.
+   */
+  readonly readLoad?: () => LoadReading | undefined
 }
 
 export interface ChangedSet {
@@ -195,7 +224,11 @@ async function executeStage(
         ]
 
   try {
-    const outcome = await runChecks(stage, ctx, queued)
+    const outcome = withLoadLine(
+      await runChecks(stage, ctx, queued),
+      stage,
+      ctx,
+    )
     return held.waitedOn === undefined
       ? outcome
       : { ...outcome, queuedMs: held.waitedMs }
@@ -204,6 +237,28 @@ async function executeStage(
   }
 }
 
+/**
+ * The lock serializes suites and does nothing about the rest of the box, so a
+ * starved spawn test and a real failure read alike. The load beside the
+ * failure is what lets a report tell them apart.
+ */
+function withLoadLine(
+  outcome: StageOutcome,
+  stage: Stage,
+  ctx: GateContext,
+): StageOutcome {
+  if (outcome.status !== 'failed') return outcome
+
+  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`
+  return {
+    ...outcome,
+    emissions: [...outcome.emissions, { kind: 'info', text }],
+  }
+}
+
 async function runChecks(
   stage: Stage,
   ctx: GateContext,

package/src/gate/stages.ts

@@ -198,17 +198,11 @@ export const STAGES: readonly Stage[] = [
         argv: ['gov', 'regen'],
         failure: 'Consumed-copy regen failed',
       },
-      {
-        kind: 'drift',
-        pathspec: 'governance/rules/standards',
-        failure:
-          'Standard-pointer rules drifted. Run bun run check and commit governance/rules/standards and .claude/rules.',
-      },
       {
         kind: 'drift',
         pathspec: '.claude/rules',
         failure:
-          'Consumed copies drifted. Run bun run check and commit governance/rules/standards and .claude/rules.',
+          'Consumed copies drifted. Run bun run check and commit .claude/rules.',
       },
     ],
     success: 'Consumed copies clean',

package/src/gov/install.ts

@@ -66,9 +66,8 @@ export function installedRuleNames(
 }
 
 /**
- * Mirrors `rule_subdir` in `scripts/lib/gov.sh`, which stays in bash for the
- * sandbox loops. A rule sitting directly under `governance/rules/` has no
- * subdirectory and installs flat.
+ * A rule sitting directly under `governance/rules/` has no subdirectory and
+ * installs flat.
  */
 export function ruleSubdir(src: string, rulesRoot: string): string {
   const subdir = dirname(relative(rulesRoot, src))

package/src/gov/stacks.ts

@@ -79,7 +79,7 @@ export function loadGovStack(
  * shape rather than two the caller has to tell apart.
  *
  * The directory wins over a rule file of the same name. They cannot collide
- * while `standards/rule.md` requires a numeric prefix on a rule slug, since a
+ * while `claude/skills/create-rule/references/rule.md` requires a numeric prefix on a rule slug, since a
  * band folder carries none.
  */
 export function expandStackEntry(root: string, entry: string): string[] {

package/src/hooks/post-merge.ts

@@ -163,7 +163,7 @@ function archiveLines(
   }
   return (
     `\n📋 Task not archived for #${number}: ${text(fields, 'message') ?? reason}\n` +
-    'Run /task-board to resolve it by hand.\n\n'
+    `Run /task-complete archive #${number} to resolve it by hand.\n\n`
   )
 }
 

package/src/labels/apply.ts

@@ -0,0 +1,39 @@
+/** What a label apply decided to do, before any write. */
+export interface LabelDiff {
+  /** Earned labels the pull request lacks and the remote carries, so addable. */
+  readonly toAdd: readonly string[]
+  /** Every earned label the pull request lacks, whether or not it is addable. */
+  readonly owed: readonly string[]
+  /** Owed labels the remote does not carry, which are reported and never created. */
+  readonly missingOnRemote: readonly string[]
+}
+
+/**
+ * Diffs what a branch earns against what its pull request already carries and
+ * what the remote can attach.
+ *
+ * The diff only adds. A label on the pull request that the map does not earn
+ * is a person's decision and never appears here, so nothing in the result can
+ * be turned into a removal. Order follows `earned`, which the map declares, so
+ * two runs over one branch produce one list.
+ *
+ * A label the remote lacks is separated from the addable set rather than
+ * dropped, because the REST add endpoint creates any label it is handed and
+ * that write to the repository settings is not the map's call.
+ */
+export function diffLabels(
+  earned: readonly string[],
+  present: readonly string[],
+  remote: readonly string[],
+): LabelDiff {
+  const has = new Set(present)
+  const carried = new Set(remote)
+
+  const owed = earned.filter((label) => !has.has(label))
+
+  return {
+    owed,
+    toAdd: owed.filter((label) => carried.has(label)),
+    missingOnRemote: owed.filter((label) => !carried.has(label)),
+  }
+}

package/src/labels/format.ts

@@ -1,5 +1,5 @@
 /**
- * Which rule in `standards/pr.md`'s `## Title` section a title breaks.
+ * Which rule in `claude/skills/git-pr/references/pr.md`'s `## Title` section a title breaks.
  *
  * `structure` stands alone rather than beside the other three, because a
  * title failing the shape match has no parsed `<type>`, `<scope>`, or
@@ -28,9 +28,9 @@ const LEADING_LETTERS = /^[A-Za-z]+/
 
 /**
  * Grades a pull request title, or a commit subject sharing the same form,
- * against `standards/pr.md`'s structure, casing, and length rules.
+ * against `claude/skills/git-pr/references/pr.md`'s structure, casing, and length rules.
  *
- * Does not check `<type>` against `standards/commit.md`'s fixed enum.
+ * Does not check `<type>` against `claude/skills/git-commit/references/commit.md`'s fixed enum.
  * `pr.md`'s own `## Title` section states format, casing, and length only,
  * and names no type list of its own to check against.
  */

package/src/labels/phase.ts

@@ -3,7 +3,7 @@ import { RECORD_ENTRIES, RECORD_ROOTS } from '@/roots/record'
 import type { RecordRoot } from '@/roots/record'
 
 /**
- * The two version namespaces `standards/versioning.md` keeps apart, and why a
+ * The two version namespaces `claude/skills/git-commit/references/versioning.md` keeps apart, and why a
  * pull request cannot be sorted between them by pattern alone.
  *
  * A phase label (`v68.5`) and a semver reference (`v3.44`) both match
@@ -186,7 +186,7 @@ const RELEASE_TITLE_PREFIX = 'chore(main): release '
  * phase label past this check. Together they name release-please's own act of
  * opening the pull request, which nothing else on the remote can perform.
  */
-function isReleasePullRequest(input: PhaseScanInput): boolean {
+export function isReleasePullRequest(input: PhaseScanInput): boolean {
   return (
     input.headRefName.startsWith(RELEASE_HEAD_PREFIX) &&
     input.title.startsWith(RELEASE_TITLE_PREFIX)
@@ -265,7 +265,7 @@ function sessionLinks(text: string): string[] {
  * The split runs on the pull request rather than on each token. A release
  * pull request's tokens are read as the semver references its generated body
  * legitimately carries, and every other pull request's tokens are read as
- * leaked phase labels, which is what `standards/versioning.md` names the
+ * leaked phase labels, which is what `claude/skills/git-commit/references/versioning.md` names the
  * defect this exists to catch.
  *
  * A release pull request reports no board reference either, and the ground is

package/src/labels/sections.ts

@@ -0,0 +1,43 @@
+import { linesOutsideFences } from '@/markdown/scan'
+
+/**
+ * The closed list of section headings a pull request body may carry, in the
+ * sentence case `claude/skills/git-pr/references/pr.md` states.
+ */
+const ALLOWED_HEADINGS: readonly string[] = [
+  '## Summary',
+  '## Key changes',
+  '## Technical context',
+  '## Testing',
+  '## For the reviewer',
+]
+
+const REQUIRED_HEADINGS: readonly string[] = ['## Summary', '## Key changes']
+
+const H2 = /^##\s/
+
+export interface SectionsCheck {
+  /** Level-two headings the closed list does not hold, as written. */
+  readonly outside: readonly string[]
+  /** Required headings the body never carries. */
+  readonly missing: readonly string[]
+}
+
+/**
+ * Grades the level-two headings of a pull request body against the closed list.
+ *
+ * The comparison is exact, so `## Key Changes` fails. `canon pr key-changes`
+ * reads its section case-insensitively, which keeps a body posted before the
+ * rename parsing while the scan holds new text to one spelling. Subheadings and
+ * fenced lines are not headings, so the list governs level two alone.
+ */
+export function checkSections(body: string): SectionsCheck {
+  const headings = linesOutsideFences(body)
+    .map((line) => line.trim())
+    .filter((line) => H2.test(line))
+
+  return {
+    outside: headings.filter((heading) => !ALLOWED_HEADINGS.includes(heading)),
+    missing: REQUIRED_HEADINGS.filter((heading) => !headings.includes(heading)),
+  }
+}

package/src/migrate/skill-names.ts

@@ -99,6 +99,25 @@ export const SKILL_NAME_MAP: Readonly<Record<string, string>> = {
   'draft-diagram': 'draft-figure',
 }
 
+/**
+ * The skills that took a two-word name from a single word, which the map above
+ * may not carry as a bare key.
+ *
+ * `canvas` became `canvas-board`, and a bare `canvas` key would rewrite every
+ * unrelated use of the word: `canon canvas serve`, `src/canvas/`,
+ * `.canon/canvas/`, and the `internal-canvas` skill. So each row keys on a form
+ * only the skill spells, a plugin invocation or a skill folder path. The tail
+ * guard rejects a following `-`, so a rewritten `canon:canvas-board` is not
+ * matched again.
+ *
+ * What this leaves behind is a prose mention of the skill by its bare name,
+ * which has no token for a sweep to find and is fixed by hand.
+ */
+export const SKILL_CITATION_MAP: Readonly<Record<string, string>> = {
+  'canon:canvas': 'canon:canvas-board',
+  'skills/canvas': 'skills/canvas-board',
+}
+
 /**
  * The skill rename.
  *
@@ -132,7 +151,7 @@ export const SKILL_NAME_MAP: Readonly<Record<string, string>> = {
  * listing every sweep reads never reaches them.
  */
 export const SKILL_NAME_RULES: RenameRules = defineRenameRules({
-  replacements: SKILL_NAME_MAP,
+  replacements: { ...SKILL_NAME_MAP, ...SKILL_CITATION_MAP },
   keepMarker: 'canon-keep-retired',
   wholeToken: true,
   excludedPrefixes: ['scripts/eval/result-'],

package/src/pr/paths.ts

@@ -3,12 +3,12 @@ import { findBacktickSpans } from '@/markdown/backticks'
 /**
  * The heading whose bullets state what a branch changed.
  *
- * Read alone, and never widened to a sibling section. `## Technical Context`
+ * Read alone, and never widened to a sibling section. `## Technical context`
  * legitimately names files a branch never touched, such as an install stamp
  * inside a target, so a reader that took the whole body would manufacture a
  * finding out of every argument the author made for the change.
  */
-export const KEY_CHANGES = 'Key Changes'
+export const KEY_CHANGES = 'Key changes'
 
 /** What one bullet claimed, kept with its bullet so a finding can quote it. */
 export interface PathClaim {
@@ -86,7 +86,7 @@ const BARE_LINE = /^:\d+(?:-\d+)?$/
  * `canon markdown audit .claude/rules --json` carries a slash and names no file.
  * Angle brackets answer a second, since `.canon/plans/feature-<slug>.md`
  * describes a shape rather than naming a file. A glob and a caret describe a
- * shape too, `^src/` being a grep pattern one body spelled in Key Changes, and
+ * shape too, `^src/` being a grep pattern one body spelled in Key changes, and
  * a leading anchor names something outside this repository.
  *
  * Deliberately not shared with `classifySpan` in `@/gov/citations`, which asks
@@ -307,7 +307,7 @@ function resolveSpan(span: string): ResolvedSpan | undefined {
 }
 
 /**
- * Every path the `## Key Changes` section claims a change to.
+ * Every path the `## Key changes` section claims a change to.
  *
  * `roots` names the entries the tree holds at its top level, which is what
  * separates a whole path from one written partially. It is passed in rather

package/src/records/backup.ts

@@ -30,7 +30,7 @@ import { type BlockedPath, guardPayload } from '@/records/push-guard'
  * rather than named here. That is what keeps this list at one line per surface
  * as archives spread, which a sibling-per-archive layout could not.
  *
- * `RECORD_KINDS` in `validate.ts` overlaps this on five names and carries one
+ * `RECORD_KINDS` in `validate.ts` overlaps this on four names and carries one
  * more that no backup reaches. The two lists differ on purpose: one is what a
  * standard governs, this is what a disk loss would take, and `standards` is
  * tracked so a backup would carry a second copy of committed files.
@@ -39,7 +39,6 @@ export const BACKED_FOLDERS = [
   'diagrams',
   'groundwork',
   'intake',
-  'memory',
   'plans',
   'proposals',
   'review',
@@ -51,6 +50,15 @@ export const BACKED_FOLDERS = [
   'walkthroughs',
 ] as const
 
+/**
+ * Folders a retired kind left at a legacy `.claude` root that the allowlist
+ * must still read, so a half-finished move that strands one still trips
+ * `split-roots`. Absent from `BACKED_FOLDERS` because nothing writes them, and
+ * absent from `RETIRED_FOLDERS` because that list stages a deletion and this
+ * folder is an archive to keep.
+ */
+const LEGACY_RECORD_FOLDERS = ['memory'] as const
+
 /**
  * Names that have left `BACKED_FOLDERS` and whose removal still has to reach a
  * records history once.
@@ -124,7 +132,9 @@ function isExcluded(name: string): boolean {
  */
 function foldersAt(dir: string): string[] {
   if (basename(dir) === '.claude') {
-    return BACKED_FOLDERS.filter((folder) => existsSync(join(dir, folder)))
+    return [...BACKED_FOLDERS, ...LEGACY_RECORD_FOLDERS].filter((folder) =>
+      existsSync(join(dir, folder)),
+    )
   }
 
   const entries = existsSync(dir)
@@ -378,7 +388,7 @@ async function enclosingRemotes(
  * Clears the four gates both verbs share and returns the records remote URL.
  *
  * The last two are the ones the payload depends on. This repository is public,
- * so a records branch on any of its remotes serves the memory pen and the
+ * so a records branch on any of its remotes serves the plans and the
  * groundwork trails to anyone who fetches all refs. Comparing the configured
  * URL against every remote of the enclosing repository is what keeps a
  * misconfigured `origin` from publishing them, and refusing when that list
@@ -416,7 +426,7 @@ async function resolveRemote(
   if (!enclosing) {
     return refuse(
       'remote-unreadable',
-      `Cannot read the remotes of the project at ${root}, so the records origin cannot be checked against them. Records carry the memory pen and the groundwork trails, and an unchecked origin risks publishing them.`,
+      `Cannot read the remotes of the project at ${root}, so the records origin cannot be checked against them. Records carry the plans and the groundwork trails, and an unchecked origin risks publishing them.`,
     )
   }
 
@@ -424,7 +434,7 @@ async function resolveRemote(
   if (enclosing.identities.includes(url)) {
     return refuse(
       'remote-shared',
-      `The records origin ${remote.text} is a remote of this project. Records carry the memory pen and the groundwork trails, so they need a repository of their own.`,
+      `The records origin ${remote.text} is a remote of this project. Records carry the plans and the groundwork trails, so they need a repository of their own.`,
     )
   }
 

package/src/records/stale-canonical.ts

@@ -3,7 +3,6 @@ import { existsSync } from 'node:fs'
 import { readFile } from 'node:fs/promises'
 import { relative } from 'node:path'
 import { gitEnv } from '@/git/env'
-import { readReviewed } from '@/records/stale'
 import { surfaceDir } from '@/roots/surface'
 
 /** The record whose drift is identity rather than a stale path. */
@@ -22,6 +21,37 @@ export interface CanonicalDoc {
   readonly latestRelease: string | null
 }
 
+const REVIEWED_FIELD = /^reviewed:[ \t]*(.*?)[ \t]*$/m
+const ISO_DATE = /^\d{4}-\d{2}-\d{2}$/
+const RAW_FRONTMATTER = /^---\n([\s\S]*?)\n---/
+
+/**
+ * Reads `reviewed` off the raw block rather than the parsed fields, for the
+ * reason `hasOpeningDate` in the validator gives: a YAML parser resolves a
+ * bare `YYYY-MM-DD` to a date on one schema and a string on another.
+ *
+ * A value that is not a calendar date reads as never reviewed and is carried
+ * back so the review can see it, rather than throwing over one hand edit.
+ */
+function readReviewed(
+  text: string,
+): Pick<CanonicalDoc, 'reviewed' | 'invalidReviewed'> {
+  const block = RAW_FRONTMATTER.exec(text)?.[1]
+  const match = block ? REVIEWED_FIELD.exec(block) : null
+  if (!match) return { reviewed: null }
+
+  const value = match[1].replace(/^(['"])(.*)\1$/, '$2')
+  const parsed = Date.parse(`${value}T00:00:00Z`)
+  const isDate =
+    ISO_DATE.test(value) &&
+    Number.isFinite(parsed) &&
+    new Date(parsed).toISOString().slice(0, 10) === value
+
+  return isDate
+    ? { reviewed: value }
+    : { reviewed: null, invalidReviewed: value }
+}
+
 export interface CanonicalReport {
   readonly ok: true
   readonly root: string