@erclx/canon 5.36.0 → 5.37.0

package/docs/workflow/visual-design-workflow.md

@@ -35,9 +35,14 @@ A record generated from a token source carries the values in tables instead, whi
 
 ### Skills
 
+#### Reviewing and measuring
+
 - `canon:ui-checklist` for what a reviewer has to look at after UI changes, and what ships without a test
 - `canon:ux-audit` for UX gap detection on existing surfaces
 - `canon:ux-measure` for what a running surface costs to paint, read against published thresholds
+
+#### Drafting
+
 - `canon:draft-and-pick` for a call settled by looking, drafting several candidates as frames on the canvas and taking your pick
 - `canon:canvas-board` for a direction worked out over several turns, drawn as HTML frames you drag, select, and restyle in the browser while the session reads your changes back. Only the pick moves into `canon/DESIGN.md`, since the canvas folder is gitignored
 - `canon:draft-identity` to draft a project's logo mark and compose it into an icon sequence and a social card, through `draft-and-pick`'s own render-and-pick loop. On an Astro project holding the card route scaffold, the card lands as a route the project keeps and is captured through a running server, so it reads the project's real stylesheet rather than typed copies of every color. Everywhere else it ships as a PNG and the run says so.

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@erclx/canon",
   "type": "module",
-  "version": "5.36.0",
+  "version": "5.37.0",
   "description": "Runs your agent's work and keeps its code good, on one setup for every repo.",
   "license": "MIT",
   "bin": {
@@ -32,7 +32,7 @@
     "test": "bun --bun vitest run",
     "prepare": "husky",
     "check": "bun src/cli.ts gate run",
-    "check:ci": "bun src/cli.ts gate run --all --no-write",
+    "check:ci": "bun src/cli.ts gate run --all",
     "update": "bun update --interactive && bun run check",
     "clean": "rm -rf node_modules && bun pm cache rm && bun install",
     "bootstrap": "./scripts/core/bootstrap.sh",

package/src/cli/help.ts

@@ -130,7 +130,7 @@ const EXAMPLES = [
   'canon labels audit --json',
   'canon census --json',
   'canon audits run --json',
-  'canon gate run --all --no-write',
+  'canon gate run --all',
   'canon upgrade --json',
   'canon upstream fetch --since 2.1.256 --json',
 ]

package/src/commands/context.ts

@@ -11,11 +11,14 @@ import {
   LENGTH_CHECKPOINT,
   matchesSiblings,
   measureFolders,
+  extraSections,
   missingSections,
   PROVENANCE_FOLDER,
+  ALLOWED_SECTIONS_BY_FOLDER,
   REQUIRED_SECTIONS,
   REQUIRED_SECTIONS_BY_FOLDER,
   requiredSections,
+  type ExtraSectionFinding,
   type SectionFinding,
 } from '@/context/audit'
 import { auditCitations, type CitationReport } from '@/context/citations'
@@ -640,6 +643,7 @@ async function runAudit(
   const entries = gateOnly ? [] : await measureFolders(root, folders)
   const drift = gateOnly ? [] : await auditIndexes(folders)
   const sections = gateOnly ? [] : missingSections(root, folders, entries)
+  const extras = gateOnly ? [] : extraSections(entries)
   const length = gateOnly ? undefined : lengthFindings(entries)
   // Absent under `--citations-only` and null when the project carries no
   // record. A run that never looked and a project with nothing to look at are
@@ -653,7 +657,7 @@ async function runAudit(
     reportScope(folders, unresolved)
     reportCitations(citations, cited)
     reportReferenceForm(entries, folders)
-    reportSections(sections, folders)
+    reportSections(sections, extras, folders)
     reportLength(length ?? [])
     reportTables(entries)
     reportProvenance(entries, folders)
@@ -691,6 +695,7 @@ async function runAudit(
         // never opened an entry.
         length,
         missingSections: sections,
+        extraSections: extras,
         indexDrift: drift,
         // Null says the run opened the project and found no record, which a
         // target that never wrote one is entitled to. Absent says the run
@@ -705,6 +710,7 @@ async function runAudit(
           // caller that read it first, since removing it would break that
           // caller without an error.
           requiredSectionsByFolder: REQUIRED_SECTIONS_BY_FOLDER,
+          allowedSectionsByFolder: ALLOWED_SECTIONS_BY_FOLDER,
         },
       })}\n`,
     )
@@ -715,6 +721,7 @@ async function runAudit(
     requirementsOverWords:
       requirements !== undefined && isOverWordCap(requirements),
     sections,
+    extraSections: extras,
     drift,
     widened,
   })
@@ -905,6 +912,7 @@ function reportReferenceForm(
  */
 function reportSections(
   missing: readonly SectionFinding[],
+  extras: readonly ExtraSectionFinding[],
   folders: readonly AuditedFolder[],
 ): void {
   logStep('Sections')
@@ -938,13 +946,30 @@ function reportSections(
 
   if (missing.length === 0) {
     logInfo('Every entry declares each required section.')
+  } else {
+    logWarn(`${plural(missing.length, 'path')} short a required section`)
+    pipeOutput(
+      missing
+        .map((found) => `${found.rel}  missing: ${found.missing.join(', ')}`)
+        .join('\n'),
+    )
+  }
+
+  logInfo(
+    `The set is closed: ${Object.entries(ALLOWED_SECTIONS_BY_FOLDER)
+      .map(([name, set]) => `canon/${name}/ allows ${set.join(', ')}`)
+      .join('. ')} as H2. Any other topic is an H3 under one of them.`,
+  )
+
+  if (extras.length === 0) {
+    logInfo('No entry carries an H2 outside the set.')
     return
   }
 
-  logWarn(`${plural(missing.length, 'path')} short a required section`)
+  logWarn(`${plural(extras.length, 'path')} carrying an H2 outside the set`)
   pipeOutput(
-    missing
-      .map((found) => `${found.rel}  missing: ${found.missing.join(', ')}`)
+    extras
+      .map((found) => `${found.rel}  extra: ${found.headings.join(', ')}`)
       .join('\n'),
   )
 }

package/src/commands/gate.ts

@@ -27,7 +27,6 @@ import { repairBareFlag } from '@/worktrees/bare-flag'
 
 interface RunCommandOptions {
   readonly all?: boolean
-  readonly write?: boolean
   readonly nested?: boolean
   readonly json?: boolean
 }
@@ -48,10 +47,6 @@ export function register(program: Command): void {
       '--all',
       'Run every stage instead of scoping shell, types, and tests to changed files',
     )
-    .option(
-      '--no-write',
-      'Check formatting instead of applying it, which is what a merge gate wants',
-    )
     .option(
       '--nested',
       'Suppress the outer frame when another script opened one',
@@ -77,7 +72,7 @@ export function register(program: Command): void {
         '',
         'Examples:',
         '  canon gate run',
-        '  canon gate run --all --no-write',
+        '  canon gate run --all',
         '  canon gate run --json',
         '',
       ].join('\n'),
@@ -92,7 +87,6 @@ async function runGate(opts: RunCommandOptions): Promise<number> {
   const mismatch = checkoutMismatchWarning(process.cwd())
   const emitJson = opts.json ?? false
   const nested = opts.nested ?? false
-  const write = opts.write ?? true
   const run = commandRunner(root)
 
   if (!emitJson && !nested) intro('canon gate run')
@@ -111,7 +105,6 @@ async function runGate(opts: RunCommandOptions): Promise<number> {
     ci: process.env.CI === 'true',
     run,
     cli: cliRunner(root),
-    write,
     changed: changed.scoped ? changed.files : undefined,
     onQueue: (label, holder) => {
       const text = `${label} is waiting for the suite pid ${holder.pid} runs at ${holder.root}`

package/src/commands/markdown.ts

@@ -18,6 +18,7 @@ import {
   bodyLines,
   scanBans,
 } from '@/markdown/scan'
+import { bulletStacks, CAP, type StackFinding } from '@/markdown/stacks'
 import {
   BASELINE,
   CHECKPOINTS,
@@ -59,6 +60,7 @@ interface FileReport {
   readonly links: readonly LinkFinding[]
   readonly colons: readonly ColonFinding[]
   readonly headingCase: readonly HeadingCaseFinding[]
+  readonly bulletStacks: readonly StackFinding[]
   readonly structure: StructureReport
   readonly renderedLines: number
   /** The stated reason, or null where the document is not exempt. */
@@ -101,6 +103,10 @@ export function register(program: Command): void {
         'report the same way. A proper noun is the one case the second cannot',
         'tell from title case, and the first is sometimes right.',
         '',
+        'Bullet stacks report a run of more than 5 plain bullets under one',
+        'heading and never exit 2. The Bullet stacks gate stage owns that',
+        'verdict, for the reason the length line below states.',
+        '',
         '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',
@@ -178,6 +184,7 @@ async function runAudit(
         bans: scanBans(lines, bans),
         colons: advisory ? findColons(lines) : [],
         headingCase: advisory ? findHeadingCase(source) : [],
+        bulletStacks: advisory ? bulletStacks(lines) : [],
         links: findBrokenLinks(lines, (path) =>
           existsSync(resolve(dirname(abs), path)),
         ),
@@ -194,6 +201,7 @@ async function runAudit(
   reportLinks(reports, root)
   reportColons(reports)
   reportHeadingCase(reports)
+  reportStacks(reports)
   reportBullets(reports, checkpoints)
   reportParagraphs(reports, checkpoints)
   reportCadence(reports, checkpoints)
@@ -229,6 +237,7 @@ async function runAudit(
           links: report.links,
           colons: report.colons,
           headingCase: report.headingCase,
+          bulletStacks: report.bulletStacks,
           longestRun: report.structure.longestRun,
           longestRunLine: report.structure.longestRunLine,
           heavyBullets: report.structure.heavyBullets,
@@ -251,6 +260,7 @@ async function runAudit(
     structure: reports.map((report) => report.structure),
     colons: reports.flatMap((report) => report.colons),
     headingCase: reports.flatMap((report) => report.headingCase),
+    bulletStacks: reports.flatMap((report) => report.bulletStacks),
   })
 
   return gating ? EXIT_GATE : 0
@@ -404,6 +414,48 @@ function reportLinks(reports: readonly FileReport[], root: string): void {
   )
 }
 
+function reportStacks(reports: readonly FileReport[]): void {
+  logStep('Bullet stacks')
+  logInfo(
+    `A run of more than ${CAP} top-level bullets, with no paragraph or heading between them.`,
+  )
+  logInfo(
+    'A run whose every item opens with a bold label or a link is exempt. This never fails a run. The Bullet stacks gate stage owns that verdict.',
+  )
+
+  const carrying = reports
+    .filter((report) => report.bulletStacks.length > 0)
+    .sort((a, b) => longestStack(b) - longestStack(a))
+
+  if (carrying.length === 0) {
+    logInfo(`No run past ${CAP} bullets.`)
+    return
+  }
+
+  const total = carrying.reduce(
+    (sum, report) => sum + report.bulletStacks.length,
+    0,
+  )
+  logWarn(`${plural(total, 'stack')} across ${plural(carrying.length, 'file')}`)
+  logInfo(
+    'Fold the run into prose, give each item an H3, or split the list at its seam.',
+  )
+  pipeOutput(
+    carrying
+      .map(
+        (report) =>
+          `${report.rel}  ${plural(report.bulletStacks.length, 'stack')}\n${report.bulletStacks
+            .map((found) => `  :${found.line}  ${found.count} bullets`)
+            .join('\n')}`,
+      )
+      .join('\n'),
+  )
+}
+
+function longestStack(report: FileReport): number {
+  return Math.max(0, ...report.bulletStacks.map((found) => found.count))
+}
+
 function reportColons(reports: readonly FileReport[]): void {
   logStep('Colons')
   logInfo(

package/src/commands/pr.ts

@@ -44,7 +44,7 @@ import {
   settleChecklist,
 } from '@/pr/evidence'
 import {
-  dropFrames,
+  dropFramesWithLegacy,
   FRAMES_BRANCH,
   type FramesApi,
   type FramesRefusal,
@@ -53,7 +53,8 @@ import {
   isFrameHead,
   isFramePass,
   isFrameTheme,
-  pruneFrames,
+  LEGACY_FRAMES_BRANCH,
+  pruneFramesWithLegacy,
   pushFrame,
   readFrame,
   type TreeEntry,
@@ -933,7 +934,7 @@ export function register(program: Command): void {
       'after',
       [
         '',
-        `Writes only refs/heads/${FRAMES_BRANCH}, through the GitHub git data API,`,
+        `An add writes only refs/heads/${FRAMES_BRANCH}, through the GitHub git data API,`,
         'so nothing is checked out and no other branch is touched. A frame lands',
         'at pr-<number>/<short-head>/<pass>/box-<n>.png, or box-<n>-<theme>.png',
         'with --theme, and `link` names that',
@@ -948,6 +949,11 @@ export function register(program: Command): void {
         'request still open, reopened, closed exactly the given days ago, or one',
         'whose state could not be read, listing that last kind under `unread`.',
         '',
+        `Both also drain the ${LEGACY_FRAMES_BRANCH} branch a rename left behind,`,
+        'removing only, and carry `legacy: true` when it changed. --prune empties',
+        'it as its pull requests expire, and --drop clears one pull request at',
+        'once. An add never writes it.',
+        '',
         'Read `reason` on the JSON record:',
         '  ok                an add pushed, or a drop or prune finished',
         '  bad-mode          not exactly one of --add, --drop, --prune',
@@ -2876,13 +2882,13 @@ function isTreeEntry(value: unknown): value is TreeEntry {
  * that already exists or no longer does, which is another writer's doing and
  * worth a re-read rather than a failure.
  */
-function ghFramesApi(call: ApiCaller): FramesApi {
-  const ref = `git/refs/heads/${FRAMES_BRANCH}`
+function ghFramesApi(call: ApiCaller, branch: string): FramesApi {
+  const ref = `git/refs/heads/${branch}`
   const refWrite = (result: ApiCall) =>
     result.ok ? 'ok' : result.status === 422 ? 'conflict' : 'failed'
   return {
     async readTip() {
-      const head = await call('GET', `git/ref/heads/${FRAMES_BRANCH}`)
+      const head = await call('GET', `git/ref/heads/${branch}`)
       if (!head.ok) {
         return head.status === 404
           ? { kind: 'missing' }
@@ -2937,7 +2943,7 @@ function ghFramesApi(call: ApiCaller): FramesApi {
     async createRef(commit) {
       return refWrite(
         await call('POST', 'git/refs', {
-          ref: `refs/heads/${FRAMES_BRANCH}`,
+          ref: `refs/heads/${branch}`,
           sha: commit,
         }),
       )
@@ -3034,7 +3040,8 @@ async function runFrames(
 
   if (Bun.which('gh') === null) return refuseFrames('gh-missing')
   const runner = ghApiRunner(root)
-  const api = ghFramesApi(runner.call)
+  const api = ghFramesApi(runner.call, FRAMES_BRANCH)
+  const legacyApi = ghFramesApi(runner.call, LEGACY_FRAMES_BRANCH)
   const refuseWrite = (reason: FramesRefusal) =>
     refuseFrames(
       reason === 'push-failed' && runner.refusedWrites.length > 0
@@ -3059,7 +3066,7 @@ async function runFrames(
 
   if (opts.prune !== undefined) {
     const days = Number(opts.prune)
-    const result = await pruneFrames(api, days, new Date())
+    const result = await pruneFramesWithLegacy(api, legacyApi, days, new Date())
     if (result.kind === 'refused') return refuseWrite(result.reason)
     const { kind: _kind, ...rest } = result
     return finish({ days, ...rest }, [
@@ -3072,7 +3079,7 @@ async function runFrames(
 
   const pull = Number(number)
   if (opts.drop === true) {
-    const result = await dropFrames(api, [pull])
+    const result = await dropFramesWithLegacy(api, legacyApi, [pull])
     if (result.kind === 'refused') return refuseWrite(result.reason)
     const { kind: _kind, ...rest } = result
     return finish({ number: pull, ...rest }, [

package/src/context/audit.ts

@@ -63,6 +63,22 @@ export const REQUIRED_SECTIONS_BY_FOLDER: Readonly<
   context: ['Overview', 'Layout'],
 }
 
+/**
+ * The closed set of H2 sections per audited folder name, which a required
+ * section belongs to. An entry carrying another H2 is a finding under
+ * `--gate`, since the set is what makes a context entry cheap to find a fact
+ * in: a domain's own topic names go one level down as H3 items under
+ * `Decisions` and `Gotchas`.
+ *
+ * Held beside the required lists for the same reason they are held here, and
+ * keyed on the folder whose standard states it.
+ */
+export const ALLOWED_SECTIONS_BY_FOLDER: Readonly<
+  Record<string, readonly string[]>
+> = {
+  context: ['Overview', 'Layout', 'Decisions', 'Gotchas'],
+}
+
 /**
  * The context standard's list, kept as its own export because the audit record
  * has published it flat under `checkpoints.requiredSections` since before any
@@ -225,6 +241,12 @@ export interface EntryReport {
    * is `missingSections`, since one entry answers for its siblings.
    */
   readonly sections: readonly string[]
+  /**
+   * H2 headings outside the folder's closed set, in document order, and empty
+   * outside a folder whose standard states one. What the folder carries in
+   * all is `extraSections`.
+   */
+  readonly otherSections: readonly string[]
   /**
    * Whether the file declares itself a skeleton, which excludes it from the
    * section check alone. Every other measure still reads it, since a stub is
@@ -281,6 +303,13 @@ export interface LengthFinding {
   readonly causes: readonly LengthCause[]
 }
 
+export interface ExtraSectionFinding {
+  /** Repo-relative path of the entry carrying the headings. */
+  readonly rel: string
+  /** H2 headings outside the closed set, never empty. */
+  readonly headings: readonly string[]
+}
+
 export interface SectionFinding {
   /**
    * Repo-relative path of whatever owes the sections: the entry itself in the
@@ -442,6 +471,33 @@ function declaredSections(
   return required.filter((section) => found.has(section))
 }
 
+const H2_TEXT = /^##\s+(.+?)\s*$/
+
+/**
+ * Finds the H2 headings outside the allowed set.
+ *
+ * H2 only, since the set closes the sections of an entry and says nothing of
+ * where its H3 items sit. Fenced blocks are skipped, so a template quoted
+ * inside an example declares nothing about the entry quoting it.
+ */
+function otherSections(
+  lines: readonly BodyLine[],
+  allowed: readonly string[],
+): string[] {
+  if (allowed.length === 0) return []
+
+  const found: string[] = []
+
+  for (const line of lines) {
+    if (line.fenced) continue
+
+    const match = line.text.match(H2_TEXT)
+    if (match && !allowed.includes(match[1])) found.push(match[1])
+  }
+
+  return found
+}
+
 /**
  * Finds the references naming a sibling entry by bare filename.
  *
@@ -500,6 +556,7 @@ export function measureEntry(
   governsContent = true,
   siblings: readonly string[] = [],
   required: readonly string[] = governsContent ? REQUIRED_SECTIONS : [],
+  allowed: readonly string[] = [],
 ): EntryReport {
   const lines = bodyLines(source)
 
@@ -510,6 +567,7 @@ export function measureEntry(
     provenance: governsContent ? provenance(lines) : [],
     bareReferences: bareReferences(lines, siblings),
     sections: declaredSections(lines, required),
+    otherSections: otherSections(lines, allowed),
     stub: isStubSeed(source),
     governed: governsContent,
   }
@@ -589,6 +647,7 @@ export async function measureFolders(
           governsContent(folder),
           names.filter((name) => name !== self),
           requiredSections(folder),
+          allowedSections(folder),
         ),
       )
     }
@@ -609,6 +668,13 @@ export function requiredSections(folder: AuditedFolder): readonly string[] {
     : []
 }
 
+/** Names the H2 sections the folder's standard allows, empty where it states no set. */
+export function allowedSections(folder: AuditedFolder): readonly string[] {
+  return Object.hasOwn(ALLOWED_SECTIONS_BY_FOLDER, folder.name)
+    ? ALLOWED_SECTIONS_BY_FOLDER[folder.name]
+    : []
+}
+
 /**
  * Reports whether a bare sibling name here is a reference by construction.
  *
@@ -688,3 +754,20 @@ export function missingSections(
 
   return findings
 }
+
+/**
+ * Names each entry carrying an H2 outside its folder's closed set.
+ *
+ * Per entry rather than per folder, unlike `missingSections`: a split folder's
+ * entries each answer for their own headings, since an extra section is a fact
+ * about the file it sits in. A stub seed is dropped for the reason
+ * `missingSections` drops one, a skeleton being exempt from the shape rather
+ * than from being well formed.
+ */
+export function extraSections(
+  entries: readonly EntryReport[],
+): ExtraSectionFinding[] {
+  return entries
+    .filter((entry) => !entry.stub && entry.otherSections.length > 0)
+    .map((entry) => ({ rel: entry.rel, headings: entry.otherSections }))
+}

package/src/context/classify/prompts.ts

@@ -2,7 +2,10 @@
  * System prompts and user-message builders for the model layer, ported
  * verbatim as data from the groundwork spike at
  * `.canon/groundwork/93-canonical-doc-drift/scripts/prompts/v3.md` (diff
- * mode) and `sweep-v1.md` (sweep mode). Neither prompt text is invented here.
+ * mode) and `sweep-v1.md` (sweep mode). The diff prompt is verbatim. The sweep
+ * prompt was tuned past `sweep-v1.md` with one decision check, measured
+ * against the groundwork's labelled set in
+ * `canon/context/context-model/overview.md`.
  *
  * Each prompt already states its own rules per canonical doc type inside one
  * string, which is the shape the spike measured, so there is one prompt per
@@ -45,6 +48,8 @@ Decision checks, in order:
 1. Judge what the text says, not how long it is. A long section that states current design once is KEEP.
 2. A trailing "Measured at <sha> on <date>" does not make a paragraph current if another paragraph in the section states an older value on the same subject.
 3. Short rationale for a current rule ("the form checks length itself because...") is KEEP. A story of the rounds that produced the rule is REWRITE.
+4. Rationale is KEEP even when it is told in the past tense. A reason naming why an alternative was left out, what an earlier approach got wrong, what a measurement caught, or what a past run cost is the evidence for the current rule, so a sentence such as "the first form timed out" or "two runs took 1281s and 1924s" or "reading figures from real data caught three wrong claims" supports a rule that stands and stays KEEP. Past tense alone is never the test.
+5. REWRITE needs the section to restate its own subject as a sequence: a superseded figure kept beside its replacement, "now" or "no longer" marking a change, branch or PR narration, or rounds of candidates. A maintenance step or an operator decision stated as a rule is current, not history.
 
 Return only JSON: {"verdict": "...", "quotes": ["<up to three short phrases copied from the section that decided it>"], "reason": "<one sentence>"}
 `

package/src/context/gate.ts

@@ -1,4 +1,4 @@
-import type { SectionFinding } from '@/context/audit'
+import type { ExtraSectionFinding, SectionFinding } from '@/context/audit'
 import type { FolderDrift } from '@/context/index-drift'
 
 export interface GateInput {
@@ -13,6 +13,8 @@ export interface GateInput {
    */
   readonly requirementsOverWords: boolean
   readonly sections: readonly SectionFinding[]
+  /** H2 headings outside a folder's closed set, gating under `--gate` alone. */
+  readonly extraSections: readonly ExtraSectionFinding[]
   readonly drift: readonly FolderDrift[]
   /**
    * Whether the caller asked for the widened gate. False leaves a missing
@@ -36,7 +38,7 @@ export function hasDrift(drift: readonly FolderDrift[]): boolean {
  * does a requirements record past its own word cap: the record states its rule
  * for itself, which makes it a fact rather than a threshold a reader weighs. The findings `--gate` adds are
  * the ones answerable from the file itself: a required section it does not
- * declare, and an index disagreeing with its folder. Entry length, depth, bullet,
+ * declare, an H2 outside the closed set, and an index disagreeing with its folder. Entry length, depth, bullet,
  * table, provenance, and the record's claim coverage are judgments, so they
  * stay out under both modes.
  */
@@ -44,6 +46,7 @@ export function isGating({
   unresolvedCitations,
   requirementsOverWords,
   sections,
+  extraSections,
   drift,
   widened,
 }: GateInput): boolean {
@@ -51,5 +54,5 @@ export function isGating({
   if (requirementsOverWords) return true
   if (!widened) return false
 
-  return sections.length > 0 || hasDrift(drift)
+  return sections.length > 0 || extraSections.length > 0 || hasDrift(drift)
 }