@erclx/canon 5.19.0 → 5.21.0

package/governance/rules/standards/requirements.md

@@ -0,0 +1,13 @@
+---
+# Generated by `canon gov regen` from standards/requirements.md. Edit that frontmatter, not this file.
+description: Shape and content rules for canon/REQUIREMENTS.md
+paths:
+  - 'canon/REQUIREMENTS.md'
+  - '.claude/REQUIREMENTS.md'
+---
+
+# Requirements standards
+
+## Authority
+
+- Follow the requirements standard for shape and content rules for canon/REQUIREMENTS.md. It is the single source. Read it with `canon standards requirements`.

package/governance/rules/standards/rule.md

@@ -0,0 +1,13 @@
+---
+# Generated by `canon gov regen` from standards/rule.md. Edit that frontmatter, not this file.
+description: Rule frontmatter, body shape, and voice for .claude/rules files
+paths:
+  - '.claude/rules/**/*.md'
+---
+
+# Governance rule standards
+
+## Authority
+
+- Follow the rule standard for rule frontmatter, body shape, and voice for .claude/rules files. It is the single source. Read it with `canon standards rule`.
+- Read it before writing or editing a rule. Do not work the shape from memory.

package/governance/rules/standards/session.md

@@ -0,0 +1,13 @@
+---
+# Generated by `canon gov regen` from standards/session.md. Edit that frontmatter, not this file.
+description: Filename and location, the sections a handoff carries, the write and read procedures, and how a role extends it
+paths:
+  - '.canon/tasks/session-*.md'
+---
+
+# Session map standards
+
+## Authority
+
+- Follow the session standard for filename and location, the sections a handoff carries, the write and read procedures, and how a role extends it. It is the single source. Read it with `canon standards session`.
+- Follow this rule rather than the tasks rule for a `session-` file. A handoff is not a task and carries neither `## Outcomes` nor `## Findings`.

package/governance/rules/{claude/570-skill.md → standards/skill.md}

@@ -1,5 +1,6 @@
 ---
-description: Route skill edits to the authoring standard and the requirement consult-first workflow
+# Generated by `canon gov regen` from standards/skill.md. Edit that frontmatter, not this file.
+description: Skill structure and authoring rules for Claude Code
 paths:
   - '.claude/skills/**/SKILL.md'
   - 'claude/skills/**/SKILL.md'
@@ -7,19 +8,14 @@ paths:
   - 'claude/skills/**/REQUIREMENT.md'
 ---
 
-# Skill standards
+# Claude skill standards
 
-## Before editing
+## Authority
 
+- Follow the skill standard for skill structure and authoring rules for Claude Code. It is the single source. Read it with `canon standards skill`.
 - Confirm `canon:create-skill`'s two creation-time questions are answered before a new `SKILL.md` lands, whether drafted by hand, by another skill, or by `canon:create-skill` itself. Carry the third question into the sibling `REQUIREMENT.md`'s `Must not` section as a review criterion rather than a gate.
 - Report it rather than proceeding silently when `canon:create-skill` does not resolve. It ships with the plugin and this rule ships with the CLI, so a project that installed governance alone does not have it.
-
-## After editing
-
 - Re-read a skill body this session edited before invoking that skill again in the same session
 - Do not read a resolved file path in a held body as evidence the body is current
-
-## Authority
-
-- Follow the skill standard for skill structure, frontmatter fields, and invocation rules. It is the single source. Read it with `canon standards skill`.
 - Follow the skill requirement standard for the shape a `REQUIREMENT.md` states. Read it with `canon standards skill-requirement`.
+- Follow the skill path standard for which root a path in a body resolves against and how a body cites a standard. Read it with `canon standards skill-paths`.

package/governance/rules/standards/standard.md

@@ -0,0 +1,13 @@
+---
+# Generated by `canon gov regen` from standards/standard.md. Edit that frontmatter, not this file.
+description: Shape and content rules for authoring a standard
+paths:
+  - 'standards/**/*.md'
+---
+
+# Standard standards
+
+## Authority
+
+- Follow the standard standard for shape and content rules for authoring a standard. It is the single source. Read it with `canon standards standard`.
+- Read it before writing or editing a standard. Do not work the shape from memory.

