@erclx/canon 4.98.0 → 4.100.0

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/tooling/web/configs/e2e/screenshot.ts

@@ -3,6 +3,12 @@ import { chromium } from '@playwright/test'
 import { mkdir } from 'fs/promises'
 import path from 'path'
 
+/** One addressable part of a route, captured beside the whole-page frame. */
+interface CaptureSection {
+  name: string
+  selector: string
+}
+
 interface CaptureCase {
   section: string
   theme: string
@@ -10,9 +16,35 @@ interface CaptureCase {
   width: number
   height: number
   evidence?: boolean
+  sections?: CaptureSection[]
   setup?: (page: Page) => Promise<void>
 }
 
+/**
+ * The landing page's own beats, top to bottom. Every entry is a section a
+ * reviewer reads on its own, so a diff lands on the part that moved rather
+ * than on one image of the whole page.
+ */
+const HOME_SECTIONS: CaptureSection[] = [
+  { name: 'top', selector: '#top' },
+  { name: 'proof', selector: '#proof' },
+  { name: 'ask', selector: '#ask' },
+  { name: 'rules', selector: '#rules' },
+  { name: 'skills', selector: '#skills' },
+  { name: 'plan', selector: '#plan' },
+  { name: 'dispatch', selector: '#dispatch' },
+  { name: 'workers', selector: '#workers' },
+  { name: 'gate', selector: '#gate' },
+  { name: 'memory', selector: '#memory' },
+  { name: 'evidence', selector: '#evidence' },
+  { name: 'loop', selector: '#loop' },
+  { name: 'merge', selector: '#merge' },
+  { name: 'provenance', selector: '#provenance' },
+  { name: 'start', selector: '#start' },
+  { name: 'field', selector: '#field' },
+  { name: 'close', selector: '#close' },
+]
+
 const CASES: CaptureCase[] = [
   {
     section: 'home',
@@ -21,6 +53,7 @@ const CASES: CaptureCase[] = [
     width: 1280,
     height: 800,
     evidence: true,
+    sections: HOME_SECTIONS,
   },
   {
     section: 'home',
@@ -28,6 +61,7 @@ const CASES: CaptureCase[] = [
     route: '/',
     width: 1280,
     height: 800,
+    sections: HOME_SECTIONS,
     setup: (page) => page.emulateMedia({ colorScheme: 'dark' }),
   },
 ]
@@ -53,6 +87,108 @@ try {
 
 const OUT_DIR = path.join('screenshots', hostname)
 
+/** Every wait on a lazy load is bounded explicitly. */
+const SETTLE_TIMEOUT = 15_000
+
+/** Marks the chrome a section frame drops, set on the page and read by the screenshot's own stylesheet. */
+const FLOATING_ATTRIBUTE = 'data-capture-floating'
+
+/**
+ * Brings the page to the state a reader arrives at, before anything is shot.
+ * A figure gated on an IntersectionObserver and a frame marked `loading=lazy`
+ * both stay at their start state until something scrolls past them, and a full
+ * page capture scrolls nothing, so each named section is scrolled into view
+ * once and the page then returns to the top. Fonts, images and frames settle
+ * afterwards, since the scroll is what starts the lazy loads.
+ */
+async function settle(
+  page: Page,
+  label: string,
+  sections: readonly CaptureSection[],
+): Promise<CaptureSection[]> {
+  const present: CaptureSection[] = []
+  for (const section of sections) {
+    const element = page.locator(section.selector)
+    // Read the count before scrolling, since a selector matching nothing
+    // otherwise costs the default timeout once per section. A miss is
+    // reported and skipped rather than raised, because `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. The project owning the
+    // selectors is the one that tests them, which is what the section spec
+    // beside its own page does.
+    if ((await element.count()) === 0) {
+      console.warn(
+        `${label}: no element matches ${section.selector}, named as section "${section.name}". Skipped.`,
+      )
+      continue
+    }
+    present.push(section)
+    await element.scrollIntoViewIfNeeded()
+  }
+  await page.evaluate(() => window.scrollTo(0, 0))
+  await page.evaluate(() => document.fonts.ready.then(() => undefined))
+  // Settle on what the scroll started rather than on a second `networkidle`,
+  // which is a lifecycle event of the navigation and does not re-arm for a
+  // load a scroll triggered afterwards.
+  await page.waitForFunction(
+    () => {
+      if (document.readyState !== 'complete') return false
+      for (const image of document.images) if (!image.complete) return false
+      for (const frame of document.querySelectorAll('iframe')) {
+        try {
+          const inner = frame.contentDocument
+          if (inner !== null && inner.readyState !== 'complete') return false
+        } catch {
+          // Cross-origin, so there is no readyState to read and nothing here
+          // can wait on it.
+        }
+      }
+      return true
+    },
+    undefined,
+    { timeout: SETTLE_TIMEOUT },
+  )
+  return present
+}
+
+/**
+ * Marks every element the page floats over its own content, which is chrome
+ * such as a sticky bar or a fixed dialog. A section taller than the viewport
+ * is scrolled into view to be shot, and the chrome rides that scroll into the
+ * middle of the frame, painting over the part the frame exists to show. The
+ * mark is an attribute rather than a style, so the rule that acts on it is
+ * carried by the screenshot itself and no state is left behind to restore.
+ *
+ * Marking costs the whole-page frame nothing, since that one is shot before
+ * this runs and carries the chrome where a reader meets it.
+ */
+async function markFloatingChrome(page: Page) {
+  await page.evaluate((attribute) => {
+    for (const node of document.querySelectorAll('body *')) {
+      const { position } = getComputedStyle(node)
+      if (position === 'sticky' || position === 'fixed') {
+        node.setAttribute(attribute, '')
+      }
+    }
+  }, FLOATING_ATTRIBUTE)
+}
+
+async function shoot(page: Page, dir: string, file: string, selector?: string) {
+  await mkdir(dir, { recursive: true })
+  const target = path.join(dir, file)
+  if (selector === undefined) {
+    await page.screenshot({ path: target, fullPage: true })
+  } 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,
+      style: `[${FLOATING_ATTRIBUTE}] { position: static !important; }`,
+    })
+  }
+  console.log(`captured ${target}`)
+}
+
 const browser = await chromium.launch()
 const consoleErrors: string[] = []
 let ranCases = 0
@@ -63,6 +199,10 @@ for (const captureCase of CASES) {
   ranCases++
   const context = await browser.newContext({
     viewport: { width: captureCase.width, height: captureCase.height },
+    // A page honoring the preference lands its own motion at the end state,
+    // which is what a still frame has to show. Playwright reads it as a
+    // context option, so it reaches no page written beside `viewport` above.
+    reducedMotion: 'reduce',
   })
   const page = await context.newPage()
 
@@ -81,19 +221,23 @@ for (const captureCase of CASES) {
   await page.goto(`${BASE_URL}${captureCase.route}`)
   await page.waitForLoadState('networkidle')
 
-  const sectionDir = path.join(OUT_DIR, captureCase.section)
-  await mkdir(sectionDir, { recursive: true })
+  const label = `${captureCase.section}/${captureCase.theme}`
+  const sections = await settle(page, label, captureCase.sections ?? [])
+
+  const sweepDir = path.join(OUT_DIR, captureCase.section)
+  const evidenceDir = path.join('evidence', captureCase.section)
+  const file = `${captureCase.theme}.png`
+
+  await shoot(page, sweepDir, file)
+  if (captureCase.evidence) await shoot(page, evidenceDir, file)
 
-  const file = path.join(sectionDir, `${captureCase.theme}.png`)
-  await page.screenshot({ path: file, fullPage: true })
-  console.log(`captured ${file}`)
+  if (sections.length > 0) await markFloatingChrome(page)
 
-  if (captureCase.evidence) {
-    const evidenceDir = path.join('evidence', captureCase.section)
-    await mkdir(evidenceDir, { recursive: true })
-    const evidenceFile = path.join(evidenceDir, `${captureCase.theme}.png`)
-    await page.screenshot({ path: evidenceFile, fullPage: true })
-    console.log(`captured ${evidenceFile}`)
+  for (const { name, selector } of sections) {
+    await shoot(page, path.join(sweepDir, name), file, selector)
+    if (captureCase.evidence) {
+      await shoot(page, path.join(evidenceDir, name), file, selector)
+    }
   }
 
   await context.close()

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, a route, and its own viewport, and the loop below writes `screenshots/<hostname>/<section>/<theme>.png`, keyed on `SCREENSHOT_BASE_URL`'s hostname so a local and a deployed run land in different folders. A case flagged `evidence: true` additionally writes `evidence/<section>/<theme>.png`, with no hostname segment. `--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 themes sit together under its section folder, so the filename carries the theme alone. `--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, a route, and its own viewport, and the loop below writes `screenshots/<hostname>/<section>/<theme>.png`, keyed on `SCREENSHOT_BASE_URL`'s hostname so a local and a deployed run land in different folders. A case flagged `evidence: true` additionally writes `evidence/<section>/<theme>.png`, with no hostname segment. `--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 themes sit together under its section folder, so the filename carries the theme alone. 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>/<theme>.png` beside the whole-page one, plus `evidence/<section>/<name>/<theme>.png` where the case is flagged. 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`.
 - `.vscode/extensions.json` and `.vscode/settings.json`: editor wiring for ESLint, Tailwind, Playwright, Vitest.
 - `.github/workflows/verify.yml`: `static-checks`, `unit-tests`, `build-verify`, and `e2e-tests` jobs.
 - `scripts/verify.sh`: extends base verify with typecheck, lint, unit tests, and build in the full order.
@@ -112,7 +112,7 @@ Append rows:
 
 `governance/rules/ui/440-surface-capture.md` is what asks a session to run the capture after a surface changes. It now fires on every component file too, reversing the route-and-page-only scope this reference once described, after a shipped batch of components carried no capture and a defect went unseen. The rule body states its own exemption for a component the production build strips out, so a reader chasing that case reads it there rather than here.
 
-The sweep under `screenshots/` is ignored again, and only a flagged case's `evidence/` output tracks in git, so the first capture a scaffolded target runs after this change is the baseline it commits there.
+The sweep under `screenshots/` is ignored again, and only a flagged case's `evidence/` output tracks in git, so the first capture a scaffolded target runs after this change is the baseline it commits there. A case naming sections commits a folder per section under that baseline rather than one file per theme, which is what lets a pull request comparison land on the part of the page that moved instead of on one image of the whole of it. The count is the section list times the themes, so a list is worth sizing against how many frames each later change has to regenerate and a reviewer has to read.
 
 ## Gitignore (extend)
 

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.