@erclx/canon 5.33.0 → 5.35.0

package/{standards/standard.md → claude/skills/create-skill/references/skill-reference.md}

@@ -1,75 +1,83 @@
 ---
-title: Standard reference
-description: Shape and content rules for authoring a standard
+title: Reference file reference
+description: Shape and content rules for a reference that sets the shape of one artifact
 ---
 
-# Standard reference
+# Reference file reference
 
-Applies to each authored standard in the folder. Skip for `index.md`, which is generated rather than authored.
+Applies to each file under a skill's `references/` that sets the shape of one document type, or of one attribute carried across every document. A session reads it at the point the skill body names it, and skills and developers consume it alike. This file governs itself, so every rule below applies to it.
 
-## Overview
+## Contents
 
-A standard is a target-facing authoring convention for one document type, or for one attribute carried across every document. Nothing installs it into a project, so a reader resolves it with `canon standards <name>` or reads it at `standards/<name>.md`, and skills and developers consume it alike. This file governs itself, so every rule below applies to it.
+- [Scope](#scope)
+- [What a working reference looks like](#what-a-working-reference-looks-like)
+- [Scoping rules](#scoping-rules)
+- [Frontmatter](#frontmatter)
+- [Structure](#structure)
+- [Rules](#rules)
+- [Success criterion](#success-criterion)
+- [Changing a reference](#changing-a-reference)
+- [Examples](#examples)
+- [Template](#template)
 
 ## Scope
 
-Governs each authored standard under `standards/`: its stated jurisdiction, success criterion, frontmatter, structure, and rule phrasing.
+Governs a shape reference at `skills/<name>/references/<file>.md`: its stated jurisdiction, success criterion, frontmatter, structure, and rule phrasing.
 
 Does not govern:
 
-- The voice, rhythm, and sentence construction a standard is written in: the `write-human` skill
-- The punctuation, formatting, and word choice a standard is written in: `markdown.md`
-- The shape of any artifact a standard governs, which is that standard's own subject
+- The `references/` folder's place in the skill, its line ceiling, and the body naming each file: `skill.md`
+- How a body or a reference cites another skill's reference: `skill-paths.md`
+- The voice, rhythm, and sentence construction a reference is written in: the `write-human` skill
+- The punctuation, formatting, and word choice a reference is written in: `../markdown-craft/references/markdown.md`
+- The shape of any artifact a reference governs, which is that reference's own subject
 
-## What a working standard looks like
+## What a working reference looks like
 
-A standard answers these questions. Each can be answered wrong, which is what makes them a test rather than a preamble.
+A shape reference answers these questions. Each can be answered wrong, which is what makes them a test rather than a preamble.
 
 - Which single document type or attribute does this govern, and where does it apply?
 - Can an author who has seen no example produce a conforming document from this file alone?
 - Does every rule state a shape the document must have, rather than a fact about the repository that happens to store it?
 - What does a conforming document achieve, stated so a reviewer can call one non-conforming without appealing to taste?
 
-A standard failing these questions is non-conforming even when it satisfies every shape rule below.
+A reference failing these questions is non-conforming even when it satisfies every shape rule below.
 
 ## Scoping rules
 
 ### Declaring scope
 
-- Govern one document type per standard, or one attribute across every document. Split unrelated conventions into separate files.
-- Open with a `## Scope` section stating what the standard governs and what it does not, placed above the shape rules. A standard that specifies shape exhaustively and jurisdiction nowhere cannot refuse a rule, so the rule with no obvious owner lands in whichever standard sits nearest.
-- Write it as one line naming the artifact or attribute and where it applies, then a `Does not govern:` list. Give each entry the excluded concern and the owner it goes to. Name a sibling standard by bare filename, since the corpus is one flat folder, and name the surface instead where the owner is one, such as a coding rule, a project policy, or the code.
+- Govern one document type per reference, or one attribute across every document. Split unrelated conventions into separate files.
+- Open with a `## Scope` section stating what the reference governs and what it does not, placed above the shape rules. A reference that specifies shape exhaustively and jurisdiction nowhere cannot refuse a rule, so the rule with no obvious owner lands in whichever reference sits nearest.
+- Write it as one line naming the artifact or attribute and where it applies, then a `Does not govern:` list. Give each entry the excluded concern and the owner it goes to.
+- Name an owner in the same `references/` folder by bare filename and one in another skill by its sibling path, `../<skill>/references/<name>.md`. Name the surface instead where the owner is one, such as a coding rule, a project policy, or the code.
 - Put the governed path in backticks inside the first sentence of that line, anchored deep enough to resolve from a project root. A bare folder name matches a same-named folder elsewhere in the tree, and a path held back until a later sentence sits beside every other path the statement mentions, including the ones it excludes.
-- Say in that same sentence when the standard governs an attribute rather than a document type. An attribute is written across every document and has no path to name, so the silence reads as an omission unless the sentence claims it.
+- Say in that same sentence when the reference governs an attribute rather than a document type. An attribute is written across every document and has no path to name, so the silence reads as an omission unless the sentence claims it.
 - Cut an entry that names no owner at all. It is either excluding something nothing was going to claim, or it is a content exclusion, which the rule below sends to the shape rules instead.
-- Declare a boundary from both sides. A yield, an exemption, or a handoff stated in one standard alone is never checked against the standard on the other side of it, which is how two files come to claim the same rule or neither does.
-- Separate a jurisdiction exclusion from a content exclusion. The first names a concern another standard owns and belongs in `## Scope`. The second names what does not belong inside the document and stays with the shape rules. Merging them puts a boundary claim where no sibling will read it.
-- Stay silent on a section the standard holds today but should not own. Claiming it makes the scope statement false the moment it moves, and the mismatch is the evidence that moves it.
+- Declare a boundary from both sides. A yield, an exemption, or a handoff stated in one reference alone is never checked against the reference on the other side of it, which is how two files come to claim the same rule or neither does.
+- Separate a jurisdiction exclusion from a content exclusion. The first names a concern another reference owns and belongs in `## Scope`. The second names what does not belong inside the document and stays with the shape rules. Merging them puts a boundary claim where no sibling will read it.
+- Stay silent on a section the reference holds today but should not own. Claiming it makes the scope statement false the moment it moves, and the mismatch is the evidence that moves it.
 
 ### Naming the file
 
 - Name the file for the artifact the scope statement governs, taking the word from the deepest path segment that names the artifact rather than the folder holding it. `plan.md` over `.canon/plans/feature-<slug>.md` and `session.md` over `.canon/tasks/session-<slug>.md` both follow it.
-- Take the singular or the plural of that word, whichever reads as the artifact. A standard over one document takes the singular, and one over a set may take either.
-- Name an attribute standard for the attribute itself, since it governs no path to derive a word from.
-- Write the derived word alone. A standard installs as a sibling and is cited by bare filename, so a qualifier makes an outlier that every later citation has to carry.
-- Rename an outlier at the moment it is found, and state the reach in the change that does it. The name is installed in every target and cited in surfaces that never see the rename, so the cost only grows.
 
 ### Staying inside it
 
-- Name no path, filename, or folder outside the document type the standard governs. A standard reaches projects whose layout is their own, so a path borrowed from the authoring repository is wrong in a target and nothing reports it.
+- Name no path, filename, or folder outside the document type the reference governs. A reference reaches projects whose layout is their own, so a path borrowed from the authoring repository is wrong in a target and nothing reports it.
 - State the rule, never the mechanism enforcing it. Hooks, scripts, checks, and skill catalogs are facts about one repository. Name the condition the document must meet and let the enforcing surface name its own case.
-- Invent inline examples rather than citing a real file elsewhere in the project. A cited file moves or is deleted and the standard goes stale in silence.
+- Invent inline examples rather than citing a real file elsewhere in the project. A cited file moves or is deleted and the reference goes stale in silence.
 
 ## Frontmatter
 
 - Start the file with a frontmatter block carrying at least `title` and `description`. A consuming surface may require more.
 - `title`: names the doc type in sentence case, suffixed `reference` (`Commit reference`, `Branch reference`)
-- `description`: one line naming what the standard covers. It becomes the index link label on install.
+- `description`: one line naming what the reference covers
 
 ## Structure
 
 - Use sentence case for every heading
-- Flat `##` rule groups for a single-topic standard. Group `##` headers by concern for a multi-topic one.
+- Flat `##` rule groups for a single-topic reference. Group `##` headers by concern for a multi-topic one.
 - When one `##` section covers more than one sub-concern, split its bullets into `###` subgroups, one subgroup per sub-concern. A flat bullet list under an `##` covers a single sub-concern. Roughly seven bullets is a signal to split, not a hard cap.
 - Order groups from the most-used rule down to the edge case
 
@@ -83,13 +91,12 @@ A standard failing these questions is non-conforming even when it satisfies ever
 
 ## Success criterion
 
-- State what a conforming artifact achieves, not only what shape it takes. A standard that specifies structure exhaustively and success nowhere cannot be argued against, only edited on taste.
+- State what a conforming artifact achieves, not only what shape it takes. A reference that specifies structure exhaustively and success nowhere cannot be argued against, only edited on taste.
 - Write the criterion as a small set of questions the artifact must answer, or a task a reader must be able to complete from it. Keep it checkable by a person in one sitting.
 - Place it near the top, above the shape rules it governs. The shape rules are the means and the criterion is the test.
 - Say that an artifact failing the criterion is non-conforming even when it satisfies every shape rule. Without that line the criterion reads as advice.
-- Add a criterion to an existing standard when that standard is next exercised, not in a sweep. A criterion written without a failure to point at is the taste-based edit this section exists to prevent, so a standard with no criterion yet is a known gap rather than a violation.
 
-## Changing a standard
+## Changing a reference
 
 ### The checkpoint
 
@@ -98,12 +105,12 @@ Answer all four before editing, and carry the answers into wherever the change i
 - What problem does this solve? Name the artifact that went wrong, rather than the improvement the change makes.
 - Which surface owns the rule today? A rule already stated somewhere moves or is cited, never restated in a second place.
 - What deterministic check catches a regression? Name it, or say none exists and the rule holds on reading alone.
-- What does this collide with? Name the sibling standard, rule, or template it contradicts, or state that nothing does.
+- What does this collide with? Name the sibling reference, rule, or template it contradicts, or state that nothing does.
 
 ### What justifies a change
 
-- Change a standard on a failure, not on a finding. A finding is that the docs say X or a paper suggests Y. A failure is a conforming artifact that satisfied every shape rule and still missed the success criterion.
-- Park findings wherever the project tracks pending work, or in the standard's own backlog section when it tracks none. They are hypotheses to test, not instructions to apply.
+- Change a reference on a failure, not on a finding. A finding is that the docs say X or a paper suggests Y. A failure is a conforming artifact that satisfied every shape rule and still missed the success criterion.
+- Park findings wherever the project tracks pending work, or in the reference's own backlog section when it tracks none. They are hypotheses to test, not instructions to apply.
 - Cite the failing artifact in the change that fixes it, so the next reader can tell which rules were paid for by evidence.
 
 ## Examples
@@ -115,20 +122,19 @@ Answer all four before editing, and carry the answers into wherever the change i
 
 ## Template
 
-- Carry one fenced template of the document the standard governs, so an author copies a shape instead of reconstructing it from prose.
-- Bind this to a standard governing a document type. An attribute standard governs a scan, a string, or a label rather than a file, so it has no document to template and carries none.
-- State that exemption in the sentence declaring the standard an attribute standard. An exemption left to inference reads as an omission, and the next author writes a template that teaches nothing.
-- Place the template below the rules it satisfies, under a `## Template` heading or inside the section holding those rules. A reader arrives at it having already read what each part means.
+- Carry one fenced template of the document the reference governs, so an author copies a shape instead of reconstructing it from prose.
+- Bind this to a reference governing a document type. An attribute reference governs a scan, a string, or a label rather than a file, so it has no document to template and carries none. State that exemption in the sentence declaring it an attribute reference.
+- Place the template below the rules it satisfies, under a `## Template` heading or inside the section holding those rules.
 - Show the skeleton alone: every required section, one placeholder line for what each holds. A full worked document is a second document to maintain.
-- Write placeholders in angle brackets rather than copying a real document. A copied file goes stale, and its backticked filenames read as citations to anything parsing the standard.
-- Switch to a bare word where the fenced language reads `<` as syntax of its own, as Mermaid and HTML do, and say in the line above the fence that the names are placeholders. A template that does not parse in its own language teaches a shape the author cannot run.
-- Carry any header, key, or label a consuming tool parses verbatim. The template is the only place an author learns which strings are load-bearing, since prose calling them fixed does not say what they are.
-- Treat the template as authoritative where it and the prose disagree. An author copies the block, so a contradiction ships as the block, and naming the winner turns a drift into a visible defect rather than a silent one.
+- Write placeholders in angle brackets rather than copying a real document. A copied file goes stale, and its backticked filenames read as citations to anything parsing the reference.
+- Switch to a bare word where the fenced language reads `<` as syntax of its own, as Mermaid and HTML do, and say in the line above the fence that the names are placeholders.
+- Carry any header, key, or label a consuming tool parses verbatim. The template is the only place an author learns which strings are load-bearing.
+- Treat the template as authoritative where it and the prose disagree. An author copies the block, so a contradiction ships as the block.
 
 ````markdown
 ---
 title: <Document type> reference
-description: <one line naming what this standard covers>
+description: <one line naming what this reference covers>
 ---
 
 # <Document type> reference
@@ -137,7 +143,7 @@ Applies to `<path/to/document>`. <One line on what the document is for and when
 
 ## Scope
 
-Governs `<path/to/document>`: <the aspects this standard sets>.
+Governs `<path/to/document>`: <the aspects this reference sets>.
 
 Does not govern:
 
@@ -160,7 +166,6 @@ A <document type> failing these is non-conforming even when it satisfies every s
 
 ## <Shape rule group>
 
-- <imperative rule, one concern per bullet>
 - <imperative rule, one concern per bullet>
 
 ## Template

package/claude/skills/create-skill/references/skill.md

@@ -32,7 +32,8 @@ Does not govern:
 
 - What a `REQUIREMENT.md` must answer, its sections, and its template: `skill-requirement.md`
 - A practice skill's closing sections and ledger: `skill-practice.md`
-- Which root a path in a body resolves against, and how a body cites a standard: `skill-paths.md`
+- Which root a path in a body resolves against, and how a body cites another skill's reference: `skill-paths.md`
+- The jurisdiction, success criterion, and rule phrasing of a reference setting one artifact's shape: `skill-reference.md`
 - Path-scoped coding rules, which load on a file match rather than on a request match: `rule.md`
 - Voice, rhythm, and sentence construction in a skill body: the `write-human` skill
 - Punctuation, formatting, and word choice in a skill body: `markdown.md`
@@ -50,7 +51,7 @@ Answer all four before editing, and carry the answers into wherever the change i
 
 ## Whether a rule belongs beside the skill
 
-A skill fires when a session invokes it or its description matches the request. A path-scoped rule fires when a session reads a file matching its glob, with no decision from the session at all. The rule is the floor and the skill is the depth.
+A skill fires when a session invokes it or its description matches the request. A path-scoped rule fires when a session reads or writes a file matching its glob, with no decision from the session at all. The rule is the floor and the skill is the depth.
 
 Run the two-part test over what the body states before calling the skill finished. Does the invariant fire when a specific path is edited, and does violating it ship silently? An invariant passing both halves belongs in a rule as well, since a session that never invoked the skill still edits that path. An invariant failing either half stays here, which is most of a body.
 
@@ -160,9 +161,14 @@ allowed-tools: <tools required>
 ## Scripts
 
 - Use `scripts/` for operations that must be deterministic or repetitive
+- Ask whether a CLI verb the project already has does the job before writing a script. A verb is already installed and tested, and a script beside it is a second copy that drifts
+- Write a script in TypeScript and run it as `bun ${CLAUDE_SKILL_DIR}/scripts/<name>.ts`. Keep bash for a few lines that start one command
+- Import no package. A plugin loads from a cache that carries no `node_modules`, so only `node:` built-ins and the CLIs the skill already requires resolve
 - Use XML tags in script output for reliable parsing: `<SECTION>content</SECTION>`
-- Use `#!/usr/bin/env bash` shebang
-- Always include `2>/dev/null || echo "FALLBACK"` guards on git and shell commands
+
+### Inline commands
+
+- Always include `2>/dev/null || echo "FALLBACK"` guards on git and shell commands a skill body runs inline. A TypeScript script handles failure with try and catch instead
 
 ## Invocation
 

package/claude/skills/draft-and-pick/SKILL.md

@@ -9,7 +9,7 @@ metadata:
 
 Some decisions are settled by looking rather than by reasoning, and no draft is wrong until one is picked. Every step here puts several candidates in front of the operator and keeps the real surface untouched until they have chosen.
 
-The candidates live on the local design canvas, the surface `canon:canvas-board` drives. Every verb below is `canon canvas`, and `canon standards canvas` fixes the content format a frame takes. Read that standard before writing the first frame.
+The candidates live on the local design canvas, the surface `canon:canvas-board` drives. Every verb below is `canon canvas`, and `${CLAUDE_SKILL_DIR}/../canvas-board/references/canvas.md` fixes the content format a frame takes. Read that reference before writing the first frame.
 
 ## Guards
 

package/claude/skills/git-commit/references/versioning.md

@@ -39,19 +39,19 @@ External release identity used in git tags and release notes. Independent of pha
 
 ## Where each appears
 
-| Surface                                                             | Phase labels | Semver tags                         |
-| ------------------------------------------------------------------- | ------------ | ----------------------------------- |
-| `.canon/tasks/`                                                     | yes          | no                                  |
-| Chat with the operator                                              | yes          | no                                  |
-| Tracked prose (context entries)                                     | conditional  | no                                  |
-| Shipped prose (`standards/`, `claude/skills/`, `governance/rules/`) | no           | no                                  |
-| PR titles                                                           | no           | only when the PR cuts a release     |
-| PR bodies                                                           | no           | only when the PR cuts a release     |
-| Review comments                                                     | no           | only when referencing a release     |
-| Issue titles and bodies                                             | no           | only when referencing a release     |
-| Commit messages                                                     | no           | only when the commit cuts a release |
-| Git tags                                                            | no           | yes                                 |
-| README and `CHANGELOG.md`                                           | no           | yes                                 |
+| Surface                                               | Phase labels | Semver tags                         |
+| ----------------------------------------------------- | ------------ | ----------------------------------- |
+| `.canon/tasks/`                                       | yes          | no                                  |
+| Chat with the operator                                | yes          | no                                  |
+| Tracked prose (context entries)                       | conditional  | no                                  |
+| Shipped prose (`claude/skills/`, `governance/rules/`) | no           | no                                  |
+| PR titles                                             | no           | only when the PR cuts a release     |
+| PR bodies                                             | no           | only when the PR cuts a release     |
+| Review comments                                       | no           | only when referencing a release     |
+| Issue titles and bodies                               | no           | only when referencing a release     |
+| Commit messages                                       | no           | only when the commit cuts a release |
+| Git tags                                              | no           | yes                                 |
+| README and `CHANGELOG.md`                             | no           | yes                                 |
 
 ## Rules
 

package/claude/skills/git-issue/references/issue.md

@@ -59,7 +59,10 @@ Does not govern:
 - `### Expected` (optional): the expected behavior, or `unclear`.
 - `### Repro` (optional): repro details, or `none`.
 - `### Proposed fix` (required): a proposed fix, or `open` when the session settled on no direction.
-- A required field is refused when present but empty. Write the fallback literal for an optional field rather than leaving it blank.
+- `### Suggested shape` (optional): the template, output, or field list the change should take, inside a `<details>` block. Omit the heading when there is none.
+- `### Why` (optional): the reasons for the fix, one bullet each. Omit the heading when there are none.
+- `### Links` (optional): the issues, pull requests, or documents the report cites, one per line. Omit the heading when there are none.
+- A required field is refused when present but empty. Write the fallback literal for From project, Expected, and Repro rather than leaving one blank.
 
 ## Formatting
 

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

@@ -87,7 +87,7 @@ canon labels scan --title "<title>" --body-file .canon/tmp/pr/body.md --json
 
 Branch on the JSON record rather than the exit code. An operator's shell can wrap `canon` in a function whose status comes from a trailing command, flattening a non-zero exit to 0, the same reason the labels step below branches on its own record rather than the exit.
 
-Stop and fix the title or body on a non-empty `phaseLabels`, `boardReferences`, `sessionLinks`, `unspelledWords`, `titleFormatIssues`, `bannedCharacters`, or a `sections` record with anything in `outside` or `missing`. Do not proceed to `### Final command` until a re-run comes back clean on all seven. `titleFormatIssues` names which `## Title` rule in `${CLAUDE_SKILL_DIR}/references/pr.md` the title breaks, structure, casing, or length, so fix the named rule rather than guessing. `sections.outside` lists each heading to rename or drop, `sections.missing` each required heading to add, and `bannedCharacters` names the character to restructure the sentence around. Leave `cutsRelease` and `semverTags` alone, since a release-please pull request legitimately carries version references its own fixed shape explains.
+Stop and fix the title or body on a non-empty `phaseLabels`, `boardReferences`, `sessionLinks`, `titleFormatIssues`, `bannedCharacters`, or a `sections` record with anything in `outside` or `missing`. Do not proceed to `### Final command` until a re-run comes back clean on all six. `titleFormatIssues` names which `## Title` rule in `${CLAUDE_SKILL_DIR}/references/pr.md` the title breaks, structure, casing, or length, so fix the named rule rather than guessing. `sections.outside` lists each heading to rename or drop, `sections.missing` each required heading to add, and `bannedCharacters` names the character to restructure the sentence around. Leave `cutsRelease` and `semverTags` alone, since a release-please pull request legitimately carries version references its own fixed shape explains.
 
 The scan stays required even where a `pull_request` workflow job runs the same verb, since a project holding an older `canon` carries no such job and no `titleFormatIssues`, `sections`, or `bannedCharacters` key.
 

package/claude/skills/git-pr/references/publish.md

@@ -66,7 +66,7 @@ A number referring to a pull request or an issue takes the form its destination
 
 Text published to a remote is the auto-linking half: a pull request body, an issue body, a comment on either, and a commit message. Write `#123` there, and `owner/repo#123` where the reference crosses repositories, which the same auto-linking reaches. A markdown file browsed from the repository tree is the other half, where neither spelling links and the backticked one marks the number as an identifier. <!-- canon-allow-reference: the two spellings this section defines, which a qualified form would destroy -->
 
-Content that installs into another repository is the third destination, and it splits on which repository the number names. A skill body loads from a plugin cache, a docs page is read through `canon docs`, and a standard through `canon standards`, so the reader holds their own repository rather than the one a bare number belongs to. Qualifying a number against a different, resolvable repository fixes that, since the reader can open that repository even without this one.
+Content that installs into another repository is the third destination, and it splits on which repository the number names. A skill body loads from a plugin cache and a docs page is read through `canon docs`, so the reader holds their own repository rather than the one a bare number belongs to. Qualifying a number against a different, resolvable repository fixes that, since the reader can open that repository even without this one.
 
 Qualifying it against `erclx/canon` fixes nothing, because a reader holding only the plugin cache or the published package still cannot open this repository's own history. A same-repository citation takes no number here at all, bare or qualified. State the fact the citation was standing in for instead, and where the identifier is the only trace of a one-off incident rather than a reproducible count, carry it into the `canon/context/` entry that owns the surface.
 

package/claude/skills/review-address/REQUIREMENT.md

@@ -55,5 +55,5 @@ A declined finding fails on a third axis, which is where its reason ends up. A w
 - Writing the review, which `review-pr` owns. The split is by side of the channel: that one posts findings from an independent session and this one is the worker's return leg.
 - Staging, committing, and pushing the follow-up, which `git-followup` owns under this skill's direction
 - Refreshing the `.claude/` docs the fixes made stale, which `context-fold` owns
-- Re-reviewing its own fixes, which hands back to the orchestrator
+- Re-reviewing its own fixes, which hands back to the reviewer
 - Re-reading a rewritten branch, which `review-pr` absorbs by testing whether the prior reviewed commit still reaches the head and paying for a full pass when it does not

package/claude/skills/review-address/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: review-address
-description: Pulls review findings and CI status on the current branch's open PR, fixes each in the working tree, refreshes any stale `.claude/` docs, replies with a summary comment, and pushes a follow-up commit. The worker's return leg after `review-pr`. Use when asked to "address the review", "fix the PR comments", "respond to review", or after an orchestrator posts findings. Do NOT use to write a review. That is `review-pr`.
+description: Pulls review findings and CI status on the current branch's open PR, fixes each in the working tree, refreshes any stale `.claude/` docs, replies with a summary comment, and pushes a follow-up commit. The worker's return leg after `review-pr`. Use when asked to "address the review", "fix the PR comments", "respond to review", or after a reviewer posts findings. Do NOT use to write a review. That is `review-pr`.
 metadata:
   family: after-pr
 ---
@@ -247,7 +247,7 @@ addressed, and leads with the rebase instead:
 Rebased PR #<number> onto origin/main. <N> files resolved by hand, <N> rebuilt by the check.
 ```
 
-Do not merge. Hand back to the orchestrator for re-review.
+Do not merge. Hand back to the reviewer for re-review, or to the orchestrator where no live reviewer answers.
 
 ## Post-review findings
 

package/claude/skills/review-craft/references/ui.md

@@ -45,7 +45,7 @@ mkdir -p .canon/tmp/pr/review/evidence/<number>
 git show <sha>:<path> > .canon/tmp/pr/review/evidence/<number>/<side>-<name>.png
 ```
 
-Take the sha from the row, so the base and head sides are exactly what the comment shows. Then open each file with the file-reading tool. A `*(new)*` base cell has no before image, and a state whose cases are all added has no Base column at all. Read the URL out of the `src=` of each `<img>`, or out of `![](` in a comment posted before the embed changed.
+Take the sha from the row, so the base and head sides are exactly what the comment shows. Then open each file with the file-reading tool. A `*(new)*` base cell has no before image, and a view or flat block whose cases are all added has no base column at all. A view row holds one case per theme cell, so a width row names two images where a flat row names one. Read the URL out of the `src=` of each `<img>`, or out of `![](` in a comment posted before the embed changed.
 
 ## How many to open
 

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

@@ -1,13 +1,13 @@
 ---
 name: review-pr
-description: Reviews an open pull request from an independent session and posts findings as a review comment on the PR. Posts a first pass against the whole change and every later pass against only the commits added since, under `## Review` while any finding is open and `## Review closed` once a pass carries none. Reads project docs and the task board for cross-feature context a self-review lacks. Use when asked to "review the PR", "review this feature's PR", "post a PR review", "re-review the PR", "close out the review", "confirm the findings are fixed", or acting as the orchestrator reviewing a worker's PR. Do NOT use to review local uncommitted changes.
+description: Reviews an open pull request from an independent session and posts findings as a review comment on the PR. Posts a first pass against the whole change and every later pass against only the commits added since, under `## Review` while any finding is open and `## Review closed` once a pass carries none. Reads project docs and the task board for cross-feature context a self-review lacks. Use when asked to "review the PR", "review this feature's PR", "post a PR review", "re-review the PR", "close out the review", "confirm the findings are fixed", or acting as the dispatched reviewer of a worker's PR. Do NOT use to review local uncommitted changes.
 metadata:
   family: after-pr
 ---
 
 # Review PR
 
-This is the orchestrator's independent review. It reviews an open PR the session
+This is a dispatched reviewer's independent review. It reviews an open PR the session
 did not write and posts the findings to the PR, so the vantage is independent
 and the output is durable.
 
@@ -19,7 +19,7 @@ none, so the most recent comment's heading reports whether any work is owed.
 Every pass is this skill, and which one it is gets detected from the thread
 rather than named by the caller.
 
-The threshold is stated here and nowhere else, and every other surface acting on it cites this skill rather than restating the grades. One rule governs both the heading and the dispatch: a pass carrying anything owed takes `## Review` and owes a dispatch to the session holding the branch, and a pass carrying nothing at all takes `## Review closed` and owes none. Owed covers a finding at any severity, a Testing question, and a reviewer request nobody has answered alike, which is what keeps the two halves from separating. Sending that dispatch is `role-orchestrator`'s step rather than this one, which posts and stops. Post the open heading whether it is the first pass or the fourth. A pull request thread then reads as `## Review`, the worker's answer under `## Review response` from `review-address`, another `## Review` while anything stays open, and `## Review closed` when nothing does.
+The threshold is stated here and nowhere else, and every other surface acting on it cites this skill rather than restating the grades. One rule governs both the heading and the dispatch: a pass carrying anything owed takes `## Review` and owes a dispatch to the session holding the branch, and a pass carrying nothing at all takes `## Review closed` and owes none. Owed covers a finding at any severity, a Testing question, and a reviewer request nobody has answered alike, which is what keeps the two halves from separating. Sending that dispatch is `role-reviewer`'s step rather than this one, which posts and stops, and `role-orchestrator` sends it only as the fallback where no live reviewer can. Post the open heading whether it is the first pass or the fourth. A pull request thread then reads as `## Review`, the worker's answer under `## Review response` from `review-address`, another `## Review` while anything stays open, and `## Review closed` when nothing does.
 
 Both of this skill's headings anchor as a section distinct from human threads, and neither invents beyond what the whole set already states. That set is eight headings across four families, stated here once so `role-orchestrator`'s poll and every reply-posting skill cite it rather than carry a copy. The review family, `## Review` and `## Review closed`, belongs to this skill alone. The reply family, `## Review response`, `## Rebase`, and `## Post-review findings`, belongs to `review-address`. The third family is a single heading, `## Evidence`, which `canon pr evidence` posts through `git-pr` and `git-followup` and which answers no comment already on the thread, so the poll excludes it from the unclassified count without reading it as a reply that owes a re-review. The fourth, `## UI review` and `## UI review closed`, belongs to `review-ui`, which posts it as a review beside this one, and nothing in this skill reads it.
 

package/claude/skills/review-pr/references/post.md

@@ -56,7 +56,7 @@ X critical, Y should-fix, Z minor. Reviewed against project docs and the board.
 
 A stale ticked box goes in a `**PR body**` block, in place of a `**`path/to/file.ext`**` block and ahead of every one of those, since it precedes the code the diff carries rather than sitting inside it.
 
-Run `canon labels scan --title "<title>" --body "<body>" --head <headRefName>` against the PR under review, since Step 1 already holds all three and this pass is the last human-shaped gate before merge. A hit lands in the same `**PR body**` block, `should-fix`, naming each finding the scan returns: a token quoted from the title or body for a phase label, a board identifier, a session link, or an unspelled word, and the broken rule's name, `structure`, a casing issue, or `length`, for a title-format hit. A heading in `sections.outside`, a heading in `sections.missing`, or a character in `bannedCharacters` is a hit of the same weight, naming the heading or the character. This reads the pull request being reviewed, distinct from the comment this pass is about to post, which the scan later in this step still covers.
+Run `canon labels scan --title "<title>" --body "<body>" --head <headRefName>` against the PR under review, since Step 1 already holds all three and this pass is the last human-shaped gate before merge. A hit lands in the same `**PR body**` block, `should-fix`, naming each finding the scan returns: a token quoted from the title or body for a phase label, a board identifier, or a session link, and the broken rule's name, `structure`, a casing issue, or `length`, for a title-format hit. A heading in `sections.outside`, a heading in `sections.missing`, or a character in `bannedCharacters` is a hit of the same weight, naming the heading or the character. This reads the pull request being reviewed, distinct from the comment this pass is about to post, which the scan later in this step still covers.
 
 A later pass carrying findings keeps that shape and changes only the summary line:
 

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

@@ -54,7 +54,7 @@ A verdict also goes stale without saying so. A push after the pass changes what
 
 - Reviewing the code and the stills, which `review-pr` owns. The two run as separate sessions so each finishes on its own clock and neither hears the other.
 - Writing the checklist and its drivable format, which `ui-checklist` owns
-- Dispatching the pass, polling its verdict, and lifting the draft mark, which `role-orchestrator` owns
+- Dispatching the pass and polling its verdict, which `role-orchestrator` owns, and the lift's gates, which `canon pr lift` reads whichever session runs it
 - A subagent inside the code reviewer, dropped because its cost stays invisible until it returns
 - Writing a tracked file or checking anything out to host a frame. The push goes through the GitHub API onto the frames branch alone, so the reviewer still enters no worktree and touches no branch a pull request holds.
 - Dropping a closed pull request's frames, which a scheduled workflow runs, and purging a dropped frame GitHub still serves by commit, which needs a platform request

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

@@ -24,7 +24,7 @@ rather than inside it, so the two passes finish on their own clocks.
 - The wrapper refuses to open the browser because its revision is absent: stop and post nothing, passing its install command to whoever launched the pass. Never install mid-pass.
 - The newest UI verdict is `## UI review closed` at the current head: stop, `The UI review already covers <short-sha>.` An open verdict at the head stops the same way only when nothing has arrived since it: drive again when a `## Review response` or `## Post-review findings` comment is newer than the verdict, or the launch names an address.
 - The hosted preview was not built from the head: stop and post nothing, naming `built`, `tip`, and `canon pr preview <number> --json` for the dispatcher. A verdict posted against an older build carries a marker naming a head nobody drove.
-- Post and stop. Never merge, never lift the draft mark, and never edit the evidence comment except through `canon pr tick`.
+- Post, then run `canon pr lift <number>` on a close. Never merge or ready the PR by hand, and edit the evidence comment only through `canon pr tick`.
 
 ## Step 1: resolve the pull request
 
@@ -94,11 +94,13 @@ Read `${CLAUDE_SKILL_DIR}/references/driving.md` on reaching this step for how a
 
 Give every box exactly one verdict, in checklist order. A box the pass could not place on a route or a width is still driven, from the opened address at 1440 wide, and the verdict names the guess. Skipping a box silently reads the same as passing it.
 
-Never judge a box ending in `(taste)`. Drive to the state, capture the frame, and mark it needs eyes. Drive a ticked box the same as an unchecked one, since a tick is a claim this pass exists to check. A tick stamped at the current head still gets driven.
+Never judge a box ending in `(taste)`. Drive to the state, capture both themes, and mark it needs eyes. Drive a ticked box the same as an unchecked one, since a tick is a claim this pass exists to check. A tick stamped at the current head still gets driven.
 
-A frame the verdict rests on is published only when the worker's evidence lacks it. Compare the box's route, width, and theme against the `states` Step 2 kept, and when a state and stem show the same thing, cite that stem and push nothing. The match is this pass's judgment over the box's wording, so the verb never makes it. Otherwise push the frame and keep the `link` the record returns:
+A frame the verdict rests on is published only when the worker's evidence lacks it, matched per theme against the `states` Step 2 kept, as `references/driving.md` states. The match is this pass's judgment over the box's wording, never the verb's. Otherwise push the frame and keep the `link` the record returns:
 
 ```bash
+# one shot of a taste box's pair, then a pass or fail frame with no theme
+canon pr frames <number> --add frames/<box-number>-<theme>.png --box <box-number> --theme <dark|light> --head <head> --pass <pass> --json
 canon pr frames <number> --add frames/<box-number>.png --box <box-number> --head <head> --pass <pass> --json
 ```
 
@@ -118,7 +120,7 @@ Close the browser with `${CLAUDE_SKILL_DIR}/scripts/pw.sh -s=<project>-<number>
 
 ## Step 7: post
 
-Read `${CLAUDE_SKILL_DIR}/references/post.md` for the heading rule, the body shape, the marker every body ends on, and the post command. Each Evidence cell holds words and names the evidence stem it matched, and the `link` its Step 5 push returned goes as given into the Frames block below the table.
+Read `${CLAUDE_SKILL_DIR}/references/post.md` for the heading rule, the body shape, the marker every body ends on, and the post command. Each box lands in the section its verdict names, and the `link` its Step 5 push returned goes as given into that box's own entry.
 
 ## Step 8: tick the passed boxes
 
@@ -139,10 +141,10 @@ gh run list --workflow phase-label-gate.yml --event pull_request_review --limit
 Read `<heading>` off the first line of the file Step 7 posted, never composed here, so the line reports what the review carries.
 
 ```plaintext
-P passed, F failed, E need eyes, N not driven. Posted to PR #<number> under <heading>.
+F failed · E need your eyes · P passed · N not driven. Posted to PR #<number> under <heading>.
 ```
 
-Add `Review-event checks: <passing|failing|unread>.` and `Ticks: <ticked N|reason>.` after it, the second naming the count Step 8 ticked or the verb's refusal `reason`. Add `S sweep finding(s).` when the sweep raised any. Report no merge recommendation, since this pass saw the app and not the change.
+Add `Review-event checks: <passing|failing|unread>.` and `Ticks: <ticked N|reason>.` after it, the second naming the count ticked or the refusal `reason`. Add `S sweep finding(s).` when the sweep raised any. Report no merge recommendation, since this pass saw the app and not the change.
 
 ## Rules
 

package/claude/skills/review-ui/references/driving.md

@@ -32,20 +32,20 @@ A box written before that format may carry no route, no width, and a verb such a
 - Text, presence, and attributes: `pw --raw eval "<expression>"`, quoting the value back.
 - Computed style: `getComputedStyle(<element>).<property>`.
 - Geometry and overflow: `getBoundingClientRect()`, and `scrollWidth` against `clientWidth` on `document.documentElement`.
-- A frame: `pw screenshot --filename=frames/<box-number>.png`, then open it with the file-reading tool before saying what it shows.
+- A frame: `pw screenshot --filename=frames/<box-number>.png`, then open it with the file-reading tool before saying what it shows. A taste box takes the shot twice, once per theme, naming the theme in the file as `frames/<box-number>-<theme>.png`. Reach each theme through the page's own control when the box names one, and through `pw set-color-scheme <dark|light>` otherwise, then read the page's background before the shot to confirm it changed. A page that paints the same under both has no second theme to show, so the box is not driven, with the reason naming that. `pw clear-color-scheme` restores the default.
 
 ## The four verdicts
 
 Each box takes exactly one.
 
-| Verdict             | When                                                    | Evidence it carries                                                                                                                                   |
-| ------------------- | ------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------- |
-| pass or fail, read  | The result is a fact the page reports                   | The value read, quoted, such as `scrollWidth 436 against clientWidth 320`                                                                             |
-| pass or fail, frame | The result has a stated criterion only an image settles | The matching evidence stem or the pushed frame's link going to the Frames block, and what the frame shows, in words                                   |
-| needs eyes          | The box ends in `(taste)`                               | The matching evidence stem or the pushed frame's link going to the Frames block, and what the frame showed, with nothing about whether it looks right |
-| not driven          | The state could not be reached                          | The reason, such as an unreachable address, a `(local only)` box on a hosted preview, or a target the snapshot does not hold                          |
+| Verdict             | When                                                    | Evidence it carries                                                                                                                                                    |
+| ------------------- | ------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| pass or fail, read  | The result is a fact the page reports                   | The value read, quoted, such as `scrollWidth 436 against clientWidth 320`                                                                                              |
+| pass or fail, frame | The result has a stated criterion only an image settles | The matching evidence stem or the pushed frame's link, inline under the failed box's heading, and what the frame shows, in words                                       |
+| needs eyes          | The box ends in `(taste)`                               | The dark and the light shot as a pair, each the matching evidence stem or a pushed frame's link, and what the frames showed, with nothing about whether it looks right |
+| not driven          | The state could not be reached                          | The reason, such as an unreachable address, a `(local only)` box on a hosted preview, or a target the snapshot does not hold                                           |
 
-A frame verdict carries one image at most, and never one the worker's evidence already shows. When a state and stem in the evidence record match the box's route, width, and theme, the evidence names that stem and nothing is pushed. Otherwise the frame goes up through `canon pr frames` and the `link` the record returned, which names the frame's path on the frames branch, goes under the Frames block and never inside the table row. Either way the words stay, describing the value or region judged, such as the element, its position, and the colors or text read, so a reader whose image fails to load can still check it.
+A pass or fail resting on a frame carries one image at most, and never one the worker's evidence already shows. A needs-eyes box carries the pair, dark and light, since a taste call is made by comparing them. Match each theme separately: when a state and stem in the evidence record match the box's route, width, and that theme, the evidence names that stem and nothing is pushed for it, so a view with the dark shot in evidence pushes the light one alone. Otherwise the frame goes up through `canon pr frames` with `--theme`, and the `link` the record returned, which names the frame's path on the frames branch, goes in the box's own section of the body and never inside a folded block. Either way the words stay, describing the value or region judged, such as the element, its position, and the colors or text read, so a reader whose image fails to load can still check it.
 
 A push that refuses leaves the words alone, with the reason named. Never cite the local frame path. A path under `.canon/` is a board identifier the label scan rejects, and it resolves only on this machine.