@erclx/canon 4.97.0 → 4.99.0

package/src/slides/styles.ts

@@ -1,4 +1,4 @@
-import { bareHex, colorValue } from '@/design/tokens'
+import { bareHex, colorValue, TOKENS } from '@/design/tokens'
 
 export type Variant = 'light' | 'dark'
 
@@ -23,11 +23,36 @@ const ROLES: Record<keyof Theme, readonly [dark: string, light: string]> = {
   accent: ['accent', 'light-accent'],
 }
 
+/**
+ * `PptxGenJS` takes one installed family name where the record declares a
+ * stack, and a `.pptx` cannot embed the face. The first family is taken with
+ * its ` Variable` suffix dropped, since that suffix names the CSS package and
+ * not the installed family, and PowerPoint picks its own substitute when the
+ * face is missing.
+ */
+function familyName(role: string): string {
+  const token = TOKENS.typography.find((entry) => entry.role === role)
+  const family = token?.family
+    .split(',')[0]
+    ?.trim()
+    .replace(/ Variable$/, '')
+  if (!family) {
+    throw new Error(`The design record declares no ${role} type role`)
+  }
+
+  return family
+}
+
 export const FONTS = {
-  heading: 'Arial',
-  body: 'Calibri',
+  heading: familyName('display'),
+  body: familyName('body'),
 } as const
 
