@erclx/canon 5.45.0 → 5.46.0

package/docs/agents/markdown-audit.md

@@ -22,14 +22,14 @@ An argument is a file, a directory, or a glob, taken against the corpus git list
 
 The ban set and checkpoints ship in `src/markdown/bans.ts` and `src/markdown/structure.ts`. `markdown.md` states each rule and the `write-human` skill states the cadence numbers, so move a number in both places in one change.
 
-| Finding         | Reports                                                                              | Gates                     |
-| --------------- | ------------------------------------------------------------------------------------ | ------------------------- |
-| Bans            | The two characters `markdown.md` bans, outside frontmatter, fences, spans, and links | Always                    |
-| Links           | A relative link resolving to nothing on disk                                         | Always                    |
-| Density         | The six limits below, under `density`                                                | On a `GATED_PATHS` prefix |
-| Reference shape | A `kind: reference` page breaking its shape, under `referenceShape`                  | On a `GATED_PATHS` prefix |
-| Colons          | A colon followed by more text in a prose line, under `colons`                        | Never                     |
-| Heading case    | A capital after the first word of a heading or `title`, under `headingCase`          | Never                     |
+| Finding         | Reports                                                                              | Gates             |
+| --------------- | ------------------------------------------------------------------------------------ | ----------------- |
+| Bans            | The two characters `markdown.md` bans, outside frontmatter, fences, spans, and links | Always            |
+| Links           | A relative link resolving to nothing on disk                                         | Always            |
+| Density         | The six limits below, under `density`                                                | On a gated prefix |
+| Reference shape | A `kind: reference` page breaking its shape, under `referenceShape`                  | On a gated prefix |
+| Colons          | A colon followed by more text in a prose line, under `colons`                        | Never             |
+| Heading case    | A capital after the first word of a heading or `title`, under `headingCase`          | Never             |
 
 A page marked `kind: reference` holds its opening, then `Output`, `Refusals`, and `See also` as H2s, each at most once and in that order. It takes no H3 and no table headed `Flag` or `Option`. An unmarked page is never measured.
 
@@ -46,9 +46,14 @@ A page marked `kind: reference` holds its opening, then `Output`, `Refusals`, an
 - A table, fence, list, heading, or bold section marker ends a run of paragraphs
 - A run whose every item opens with a bold label or a link is exempt, and numbered items never count
 - Only context entries, docs, skill bodies, references, and requirements, tooling seeds and stack references, the wiki, `README.md`, and `CONTRIBUTING.md` take a finding
-- A bullet run gates on those paths, and the rest gates under `GATED_PATHS` in `src/markdown/scope.ts`. Outside a canon checkout nothing gates.
+- A requirement gates only once the gated list below names its own file, never through its skill's prefix and never on a bullet run alone
 
-A requirement is the one exception to both. It gates only once `GATED_PATHS` names its own file, never through its skill's prefix and never on a bullet run alone.
+| Root              | A density or reference shape finding gates                                                                 |
+| ----------------- | ---------------------------------------------------------------------------------------------------------- |
+| Canon's checkout  | Under a `GATED_PATHS` prefix in `src/markdown/scope.ts`, and a bullet run on every density path above      |
+| Any other project | Under a prefix `canon/config/markdown.toml` lists, a bullet run included. With no such file nothing gates. |
+
+A project's list grows through `canon markdown gated add <prefix>`, which appends a folder only once it carries no finding, and `canon init` starts a new project with every root that passes already listed. A config that does not parse refuses the audit with its path named.
 
 Five measures report and never set the exit code on their own.
 

package/docs/target/projects.md

@@ -72,6 +72,8 @@ The default is `base`. Escalate only for a project writing code, and `target-set
 
 `canon init` installs base tooling, the Claude workflow, and governance. Pass `--stack <name>` for a language stack.
 
+Init then lists each markdown root that already passes the density limits in `canon/config/markdown.toml`, so those folders fail a push from the start. A root carrying a finding is named and left out, and `canon:document-repair` brings it to zero later. An existing config is kept as it is.
+
 - `--skip governance` leaves `.claude/rules/` empty. The run prints the `canon gov install <stack> <path>` command that restores the rules it dropped.
 
 ## Add a domain later

package/docs/workflow/skill-map.md

@@ -99,8 +99,9 @@ Groups run in the order a project meets them. Every name `canon claude skills li
 
 ## Keep the project current with the toolkit
 
