@erclx/canon 4.41.0 → 4.43.0

package/claude/.claude-plugin/plugin.json

@@ -1,7 +1,7 @@
 {
   "name": "canon",
   "description": "Automated governance, versioning, and discovery tools for Claude Code.",
-  "version": "4.41.0",
+  "version": "4.43.0",
   "author": {
     "name": "Eric Le",
     "url": "https://github.com/erclx"

package/claude/skills/canon-cli/SKILL.md

@@ -34,6 +34,7 @@ Run `canon tooling sync <stack> <target> --check` for the list resolved against
 - `astro.config.mjs`
 - `eslint.config.js`
 - `playwright.config.ts`
+- `src/components/dev/scenarios.astro`
 - `tsconfig.json`
 - `vitest.config.ts`
 

package/claude/skills/claude-autoship/SKILL.md

@@ -91,7 +91,7 @@ Do not loop. Do not bypass hooks.
 
 If the diff touches UI files (JSX, TSX, Vue, Svelte, HTML, or CSS under `src/`), invoke `canon:claude-ui-test`.
 
-If `claude-ui-test` produces a manual checklist, stop: `❌ UI requires visual verification. Checklist at .canon/review/ui-checklist-<slug>.md. Verify manually, then run /git-ship.`
+If `claude-ui-test` produces a manual checklist, stop: `❌ UI requires visual verification. Checklist at .canon/tmp/ui-checklist/<slug>.md, which reaches the pull request once /git-ship runs. Verify manually, then run /git-ship.`
 
 If all UI changes are covered by e2e tests, continue.
 

package/claude/skills/claude-docs/SKILL.md

@@ -235,7 +235,7 @@ For each receipt, count the H2 items still marked 📝 pending:
 
 That standard owns what a fold writes and which entry types take one. `claude-memory-review` collects a receipt on the same rule, so neither body restates it.
 
-Do not sweep `ui-checklist-*.md` (pending human verification), `ux-audit-*.md`, or `ux-measure-*.md` (standalone deliverables). Those sit at `.canon/review/` itself rather than under a producer folder, so the two globs above never reach them.
+Do not sweep `ux-audit-*.md` or `ux-measure-*.md` (standalone deliverables). Those sit at `.canon/review/` itself rather than under a producer folder, so the two globs above never reach them.
 
 Output one line per file swept:
 

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

@@ -11,13 +11,15 @@ Without this skill, UI work ships on the confidence of the session that wrote it
 
 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 automatable and visual-only before writing anything
 - 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 branch-derived path at the main worktree root, overwriting
+- Write a produced checklist to the `.canon/tmp/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
@@ -26,6 +28,7 @@ The visual half is where the record is lost. A checklist printed into chat scrol
 - Re-test what unit or component tests written during implementation already cover
 - 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
 

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

@@ -59,19 +59,19 @@ If all changes are automatable, skip the manual 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/review/ui-checklist-<slug>.md` at the main worktree root, not the current worktree. Resolve that root the way `claude-worktree` does. Create the directory if it does not exist. Always overwrite.
+When a manual checklist is produced, write it directly to `.canon/tmp/ui-checklist/<slug>.md` at the main worktree root, not the current worktree. Resolve that root the way `claude-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 all changes are covered by e2e tests and no checklist was produced.
 
-The `.canon/review/` directory is gitignored. Do not stage or commit the file.
+The `.canon/tmp/` directory is gitignored. Do not stage or commit the file.
 
 ## Output order
 
 1. Write and run e2e tests (report pass/fail)
 2. If a manual checklist was produced, write it to file, then output only the file path in chat:
-   `📝 Wrote .canon/review/ui-checklist-<slug>.md`
+   `📝 Wrote .canon/tmp/ui-checklist/<slug>.md`
 3. If no checklist was needed: `✅ All changes covered by e2e tests. No manual verification needed.`
 
 Do not repeat the full checklist in chat.

package/claude/skills/git-pr/SKILL.md

@@ -135,6 +135,30 @@ rm -rf .canon/tmp/pr
 printf 'number=%s\nurl=%s\n' "$pr_number" "$pr_url"
 ```
 
+### Post the UI checklist
+
+`claude-ui-test` writes a manual checklist to `.canon/tmp/ui-checklist/<slug>.md` at the main worktree root when a change needs visual verification, with `<slug>` derived per `${CLAUDE_SKILL_DIR}/../../standards/slug.md`. This step is the file's sole consumer. Resolve the main root the way `claude-worktree` does (`git worktree list --porcelain | grep -m 1 '^worktree ' | cut -d' ' -f2-`, falling back to `pwd`) and check for the file there. A missing file means no checklist was produced, and there is nothing to post.
+
+When it exists, scan it against `${CLAUDE_SKILL_DIR}/../../standards/publish.md` before posting, the same as the pull request body above. Post it as its own comment on `<number>`, the number the final command above resolved, rather than folding it into the body, since a later push editing the body would overwrite checkboxes a reviewer already ticked:
+
+```bash
+gh pr comment <number> --body-file <main-root>/.canon/tmp/ui-checklist/<slug>.md
+```
+
+Run the cleanup below only once that call reports success. On a failure, stop and leave the file in place: a retry needs the checklist to still be there, and deleting it on a failed post loses the only copy with nothing landed on the pull request.
+
+From a linked worktree the file-editing tools refuse a main-root path, so the cleanup goes out through `Bash` as two plain commands, the file and then the folder, rather than joined by `&&`, which is refused as compound:
+
+```bash
+rm <main-root>/.canon/tmp/ui-checklist/<slug>.md
+```
+
+```bash
+rmdir <main-root>/.canon/tmp/ui-checklist 2>/dev/null || true
+```
+
+The `rmdir` is a no-op when another branch's pending checklist still sits in the folder, which keeps this step from deleting a handoff that is not its own.
+
 ### Record the number on the task
 
 Write the `number` the final command printed onto the task the branch is closing. Do not resolve it again. `${CLAUDE_SKILL_DIR}/REQUIREMENT.md` states why: a lookup that resolves by branch alone can return a closed pull request sharing that head, so the number is resolved once and reused rather than re-derived.
@@ -167,4 +191,8 @@ Add a further line only when the labelling command printed its warning, quoting
 
 `⚠️ Labels not applied: <what gh reported>`
 
+Add a line when the UI checklist step posted a comment, naming the pull request it landed on:
+
+`📋 Posted the UI checklist to <number>.`
+
 Do not add any other text.

package/docs/workflow/ai-workflow.md

@@ -78,7 +78,7 @@ When features are independent, run them in parallel instead of sequentially. Use
 
 - Create a worktree per feature, then start a Claude Code session in each
 - Invoke `canon:claude-feature` in each session. Plans land at the main worktree root as `.canon/plans/feature-<slug>.md`, one per feature, no collisions. Small features stay in chat and skip the file.
-- Implement, verify, and review each feature independently. `claude-review` and `claude-ui-test` write per-branch files at the main worktree root (`review/branch/review-<slug>.md`, `review/ui-checklist-<slug>.md`), so parallel sessions do not overwrite each other. The slug is the branch name with any leading type segment dropped, so `feat/jwt-expiration` and the plan at `feature-jwt-expiration.md` meet on one name
+- Implement, verify, and review each feature independently. `claude-review` writes a per-branch report at the main worktree root (`review/branch/review-<slug>.md`), and `claude-ui-test` writes a per-branch checklist handoff there too (`tmp/ui-checklist/<slug>.md`) that `git-pr` posts to the pull request and removes, so parallel sessions do not overwrite each other. The slug is the branch name with any leading type segment dropped, so `feat/jwt-expiration` and the plan at `feature-jwt-expiration.md` meet on one name
 - Ship each worktree separately with `canon:git-ship`
 - For full autonomy per worktree, invoke `canon:claude-autoship` instead of the manual chain. Approve the plan, walk away, come back to a pull request the chain marked as a draft and then read the flag back on. The mark says the work has had no review yet, and it holds no window, since readying a pull request to merge lifts it and is the operator's act.
 

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@erclx/canon",
   "type": "module",
-  "version": "4.41.0",
+  "version": "4.43.0",
   "description": "Infrastructure and quality tooling for developer workflows",
   "license": "MIT",
   "bin": {

package/tooling/astro/configs/src/components/dev/scenarios.astro

@@ -0,0 +1,127 @@
+---
+/**
+ * Serves candidate treatments of one decision from the running page, selected
+ * by a query parameter, with a switcher for moving between them.
+ *
+ * It exists because a decision about how something feels to cause cannot be
+ * settled from a capture or a recording, both of which are passive, and the
+ * operator has to drive the candidates themselves. Five decisions were served
+ * that way in one run, each with a hand-written parameter, switcher, and
+ * removal, none of which resembled the last.
+ *
+ * Renders nothing in a production build, and nothing in development either
+ * until the page is asked for an arm by name, so a page loaded without the
+ * parameter is what ships.
+ *
+ * An arm carries CSS when the decision is a treatment. When it is a value the
+ * page reads at runtime, a pace or a shader uniform, the arm carries no CSS
+ * and the module holding that value reads the active id off
+ * `document.documentElement.dataset[param]`.
+ */
+interface Arm {
+  /** Appears in the URL. Use `0` for what ships, so the baseline is an arm. */
+  readonly id: string
+  /** Names the arm and what it costs, since an arm with no cost is not one. */
+  readonly label: string
+  readonly css?: string
+}
+
+interface Props {
+  /** The query parameter, which is also the dataset key an arm is read from. */
+  readonly param: string
+  readonly arms: readonly Arm[]
+  /**
+   * Where the switcher mounts, as a selector. A decision inside a modal needs
+   * its switcher inside that modal, since anything outside it sits under the
+   * backdrop. Defaults to the body.
+   */
+  readonly mountInto?: string
+}
+
+const { param, arms, mountInto } = Astro.props
+
+// The component leaves the production tree rather than gating itself at
+// runtime, so neither an arm nor the parameter can reach a reader.
+const enabled = import.meta.env.DEV
+
+// Held as a string and written with `set:html`. Inside an Astro expression a
+// script's children are parsed the way JSX children are, so every brace in the
+// source reads as an interpolation and the body ships as an unevaluated
+// literal. It did, once, silently.
+const SOURCE = `
+const wanted = new URLSearchParams(location.search).get(param)
+const active = arms.find((arm) => arm.id === wanted)
+
+if (active) {
+  document.documentElement.dataset[param] = active.id
+
+  if (active.css) {
+    const style = document.createElement('style')
+    style.textContent = active.css
+    document.head.appendChild(style)
+  }
+
+  const render = () => {
+    const host = mountInto ? document.querySelector(mountInto) : document.body
+    if (!host) return
+    const bar = document.createElement('div')
+    bar.setAttribute('data-scenario-switcher', '')
+    for (const arm of arms) {
+      const link = document.createElement('a')
+      link.href = '?' + param + '=' + arm.id
+      link.textContent = arm.label
+      if (arm.id === active.id) link.setAttribute('data-current', 'true')
+      bar.appendChild(link)
+    }
+    host.appendChild(bar)
+  }
+
+  if (document.readyState === 'loading') {
+    document.addEventListener('DOMContentLoaded', render)
+  } else {
+    render()
+  }
+}
+`
+
+const SWITCHER_CSS = `
+/* Bottom left rather than bottom centre, which Astro's dev toolbar owns.
+   Centred, the toolbar sits over the switcher and swallows every click on it. */
+[data-scenario-switcher] {
+  position: fixed;
+  left: 1.5rem;
+  bottom: 1.5rem;
+  z-index: 60;
+  display: flex;
+  flex-wrap: wrap;
+  gap: 0.5rem;
+  max-width: calc(100vw - 3rem);
+  font: 500 13px system-ui, sans-serif;
+}
+[data-scenario-switcher] a {
+  padding: 0.4rem 0.8rem;
+  border: 1px solid rgb(128 128 128 / 0.4);
+  border-radius: 999px;
+  background: rgb(255 255 255 / 0.9);
+  color: #1a1815;
+  text-decoration: none;
+  white-space: nowrap;
+}
+[data-scenario-switcher] a[data-current='true'] {
+  background: #1a1815;
+  color: #f8f4ed;
+}
+`
+---
+
+{
+  enabled && (
+    <script
+      is:inline
+      define:vars={{ param, arms, mountInto }}
+      set:html={SOURCE}
+    />
+  )
+}
+
+{enabled && <style is:global set:html={SWITCHER_CSS} />}

package/tooling/astro/reference.md

@@ -58,3 +58,10 @@ Append to the `## Scripts` table:
 ## CI docs (extend)
 
 In `.claude/context/ci.md`, the Typecheck row's assertion reads: `` `astro check` passes ``. The Build row's assertion reads: `` `astro build` succeeds ``.
+
+## Scenario switcher
+
+- `src/components/dev/scenarios.astro` ships as a golden config, always overwritten on sync, since it is toolkit-authored infrastructure rather than a file a project hand-edits.
+- Import it into a page under test to drive candidate treatments of one decision by hand, selected by a query parameter, with a switcher for moving between them.
+- Guarded by `import.meta.env.DEV`, so it renders nothing and ships nothing in a production build.
+- Astro-only. It uses `is:inline`, `define:vars`, and `set:html`, which only the `.astro` file format parses. `vite-react` gets no equivalent until a real decision drives one.