@erclx/canon 5.52.0 → 5.54.0

package/src/records/validate.ts

@@ -1,4 +1,4 @@
-import { existsSync, statSync } from 'node:fs'
+import { existsSync } from 'node:fs'
 import { readdir, readFile } from 'node:fs/promises'
 import { join } from 'node:path'
 import { parseFrontmatter, readField } from '@/indexes/frontmatter'
@@ -12,17 +12,8 @@ import {
   recordDir as resolveRecordDir,
   recordDirs as resolveRecordDirs,
 } from '@/roots/record'
-import {
-  TEACH_GLOSSARY,
-  TEACH_MISSION,
-  TEACH_RECORDS,
-  TEACH_REFERENCE,
-  TEACH_RESOURCES,
-  TEACH_SUCCESS_HEADING,
-  WORKSPACE_NAME,
-} from '@/teach/workspace'
 
-export const RECORD_KINDS = ['plans', 'groundwork', 'intake', 'teach'] as const
+export const RECORD_KINDS = ['plans', 'groundwork', 'intake'] as const
 
 export type RecordKind = (typeof RECORD_KINDS)[number]
 
@@ -759,171 +750,9 @@ async function checkDump(dir: string, slug: string): Promise<Finding[]> {
   return [...findings, ...perCluster.flat()]
 }
 
-const NUMBERED_RECORD = /^\d{4}-[a-z0-9]+(-[a-z0-9]+)*\.md$/
-/**
- * A kebab slug that does not open with an ordinal. The lookahead rejects a
- * leading run of digits followed by a hyphen and nothing else, so a subject
- * whose own name starts with a digit still passes.
- */
-const REFERENCE_NAME = /^(?!\d+-)[a-z0-9]+(-[a-z0-9]+)*\.md$/
-
-/** The two fields every markdown file in a workspace carries. */
-async function checkTeachFile(
-  dir: string,
-  slug: string,
-  file: string,
-  subject: string,
-): Promise<Finding[]> {
-  const frontmatter = parseFrontmatter(await readFile(join(dir, file), 'utf8'))
-
-  const missing = ['title', 'description'].filter(
-    (field) => !readField(frontmatter, field),
-  )
-
-  if (missing.length === 0) return []
-
-  return [
-    finding(
-      'frontmatter-incomplete',
-      slug,
-      subject,
-      `carries no ${missing.join(' and no ')}.`,
-    ),
-  ]
-}
-
-/**
- * One markdown subfolder of a workspace. `lessons/` and `assets/` are never
- * reached, because a lesson is generated markup carrying no frontmatter and a
- * walk over it would report every one as malformed.
- */
-async function checkTeachSubfolder(
-  dir: string,
-  slug: string,
-  folder: string,
-  name: RegExp,
-  message: string,
-): Promise<Finding[]> {
-  const path = join(dir, folder)
-
-  // Tested as a directory rather than for presence. Every other walk in this
-  // module takes its path from `listFolders`, and this one is built from a
-  // fixed name, so a workspace holding a plain file called `reference` would
-  // reach `readdir` and take the whole run down with `ENOTDIR`.
-  if (!statSync(path, { throwIfNoEntry: false })?.isDirectory()) return []
-
-  const files = await listMarkdown(path)
-
-  const malformed = files
-    .filter((file) => !name.test(file))
-    .map((file) =>
-      finding('name-malformed', slug, `${folder}/${file}`, message),
-    )
-
-  const perFile = await Promise.all(
-    files.map((file) => checkTeachFile(path, slug, file, `${folder}/${file}`)),
-  )
-
-  return [...malformed, ...perFile.flat()]
-}
-
-async function checkWorkspace(dir: string, slug: string): Promise<Finding[]> {
-  const findings: Finding[] = []
-
-  if (!WORKSPACE_NAME.test(slug)) {
-    findings.push(
-      finding(
-        'name-malformed',
-        slug,
-        slug,
-        'is not named NN-<topic> with a two-digit ordinal, so a listing sorts alphabetically rather than by when each workspace opened.',
-      ),
-    )
-  }
-
-  const files = await listMarkdown(dir)
-
-  if (!files.includes(TEACH_MISSION)) {
-    findings.push(
-      finding(
-        'index-missing',
-        slug,
-        TEACH_MISSION,
-        'is absent, so the workspace states no subject and no success to finish against.',
-      ),
-    )
-  }
-
-  for (const required of [TEACH_RESOURCES, TEACH_GLOSSARY]) {
-    if (!files.includes(required)) {
-      findings.push(
-        finding(
-          'section-missing',
-          slug,
-          required,
-          'is required and the workspace carries no such file.',
-        ),
-      )
-    }
-  }
-
-  const perFile = await Promise.all(
-    files.map((file) => checkTeachFile(dir, slug, file, file)),
-  )
-  findings.push(...perFile.flat())
-
-  if (files.includes(TEACH_MISSION)) {
-    const text = await readFile(join(dir, TEACH_MISSION), 'utf8')
-
-    if (!hasOpeningDate(parseFrontmatter(text)?.raw ?? '')) {
-      findings.push(
-        finding(
-          'date-malformed',
-          slug,
-          TEACH_MISSION,
-          'carries no date field as YYYY-MM-DD, so the workspace states no opening day.',
-        ),
-      )
-    }
-
-    if (
-      !linesOutsideFences(text).some(
-        (line) => line.trim() === TEACH_SUCCESS_HEADING,
-      )
-    ) {
-      findings.push(
-        finding(
-          'section-missing',
-          slug,
-          TEACH_SUCCESS_HEADING,
-          'is absent, so the mission names no observable thing the learner will be able to do.',
-        ),
-      )
-    }
-  }
-
-  return [
-    ...findings,
-    ...(await checkTeachSubfolder(
-      dir,
-      slug,
-      TEACH_REFERENCE,
-      REFERENCE_NAME,
-      'is not named <slug>.md as a kebab slug opening with no ordinal, so a page looked up rather than worked through implies an order no reader follows.',
-    )),
-    ...(await checkTeachSubfolder(
-      dir,
-      slug,
-      TEACH_RECORDS,
-      NUMBERED_RECORD,
-      'is not numbered NNNN-<slug>.md, so the records carry no read order.',
-    )),
-  ]
-}
-
 /**
- * The three kinds whose records are folders rather than files. Keyed by kind so
- * a seventh arrives as an entry here and the compiler names the walk it owes,
+ * The two kinds whose records are folders rather than files. Keyed by kind so
+ * a third arrives as an entry here and the compiler names the walk it owes,
  * where a ternary chain would silently fall through to whichever branch is last.
  */
 const FOLDER_CHECK: Readonly<