package/governance/rules/standards/tasks.md

@@ -0,0 +1,15 @@
+---
+# Generated by `canon gov regen` from standards/tasks.md. Edit that frontmatter, not this file.
+description: Folder layout, filename convention, file format, origin lines, and archiving for task files under .canon/tasks/
+paths:
+  - '.canon/tasks/**'
+---
+
+# Tasks standards
+
+## Authority
+
+- Follow the tasks standard for folder layout, filename convention, file format, origin lines, and archiving for task files under .canon/tasks/. It is the single source. Read it with `canon standards tasks`.
+- Follow the board standard for `priority.md` and `backlog.md`, their readiness groups, and row order. Read it with `canon standards board`.
+- Never hand-edit `.canon/tasks/index.md`. A hook regenerates it from sibling frontmatter.
+- Follow the task decline standard for a task decided against. Read it with `canon standards tasks-decline`.

package/governance/rules/{canon/661-teach.md → standards/teach.md}

@@ -1,5 +1,6 @@
 ---
-description: Route .canon/teach/ edits to the teach standard for layout, ordinal naming, and the mission and record formats, in the projects that open a learning workspace
+# Generated by `canon gov regen` from standards/teach.md. Edit that frontmatter, not this file.
+description: Workspace layout, ordinal naming, frontmatter, and the mission and learning-record formats for a learning workspace
 paths:
   - '.canon/teach/**'
 ---
@@ -8,6 +9,6 @@ paths:
 
 ## Authority
 
-- Follow the teach standard for the folder layout, ordinal naming, frontmatter, and the mission and learning-record formats. It is the single source. Read it with `canon standards teach`.
+- Follow the teach standard for workspace layout, ordinal naming, frontmatter, and the mission and learning-record formats for a learning workspace. It is the single source. Read it with `canon standards teach`.
 - Follow the glossary standard for the glossary every workspace carries at its root. It is the single source for the entry shape, the ordering, and which terms the file carries. Read it with `canon standards glossary`.
 - Report it rather than proceeding silently when that file does not resolve. It ships with the plugin and this rule ships with the CLI, so a project that installed governance alone does not have it.

package/governance/rules/standards/wiki.md

@@ -0,0 +1,13 @@
+---
+# Generated by `canon gov regen` from standards/wiki.md. Edit that frontmatter, not this file.
+description: Folder split, frontmatter, naming convention, and sourcing for a wiki reference page
+paths:
+  - 'wiki/**/*.md'
+---
+
+# Wiki standards
+
+## Authority
+
+- Follow the wiki standard for folder split, frontmatter, naming convention, and sourcing for a wiki reference page. It is the single source. Read it with `canon standards wiki`.
+- Read it before drafting a page. Do not work the placement criterion or the naming convention from memory.

package/governance/rules/standards/wireframes.md

@@ -0,0 +1,14 @@
+---
+# Generated by `canon gov regen` from standards/wireframes.md. Edit that frontmatter, not this file.
+description: Shape and content rules for canon/wireframes/<surface>.md files
+paths:
+  - 'canon/wireframes/**'
+  - '.claude/wireframes/**'
+---
+
+# Wireframe standards
+
+## Authority
+
+- Follow the wireframes standard for shape and content rules for canon/wireframes/<surface>.md files. It is the single source. Read it with `canon standards wireframes`.
+- Read it before adding or revising a surface.

package/governance/rules/writing/800-prose.md

@@ -12,4 +12,4 @@ paths:
 - Load it before drafting a passage, not after revising one.
 - Report it rather than proceeding silently when the skill does not resolve.
 - Do not work these rules from memory.
-- Punctuation, formatting, and file references are a separate topic. `801-markdown` routes them.
+- Punctuation, formatting, and file references are a separate topic. The markdown rule routes them.

package/governance/stacks/base.toml

@@ -5,5 +5,7 @@ extends = ""
 # session conduct and `.claude/` authoring rules, `tooling` the dev setup and
 # CI workflow rules, and `writing` the prose and document-shape rules. The
 # `code` group is left to the stacks that write code, so a docs or writing
