@erclx/canon 5.34.0 → 5.35.0

package/README.md

@@ -65,7 +65,6 @@ Each domain has a canonical source in this repo and a thin install or sync CLI o
 | -------------- | ------------------------------------------------------------------------------------------------------------------------ | --------------------------------------------------------------- |
 | Plugin skills  | Skills that plan a feature, review a diff, sync the planning docs, and run the ship chain                                | Loaded live from the plugin, never copied                       |
 | Governance     | Coding and authoring rules that load into a Claude session when a matching path is edited                                | Installed per project by `canon gov install`, refreshed by sync |
-| Standards      | Authoring conventions for commits, branches, plans, tasks, and markdown                                                  | Opened by name, read by name with `canon standards <name>`      |
 | Tooling stacks | Golden configs, seeds, and a reference per framework                                                                     | Laid down by `canon init`, reconciled by `canon tooling sync`   |
 | Design system  | Ships a `DESIGN.md` token format, a skill that drafts one from an existing project or from scratch, and a render command | `canon design render`                                           |
 | Slides         | A folder of HTML slides per deck, drawn in the project's tokens and rebuilt as editable shapes                           | `canon slides render` writes PowerPoint                         |
@@ -74,7 +73,7 @@ Each domain has a canonical source in this repo and a thin install or sync CLI o
 | Transcripts    | A YouTube transcript with metadata frontmatter                                                                           | `canon transcripts <url>` writes it into any repo               |
 | Sandbox        | Scenario scaffolds that provision an isolated project state for verifying each domain flow                               | `canon sandbox`                                                 |
 
-Those domains reach you in three shapes. A tooling stack lands as real files under version control, because a config is something your build reads and your project owns. A standard stays here and is opened by name, so there is no copy in your repo to drift from this one.
+Those domains reach you in three shapes. A tooling stack lands as real files under version control, because a config is something your build reads and your project owns. A plugin skill and the references it carries are never copied, so there is no copy in your repo to drift from this one.
 
 Governance is the third shape. A rule with a path glob loads only when a matching path is edited, and a rule with none loads every session. Run `canon gov list` to see the glob beside each rule.
 