-| Skill                         | When to use                                          |
-| ----------------------------- | ---------------------------------------------------- |
-| `canon:target-check`          | In a target, to compare each domain with the toolkit |
-| `canon:canon-feedback`        | The toolkit is broken, missing, or off               |
-| `canon:canon-feedback-triage` | In the toolkit repo, to file feedback issues         |
+| Skill                         | When to use                                             |
+| ----------------------------- | ------------------------------------------------------- |
+| `canon:target-check`          | In a target, to compare each domain with the toolkit    |
+| `canon:document-repair`       | Rewrite a failing docs folder to the limits and gate it |
+| `canon:canon-feedback`        | The toolkit is broken, missing, or off                  |
+| `canon:canon-feedback-triage` | In the toolkit repo, to file feedback issues            |

package/governance/renames.toml

@@ -15,7 +15,6 @@
 # file.
 [renamed]
 "015-output" = "566-output"
-"035-tasks" = "602-tasks"
 "055-scratch" = "604-scratch"
 "085-worktrees" = "605-worktrees"
 "087-git" = "606-git"
@@ -32,7 +31,6 @@
 "655-tasks" = "tasks"
 "570-skill" = "skill"
 "801-markdown" = "markdown"
-"602-tasks" = "task-scope"
 "604-scratch" = "scratch"
 "605-worktrees" = "worktrees"
 "606-git" = "git"

package/governance/rules/claude/output.md

@@ -1,5 +1,5 @@
 ---
-description: Report file paths correctly for the reading surface and group them when the response covers many
+description: Report file paths correctly for the reading surface, group them when the response covers many, and name sessions to a person
 ---
 
 # Output standards
@@ -17,3 +17,7 @@ description: Report file paths correctly for the reading surface and group them
 
 - Group paths under `**Created:**`, `**Modified:**`, and `**Deleted:**` headers when the response covers multiple files, with every path under them in that form.
 - Put a single-file change's path on its own line, with no header.
+
+## Naming sessions
+
+- Name a session to a person by its roster name from `canon sessions list`, and give its id only beside the name, never alone.

package/governance/rules/code/routing.md

@@ -1,5 +1,5 @@
 ---
-description: Routes code placement and shape decisions to the skills that carry them
+description: Routes code placement and shape decisions to the skills that carry them, and library calls to the official docs
 ---
 
 # Code standards
@@ -11,3 +11,7 @@ description: Routes code placement and shape decisions to the skills that carry
 ## Shape
 
 - Load the `canon:code-craft` skill before deciding the shape of a new function, class, or module, and report it rather than proceeding silently when it does not resolve.
+
+## Libraries
+
+- Before calling a library API the codebase does not already use, fetch the official docs for the installed version and match the call to them, since recall of an API goes stale.

package/governance/stacks/base.toml