-# project loads no rule it can never apply.
-rules = ["canon", "claude", "tooling", "writing", "120-bash"]
+# project loads no rule it can never apply. `standards` holds one rule per
+# standard routing its paths to it, generated by `canon gov regen` from each
+# standard's frontmatter rather than authored.
+rules = ["canon", "claude", "standards", "tooling", "writing", "120-bash"]

package/package.json

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

package/src/canvas/capture.ts

@@ -1,6 +1,12 @@
-import { join } from 'node:path'
+import { mkdirSync, rmSync, writeFileSync } from 'node:fs'
+import { dirname, join } from 'node:path'
 import type { CaptureResult } from '@/capture/render'
-import { type ContentRefused, type Frame, readPage } from '@/canvas/content'
+import {
+  type ContentRefused,
+  canvasDir,
+  type Frame,
+  readPage,
+} from '@/canvas/content'
 import {
   type CanvasOptions,
   type CanvasOutcome,
@@ -134,6 +140,34 @@ export async function captureCanvas(
   const early = resolveCaptureTargets(root, spec, '')
   if (!early.ok) return early
 
+  return serveFor(root, deps, async (base, capture) => {
+    const resolved = resolveCaptureTargets(root, spec, base, out)
+    if (!resolved.ok) return resolved
+
+    const captures: { target: CaptureTarget; result: CaptureResult }[] = []
+    for (const target of resolved.targets) {
+      const [result] = await capture(target.url, {
+        selector: CAPTURE_SELECTOR,
+        width: target.width,
+        outDir: target.pngPath,
+      })
+      if (result) captures.push({ target, result })
+    }
+    return { ok: true, captures }
+  })
+}
+
+type ServeRefused = {
+  readonly ok: false
+  readonly reason: 'no-server' | 'capture-failed'
+  readonly detail: string
+}
+
+async function serveFor<T>(
+  root: string,
+  deps: CaptureDeps,
+  run: (base: string, capture: CaptureEngine) => Promise<T>,
+): Promise<T | ServeRefused> {
   const start = deps.start ?? startCanvas
   const server = start(root, { port: 0, shell: new Response('') })
   if (!server.ok) {
@@ -145,21 +179,9 @@ export async function captureCanvas(
   }
 
   try {
-    const resolved = resolveCaptureTargets(root, spec, server.url, out)
-    if (!resolved.ok) return resolved
-
     const capture =
       deps.capture ?? (await import('@/capture/render')).captureSources
-    const captures: { target: CaptureTarget; result: CaptureResult }[] = []
-    for (const target of resolved.targets) {
-      const [result] = await capture(target.url, {
-        selector: CAPTURE_SELECTOR,
-        width: target.width,
-        outDir: target.pngPath,
-      })
-      if (result) captures.push({ target, result })
-    }
-    return { ok: true, captures }
+    return await run(server.url, capture)
   } catch (error) {
     return {
       ok: false,
@@ -170,3 +192,194 @@ export async function captureCanvas(
     await server.stop()
   }
 }
+
+/** The element a composite is captured by, holding every frame and no chrome. */
+export const COMPOSITE_SELECTOR = '#canvas-composite'
+
+/**
+ * The container holds no text, so its family exists only for the engine's
+ * font probe, which rejects a family the machine lacks. The browser default is
+ * Times New Roman, which a Linux runner often lacks, and `system-ui` is the one
+ * every platform maps. Each frame keeps its own fonts inside its iframe.
+ */
+const COMPOSITE_FONT = 'system-ui'
+
+export interface Placement {
+  readonly frame: string
+  readonly url: string
+  readonly left: number
+  readonly top: number
+  readonly width: number
+  readonly height: number
+}
+
+export interface Composite {
+  readonly placements: readonly Placement[]
+  readonly width: number
+  readonly height: number
+  readonly html: string
+}
+
+/**
+ * One document showing every frame of a page at its layout position. Offsets
+ * run from the top left of the union of the boxes, so a negative coordinate
+ * never clips and a lone frame fills the container exactly. Each iframe takes
+ * its box, so a document taller than its frame clips as it does on the board,
+ * and frames paint in the order given, which is the board's.
+ */
+export function buildComposite(
+  page: string,
+  frames: readonly Frame[],
+  base: string,
+): Composite {
+  const left = Math.min(...frames.map((frame) => frame.x))
+  const top = Math.min(...frames.map((frame) => frame.y))
+  const right = Math.max(...frames.map((frame) => frame.x + frame.width))
+  const bottom = Math.max(...frames.map((frame) => frame.y + frame.height))
+  const width = right - left
+  const height = bottom - top
+
+  const placements = frames.map((frame) => ({
+    frame: frame.name,
+    url: frameUrl(base, page, frame),
+    left: frame.x - left,
+    top: frame.y - top,
+    width: frame.width,
+    height: frame.height,
+  }))
+
+  const iframes = placements.map(
+    (p) =>
+      `<iframe title="${escapeAttribute(p.frame)}" src="${escapeAttribute(p.url)}" style="left:${p.left}px;top:${p.top}px;width:${p.width}px;height:${p.height}px"></iframe>`,
+  )
+  const html = [
+    '<!doctype html>',
+    '<html><head><meta charset="utf-8">',
+    `<style>html,body{margin:0;background:transparent}#canvas-composite{position:relative;font-family:${COMPOSITE_FONT}}#canvas-composite iframe{position:absolute;display:block;border:0;background:transparent}</style>`,
+    '</head><body>',
+    `<div id="canvas-composite" style="width:${width}px;height:${height}px">`,
+    ...iframes,
+    '</div></body></html>',
+    '',
+  ].join('\n')
+
+  return { placements, width, height, html }
+}
+
+function escapeAttribute(value: string): string {
+  return value.replaceAll('&', '&amp;').replaceAll('"', '&quot;')
+}
+
+/**
+ * Where the generated document is served from, inside the canvas folder so it
+ * shares the frames' origin. Chromium skips painting a cross-origin iframe
+ * outside the viewport, and the engine's viewport is 720 pixels tall, so a
+ * document on another origin captured every frame below that line blank. A dot
+ * folder is no page name, so the board never lists it.
+ */
+const COMPOSITE_FOLDER = '.composite'
+
+export interface CompositeTarget {
+  readonly page: string
+  readonly composite: Composite
+  readonly htmlPath: string
+  /** The served address of the document at `htmlPath`. */
+  readonly url: string
+  readonly pngPath: string
+}
+
+export type CompositeTargetOutcome =
+  | { readonly ok: true; readonly target: CompositeTarget }
+  | ContentRefused
+
+/**
+ * Turns `<page>` into one composite. `out` is the PNG, and without it the PNG
+ * lands at `<page>.png` beside the per-frame folder of the same name, so the
+ * two captures of one page never collide.
+ */
+export function resolveCompositeTarget(
+  root: string,
+  spec: string,
+  base: string,
+  out?: string,
+): CompositeTargetOutcome {
+  if (spec.includes('/')) {
+    return refuse(
+      'invalid-name',
+      `--composite takes a page, not ${spec}, so capture <page> or drop the flag`,
+    )
+  }
+
+  const page = readPage(root, spec)
+  if (!page) return refuse('no-page', `page ${spec} does not exist`)
+  if (page.frames.length === 0) {
+    return refuse('no-frame', `page ${spec} has no frames`)
+  }
+
+  const file = `${spec}.html`
+  return {
+    ok: true,
+    target: {
+      page: spec,
+      composite: buildComposite(spec, page.frames, base),
+      htmlPath: join(canvasDir(root), COMPOSITE_FOLDER, file),
+      url: `${base}${FRAMES_PREFIX.slice(1)}${COMPOSITE_FOLDER}/${encodeURIComponent(file)}`,
+      pngPath:
+        out ?? join(recordDir(root, 'tmp', 'canvas-capture'), `${spec}.png`),
+    },
+  }
+}
+
+export type CompositeOutcome =
+  | {
+      readonly ok: true
+      readonly composite: {
+        readonly target: CompositeTarget
+        readonly result: CaptureResult
+      }
+    }
+  | ContentRefused
+  | ServeRefused
+
+/**
+ * Captures a page as one PNG through the served canvas, the way `captureCanvas`
+ * captures each frame. The viewport is the container's width, so no frame's
+ * media query resolves against a window narrower than the frame itself. The
+ * page load the engine waits on waits on every iframe.
+ */
+export async function captureComposite(
+  root: string,
+  spec: string,
+  out?: string,
+  deps: CaptureDeps = {},
+): Promise<CompositeOutcome> {
+  const early = resolveCompositeTarget(root, spec, '')
+  if (!early.ok) return early
+
+  return serveFor(root, deps, async (base, capture) => {
+    const resolved = resolveCompositeTarget(root, spec, base, out)
+    if (!resolved.ok) return resolved
+
+    const { target } = resolved
+    mkdirSync(dirname(target.htmlPath), { recursive: true })
+    writeFileSync(target.htmlPath, target.composite.html)
+    let result: CaptureResult | undefined
+    try {
+      ;[result] = await capture(target.url, {
+        selector: COMPOSITE_SELECTOR,
+        width: target.composite.width,
+        outDir: target.pngPath,
+      })
+    } finally {
+      rmSync(target.htmlPath, { force: true })
+    }
+    if (!result) {
+      return {
+        ok: false,
+        reason: 'capture-failed',
+        detail: `the engine rendered nothing for ${spec}`,
+      }
+    }
+    return { ok: true, composite: { target, result } }
+  })
+}

package/src/claude/cases/misc.ts

@@ -84,6 +84,11 @@ export const MISC_CASES: readonly SkillCase[] = [
       'Find me the strongest evidence on whether rent control reduces housing supply. Where should I look?',
     expect: 'search-craft',
   },
+  {
+    prompt:
+      'The composed demo video looks generic and the zoom drags. What should the captions say, and how fast should the push-in be?',
+    expect: 'video-craft',
+  },
   {
     prompt:
       "I've got the plan approved and it touches the parser, the command, and the docs. How should I build it so I don't end up with one giant diff?",

package/src/claude/cases/workflow.ts

@@ -38,12 +38,6 @@ export const WORKFLOW_CASES: readonly SkillCase[] = [
       'Fold what we decided this session into the context entries and mark off what shipped on the task board.',
     expect: 'context-fold',
   },
-  {
-    prompt:
-      'I typed the old fold skill name and it says it was renamed, where did it go?',
-    // The pointer answers under its old name on purpose. canon-keep-retired
-    expect: 'docs-fold',
-  },
   {
     prompt:
       'Sketch out a plan for adding this new capability before we touch any code.',
@@ -143,16 +137,10 @@ export const WORKFLOW_CASES: readonly SkillCase[] = [
     prompt: 'Turn this topic into a slide deck I can render.',
     expect: 'draft-slides',
   },
-  {
-    prompt:
-      'Check whether the markdown I changed violates any authoring standards.',
-    expect: 'standards-audit',
-  },
-  // Rot across documents nobody changed is what separates this from
-  // `standards-audit`, which is diff-scoped and reports a stated rule broken on
-  // a given line. It is also not `target-check`, which asks whether a document
-  // exists and holds its sections rather than whether it still describes the
-  // tree.
+  // Rot across documents nobody changed is what this reads, rather than a
+  // stated rule broken on a given line. It is also not `target-check`, which
+  // asks whether a document exists and holds its sections rather than whether
+  // it still describes the tree.
   {
     prompt:
       'Which of our docs have gone stale, grown too long, or ended up in the wrong file?',
@@ -230,10 +218,6 @@ export const WORKFLOW_CASES: readonly SkillCase[] = [
       "Go through what's still unanswered in the intake folder and decide.",
     expect: 'plan-intake-answer',
   },
-  {
-    prompt: 'Check this markdown against the house style rules.',
-    expect: 'standards-audit',
-  },
   {
     prompt: 'Find the rough, unfinished-feeling spots in this interface.',
     expect: 'ux-audit',

package/src/claude/routing.ts

@@ -196,7 +196,7 @@ function frontmatter(text: string): string {
  *
  * A glob opening `**` reaches every folder in the tree, so it answers that a
  * file type is governed and never that a named path is. Counting one would
- * report every markdown path covered by `801-markdown` and leave the column
+ * report every markdown path covered by the markdown rule and leave the column
  * saying nothing a reader could act on.
  */
 function isAnchored(glob: string): boolean {

package/src/commands/canvas.ts

@@ -13,7 +13,7 @@ import {
   readSelection,
   renamePage,
 } from '@/canvas/content'
-import { captureCanvas } from '@/canvas/capture'
+import { captureCanvas, captureComposite } from '@/canvas/capture'
 import {
   type EditRefused,
   editFrameAtIndex,
@@ -468,6 +468,10 @@ export function register(program: Command): void {
       .option(
         '-o, --out <path>',
         'The PNG for a frame, or the folder for a page; defaults to session scratch',
+      )
+      .option(
+        '--composite',
+        'Capture a page as one PNG with every frame at its layout position; --out is then the PNG',
       ),
   )
     .addHelpText(
@@ -478,18 +482,25 @@ export function register(program: Command): void {
         'the injected tokens are in the PNG and each frame renders at its own',
         'width. The raw file on disk is never captured.',
         '',
+        'With --composite, each frame is clipped to its box as on the board and',
+        'shows in its default theme, with no captions or selection outline.',
+        '',
         'Exit codes:',
         '  0  every frame rendered',
         '  1  refused or a frame failed, with the reason on stderr or in the JSON record',
         '',
       ].join('\n'),
     )
-    .action(async (target: string, opts: RootOptions & { out?: string }) => {
+    .action(async (target: string, opts: CaptureOptions) => {
       const resolved = await resolveRoot(opts)
       if (!resolved.ok) {
         process.exitCode = refuse(resolved, opts.json ?? false)
         return
       }
+      if (opts.composite) {
+        process.exitCode = await runComposite(resolved.root, target, opts)
+        return
+      }
       let outcome: Awaited<ReturnType<typeof captureCanvas>>
       try {
         outcome = await captureCanvas(
@@ -543,6 +554,69 @@ export function register(program: Command): void {
     })
 }
 
+interface CaptureOptions extends RootOptions {
+  readonly out?: string
+  readonly composite?: boolean
+}
+
+async function runComposite(
+  root: string,
+  target: string,
+  opts: CaptureOptions,
+): Promise<number> {
+  const emitJson = opts.json ?? false
+  let outcome: Awaited<ReturnType<typeof captureComposite>>
+  try {
+    outcome = await captureComposite(
+      root,
+      target,
+      opts.out ? resolve(process.cwd(), opts.out) : undefined,
+    )
+  } catch (error) {
+    const detail = error instanceof Error ? error.message : String(error)
+    return refuse({ ok: false, reason: 'capture-failed', detail }, emitJson)
+  }
+  if (!outcome.ok) return refuse(outcome, emitJson)
+
+  const { target: item, result } = outcome.composite
+  if (result.status === 'failed') {
+    if (emitJson) {
+      writeJson({
+        ok: false,
+        composite: {
+          page: item.page,
+          status: result.status,
+          reason: result.reason,
+        },
+      })
+    }
+    intro(BANNER)
+    logError(`${item.page}: ${result.reason}`)
+    outro()
+    return 1
+  }
+
+  if (emitJson) {
+    writeJson({
+      ok: true,
+      composite: {
+        page: item.page,
+        status: result.status,
+        path: result.pngPath,
+        width: result.width,
+        height: result.height,
+      },
+    })
+  }
+  intro(BANNER)
+  logAdd(
+    `${item.page} composite of ${plural(item.composite.placements.length, 'frame')}`,
+  )
+  logInfo(`${displayPath(result.pngPath)} ${result.width}x${result.height}`)
+  outro()
+  return 0
+}
+
 /** NaN for a value that is not a number, which the content module refuses. */
 function parsePosition(raw: string | undefined, fallback: number): number {
   if (raw === undefined) return fallback