@@ -152,9 +151,9 @@ git init
 canon init
 ```
 
-`canon init` installs base tooling configs, Claude seeds, and governance rules in one pass, and scaffolds a `.claude/wiki/` stub for your project's own reference pages. Governance defaults to the `base` stack, so a bare init lands the coding and doc-authoring rules in `.claude/rules/`. Each rule names the standard it answers to and reads it with `canon standards <name>`, so no corpus is copied into your project.
+`canon init` installs base tooling configs, Claude seeds, and governance rules in one pass, and scaffolds a `.claude/wiki/` stub for your project's own reference pages. Governance defaults to the `base` stack, so a bare init lands the workflow and doc-authoring rules in `.claude/rules/`. Each rule names the skill it loads, so no corpus is copied into your project.
 
-Pass `--stack <name>` for a framework stack, or `--skip governance` to leave rules out. Run `canon tooling list --json` to see the catalog.
+Pass `--stack <name>` for a language stack such as `node` or `python`, or `--skip governance` to leave rules out. Run `canon tooling list --json` to see the catalog.
 
 For the full journey from scaffold through adding a domain later to syncing upstream drift, see [target projects](docs/target/projects.md).
 
@@ -164,7 +163,6 @@ Each domain carries an entry written for someone maintaining the toolkit rather
 
 - [Claude Code plugin](canon/context/claude-plugin/index.md)
 - [Governance rules](canon/context/governance/index.md)
-- [Standards](canon/context/standards/index.md)
 - [Tooling stacks](canon/context/tooling/index.md)
 - [Design system](canon/context/design/index.md)
 - [Slides](canon/context/features/slides.md)

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

@@ -1,7 +1,7 @@
 {
   "name": "canon",
   "description": "Runs your agent's work and keeps its code good, on one setup for every repo.",
-  "version": "5.34.0",
+  "version": "5.35.0",
   "author": {
     "name": "Eric Le",
     "url": "https://github.com/erclx"

package/claude/skills/api-design/REQUIREMENT.md

@@ -9,7 +9,7 @@ description: Why a session changing what a caller can see needs stated rules on
 
 Without this skill, a session changing a surface a caller depends on has nothing in front of it about what that caller can see or how a change lands without breaking it. It works for the one caller it opened, renames a field in place, returns whatever record it had in hand, and nothing in the toolkit answers before the change ships.
 
-The absence is measured across the shipped corpus. No folder under `claude/skills/` matches `api`, `interface`, or `contract`, and no file across `claude/`, `governance/`, and `standards/` carries `hyrum` or a form of `idempotent`. The only related lines are the two error bullets in the core code rule, which state that errors are structured and hide internals and say nothing about exposure, versioning, or retries.
+The absence is measured across the shipped corpus. No folder under `claude/skills/` matches `api`, `interface`, or `contract`, and no file across `claude/` and `governance/` carries `hyrum` or a form of `idempotent`. The only related lines are the two error bullets in the core code rule, which state that errors are structured and hide internals and say nothing about exposure, versioning, or retries.
 
 The one skill nearest the subject leaves the pointer open. `codebase-layout` excludes shaping "a module's interface and seams" in its description and names no skill to take it, so a session routed away from layout on that question lands nowhere.
 

package/claude/skills/auto-ship/references/draft-mark.md

@@ -29,4 +29,4 @@ The number crosses from that step's output into a command this session types, wh
 
 Report what the read returned rather than what the command printed, since the exit says the call ran and says nothing about the state. A `true` reports a draft. A `false` reports the pull request as opened ready and unsupervised, and the chain stops there. Never re-issue the mark on a disagreeing read, which fights whoever readied it instead of guarding anything.
 
-Placement is why the call sits ahead of the watch rather than after it. Marking afterwards leaves the pull request unmarked for the whole CI run, which is the stretch an unattended worker's branch is least supervised. What the mark buys is a reader learning the pull request has had no review yet. It buys no bound on that stretch: readying a pull request to merge lifts the mark, GitHub requires it before a merge, and the act belongs to the operator or to the controlling session that closed the review, whichever it is, taken directly on the pull request rather than delegated to a worker. `role-worker` states the mirroring refusal.
+Placement is why the call sits ahead of the watch rather than after it. Marking afterwards leaves the pull request unmarked for the whole CI run, which is the stretch an unattended worker's branch is least supervised. What the mark buys is a reader learning the pull request has had no review yet. It buys no bound on that stretch: readying a pull request to merge lifts the mark, GitHub requires it before a merge, and the act runs through `canon pr lift`, which a reviewer runs on its close and the controlling session runs as the fallback, or through the operator directly. `role-worker` states the mirroring refusal of an instruction to ready the pull request directly, whoever sends it.

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

@@ -27,15 +27,14 @@ Consult to pick the `canon` verb for a job, and before running a verb that write
 
 ## Domains
 
-| Job                                                             | Verb              |
-| --------------------------------------------------------------- | ----------------- |
-| Install or sync governance rules                                | `canon gov`       |
-| Read an authoring standard by name                              | `canon standards` |
-| Sync a tooling stack's configs and seeds, or read its reference | `canon tooling`   |
-| Set up or sync the Claude workflow                              | `canon claude`    |
-| Scaffold a wiki                                                 | `canon wiki`      |
-| Regenerate the `index.md` files                                 | `canon indexes`   |
-| Read a toolkit reference doc                                    | `canon docs`      |
+| Job                                                             | Verb            |
+| --------------------------------------------------------------- | --------------- |
+| Install or sync governance rules                                | `canon gov`     |
+| Sync a tooling stack's configs and seeds, or read its reference | `canon tooling` |
+| Set up or sync the Claude workflow                              | `canon claude`  |
+| Scaffold a wiki                                                 | `canon wiki`    |
+| Regenerate the `index.md` files                                 | `canon indexes` |
+| Read a toolkit reference doc                                    | `canon docs`    |
 
 ## Author and render
 
@@ -84,12 +83,12 @@ Read the doc each line names before running one of these. `canon docs install-an
 
 - `canon sync` runs every installed domain's sync, so it carries each risk below.
 - `canon gov sync` replaces a rule you edited and deletes a rule the toolkit retired, edited or not.
-- `canon tooling sync --write` replaces every golden config a stack ships. Seeds are copy-once and dictionaries merge. Nothing writes without the flag. See `canon docs sync`.
+- `canon tooling sync --write` replaces every golden config a stack ships. Seeds are copy-once. Nothing writes without the flag. See `canon docs sync`.
 - `canon design sync` replaces the shipped design files and leaves `.claude/design/project/` alone.
 - `canon migrate --write` rewrites files that cite a retired name or layout. It reports and writes nothing without the flag. See `canon docs migrate`.
 - `canon indexes regen` rewrites each generated `index.md` from the folder's current state, so a hand edit there is lost. See `canon docs indexes`.
 
-No command writes a standard into a project, so `canon standards` is safe to run. `CLAUDE.md` and the other seed docs are copy-once, and no sync updates them. Merge those by hand against the toolkit copy.
+`CLAUDE.md` and the other seed docs are copy-once, and no sync updates them. Merge those by hand against the toolkit copy.
 
 ## Source of truth
 

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

@@ -11,7 +11,8 @@ Read these files in parallel:
 
 - `${CLAUDE_SKILL_DIR}/references/skill.md`: skill structure, skill types, frontmatter fields, invocation rules
 - `${CLAUDE_SKILL_DIR}/references/skill-requirement.md`: what `REQUIREMENT.md` must answer, its sections, and its template
-- `${CLAUDE_SKILL_DIR}/references/skill-paths.md`: which root a path in the body resolves against, and how the body cites a standard
+- `${CLAUDE_SKILL_DIR}/references/skill-paths.md`: which root a path in the body resolves against, and how the body cites another skill's reference
+- `${CLAUDE_SKILL_DIR}/references/skill-reference.md`, when the skill carries a reference setting the shape of one artifact: its scope, success criterion, frontmatter, and rule phrasing
 - `${CLAUDE_SKILL_DIR}/../markdown-craft/references/markdown.md`: punctuation and formatting for skill body text
 - `${CLAUDE_SKILL_DIR}/references/skill-practice.md`, when the skill carries engineering practice: the closing sections a practice skill owes and the anatomy behind them
 - The `write-human` skill: voice, rhythm, and sentence construction for skill body text

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