@@ -934,7 +763,6 @@ const FOLDER_CHECK: Readonly<
 > = {
   groundwork: checkTrack,
   intake: checkDump,
-  teach: checkWorkspace,
 }
 
 /**

package/src/sandbox/equivalence.ts

@@ -74,11 +74,6 @@ export const MASKS: readonly Mask[] = [
     reason:
       'the install stamp carries a `syncedAt` wall-clock time, so two provisions of one commit differ',
   },
-  {
-    arm: 'claude:read-frames/resolved',
-    key: /^file:demos\/cold-open\.webm$/,
-    reason: 'ffmpeg output carries an encoder timestamp, so two runs differ',
-  },
   {
     key: /^log$/,
     replace: /sandbox-occupant-\d+|\(pid \d+\)/g,

package/src/shipped/references.ts

@@ -15,8 +15,7 @@ import { isMarked } from '@/sweep/exempt-marker'
  * number resolves.
  *
  * That is also what keeps the check a prose pattern rather than a parser.
- * `src/design/base.css` and `src/design/tokens.ts` carry sixteen values shaped
- * `#191512`, which no width or boundary rule separates from a pull request
+ * `src/design/tokens.ts` carries twenty values shaped `#191512`, which no width or boundary rule separates from a pull request
  * number, so telling them apart would need the line's syntactic position.
  */
 export const SHIPPED_CORPORA = [

package/src/sync/check.ts

@@ -2,7 +2,6 @@ import { existsSync } from 'node:fs'
 import { basename, join, sep } from 'node:path'
 import { execa } from 'execa'
 import { gitEnv } from '@/git/env'
-import { createDesignAdapter, DESIGN_INSTALL_DIR } from '@/design/adapter'
 import { createGovAdapter } from '@/gov/adapter'
 import { successorResolver } from '@/gov/renames'
 import { lookupRules } from '@/gov/install'
@@ -46,17 +45,11 @@ import { readSkew, type SkewReport } from '@/version/skew'
  * being one of these, because `src/tooling/` never calls `planSync`, so the
  * three lookups below have no entry to offer it. Standards and snippets left
  * the list with their install channels: nothing writes either corpus into a
- * target, so there is no installed copy to attribute.
- *
- * Design joins as a scanned domain rather than a stamp-only one because its
- * base file is attributed the same way a rule is, and its install marker is
- * what keeps it off a target that never asked for it: a project with no
- * `.claude/design/` is never scanned, so design values arrive on an install
- * rather than on the next sync.
+ * target, so there is no installed copy to attribute. Design left with its
+ * install verb for the same reason.
  */
 export const SCANNED_DOMAINS = [
   'governance',
-  'design',
 ] as const satisfies readonly StampDomain[]
 
 export type ScannedDomain = (typeof SCANNED_DOMAINS)[number]
@@ -68,17 +61,14 @@ export type ScannedDomain = (typeof SCANNED_DOMAINS)[number]
  */
 const SYNCED_SOURCES: Record<ScannedDomain, string> = {
   governance: 'governance/rules/',
-  design: 'src/design/',
 }
 
 const ADAPTERS: Record<ScannedDomain, (root: string) => SyncAdapter> = {
   governance: createGovAdapter,
-  design: createDesignAdapter,
 }
 
 const INSTALL_MARKERS: Record<ScannedDomain, readonly string[]> = {
   governance: ['.claude', 'rules', 'canon'],
-  design: DESIGN_INSTALL_DIR.split(sep),
 }
 
 export interface StateCounts {
@@ -215,33 +205,18 @@ export interface CheckReport {
   readonly skew: SkewReport
 }
 
-/**
- * Scanned domains a target takes deliberately rather than by being managed.
- *
- * An absent one is a choice, so it is never reported as unstamped. Governance
- * wants the opposite reading, since a managed target without it has yet to
- * install what every project is expected to carry, and naming it is the only
- * place that shows up.
- */
-export const OPT_IN_DOMAINS: readonly ScannedDomain[] = ['design']
-
 /**
  * Scanned domains this target should have stamped and has not, which is the
  * one line a domain nobody installed ever appears on.
  *
  * An unmigrated domain is excluded because the relocation is its remedy rather
- * than a sync, and an opt-in domain the target does not hold is excluded
- * because there is nothing there to stamp and the sync it would name refuses.
+ * than a sync.
  */
 export function uncoveredDomains(report: CheckReport): ScannedDomain[] {
   const unmigrated = new Set(report.unmigrated.map((entry) => entry.domain))
-  const installed = new Set(report.domains.map((entry) => entry.domain))
 
   return SCANNED_DOMAINS.filter(
-    (domain) =>
-      !report.covers.includes(domain) &&
-      !unmigrated.has(domain) &&
-      (!OPT_IN_DOMAINS.includes(domain) || installed.has(domain)),
+    (domain) => !report.covers.includes(domain) && !unmigrated.has(domain),
   )
 }
 

package/src/sync/stamp.ts

@@ -10,17 +10,17 @@ import { compareVersions, parseVersion } from '@/version/compare'
 import { readInstalled } from '@/version/installed'
 
 /**
- * Domains the stamp can record. Governance and design both attribute file by
- * file through the sync engine. Tooling runs its own inject and manifest
- * machinery, so it records the stack chain it resolved instead and carries no
- * file hashes.
+ * Domains the stamp can record. Governance attributes file by file through
+ * the sync engine. Tooling runs its own inject and manifest machinery, so it
+ * records the stack chain it resolved instead and carries no file hashes.
  *
  * A stamp written before the standards or snippets install channel closed
- * still carries a `standards` or `snippets` record. `isStamp` ignores the key
+ * still carries a `standards` or `snippets` record, and one written before the
+ * design install retired carries a `design` record. `isStamp` ignores the key
  * and `sortDomains` drops it on the next write, so the target loses a domain
  * nothing can refresh rather than losing the whole file.
  */
-export const STAMP_DOMAINS = ['governance', 'design', 'tooling'] as const
+export const STAMP_DOMAINS = ['governance', 'tooling'] as const
 
 export type StampDomain = (typeof STAMP_DOMAINS)[number]
 

package/src/sync/target.ts

@@ -1,9 +1,8 @@
 import { existsSync } from 'node:fs'
 import { join } from 'node:path'
-import { DESIGN_INSTALL_DIR } from '@/design/adapter'
 import { isDirectory } from '@/targets/validate'
 
-export const SYNC_DOMAINS = ['governance', 'design', 'claude'] as const
+export const SYNC_DOMAINS = ['governance', 'claude'] as const
 
 export type SyncDomain = (typeof SYNC_DOMAINS)[number]
 
@@ -14,7 +13,6 @@ export interface DomainState {
 
 const DOMAIN_MARKERS: Record<SyncDomain, string> = {
   governance: join('.claude', 'rules'),
-  design: DESIGN_INSTALL_DIR,
   claude: '.claude',
 }
 
@@ -26,7 +24,6 @@ const DOMAIN_MARKERS: Record<SyncDomain, string> = {
  */
 const DOMAIN_PATHS: Record<SyncDomain, readonly string[]> = {
   governance: ['.claude/rules/', '.claude/GOV.md'],
-  design: ['.claude/design/'],
   claude: ['.gitignore'],
 }
 

package/tooling/claude/reference.md

@@ -16,7 +16,7 @@ The claude stack installs the Claude Code workflow into a project through `canon
 
 - `.canon/tasks/` holds one file per task plus a generated `index.md`, local scratch only, with `archive/` holding the tasks that shipped
 - `.canon/plans/` holds execution detail for multi-step tasks, and `canon tasks archive` moves a `feature-*.md` plan into `archive/` when the `post-merge` hook archives its task
-- `.canon/review/` holds one subfolder per producer, with `design/` for `canon design render`
+- `.canon/review/` holds the reports a review or measurement skill writes, such as `ux-measure-<slug>.md`
 - `.canon/tmp/` is ephemeral scratch, safe to delete without loss
 - `.claude/worktrees/` is where `EnterWorktree` creates a linked worktree, which is why it stays under `.claude/`
 

package/tooling/claude/seeds/canon/DESIGN.md

@@ -1,6 +1,6 @@
 # Design
 
-Authoring guidance: the design standard. Values live in `<your stylesheet>`, such as `src/styles/tokens.css` or a Tailwind `@theme` block. A project with none writes them under `.claude/design/project/`, beside the installed base stylesheet.
+Authoring guidance: the design standard. Values live in `<your stylesheet>`, such as `src/styles/tokens.css` or a Tailwind `@theme` block. A project with none writes a stylesheet of its own and names it here.
 
 ## Overview
 

package/claude/skills/canvas-board/REQUIREMENT.md

@@ -1,35 +0,0 @@
----
-name: canvas-board
-description: Scope boundary for driving the local design canvas, and the line between a drafted frame and the design it feeds
----
-
-# Canvas board requirement
-
-## Gap
-
-Without this skill, a session asked to draw on the canvas writes frames nothing is serving and reports them drawn. It trusts a passing capture, though a blank shell passes every capture while the operator sees an empty tab. From a linked worktree it writes a copy the canvas never serves, and it captures after every edit.
-
-It reads "this one" from the conversation rather than the operator's selection, or acts on a stale element pick and edits the wrong element. It restyles through a class while the operator's inspector edit sits inline, so the change never shows. A picked frame stays on the canvas as the only record, and the project's design record never learns it.
-
-## Must
-
-- The canvas is serving and its live shell loads at the address the server reported before any frame is written, and a refusal or a blank shell is reported rather than drawn into
-- Pages and frames go through the verbs, so the session and the operator's drags share one writer, and a frame from a linked worktree takes the main-root route
-- The operator's selection decides what "this one" means, and a stale element pick reads as unknown
-- A frame's inline styles are read before a restyle, the run names which operator edits it kept and dropped, and capture runs once per finished frame or page
-- A picked frame is handed to `design-record` by page and frame, while a picked layout stays on the canvas for the plan that builds it
-
-## Must not
-
-- Present the canvas as the project's source of truth for design, or promise it survives a lost checkout
-- Write frames when `canon` or its canvas command is missing
-- Name any third-party design tool, or the canvas's predecessor surface
-- Be reached only by the author typing its name, since a request to draw, select, or capture on the canvas should reach it by description
-
-## Out of scope
-
-- Drafting candidates for a taste decision and taking the pick, which `pick-by-eye` owns
-- What the canvas verbs do internally, which the CLI's own contract owns
-- The content format a frame and a layout take, which the canvas standard owns
-- Landing a pick in the reference folder and carrying its values into the design document, which `design-record` owns
-- Tracing reference images into design values and backing up the canvas folder, which no skill owns

package/claude/skills/canvas-board/SKILL.md

@@ -1,143 +0,0 @@
----
-name: canvas-board
-description: Drives the local design canvas, where pages hold HTML frames the operator sees, drags, selects, and edits in the browser. Starts the canvas when it is not running, confirms the live shell loads, makes pages and frames, edits a frame through its file, reads what the operator selected or restyled, captures finished frames, and hands a picked frame to `design-record`. Use when asked to "open the canvas", "put this on the canvas", "draw a frame for X", "change the one I selected", "what did I pick", "capture this frame", or "move that frame on the canvas". Do NOT use to draft candidates for a taste decision, which is `pick-by-eye`.
-metadata:
-  family: decide
----
-
-# Canvas board
-
-Drive the canvas the operator is looking at. A page is a folder of HTML frames and a frame is one file, so a session draws by writing files and the operator sees each write land in the browser. The content format is fixed by `${CLAUDE_SKILL_DIR}/references/canvas.md`. Read it before writing a frame.
-
-Every verb below is `canon canvas`. Run `canon canvas --help` for the verbs and their refusals, and read `${CLAUDE_SKILL_DIR}/references/canvas.md` for the content format.
-
-## Guards
-
-- If `canon` is not on PATH, stop: `❌ canon CLI not found.`
-- If `canon canvas --help` reports no such command, stop: `❌ The installed canon carries no canvas command. Update the CLI and re-run.`
-- Write no frame before the canvas is serving and the shell has loaded. A frame nobody can see is a draft reported as delivered.
-- Never present a frame as the project's design. The canvas is a drafting surface and the project's design record holds what was decided.
-- Never promise the canvas survives a lost checkout. Its folder is gitignored and nothing backs it up.
-
-## Step 1: start the canvas and confirm the shell
-
-Read the pages first, which also proves the verb resolves:
-
-```bash
-canon canvas list --json
-```
-
-The record carries `content`, the folder every page lives in. It sits at the main worktree root whichever worktree the session runs in, so write through that path rather than one composed from the current directory.
-
-Start the server in the background unless the operator named an address that already answers, since it runs until interrupted. No verb reports a running server, and a second one is harmless, since it walks to the next free port and serves the same folder:
-
-```bash
-canon canvas serve --json
-```
-
-Read `url` off the record rather than composing one, since the server walks past a port already in use. Report the refusal and its `reason` when `ok` is false, and stop there.
-
-### Check the shell
-
-Fetch the printed address and check the shell itself, not a capture, since every capture goes through the frame route alone and passes on a blank shell.
-
-- The body is non-empty and carries a `<script` tag. An empty `200` means the shell failed to build, usually a missing dependency, so report a blank shell and stop.
-- `<url>/api/pages` answers with JSON listing the pages.
-
-Hand the operator the address as a markdown link carrying the URL as its text and its target.
-
-## Step 2: make pages and frames
-
-- Add a page for each decision being drafted: `canon canvas page add <page> --json`.
-- Follow the house style in `${CLAUDE_SKILL_DIR}/references/canvas.md` before drafting an explanation frame.
-- Add each frame with `canon canvas frame add <page> <frame> --width <px> --height <px> --json`, which writes the file and its box in one locked step
-
-Give each frame the width it should render at, since a capture and the canvas both render at it. The verb places the frame after the last one, and a position the operator asks for goes through `frame move`.
-
-### Layout and naming
-
-Lay frames out through the verbs rather than by hand, since the operator's drags write the same `layout.json` under a lock.
-
-- Move a frame with `canon canvas frame move <page> <frame> --x <px> --y <px> --json`
-- Name pages and frames for what they hold, such as `pricing` and `pricing-dense`, so the operator can say which one by name.
-- After an insert or a resize, re-lay the page with `canon canvas arrange <page> --json`. It keeps dragged rows, sets the standard gap, and drops entries whose file is gone.
-- Run `arrange --check` to report without writing
-
-## Step 3: edit a frame through its file
-
-Write the frame's whole document to the `path` the add verb reported. The open canvas reloads the frame when its file changes.
-
-- From a linked worktree, `Edit` and `Write` refuse a main-root path. Write the whole file through one plain `Bash` heredoc, the route `session-worktree` states, never a worktree copy.
-- Change one property with `canon canvas edit <page>/<frame> --element <index> --set <property>=<value> --json` when its set covers the change, since it leaves every other byte as it was
-- Use the project's custom properties for every value the token stylesheet defines. The `serve` record names the source under `tokens`, and `none` means frames render unstyled, so say so.
-
-### Fit the box
-
-Fit the box to the content once the write lands, with `canon canvas fit <page>/<frame> --json`, and read each row's `wide` and `font`.
-
-- A `wide` frame needs its box widened, which fit never does
-- A `font` frame names a family the canvas does not serve, so set its text to a served face and fit again
-- A fit that grew a frame leaves the rows below overlapped until `canvas arrange` runs
-
-### Mark the frame
-
-Mark the frame before the first write, so the operator sees which frame is being worked on before anything lands, and clear the mark once the edits to it are done:
-
-```bash
-canon canvas editing <page>/<frame> --json
-canon canvas editing <page>/<frame> --done --json
-```
-
-- A mark lapses after five minutes, so mark the frame again during a longer edit.
-- Clear it on every exit from the edit, including one that stopped on a refusal. Clearing a frame that holds no mark succeeds.
-- On `unknown command 'editing'`, the CLI predates the mark, so go on without it. Never run `canvas edit` in its place, since that verb writes the frame.
-
-## Step 4: read what the operator pointed at
-
-Read the selection when the operator says "this one", "the selected frame", or "that button":
-
-```bash
-canon canvas selection --json
-```
-
-- `selection: null` means nothing is selected or the selected frame is gone. Ask which one rather than guessing.
-- An `element` carrying `stale: true` was picked against an earlier file, so its `index` may land elsewhere. Ask the operator to pick again rather than matching its `tag` and `text` by eye.
-- A fresh `element` gives the `index` that `canvas edit` takes.
-
-## Step 5: respect the operator's inspector edits
-
-The operator restyles elements from the inspector, and each edit lands as inline `style` on the element. Inline style beats a class, so a class change made afterwards does not show.
-
-- Read the frame's inline `style` attributes before restyling anything in it.
-- Keep an inline property the operator set unless the change replaces it, and drop it, through `canvas edit` with an empty value or by rewriting the file, when it does.
-- Say which operator edits were kept and which were dropped.
-
-## Step 6: capture finished work
-
-Capture once per finished frame or page, not after every edit. The live canvas is the working view, and a capture is the record handed on.
-
-- Capture a frame with `canon canvas capture <page>/<frame> --json`. Each PNG is the whole document, so its height follows the content rather than the box.
-- Capture a page with `canon canvas capture <page> --composite --json`, which shows each frame clipped to its box at its layout position
-- Read each `path` off the record rather than composing one.
-
-A capture refused because a font is not installed names the family it read off the frame's text. Set that text's `font-family` to a named family the machine has, never a generic keyword such as `sans-serif`, and capture again rather than reporting the frame as captured.
-
-## Step 7: hand a picked frame on
-
-When the operator picks a frame, the decision leaves the canvas. Hand it to `canon:design-record`, which lands the frame in the project's reference folder and carries its values into the design document. Report it rather than proceeding silently when that skill does not resolve.
-
-- Name the page and frame the decision came from in the handoff and the reply, and leave the frame on the canvas until the operator clears it
-- Name the frame in the plan that builds a picked layout, since the layout reaches code through that plan
-- Never cite a frame path from a tracked file. The folder is gitignored, so the citation resolves on this machine alone.
-
-## Output
-
-```plaintext
-✅ Canvas: <url the serve verb reported>
-Page:     <page>, <n> frames
-Selected: <page>/<frame>, element <index>, or none, or stale
-Capture:  <path of each capture written>
-Handed:   <the frame handed to design-record, the plan that cites it, or not yet>
-```
-
-Write the canvas line's URL as a markdown link. Omit the capture line when nothing was captured and the handed line when no frame was picked. Emit every path from the project root.