+/**
+ * Deck-owned point sizes. The record's `t0` to `t6` steps are screen pixels,
+ * which read as points on a 13.33 inch slide would shrink the cover to 38 and
+ * the body to 11, so only the face and the colors come from the record.
+ */
 export const TYPE = {
   cover: 44,
   section: 40,

package/src/tasks/archive.ts

@@ -7,6 +7,7 @@ import { recordDir, recordDirs } from '@/record-root'
 
 const TASKS = 'tasks'
 const PLANS = 'plans'
+const READY = 'ready'
 const ARCHIVE = 'archive'
 const DECLINED = 'declined'
 const BACKLOG = 'backlog.md'
@@ -75,6 +76,12 @@ export interface PlanMove {
   readonly to: string
 }
 
+/** A ready folder carried into the archive alongside the plan that is its verbatim source. */
+export interface ReadyMove {
+  readonly from: string
+  readonly to: string
+}
+
 export interface ArchiveSuccess {
   readonly ok: true
   readonly stem: string
@@ -84,6 +91,8 @@ export interface ArchiveSuccess {
   readonly indexRegenerated: boolean
   /** Undefined when the task cited no live plan, or when another task still holds it. */
   readonly plan: PlanMove | undefined
+  /** Undefined when the plan stays, or when no ready folder resolves and can move. */
+  readonly ready: ReadyMove | undefined
   readonly closed: number
   readonly cut: number
 }
@@ -280,6 +289,32 @@ export function retargetPlanLine(text: string, target: string): string {
   return text.replace(PLAN_PATTERN, () => planLine(target))
 }
 
+/** The `Ready:` line in either form, matched the way `PLAN_PATTERN` matches `Plan:`. */
+const READY_PATTERN = /^Ready:[ \t]*(?:\[[^\]]*\]\(([^)]+)\)|(\S+))[ \t]*$/m
+
+/** A ready folder path as a plan's constraints write it, the folder name captured. */
+const READY_PATH_PATTERN = /(\.(?:canon|claude)\/ready\/)([^\s/`)]+)(?=\/)/g
+
+export function readReadyTarget(text: string): string | undefined {
+  const match = READY_PATTERN.exec(text)
+  if (!match) return undefined
+  return match[1] ?? match[2]
+}
+
+/**
+ * Builds a `Ready:` line as a link whose target keeps the trailing slash a
+ * folder carries, the label taken from the folder's own name.
+ */
+export function readyLine(target: string): string {
+  const folder = target.replace(/\/+$/, '')
+
+  return `Ready: [${basename(folder)}](${folder}/)`
+}
+
+export function retargetReadyLine(text: string, target: string): string {
+  return text.replace(READY_PATTERN, () => readyLine(target))
+}
+
 /**
  * Builds the `Declined:` line recording why a task was decided against and by
  * whom. Free prose after the colon, since the line names no file to link,
@@ -731,22 +766,41 @@ export async function archiveTask(
   }
 
   const plan = await planToArchive(dir, root, stem, text)
+  const ready = plan && (await readyToArchive(dir, root, text, plan))
   const destination = archiveDir(root)
   const to = join(destination, `${stem}.md`)
 
   // The plan moves first so the line written below describes a file already at
   // its new path. Writing the retarget first and failing the move would leave a
   // pointer at a folder holding nothing, and `.canon/plans/` is gitignored, so
-  // no history recovers the target it named.
+  // no history recovers the target it named. The folder follows the plan and
+  // both precede the task, so a failed rename never leaves the task archived
+  // with its folder live, which the unattended post-merge hook cannot repair.
   if (plan) {
     await mkdir(dirname(plan.to), { recursive: true })
     await rename(plan.from, plan.to)
   }
 
+  if (ready) {
+    await mkdir(dirname(ready.to), { recursive: true })
+    await rename(ready.from, ready.to)
+    await writeFile(
+      plan.to,
+      retargetReadyPaths(await readFile(plan.to, 'utf8'), basename(ready.from)),
+    )
+  }
+
   await mkdir(destination, { recursive: true })
   await rename(from, to)
-  if (plan)
-    await writeFile(to, retargetPlanLine(text, linkTo(destination, plan.to)))
+  if (plan) {
+    const retargeted = retargetPlanLine(text, linkTo(destination, plan.to))
+    await writeFile(
+      to,
+      ready
+        ? retargetReadyLine(retargeted, `${linkTo(destination, ready.to)}/`)
+        : retargeted,
+    )
+  }
 
   const priorityRowRemoved = await clearPriorityRow(dir, stem)
   const regen = await regenOne(dir, { dryRun: false })
@@ -759,6 +813,7 @@ export async function archiveTask(
     priorityRowRemoved,
     indexRegenerated: regen.action === 'written',
     plan,
+    ready: ready || undefined,
     closed: closed.length,
     cut: cut.length,
   }
@@ -797,6 +852,63 @@ async function planToArchive(
   }
 }
 
+/**
+ * The ready folder that travels with the plan, or nothing. It is read from the
+ * task's `Ready:` line, falling back to a folder path in the plan's own text for
+ * a task written before the line was defined. It moves only with its plan,
+ * since the folder is the plan's verbatim source and a plan another task still
+ * cites still needs it, so the caller passes the plan `planToArchive` settled.
+ *
+ * A target naming no folder, one already archived, or a destination taken
+ * yields nothing and refuses nothing, the way a mistyped `Plan:` does.
+ */
+async function readyToArchive(
+  dir: string,
+  root: string,
+  text: string,
+  plan: PlanMove,
+): Promise<ReadyMove | undefined> {
+  const live =
+    readyFolder(dir, root, text) ??
+    readyFolder(dir, root, await readFile(plan.from, 'utf8'))
+  if (!live) return undefined
+
+  const to = join(recordDir(root, READY, ARCHIVE), basename(live))
+  if (existsSync(to)) return undefined
+
+  return { from: live, to }
+}
+
+function readyFolder(
+  dir: string,
+  root: string,
+  text: string,
+): string | undefined {
+  const target = readReadyTarget(text)
+  const named = target ? [resolve(dir, target), resolve(root, target)] : []
+  const constrained = [...text.matchAll(READY_PATH_PATTERN)].map(([, , name]) =>
+    join(recordDir(root, READY), name),
+  )
+  const archives = recordDirs(root, READY, ARCHIVE)
+
+  return [...named, ...constrained].find(
+    (path) =>
+      recordDirs(root, READY).some((base) => dirname(path) === base) &&
+      basename(path) !== ARCHIVE &&
+      !archives.some((base) => isUnder(path, base)) &&
+      existsSync(path),
+  )
+}
+
+/** Points the plan's literal folder paths at `ready/archive/`, since the folder no longer sits where they say. */
+function retargetReadyPaths(text: string, folder: string): string {
+  return text.replace(
+    READY_PATH_PATTERN,
+    (whole: string, prefix: string, name: string) =>
+      name === folder ? `${prefix}${ARCHIVE}/${name}` : whole,
+  )
+}
+
 /**
  * The archived plan as the archived task cites it. Both halves land a folder
  * deeper than the live pair, so the link is measured between the two

package/standards/ready.md

@@ -78,7 +78,7 @@ Below the frontmatter, state in prose what the worker still owns beyond copying
 ## Lifecycle
 
 - Write the ready folder in the same session that writes the files it carries. A folder assembled later from memory is a plan with extra steps, not a handoff.
-- Move the folder to `.canon/ready/archive/<nn>-<slug>/` by hand when the task that shipped it archives. No board verb currently automates this move. `canon tasks archive` moves the task and its plan and leaves the ready folder where it is.
+- Leave the move to `canon tasks archive`, which carries the folder to `.canon/ready/archive/<nn>-<slug>/` with its plan when the task that shipped it archives, and retargets the task's `Ready:` line. A plan another live task still cites keeps its folder.
 - Never delete a ready folder. The archived copy sits beside the merged pull request as the exact text that shipped, the way an archived plan sits beside the reasoning that produced it.
 
 ## Anti-patterns
@@ -86,7 +86,7 @@ Below the frontmatter, state in prose what the worker still owns beyond copying
 - **The folder with an undeclared destination.** A file the plan's `**Files to touch:**` does not list passes the collision check unseen, and a second track can write the same path without either side finding out.
 - **The rewritten copy.** A worker that reads the folder's files as inspiration and writes its own version loses the exact text the handoff exists to carry.
 - **The folder as scratch.** Notes, alternates, or draft passages left in the folder beside the real files leave the worker guessing which is the source.
-- **The folder left live after shipping.** A ready folder nobody moves to the archive reads as unshipped work to the next session that lists the live folder.
+- **The folder left live after shipping.** A ready folder the archive verb did not move reads as unshipped work to the next session that lists the live folder. The verb skips one whose task carries no `Ready:` line and cites no folder path in its plan.
 
 ## Template
 

package/standards/tasks.md

@@ -213,7 +213,9 @@ A task with no origin is either lost context or work nobody decided to do. The i
 
 An intake folder answers that direction at folder scope rather than item scope, since one dump dispositions many items and most close without ever becoming a task. What names a folder is every item answered and no task citing it, on the board or in the archive. That is a dump nobody acted on. Counting the archive and declined folder beside the board is what separates it from one already promoted and settled, and a check reading the board alone calls every finished folder abandoned.
 
-`Plan:`, `Groundwork:`, and `Intake:` name their target as a markdown link whose text is the file or folder stem, so the line resolves on a ctrl-click the way `priority.md` rows already do. Write the path relative to `.canon/tasks/`, which makes it `../plans/`, `../groundwork/`, and `../intake/`. A path written from the project root renders as a link and resolves to nothing in an editor rooted at the project. `Issue:` stays a bare `#NNN`, since an issue number is not a path and a full URL would write the remote into a gitignored file.
+`Plan:`, `Groundwork:`, and `Intake:` name their target as a markdown link whose text is the file or folder stem, so the line resolves on a ctrl-click the way `priority.md` rows already do. Write the path relative to `.canon/tasks/`, which makes it `../plans/`, `../groundwork/`, and `../intake/`. A path written from the project root renders as a link and resolves to nothing in an editor rooted at the project. `Ready:` names the ready folder a task's plan copies from, as a link to `../ready/<nn>-<slug>/` with the trailing slash a folder carries. Include it only when the folder exists. `canon tasks archive` reads it to move the folder, and falls back to a `.canon/ready/<nn>-<slug>/` path in the plan when a task carries no line.
+
+`Issue:` stays a bare `#NNN`, since an issue number is not a path and a full URL would write the remote into a gitignored file.
 
 Phase-label format and where labels may appear are governed by `standards/versioning.md`.
 
@@ -257,7 +259,7 @@ The archive nests inside `.canon/tasks/` rather than sitting beside it as a flat
 
 One destination rather than a per-project choice is what lets the move happen without asking. It mirrors the plans archive at `.canon/plans/archive/`, sitting inside the folder it archives the same way, and it inherits the board's own ignore entry rather than needing one of its own. The cost is that an archived task does not appear in diffs, which is the cost the live board already carries.
 
-Archiving a task archives its plan alongside it, when the closing task is that plan's last live citation. The archived task's `Plan:` line is retargeted at `../../plans/archive/feature-<slug>.md`, a folder deeper than the live task wrote it, so a completed task still leads to the reasoning behind it. A plan several tasks share stays live and the task archives anyway, since moving it on the first task to close strands every sibling's pointer at a path that has gone.
+Archiving a task archives its plan alongside it, when the closing task is that plan's last live citation. The archived task's `Plan:` line is retargeted at `../../plans/archive/feature-<slug>.md`, a folder deeper than the live task wrote it, so a completed task still leads to the reasoning behind it. The ready folder the task's `Ready:` line names moves with the plan to `.canon/ready/archive/<nn>-<slug>/`, and the `Ready:` line and the plan's path to the folder are retargeted, since the folder is the plan's verbatim source. A plan several tasks share stays live and the task archives anyway, since moving it on the first task to close strands every sibling's pointer at a path that has gone. Its ready folder stays with it.
 
 One act rather than two is what makes the pair safe. The merge is the event that settles a plan, and a `post-merge` hook reaching the archive with nobody watching cannot act on a warning, so a second call after it would be a second failure point leaving the task archived and the plan live.
 

package/claude/skills/ui-test/REQUIREMENT.md

@@ -1,48 +0,0 @@
----
-name: ui-test
-description: Why UI changes split into what a browser can assert and what only an eye can judge, and why the visual half is written to disk rather than printed
----
-
-# UI test requirement
-
-## Gap
-
-Without this skill, UI work ships on the confidence of the session that wrote it. What verification does happen mixes the two kinds without noticing, so a checklist item about spacing sits beside one about a form submission, and neither is done properly because they need different work from different people. Tests get written against a config the project does not use, or duplicate what a component test already covers.
-
-The automatable half fails the other way. Sending every interaction, state, and form to Playwright leaves the layers unrouted, so a loading state lands in a full browser run and the end to end suite grows on each UI change. A state a component test reaches costs a browser to check, and the cost recurs on every later run.
-
-The visual half is where the record is lost. A checklist printed into chat scrolls away before anyone verifies it, so the ship step has nothing to gate on and the work reads as verified because a list was produced. Written from a linked worktree against `pwd`, the file lands where the caller does not look.
-
-Writing the checklist correctly to disk does not close the gap either. The file sits under a gitignored folder on the machine that authored it, so a pull request reviewer, on that machine or another, never sees it. A record that only the author can open reads as verified for the same reason a record that never existed does.
-
-## Must
-
-- Split every change into visual-only and automatable before writing anything, then route each automatable one to its layer through `test-craft`
-- Write end to end only for a journey or a behavior only a real browser renders, and component or unit tests for the rest
-- Name a missing component runner in the output and put the state on the checklist
-- Read the project's existing test config and patterns before writing a test against them
-- Assert a user action and its outcome per test, covering the happy path and the key edge cases
-- Run the tests after writing them and fix what fails
-- Write a produced checklist to the `.canon/tmp/handoff/ui-checklist/<slug>.md` handoff at the main worktree root, overwriting
-- Report that everything is covered rather than manufacturing a checklist to show work
-
-## Must not
-
-- Try to assert a visual property programmatically
-- Re-test what unit or component tests written during implementation already cover
-- Route a state a component test reaches into end to end, or fall back to end to end silently when no runner exists
-- Repeat the full checklist in chat, which is what made it evaporate
-- Stage or commit the checklist, which is gitignored scratch
-- Talk to GitHub directly. Posting the checklist to a pull request belongs to `git-pr`, the sole consumer of the handoff file
-
-## Guards
-
-- No implementation context in the session: stop, since there is nothing to derive tests from
-- Every change automatable: skip the file write and report the coverage
-
-## Out of scope
-
-- Judging whether the UI is any good, which `ux-audit` owns
-- The rules for choosing a layer, which `test-craft` owns
-- Deciding whether an outstanding checklist blocks the ship, which the calling pipeline gates on
-- Performing the visual verification, which needs a person

package/claude/skills/ui-test/SKILL.md

@@ -1,87 +0,0 @@
----
-name: ui-test
-description: Routes each UI change to the test layer that can catch its break, writes end to end tests only for journeys and browser-only behavior, and produces a manual checklist for visual-only items. Use after implementing UI changes, or when asked "what should I test", "what do I verify", or "give me a test checklist". Do NOT use in empty sessions with no implementation context.
----
-
-# UI test
-
-## Guards
-
-- If no implementation context exists in the session, stop: `❌ No implementation context. Describe what you built first.`
-- Load `canon:test-craft` before writing any test, and report it rather than proceeding silently when it does not resolve.
-
-## Analysis
-
-Review the session to identify what was built or changed. Categorize each change, then route it:
-
-- **Visual-only:** spacing, alignment, color, typography, layout proportions, animation timing. These become a manual checklist.
-- **Journey or browser-only:** a flow across routes, a route change, or a behavior only a real browser renders, such as scroll, focus order across pages, or layout. These become end to end tests.
-- **Everything else:** interactions, state transitions, form submissions, keyboard handling, conditional rendering, loading, empty, and error states. Route these through the `test-craft` layer table to a component test, or to a unit test when the logic renders nothing.
-
-Never write an end to end test for a state a component test reaches. Exclude anything already covered by tests written during implementation.
-
-## Component and unit tests
-
-- Read the project's test config and an existing test at the layer first, and follow its runner, suffix, and placement.
-- Read the `test-craft` component reference before the first component test.
-- Assert each state through what a user sees or does, covering the happy path and the key edges.
-- When the project has no component runner, write the checklist item for that state instead of an end to end test, and name the missing runner in the output. Do not fall back to end to end silently.
-
-## E2e tests
-
-Write Playwright tests for journeys and browser-only behavior only. Follow these rules:
-
-- Read the `test-craft` end to end reference before the first one.
-- Add tests to the project's existing `e2e/` layout and naming. If none exists, create `e2e/<feature>.spec.ts`.
-- Use the project's existing Playwright config and test patterns. Read them first.
-- Each test performs a user action across the journey and asserts the expected outcome.
-- For Chrome extensions: load the unpacked extension via Playwright's `--load-extension` flag and use the extension's sidepanel or popup URL as the test target.
-- Run every test written, at every layer. Fix failures before finishing.
-
-Test structure:
-
-```typescript
-test('description of user flow', async ({ page }) => {
-  // Arrange: navigate, set up state
-  // Act: perform user action
-  // Assert: verify expected outcome
-})
-```
-
-## Manual checklist
-
-For visual-only items that cannot be asserted programmatically, and for any state left without a runner, produce a checklist. Group by feature area. Use `- [ ]` checkbox syntax.
-
-```markdown
-**What to verify visually:**
-
-**<Feature area>**
-
-- [ ] <action> → <expected visual result>
-```
-
-If every change is covered by a test, skip the manual checklist:
-
-`✅ All changes covered by tests. No manual verification needed.`
-
-### Persist the checklist
-
-Derive `<slug>` per `${CLAUDE_SKILL_DIR}/../../standards/slug.md`. Fall back to `latest` on an empty result.
-
-When a manual checklist is produced, write it directly to `.canon/tmp/handoff/ui-checklist/<slug>.md` at the main worktree root, not the current worktree. Resolve that root the way `session-worktree` does. Create the directory if it does not exist. Always overwrite. This is a handoff file rather than a deliverable: `git-pr` posts it as a pull request comment once one opens, then removes it, and nothing here talks to `gh` directly.
-
-From a linked worktree the file-editing tools refuse that path, so the checklist goes out through `Bash`. Send the `mkdir -p` and the heredoc as two plain commands rather than joining them with `&&`, which is refused as compound.
-
-Skip the file write when every change is covered by tests and no checklist was produced.
-
-The `.canon/tmp/` directory is gitignored. Do not stage or commit the file.
-
-## Output order
-
-1. Write and run the tests, naming each one's layer (report pass/fail)
-2. Name any state left to the checklist for want of a component runner
-3. If a manual checklist was produced, write it to file, then output only the file path in chat:
-   `📝 Wrote .canon/tmp/handoff/ui-checklist/<slug>.md`
-4. If no checklist was needed: `✅ All changes covered by tests. No manual verification needed.`
-
-Do not repeat the full checklist in chat.