@erclx/canon 4.116.0 → 4.117.0

package/src/tooling/scan.ts

@@ -2,7 +2,12 @@ import { existsSync, readFileSync } from 'node:fs'
 import { join } from 'node:path'
 import { resolveSurfacePath } from '@/surface-root'
 import { mergeSections } from '@/tooling/gitignore'
-import { ancestorsFirst, listFiles, type Manifest } from '@/tooling/manifest'
+import {
+  ancestorsFirst,
+  configPaths,
+  listFiles,
+  type Manifest,
+} from '@/tooling/manifest'
 import {
   collectDeps,
   collectScripts,
@@ -63,10 +68,13 @@ function isIdentical(a: string, b: string): boolean {
  * stack first, while dependencies and gitignore entries resolve from the
  * furthest ancestor inward.
  *
- * A target below its git toplevel is scanned as a subfolder: a path GitHub
- * reads only at the root moves to `withheld` and counts as no change, and the
- * nested spell config joins the seeds. The scope is read here so every caller
- * of `scan` agrees without passing a flag.
+ * A seed at a path the chain also ships as a config is left to the config,
+ * so the path is reported once.
+ *
+ * A target below its git toplevel is scanned as a subfolder: a config or seed
+ * GitHub reads only at the root moves to `withheld` and counts as no change,
+ * and the nested spell config joins the seeds. The scope is read here so every
+ * caller of `scan` agrees without passing a flag.
  */
 export function scan(chain: readonly Manifest[], target: string): ScanResult {
   const isSubfolder = isSubfolderTarget(target)
@@ -98,13 +106,22 @@ export function scan(chain: readonly Manifest[], target: string): ScanResult {
   }
 
   const seeds: SeedState[] = []
-  const seenSeeds = new Set<string>()
+  const seenSeeds = configPaths(chain)
 
   for (const manifest of chain) {
     for (const rel of listFiles(manifest.seedsDir)) {
       if (seenSeeds.has(rel)) continue
       seenSeeds.add(rel)
 
+      if (isSubfolder && isWithheldInSubfolder(rel)) {
+        withheld.push({
+          rel,
+          stack: manifest.name,
+          present: existsSync(join(target, rel)),
+        })
+        continue
+      }
+
       seeds.push({
         rel,
         state: existsSync(resolveSurfacePath(target, rel))

package/src/tooling/subfolder.ts

@@ -50,9 +50,9 @@ export function subfolderPath(target: string): string | undefined {
 
 /**
  * GitHub reads workflows only at the repository root, so a `.github/` copied
- * into a subfolder is a file nothing runs. `scan` and `injectConfigs` both
- * read this, so the set the diff withholds and the set the sync skips cannot
- * disagree.
+ * into a subfolder is a file nothing runs. `scan`, `injectConfigs`, and
+ * `injectSeeds` all read this, so the set the diff withholds and the set the
+ * sync skips cannot disagree, whether the path ships as a config or a seed.
  */
 export function isWithheldInSubfolder(rel: string): boolean {
   return rel.startsWith(WITHHELD_PREFIX)

package/standards/context.md

@@ -105,8 +105,8 @@ Only the `development` entry carries this section. It is not a general-purpose h
 
 ## Length
 
-- Aim for one entry per domain. There is no hard cap. Length is a symptom, not the defect.
-- Past roughly 150 rendered lines, check three things before adding more: whether the entry still covers a single domain, whether it has filled with content `ls` or `--help` reproduces, and whether it has accumulated the history of its own changes. Fix whichever is true rather than trimming to hit a number. Rendered lines count as `markdown.md` defines them.
+- Aim for one entry per domain. Length is a symptom, not the defect, and the one hard cap is the whole-document ceiling `markdown.md` states.
+- Past roughly 150 rendered lines, check three things before adding more: whether the entry still covers a single domain, whether it has filled with content `ls` or `--help` reproduces, and whether it has accumulated the history of its own changes. Fix whichever is true rather than trimming to hit a number. The 150 is a diagnostic checkpoint and never gates. Rendered lines count as `markdown.md` defines them.
 - Never cut a `## Decisions` or `## Gotchas` entry to shorten a file. Cut a `## Layout` or `## CLI` section instead.
 - Retire a decision or gotcha once its subject is gone, rewriting the bullet to state the current design rather than leaving the narration of what it replaced beside it. A rejected alternative is not a retired one, so what was tried and why it lost stays whatever its age. The rule above protects content whose subject is live, and this one releases content whose subject is not.
 - Rewrite a decision a later one replaced rather than appending the replacement beside it. The subject is still live, so the rule above does not reach it, and two bullets on one subject leave a reader to work out which of them is current. State the design that stands and keep the superseded reasoning only where it is the alternative that lost.

package/standards/markdown.md

@@ -32,6 +32,8 @@ Does not govern:
 - Proper nouns and product names retain their casing in headings
 - Past roughly 40 rendered lines with no heading of any level breaking them, add a subheading at the seam. Measure the longest such run rather than everything under one `##`, and exclude fenced code blocks. The number is a checkpoint, not a cap.
 - Count rendered lines rather than source lines, wrapping each source line at 80 columns and summing the heights. Source lines undercount a file authored one line per bullet, where a block of fifteen paragraph-bullets occupies fifteen lines and renders past sixty. A checkpoint another standard states counts the same unit, so a file measured one way never sits beside a run measured another.
+- Keep a whole document at or under 300 rendered lines, counted over the full source with frontmatter and fenced blocks included, since a session pays for every line it loads. This one is a ceiling rather than a checkpoint. `canon markdown audit` lists every document past it without failing the run, and a gate stage reads the same number, so whether a push fails on it is the project's gate to decide. Split the document at a seam rather than compressing it.
+- Exempt a file named `CHANGELOG.md`, which a release tool rewrites, and a document carrying `<!-- canon-length-exempt: <reason> -->` on a line of its own outside a fenced block. A marker naming no reason exempts nothing.
 - Exempt a block whose lines are all list items at one level averaging under roughly 130 characters. A flat list of short peers is already navigable, and a subheading dropped into it splits a set that belongs together. Bullet count says nothing on its own, since a catalog of one-liners and a stack of paragraphs reach the same count and read nothing alike, so weight is what decides.
 - Mixing prose with that list, or nesting levels inside it, ends the exemption at any weight.
 - Exempt a block whose lines are all table rows, at any length. The peer list above is exempt because it is already navigable, and a table because the remedy does not exist: a subheading dropped inside one splits the table rather than the run, so no edit short of rewriting it as a list clears the checkpoint.

package/standards/skill.md

@@ -180,6 +180,7 @@ Without this skill, a session <observed failure>, <observed failure>.
 - Contain only behavioral rules (what to do, what not to do) and pointers to reference docs. Narrative descriptions of what files are or how the system works belong in `docs/`, not in the skill body.
 - State rules, not inventories. Reference docs for lists that change, and phrase a rule as a ban on the forbidden shape rather than an enumeration of allowed options, so it stays stable as categories change.
 - Cut any rule that resists crisp one-line phrasing. Vague guidance is worse than none.
+- State the current rule only, in the body and in every file under `references/`. The incident and the date that earned a rule go in `REQUIREMENT.md` under `Gap`, or stay in git. A date inside a fence or a code span is example data and stays. `canon claude skills audit` names every other ISO date.
 - Group bullets under H2 headings by domain concern. Keep dos and don'ts together under the topic they belong to rather than splitting them into flat rules and constraints sections.
 - One actionable constraint per bullet. Prefer the `X over Y` form for preferences.
 - Do not include code examples unless a one to three line inline snippet captures a pattern the model cannot infer.

package/tooling/base/reference.md

@@ -15,8 +15,6 @@ Golden config files live in `tooling/base/configs/` and are copied into the targ
 - `.editorconfig`: `root = true`, with an `[*.sh]` block setting `indent_style = space` and `indent_size = 2`.
 - `commitlint.config.js`: ESM default export extending `@commitlint/config-conventional`. Rules are `header-max-length: 72`, `scope-case: lower-case`, `subject-full-stop: never`, and `subject-case` disabled.
 - `.husky/`: `pre-commit`, `commit-msg`, `pre-push`, `post-merge`, `post-rewrite`.
-- `.github/workflows/verify.yml`: runs on pull requests targeting `main` and on `workflow_dispatch`.
-- `.github/pull_request_template.md`: `## Summary`, `## Key Changes`, `## Technical Context`, `## Testing`.
 - `.vscode/extensions.json` and `.vscode/settings.json`: editor wiring for Prettier, cspell, shfmt, and shellcheck.
 - `scripts/verify.sh`: the maintenance entry point behind `check`.
 
@@ -28,6 +26,8 @@ Seeds live in `tooling/base/seeds/`. Sync drops each once on first install and n
 - `.cspell/project-terms.txt` and `.cspell/tech-stack.txt`: one word per line, sorted alphabetically.
 - `.lintstagedrc`: the glob map below.
 - `.prettierignore`: created empty. Projects add their own entries.
+- `.github/workflows/verify.yml`: runs on pull requests targeting `main` and on `workflow_dispatch`. A project with more than one language root adds its own jobs here.
+- `.github/pull_request_template.md`: `## Summary`, `## Key Changes`, `## Technical Context`, `## Testing`. A project adds the checklist lines its own review needs.
 - `canon/context/`: extend the `ci` and `development` entries with project-specific commands, workflows, or deploy steps. Canonical rationale stays in this reference.
 
 ## Tool pairing

package/tooling/web/configs/e2e/screenshot.ts

@@ -1,4 +1,4 @@
-import type { Page } from '@playwright/test'
+import type { Locator, Page } from '@playwright/test'
 import { chromium } from '@playwright/test'
 import { mkdir } from 'fs/promises'
 import path from 'path'
@@ -37,6 +37,8 @@ interface CaptureCase {
   /** Names of viewports this case skips, for a route that reflows rather than breaks at that width. */
   excludeViewports?: readonly string[]
   evidence?: boolean
+  /** Selectors painted over in every frame the case writes, for a value that moves between runs with no code change. */
+  mask?: readonly string[]
   sections?: CaptureSection[]
   setup?: (page: Page) => Promise<void>
 }
@@ -72,12 +74,14 @@ const CASES: CaptureCase[] = [
     theme: 'default',
     route: '/',
     evidence: true,
+    mask: ['.version'],
     sections: HOME_SECTIONS,
   },
   {
     section: 'home',
     theme: 'dark',
     route: '/',
+    mask: ['.version'],
     sections: HOME_SECTIONS,
     setup: (page) => page.emulateMedia({ colorScheme: 'dark' }),
   },
@@ -234,16 +238,47 @@ async function markFloatingChrome(page: Page) {
   }, FLOATING_ATTRIBUTE)
 }
 
-async function shoot(page: Page, dir: string, file: string, selector?: string) {
+/**
+ * Turns a case's mask selectors into the locators every frame paints over. A
+ * selector matching nothing is reported and kept out rather than raised, for
+ * the same template reason `settle` gives for a missing section.
+ */
+async function resolveMask(
+  page: Page,
+  label: string,
+  selectors: readonly string[],
+): Promise<Locator[]> {
+  const mask: Locator[] = []
+  for (const selector of selectors) {
+    const element = page.locator(selector)
+    if ((await element.count()) === 0) {
+      console.warn(
+        `${label}: no element matches ${selector}, named as a mask. Skipped.`,
+      )
+      continue
+    }
+    mask.push(element)
+  }
+  return mask
+}
+
+async function shoot(
+  page: Page,
+  dir: string,
+  file: string,
+  mask: Locator[],
+  selector?: string,
+) {
   await mkdir(dir, { recursive: true })
   const target = path.join(dir, file)
   if (selector === undefined) {
-    await page.screenshot({ path: target, fullPage: true })
+    await page.screenshot({ path: target, fullPage: true, mask })
   } else {
     // Floating chrome keeps the space it already occupies, so dropping it out
     // of its own layer moves nothing and leaves every box the size it was.
     await page.locator(selector).screenshot({
       path: target,
+      mask,
       style: `[${FLOATING_ATTRIBUTE}] { position: static !important; }`,
     })
   }
@@ -281,21 +316,22 @@ for (const { captureCase, viewport, label } of RUNS) {
   await page.waitForLoadState('networkidle')
 
   const sections = await settle(page, label, captureCase.sections ?? [])
+  const mask = await resolveMask(page, label, captureCase.mask ?? [])
 
   const sweepDir = path.join(OUT_DIR, captureCase.section)
   const evidenceDir = path.join('evidence', captureCase.section)
   const file = `${viewport.name}--${captureCase.theme}.png`
   const writesEvidence = captureCase.evidence && viewport.evidence
 
-  await shoot(page, sweepDir, file)
-  if (writesEvidence) await shoot(page, evidenceDir, file)
+  await shoot(page, sweepDir, file, mask)
+  if (writesEvidence) await shoot(page, evidenceDir, file, mask)
 
   if (sections.length > 0) await markFloatingChrome(page)
 
   for (const { name, selector } of sections) {
-    await shoot(page, path.join(sweepDir, name), file, selector)
+    await shoot(page, path.join(sweepDir, name), file, mask, selector)
     if (writesEvidence) {
-      await shoot(page, path.join(evidenceDir, name), file, selector)
+      await shoot(page, path.join(evidenceDir, name), file, mask, selector)
     }
   }
 

package/tooling/web/reference.md

@@ -12,7 +12,7 @@ Golden config files live in `tooling/web/configs/` and are copied into the targe
 
 - `eslint.config.js`: flat config with `@eslint/js`, `typescript-eslint`, React hooks, import sort, check-file, vitest rules scoped to test files, `eslint-config-prettier` last.
 - `src/test/setup.ts`: `@testing-library/jest-dom` import, `cleanup` after each test.
-- `e2e/screenshot.ts`: capture template. A single `CASES` record at the top carries one entry per output file, each naming a section, a theme, and a route, and the loop below crosses every case with the `VIEWPORTS` array and writes `screenshots/<hostname>/<section>/<width>--<theme>.png`, keyed on `SCREENSHOT_BASE_URL`'s hostname so a local and a deployed run land in different folders. `VIEWPORTS` holds four breakpoint buckets named by width, 320, 768, 1280 and 1536, with 320 as the base a page has to hold without wrapping or clipping. A case flagged `evidence: true` additionally writes `evidence/<section>/<width>--<theme>.png`, with no hostname segment, at the viewports flagged `evidence` alone, which are 320 and 1280. Committing all four multiplies the tracked frames by the width count, so the flag is what keeps the tracked set at twice the sections rather than four times. A case may name `excludeViewports` to skip a width, for a route whose long-form prose reflows at 320 instead of breaking. `SCREENSHOT_FILTER` narrows a run to the cases whose label, `<section>/<width>--<theme>`, contains any comma-separated term, exits 1 when nothing matches and lists the labels that exist, and leaves the rest of the sweep alone. `--require-base-url` skips a flagged case entirely, so a production smoke run neither writes to the committed path nor counts an evidence route in its console-clean check, and exits 1 when that leaves zero cases run, so flagging every case cannot silence the production check without saying so. Per-project cases extend the one record. A route's widths and themes sit together under its section folder, so the filename carries both. A case may also name `sections`, one `{ name, selector }` per addressable part of the route, and each writes its own frame at `screenshots/<hostname>/<section>/<name>/<width>--<theme>.png` beside the whole-page one, plus `evidence/<section>/<name>/<width>--<theme>.png` where the case is flagged and the width carries `evidence`. The field is optional, so a case that names none captures the page alone as before, and a selector matching nothing is reported and skipped rather than raised, since `CASES` is a template a project rewrites and a target that syncs this file before editing its own list would otherwise capture nothing at all. Testing that every named section resolves belongs to the project that owns the selectors, beside its own page. Every case settles before anything is shot: the context is created with `reducedMotion: 'reduce'`, each named section is scrolled into view so an `IntersectionObserver` fires and a frame marked `loading="lazy"` loads, the page returns to the top, and fonts, images and same-origin frames are waited out on a bounded condition rather than on a second `networkidle`, which is a lifecycle event of the navigation and does not re-arm for a load a scroll started. A section frame drops the page's floating chrome, being whatever computes to `position: sticky` or `fixed`, because a section taller than the viewport is scrolled into view to be cut and a sticky bar otherwise rides that scroll into the middle of the frame. The whole-page frame is shot first and keeps its chrome. `--check-console-clean` collects `console`-level error messages per case and exits 1 with the list if any fired, turning the capture into a smoke check. `--require-base-url` exits 1 before launching a browser when `SCREENSHOT_BASE_URL` is unset, guarding a script meant to run against a real deployment from silently capturing `localhost`.
+- `e2e/screenshot.ts`: capture template. A single `CASES` record at the top carries one entry per output file, each naming a section, a theme, and a route, and the loop below crosses every case with the `VIEWPORTS` array and writes `screenshots/<hostname>/<section>/<width>--<theme>.png`, keyed on `SCREENSHOT_BASE_URL`'s hostname so a local and a deployed run land in different folders. `VIEWPORTS` holds four breakpoint buckets named by width, 320, 768, 1280 and 1536, with 320 as the base a page has to hold without wrapping or clipping. A case flagged `evidence: true` additionally writes `evidence/<section>/<width>--<theme>.png`, with no hostname segment, at the viewports flagged `evidence` alone, which are 320 and 1280. Committing all four multiplies the tracked frames by the width count, so the flag is what keeps the tracked set at twice the sections rather than four times. A case may name `excludeViewports` to skip a width, for a route whose long-form prose reflows at 320 instead of breaking. `SCREENSHOT_FILTER` narrows a run to the cases whose label, `<section>/<width>--<theme>`, contains any comma-separated term, exits 1 when nothing matches and lists the labels that exist, and leaves the rest of the sweep alone. `--require-base-url` skips a flagged case entirely, so a production smoke run neither writes to the committed path nor counts an evidence route in its console-clean check, and exits 1 when that leaves zero cases run, so flagging every case cannot silence the production check without saying so. Per-project cases extend the one record. A route's widths and themes sit together under its section folder, so the filename carries both. A case may also name `sections`, one `{ name, selector }` per addressable part of the route, and each writes its own frame at `screenshots/<hostname>/<section>/<name>/<width>--<theme>.png` beside the whole-page one, plus `evidence/<section>/<name>/<width>--<theme>.png` where the case is flagged and the width carries `evidence`. The field is optional, so a case that names none captures the page alone as before, and a selector matching nothing is reported and skipped rather than raised, since `CASES` is a template a project rewrites and a target that syncs this file before editing its own list would otherwise capture nothing at all. Testing that every named section resolves belongs to the project that owns the selectors, beside its own page. A case may also name `mask`, a list of selectors whose boxes are painted over in every frame the case writes, whole-page and section alike, for a value that moves between runs with no code change, so a double capture still compares everything else. A mask selector matching nothing is reported and skipped the same way. Every case settles before anything is shot: the context is created with `reducedMotion: 'reduce'`, each named section is scrolled into view so an `IntersectionObserver` fires and a frame marked `loading="lazy"` loads, the page returns to the top, and fonts, images and same-origin frames are waited out on a bounded condition rather than on a second `networkidle`, which is a lifecycle event of the navigation and does not re-arm for a load a scroll started. A section frame drops the page's floating chrome, being whatever computes to `position: sticky` or `fixed`, because a section taller than the viewport is scrolled into view to be cut and a sticky bar otherwise rides that scroll into the middle of the frame. The whole-page frame is shot first and keeps its chrome. `--check-console-clean` collects `console`-level error messages per case and exits 1 with the list if any fired, turning the capture into a smoke check. `--require-base-url` exits 1 before launching a browser when `SCREENSHOT_BASE_URL` is unset, guarding a script meant to run against a real deployment from silently capturing `localhost`.
 - `scripts/screenshot.sh`: sources `scripts/lib/preview-server.sh`, then runs the capture against the served preview.
 - `scripts/lib/preview-server.sh`: sourced, never executed. Builds, serves on `PREVIEW_PORT`, blocks until the port answers, and traps the whole process group on exit, including the detached grandchild `lsof` finds. Both capture scripts source it so the startup lives once.
 - `scripts/readme-screenshot.sh`: captures one case under `SCREENSHOT_FILTER` and copies its light and dark frames to `assets/evidence/readme/`. `README_FILTER` ships empty with `header/1280` as its example, and the script exits 1 until a project fills it, since a shipped default would capture the wrong part of the page in every project but one. Its copy reads from `screenshots/<hostname>/`, which is where the harness writes.