@@ -1,17 +1,17 @@
 ---
 title: Skill path reference
-description: Which root a file a skill body names resolves against, and how a body cites a standard
+description: Which root a file a skill body names resolves against, and how a body cites another skill's reference
 ---
 
 # Skill path reference
 
 Applies to every path a skill body names, under `skills/<name>/`. A skill reads from two roots, so the path it writes decides whether the file is found once the skill runs from another project.
 
-This is an attribute standard. It governs the path strings a body carries rather than a file of its own, so it carries no template.
+This is an attribute reference. It governs the path strings a body carries rather than a file of its own, so it carries no template.
 
 ## Scope
 
-Governs how a `SKILL.md` body or a file under its `references/` names a bundled asset, an installed shared doc, or a standard.
+Governs how a `SKILL.md` body or a file under its `references/` names a bundled asset, an installed shared doc, or another skill's reference.
 
 Does not govern:
 
@@ -23,7 +23,7 @@ Does not govern:
 A path in a skill body works when the skill resolves it from any project it runs in:
 
 - Does each bundled asset resolve against the skill's own directory rather than the session's working directory?
-- Does each cited standard resolve in a target that installed nothing but the plugin?
+- Does each cited reference resolve in a target that installed nothing but the plugin?
 - Does a procedure two skills share live in one place, with each body citing it?
 
 A body failing any of these is non-conforming even when every path resolves in this repository.
@@ -34,18 +34,15 @@ Know which root a file lives under before referencing it.
 
 - Bundled skill assets (`references/`, `scripts/`, `assets/`) resolve against the skill's own directory. Reference them with `${CLAUDE_SKILL_DIR}/<path>`, never a bare relative path, which resolves against the session cwd and fails when a plugin skill runs from another project.
 - Installed shared docs (`.claude/rules/`, `canon/context/`) resolve against the target project cwd, where install placed them. Reference them by that path.
-- Do not hand-copy a standard into a skill. If a skill must carry its own copy, generate it from the single source and reference it through `${CLAUDE_SKILL_DIR}`, so one owner keeps every copy in sync.
+- Do not hand-copy another skill's reference into a skill. If a skill must carry its own copy, generate it from the single source and reference it through `${CLAUDE_SKILL_DIR}`, so one owner keeps every copy in sync.
 
-## Citing a standard
+## Citing another skill's reference
 
-No standard installs into a project, so a body cites one place rather than choosing between two.
+A reference shared across skills lives in the `references/` of the skill that owns it, so a body cites it by the sibling path.
 
-- Cite `${CLAUDE_SKILL_DIR}/../../standards/X.md`. The plugin ships the whole standards folder beside `skills/`, so the path resolves in every install.
-- Cite another skill's reference as `${CLAUDE_SKILL_DIR}/../<skill>/references/<name>.md`. A standard that moved into the skill owning it lives there, and the plugin ships the skills side by side, so the sibling path resolves in every install. Name the owner skill rather than copying the file.
-- Never cite `.claude/standards/X.md` from a shipped body. A target holds no such folder. <!-- audit-ignore-citations: .claude/standards/X.md -->
-- Name `canon standards X` instead where the body wants the document rather than a path to open, such as a value it captures or reports. That verb resolves `standards/` at the project root and then the corpus inside the package.
-- State the path once per body, at the site that reads the standard. A later mention of a standard the body already read stays bare, since repeating the path at every mention is noise rather than instruction.
-- A guard on a standard's presence names the file rather than the folder holding it, since a folder test answers for a sibling that happens to be there.
+- Cite another skill's reference as `${CLAUDE_SKILL_DIR}/../<skill>/references/<name>.md`. The plugin ships the skills side by side, so the sibling path resolves in every install. Name the owner skill rather than copying the file.
+- State the path once per body, at the site that reads the reference. A later mention of a reference the body already read stays bare, since repeating the path at every mention is noise rather than instruction.
+- A guard on a reference's presence names the file rather than the folder holding it, since a folder test answers for a sibling that happens to be there.
 - Use `${CLAUDE_SKILL_DIR}`, never a bare `../../` and never `${CLAUDE_PLUGIN_ROOT}`, since only the first expands before the body reaches the model.
-- Cite a shared procedure, never restate it. A procedure two or more skills execute gets one definition in a standard and a citation in each body.
-- Keep the trigger in the body and the procedure in the standard. The citing skill states when the procedure runs and what it runs against, since that varies per skill and the standard cannot know it.
+- Cite a shared procedure, never restate it. A procedure two or more skills execute gets one definition in its owner's reference and a citation in each body.
+- Keep the trigger in the body and the procedure in the reference. The citing skill states when the procedure runs and what it runs against, since that varies per skill and the reference cannot know it.

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`
@@ -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-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-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