@@ -4,7 +4,6 @@ extends = ""
 # `canon gov detect`. Every other rule is opt-in.
 rules = [
   "output",
-  "task-scope",
   "scratch",
   "worktrees",
   "git",

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@erclx/canon",
   "type": "module",
-  "version": "5.45.0",
+  "version": "5.46.0",
   "description": "Runs your agent's work and keeps its code good, on one setup for every repo.",
   "license": "MIT",
   "bin": {

package/src/claude/cases/workflow.ts

@@ -146,6 +146,18 @@ export const WORKFLOW_CASES: readonly SkillCase[] = [
       'Are our requirements and architecture docs still true, and when were they last reviewed?',
     expect: 'document-health',
   },
+  // A repair rather than a report, and folder by folder until each gates,
+  // which is what separates it from `document-health` above.
+  {
+    prompt:
+      'Our docs folder fails the paragraph and bullet limits everywhere, so rewrite it until it passes and lock it in.',
+    expect: 'document-repair',
+  },
+  {
+    prompt:
+      'Bring the context entries under the density limits one folder at a time and gate each once it is clean.',
+    expect: 'document-repair',
+  },
   {
     prompt: 'Open a new entry on the task board for this piece of work.',
     expect: 'task-board',

package/src/commands/context.ts

@@ -56,6 +56,11 @@ import {
   presentNames,
   resolveFolders,
 } from '@/context/folders'
+import {
+  type CoverageReport,
+  measureCoverage,
+  readRoots,
+} from '@/context/coverage'
 import { isGating } from '@/context/gate'
 import { isShapeGated, SHAPE_GATED_FOLDERS } from '@/context/shape-gated'
 import { currentWorktreeRoot } from '@/git/worktree'
@@ -101,7 +106,7 @@ export function register(program: Command): void {
   context
     .command('audit')
     .description(
-      'Report required sections, entry length, citations, reference form, catalog tables, provenance, index drift, and the requirements record against its own word cap',
+      'Report required sections, entry length, citations, reference form, catalog tables, provenance, index drift, code folders no entry names, and the requirements record against its own word cap',
     )
     .argument('[path]', 'Project root, defaulting to the current directory')
     .helpOption('-h, --help', 'Show this help message')
@@ -113,7 +118,7 @@ export function register(program: Command): void {
     .option('--citations-only', 'Run the gating citation check alone')
     .option(
       '--gate',
-      'Also fail on a missing required section, an H2 outside the set, a shape break in a gated folder, or index drift, the findings that are facts',
+      'Also fail on a missing required section, an H2 outside the set, a shape break in a gated folder, index drift, or a code folder no entry names, the findings that are facts',
     )
     .addHelpText(
       'after',
@@ -129,7 +134,9 @@ export function register(program: Command): void {
         '--citations-only, which never measures it. A record stating no',
         'cap is reported and never gated. --gate widens the gate to the',
         'findings that are facts rather than judgments: a missing',
-        'required section, an H2 outside the closed set, and index drift.',
+        'required section, an H2 outside the closed set, index drift, and',
+        'a code folder no Layout names or two entries claim. The roots come',
+        'from canon/config/context.toml and default to src when present.',
         'A context entry requires Overview and Layout and allows Gotchas.',
         'A shape break, such as a Decisions section or a sixth gotcha, is',
         'reported everywhere and gated only under a shape-gated folder.',
@@ -667,6 +674,9 @@ async function runAudit(
         isShapeGated(relative(top, join(root, rel))),
       )
   const length = gateOnly ? undefined : lengthFindings(entries)
+  const coverage: CoverageReport | undefined = gateOnly
+    ? undefined
+    : measureCoverage(root, readRoots(root), folders)
   // 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
   // different answers, and one value for both reports the second as the first.
@@ -685,6 +695,7 @@ async function runAudit(
     reportTables(entries)
     reportProvenance(entries, folders)
     reportDrift(drift)
+    reportCoverage(coverage ?? { kind: 'no-root' })
     reportRequirements(requirements, root)
     outro()
   }
@@ -721,6 +732,8 @@ async function runAudit(
         extraSections: extras,
         shapeFindings: shape,
         indexDrift: drift,
+        // Absent under `--citations-only`, which never measures it.
+        coverage,
         // 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
         // never looked, which is `--citations-only`.
@@ -753,6 +766,7 @@ async function runAudit(
     extraSections: extras,
     shape,
     drift,
+    coverage: coverage ?? { kind: 'no-root' },
     widened,
   })
 
@@ -1210,6 +1224,46 @@ function reportProvenance(
   )
 }
 
+function reportCoverage(report: CoverageReport): void {
+  logStep('Coverage')
+
+  if (report.kind === 'no-root') {
+    logInfo(
+      'No code root found, since no canon/config/context.toml declares one and there is no src/, so nothing was measured.',
+    )
+    return
+  }
+
+  if (report.kind === 'invalid') {
+    logWarn(report.reason)
+    return
+  }
+
+  if (report.kind === 'opted-out') {
+    logInfo(
+      'canon/config/context.toml declares roots = [], so coverage was not measured.',
+    )
+    return
+  }
+
+  const { unnamed, doubled, missingRoots } = report.findings
+  const lines = [
+    ...missingRoots.map((root) => `${root}  matches no folder`),
+    ...unnamed.map((folder) => `${folder}  named in no Layout`),
+    ...doubled.map(
+      ({ folder, rels }) => `${folder}  Layout H3 in ${rels.join(', ')}`,
+    ),
+  ]
+
+  if (lines.length === 0) {
+    logInfo(`Every folder under ${report.roots.join(', ')} is named once.`)
+    return
+  }
+
+  logWarn(plural(lines.length, 'coverage finding'))
+  pipeOutput(lines.join('\n'))
+}
+
 /** Reports the requirements record against the word cap it states, if any. */
 function reportRequirements(
   report: RequirementsReport | undefined,

package/src/commands/labels.ts

@@ -5,6 +5,7 @@ import { execa } from 'execa'
 import { gitEnv } from '@/git/env'
 import { diffLabels } from '@/labels/apply'
 import { type LabelAuditRefusal, auditLabels } from '@/labels/audit'
+import { checkClosing } from '@/labels/closing'
 import { resolveScanInput } from '@/labels/event'
 import { checkTitleFormat, type TitleFormatIssue } from '@/labels/format'
 import { MAP_REL } from '@/labels/map'
@@ -34,6 +35,7 @@ interface ScanOptions {
   readonly body?: string
   readonly bodyFile?: string
   readonly head?: string
+  readonly closes?: string
   readonly json?: boolean
 }
 
@@ -196,6 +198,10 @@ export function register(program: Command): void {
       'Body to scan, read from a file, overriding the event payload',
     )
     .option('--head <ref>', 'Head branch, overriding the event payload')
+    .option(
+      '--closes <numbers>',
+      'Issues the body must close, a comma list or `none`, graded when given',
+    )
     .option('--json', 'Add a machine-readable record on stdout')
     .addHelpText(
       'after',
@@ -239,12 +245,20 @@ export function register(program: Command): void {
         'character, an em dash or a semicolon, in the title or body of a pull',
         'request or a review, outside a code span or a link.',
         '',
+        'With --closes, it also grades the closing lines. Each issue named needs',
+        'its own `Closes #NNN` keyword in the body, and a closing keyword for an',
+        'issue the list leaves out fails. `none` expects no closing line.',
+        'Without the flag the check does not run, so the pull request job and a',
+        'followup keep their behavior. A keyword in a code span or a fence is',
+        'not read, as GitHub does not read it.',
+        '',
         'Exit codes:',
-        '  0  none of the six found',
+        '  0  none of the eight found',
         '  1  refused, with the reason on stderr or in the JSON record',
         '  2  the title or body carries a phase label, a board identifier, a',
         '     session link, a banned character, a heading outside the closed',
-        '     list or a required one missing, or a title',
+        '     list or a required one missing, a missing or stray closing line',
+        '     under --closes, or a title',
         "     breaking claude/skills/git-pr/references/pr.md's format, casing, or length",
         '',
         'Examples:',
@@ -536,11 +550,42 @@ async function runApply(number: string, opts: ApplyOptions): Promise<number> {
   return owed.length === 0 ? 0 : 2
 }
 
+/**
+ * Reads `--closes` as the issues the body must close. Undefined when the flag
+ * is absent, which skips the check, and a message when the value is neither
+ * `none` nor a comma list of numbers, since a guessed list would grade the
+ * body against the wrong issues.
+ */
+function parseCloses(value: string | undefined): number[] | string | undefined {
+  if (value === undefined) return undefined
+  if (value === 'none') return []
+  if (!/^\d+(,\d+)*$/.test(value)) {
+    return `--closes takes a comma list of issue numbers or none, not ${value}`
+  }
+
+  return [...new Set(value.split(',').map(Number))]
+}
+
 async function runScan(opts: ScanOptions): Promise<number> {
   const emitJson = opts.json ?? false
 
   intro('canon labels scan')
 
+  const expected = parseCloses(opts.closes)
+
+  if (typeof expected === 'string') {
+    logStep('Refused')
+    logWarn(expected)
+    outro()
+
+    if (emitJson) {
+      process.stdout.write(
+        `${JSON.stringify({ reason: 'bad-input', message: expected })}\n`,
+      )
+    }
+    return 1
+  }
+
   const resolved = resolveScanInput(opts)
 
   if (resolved.kind === 'refused') {
@@ -693,6 +738,37 @@ async function runScan(opts: ScanOptions): Promise<number> {
     for (const issue of titleFormatIssues) logWarn(TITLE_FORMAT_MESSAGES[issue])
   }
 
+  const closing =
+    expected === undefined
+      ? { missing: [], stray: [] }
+      : checkClosing(resolved.body, expected)
+
+  logStep(
+    expected === undefined
+      ? 'Closing lines not checked'
+      : closing.missing.length === 0 && closing.stray.length === 0
+        ? 'Clean'
+        : 'Closing line issue found',
+  )
+  if (expected === undefined) {
+    logInfo('no --closes list, so the closing lines are not graded')
+  } else if (closing.missing.length === 0 && closing.stray.length === 0) {
+    logInfo('the closing lines match the issues the task closes')
+  } else {
+    if (closing.missing.length > 0) {
+      logWarn(
+        `${plural(closing.missing.length, 'issue')} with no closing line. Add one \`Closes #NNN\` per issue.`,
+      )
+      for (const number of closing.missing) logWarn(`#${number}`)
+    }
+    if (closing.stray.length > 0) {
+      logWarn(
+        `${plural(closing.stray.length, 'closing line')} for an issue this pull request does not close. Delete each.`,
+      )
+      for (const number of closing.stray) logWarn(`#${number}`)
+    }
+  }
+
   outro()
 
   if (emitJson) {
@@ -706,6 +782,8 @@ async function runScan(opts: ScanOptions): Promise<number> {
         titleFormatIssues,
         sections: { checked: sectionsChecked, ...sections },
         bannedCharacters,
+        missingClosures: closing.missing,
+        strayClosures: closing.stray,
       })}\n`,
     )
   }
@@ -716,7 +794,9 @@ async function runScan(opts: ScanOptions): Promise<number> {
     titleFormatIssues.length === 0 &&
     sections.outside.length === 0 &&
     sections.missing.length === 0 &&
-    banFindings.length === 0
+    banFindings.length === 0 &&
+    closing.missing.length === 0 &&
+    closing.stray.length === 0
     ? 0
     : 2
 }