@erclx/canon 5.19.0 → 5.20.0

package/standards/skill.md

@@ -1,6 +1,18 @@
 ---
 title: Claude skill reference
-description: Claude skill structure and authoring rules
+description: Skill structure and authoring rules for Claude Code
+paths:
+  - '.claude/skills/**/SKILL.md'
+  - 'claude/skills/**/SKILL.md'
+  - '.claude/skills/**/REQUIREMENT.md'
+  - 'claude/skills/**/REQUIREMENT.md'
+rule:
+  - "Confirm `canon:create-skill`'s two creation-time questions are answered before a new `SKILL.md` lands, whether drafted by hand, by another skill, or by `canon:create-skill` itself. Carry the third question into the sibling `REQUIREMENT.md`'s `Must not` section as a review criterion rather than a gate."
+  - 'Report it rather than proceeding silently when `canon:create-skill` does not resolve. It ships with the plugin and this rule ships with the CLI, so a project that installed governance alone does not have it.'
+  - 'Re-read a skill body this session edited before invoking that skill again in the same session'
+  - 'Do not read a resolved file path in a held body as evidence the body is current'
+  - 'Follow the skill requirement standard for the shape a `REQUIREMENT.md` states. Read it with `canon standards skill-requirement`.'
+  - 'Follow the skill path standard for which root a path in a body resolves against and how a body cites a standard. Read it with `canon standards skill-paths`.'
 ---
 
 # Claude skill reference
@@ -17,11 +29,12 @@ 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`
 - 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`
 - The transform from a branch name to a slug a skill carries in a filename: `slug.md`
-- Whether a new skill earns its place: the three-question test in the `create-skill` skill and the clause in `570-skill.md`
+- Whether a new skill earns its place: the three-question test in the `create-skill` skill and the creation-time bullet in this standard's own `rule` frontmatter
 
 ## Changing a skill
 
@@ -146,27 +159,6 @@ allowed-tools: <tools required>
 - Use `#!/usr/bin/env bash` shebang
 - Always include `2>/dev/null || echo "FALLBACK"` guards on git and shell commands
 
-## Path resolution
-
-A skill reads from two roots, so know which one 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.
-
-### Citing a standard
-
-No standard installs into a project, so a body cites one place rather than choosing between two.
-
-- Cite `${CLAUDE_SKILL_DIR}/../../standards/X.md`. The plugin ships the whole standards folder beside `skills/`, so the path resolves in every install.
-- 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.
-- 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.
-
 ## Invocation
 
 - Invoke a plugin skill by its namespaced name, `/<plugin>:<skill-name>`.

package/standards/standard.md

@@ -1,6 +1,10 @@
 ---
 title: Standard reference
 description: Shape and content rules for authoring a standard
+paths:
+  - 'standards/**/*.md'
+rule:
+  - 'Read it before writing or editing a standard. Do not work the shape from memory.'
 ---
 
 # Standard reference
@@ -64,7 +68,9 @@ A standard failing these questions is non-conforming even when it satisfies ever
 
 - 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 standard covers. It becomes the index link label on install, and the generated rule's description and pointer bullet.
+- `paths` (optional): the globs where the standard applies, one per entry, copied verbatim into the rule `canon gov regen` generates for it. Omit it when no path should route to the standard, and no rule is generated.
+- `rule` (optional): operative bullets the generated rule carries after its pointer bullet, one per entry, each a full sentence. Quote an entry holding a backtick, a colon, or a leading `-`.
 
 ## Structure
 

package/standards/tasks-decline.md

@@ -0,0 +1,38 @@
+---
+title: Task decline reference
+description: Where a task decided against moves, the Declined line it carries, and what happens to its plan and board row
+---
+
+# Task decline reference
+
+Applies to a task under `.canon/tasks/` that somebody decided against doing. `canon tasks decline` performs the move, and this file fixes what the move leaves behind.
+
+This is an attribute standard. It governs one origin line and one folder move rather than a file of its own, so it carries no template.
+
+## Scope
+
+Governs the `.canon/tasks/declined/` folder, the `Declined:` line, and what declining does to the task's plan and board row.
+
+Does not govern:
+
+- The task file's layout, filename, format, other origin lines, and archiving: `tasks.md`
+- The board rows the move clears: `board.md`
+
+## What a working decline looks like
+
+A declined task works when a later reader can tell, from the folder and the file alone:
+
+- Was the work decided against, rather than shipped or merely unscheduled?
+- Who decided, when, and why?
+
+## Declining
+
+A task decided against moves to `.canon/tasks/declined/` rather than `.canon/tasks/archive/`. The two folders answer different questions: archive means the work shipped, declined means somebody decided against doing it. Neither reading fits a task that is merely unscheduled, which stays on `backlog.md` rather than moving anywhere, since nobody has decided against it and it may still rise when the board has room.
+
+`canon tasks decline` carries no outcome-state gate, so a task can be decided against at any outcome state, open outcomes included.
+
+The decision is recorded on the task itself with a `Declined:` line, in the `Plan:`/`Pull request:` family: `Declined: <reason>, <who> on <YYYY-MM-DD>`. It anchors the same way `Pull request:` does, after the last origin line the task carries. The line is free prose after the colon, since it names no file to link.
+
+Declining a task moves its plan alongside it the same way archiving does, when the declining task is that plan's last live citation. A plan several tasks share stays where it is, and a declined task's plan lands in `.canon/plans/archive/` indistinguishable from a shipped one by folder alone. The task file under `.canon/tasks/declined/` is what records which it was.
+
+The move clears whichever of `priority.md` or `backlog.md` holds the task's row.

package/standards/tasks.md

@@ -1,6 +1,12 @@
 ---
 title: Tasks reference
 description: Folder layout, filename convention, file format, origin lines, and archiving for task files under .canon/tasks/
+paths:
+  - '.canon/tasks/**'
+rule:
+  - 'Follow the board standard for `priority.md` and `backlog.md`, their readiness groups, and row order. Read it with `canon standards board`.'
+  - 'Never hand-edit `.canon/tasks/index.md`. A hook regenerates it from sibling frontmatter.'
+  - 'Follow the task decline standard for a task decided against. Read it with `canon standards tasks-decline`.'
 ---
 
 # Tasks reference
@@ -13,10 +19,11 @@ The folder is gitignored. Board state changes when work ships rather than when a
 
 ## Scope
 
-Governs the task files under `.canon/tasks/`: folder layout, filenames, frontmatter, file format, origin lines, archiving, and declining.
+Governs the task files under `.canon/tasks/`: folder layout, filenames, frontmatter, file format, origin lines, and archiving.
 
 Does not govern:
 
+- The declined folder, the `Declined:` line, and what declining does to a plan and a board row: `tasks-decline.md`
 - Execution order, readiness groups, the backlog, and the generated index beside the tasks: `board.md`
 - The plan file a task cites, its sections, and its answer contract: `plan.md`
 - Phase-label format and which surfaces a label may appear on: `versioning.md`
@@ -161,15 +168,3 @@ The archive nests inside `.canon/tasks/` rather than sitting beside it as a flat
 Archiving a task archives its plan alongside it, when the closing task is that plan's last live citation. The archived task's `Plan:` line is retargeted at `../../plans/archive/feature-<slug>.md`. The ready folder its `Ready:` line names moves with the plan to `.canon/ready/archive/<nn>-<slug>/`, and both pointers to it are retargeted. A plan several tasks share stays live with its ready folder, and the task archives anyway.
 
 A task with an open outcome stays on the board, and so does its plan. Close it, or cut it from the task when the work is being abandoned, so what was dropped is recorded rather than inferred from an archived file. Cutting means striking the outcome's body: `- ~~<outcome>~~ <why>`. A struck body reads as cut whatever its checkbox holds, so a task carrying only cut outcomes still archives.
-
-## Declining
-
-A task decided against moves to `.canon/tasks/declined/` rather than `.canon/tasks/archive/`. The two folders answer different questions: archive means the work shipped, declined means somebody decided against doing it. Neither reading fits a task that is merely unscheduled, which stays on `backlog.md` rather than moving anywhere, since nobody has decided against it and it may still rise when the board has room.
-
-`canon tasks decline` carries no outcome-state gate, so a task can be decided against at any outcome state, open outcomes included.
-
-The decision is recorded on the task itself with a `Declined:` line, in the `Plan:`/`Pull request:` family: `Declined: <reason>, <who> on <YYYY-MM-DD>`. It anchors the same way `Pull request:` does, after the last origin line the task carries. The line is free prose after the colon, since it names no file to link.
-
-Declining a task moves its plan alongside it the same way archiving does, when the declining task is that plan's last live citation. A plan several tasks share stays where it is, and a declined task's plan lands in `.canon/plans/archive/` indistinguishable from a shipped one by folder alone. The task file under `.canon/tasks/declined/` is what records which it was.
-
-The move clears whichever of `priority.md` or `backlog.md` holds the task's row.

package/standards/teach.md

@@ -1,6 +1,11 @@
 ---
 title: Teach reference
 description: Workspace layout, ordinal naming, frontmatter, and the mission and learning-record formats for a learning workspace
+paths:
+  - '.canon/teach/**'
+rule:
+  - 'Follow the glossary standard for the glossary every workspace carries at its root. It is the single source for the entry shape, the ordering, and which terms the file carries. Read it with `canon standards glossary`.'
+  - 'Report it rather than proceeding silently when that file does not resolve. It ships with the plugin and this rule ships with the CLI, so a project that installed governance alone does not have it.'
 ---
 
 # Teach reference

package/standards/wiki.md

@@ -1,6 +1,10 @@
 ---
 title: Wiki reference
 description: Folder split, frontmatter, naming convention, and sourcing for a wiki reference page
+paths:
+  - 'wiki/**/*.md'
+rule:
+  - 'Read it before drafting a page. Do not work the placement criterion or the naming convention from memory.'
 ---
 
 # Wiki reference

package/standards/wireframes.md

@@ -1,6 +1,11 @@
 ---
 title: Wireframe reference
 description: Shape and content rules for canon/wireframes/<surface>.md files
+paths:
+  - 'canon/wireframes/**'
+  - '.claude/wireframes/**'
+rule:
+  - 'Read it before adding or revising a surface.'
 ---
 
 # Wireframe reference

package/governance/rules/canon/610-context.md

@@ -1,17 +0,0 @@
----
-description: Route canon/context edits to the context-entry standard and the consult-first workflow
-paths:
-  - 'canon/context/**'
-  - '.claude/context/**'
----
-
-# Context entry standards
-
-## Before editing
-
-- Before non-trivial work in a domain, read its `canon/context/<domain>.md` entry. Use `canon/context/index.md` to find it.
-- Leave the entry conforming when work in its domain changes what it describes.
-
-## Authority
-
-- Follow the context standard for entry shape: frontmatter, sections, length, and what goes in. It is the single source. Read it with `canon standards context`.

package/governance/rules/canon/620-wireframes.md

@@ -1,13 +0,0 @@
----
-description: Route canon/wireframes edits to the wireframe standard for layout and interaction intent
-paths:
-  - 'canon/wireframes/**'
-  - '.claude/wireframes/**'
----
-
-# Wireframe standards
-
-## Authority
-
-- Follow the wireframes standard for layout and interaction intent: regions, the states table and its evidence links, copy, behavior, exclusions, and what moves to `canon/context/`. It is the single source. Read it with `canon standards wireframes`.
-- Read it before adding or revising a surface.

package/governance/rules/canon/630-requirements.md

@@ -1,12 +0,0 @@
----
-description: Route canon/REQUIREMENTS.md edits to the requirements standard for product scope and goals
-paths:
-  - 'canon/REQUIREMENTS.md'
-  - '.claude/REQUIREMENTS.md'
----
-
-# Requirements standards
-
-## Authority
-
-- Follow the requirements standard for what belongs in the problem, goals, non-goals, MVP features, and constraints. It is the single source. Read it with `canon standards requirements`.

package/governance/rules/canon/650-design.md

@@ -1,12 +0,0 @@
----
-description: Route canon/DESIGN.md edits to the design standard for visual intent and token tables
-paths:
-  - 'canon/DESIGN.md'
-  - '.claude/DESIGN.md'
----
-
-# Design standards
-
-## Authority
-
-- Follow the design standard for visual intent, the token tables, and the render contract. It is the single source. Read it with `canon standards design`.

package/governance/rules/canon/655-tasks.md

@@ -1,13 +0,0 @@
----
-description: Route .canon/tasks/ edits to the tasks standard for task files and the board standard for priority.md and backlog.md
-paths:
-  - '.canon/tasks/**'
----
-
-# Tasks standards
-
-## Authority
-
-- Follow the tasks standard for filenames, frontmatter, what belongs, and the task file format. It is the single source. Read it with `canon standards tasks`.
-- Follow the board standard for `priority.md` and `backlog.md`, their readiness groups, and row order. Read it with `canon standards board`.
-- Never hand-edit `.canon/tasks/index.md`. A hook regenerates it from sibling frontmatter.

package/governance/rules/canon/656-groundwork.md

@@ -1,11 +0,0 @@
----
-description: Route .canon/groundwork/ edits to the groundwork standard for ordinal naming, numbering, frontmatter, and required file contents
-paths:
-  - '.canon/groundwork/**'
----
-
-# Groundwork standards
-
-## Authority
-
-- Follow the groundwork standard for reserved numbering, frontmatter and dating, what each required file holds, and the conventions a track keeps. It is the single source. Read it with `canon standards groundwork`.

package/governance/rules/canon/657-intake.md

@@ -1,11 +0,0 @@
----
-description: Route .canon/intake/ edits to the intake standard for the item format, the answer contract, and ordinal naming
-paths:
-  - '.canon/intake/**'
----
-
-# Intake standards
-
-## Authority
-
-- Follow the intake standard for the folder layout, frontmatter and dating, the item format, and retrieval. It is the single source. Read it with `canon standards intake`.

package/governance/rules/canon/659-memory.md

@@ -1,11 +0,0 @@
----
-description: Route .canon/memory/ edits to the memory standard for the filename, frontmatter, body shape, and lifecycle
-paths:
-  - '.canon/memory/**'
----
-
-# Memory standards
-
-## Authority
-
-- Follow the memory standard for the filename and type prefix, the frontmatter, the body shape per type, links between entries, and the lifecycle. It is the single source. Read it with `canon standards memory`.

package/governance/rules/canon/660-diagrams.md

@@ -1,19 +0,0 @@
----
-description: Route .canon/diagrams edits to the diagrams standard for entry kinds, frontmatter, and explanation prose
-paths:
-  - '.canon/diagrams/**'
-  - '.claude/DIAGRAMS.md'
----
-
-# Diagrams standards
-
-## Authority
-
-- Follow the diagrams standard for which question an entry answers, the entry kinds and their source signals, the frontmatter, and the explanation prose beneath the fence. It is the single source. Read it with `canon standards diagrams`.
-- Layout, budgets, accessibility, labels, and render verification inside the fence are a separate topic. `802-mermaid` routes them to `mermaid.md`.
-- A diagram entry carries structure and flow, not implementation. Read the standard before adding or revising a kind.
-
-## Scope
-
-- Write a new diagram to `.canon/diagrams/<kind>.md`, never to `.claude/DIAGRAMS.md`
-- Convert a `.claude/DIAGRAMS.md` left by an older install into per-kind entries before editing it

package/governance/rules/canon/662-session.md

@@ -1,15 +0,0 @@
----
-description: Route .canon/tasks/ session map edits to the session standard for the filename, the core sections, and what a handoff carries
-paths:
-  - '.canon/tasks/session-*.md'
----
-
-# Session map standards
-
-## What a handoff carries
-
-- Follow this rule rather than `655-tasks.md` for a `session-` file. A handoff is not a task and carries neither `## Outcomes` nor `## Findings`.
-
-## Authority
-
-- Follow the session standard for the filename and location, frontmatter, the core sections, and the write and read procedures. It is the single source. Read it with `canon standards session`.

package/governance/rules/canon/663-ready.md

@@ -1,15 +0,0 @@
----
-description: Route .canon/ready/ edits to the ready standard for the folder layout, the overview frontmatter, and the thin-plan contract
-paths:
-  - '.canon/ready/**'
----
-
-# Ready standards
-
-## Writing a ready folder
-
-- Load the `canon:draft-ready` skill to write a ready folder, its overview, the thin plan, and the task row. It owns the procedure. Report it rather than proceeding silently when it does not resolve, since it ships with the plugin and this rule ships with the CLI.
-
-## Authority
-
-- Follow the ready standard for the folder layout, ordinal naming, the overview frontmatter, the mirrored tree, and the thin-plan contract. It is the single source. Read it with `canon standards ready`.

package/governance/rules/claude/590-rule-authoring.md

@@ -1,12 +0,0 @@
----
-description: Enforce frontmatter, body shape, and voice for governance rule files
-paths:
-  - '.claude/rules/**/*.md'
----
-
-# Rule authoring standards
-
-## Authority
-
-- Follow the rule-authoring standard for rule frontmatter, body shape, and voice. It is the single source. Read it with `canon standards rule`.
-- Read it before writing or editing a rule. Do not work the shape from memory.

package/governance/rules/writing/801-markdown.md

@@ -1,14 +0,0 @@
----
-description: Route markdown edits to the markdown standard for headings, lists, punctuation, and frontmatter wording
-paths:
-  - '**/*.md'
----
-
-# Markdown mechanics standards
-
-## Authority
-
-- Follow the markdown standard for headings, paragraph and list structure, code spans, punctuation, emphasis, file references, and the wording of a `title` or `description`. It is the single source. Read it with `canon standards markdown`.
-- Read it before a substantial markdown edit. Do not work the banned characters from memory.
-- Run `canon markdown audit <path>` after the edit, and rewrite the sentence carrying a hit rather than swapping the token for a near-synonym.
-- Voice, rhythm, and sentence construction are a separate topic. `800-prose` routes them.

package/governance/rules/writing/802-mermaid.md

@@ -1,14 +0,0 @@
----
-description: Route a drafted Mermaid fence to the mermaid standard for layout, budgets, accessibility, labels, and render verification
-paths:
-  - '**/*.md'
----
-
-# Mermaid diagram standards
-
-## Authority
-
-- Apply this rule only when the edit drafts or revises a Mermaid fence. Skip it on a markdown edit carrying no diagram.
-- Follow the mermaid standard for direction and layout, node and edge budgets, the accessibility fields, punctuation inside labels, and how a render is verified. It is the single source. Read it with `canon standards mermaid`.
-- Read it before drafting the fence. Do not work the layout or the budgets from memory.
-- Which diagram a document carries and what question it answers is a separate topic. `660-diagrams` routes it.

package/governance/rules/writing/880-readme.md

@@ -1,11 +0,0 @@
----
-description: Route README edits to the readme standard for structure, sections, and content conventions
-paths:
-  - '**/README.md'
----
-
-# README standards
-
-## Authority
-
-- Follow the readme standard for voice, structure, required and optional sections, heading hierarchy, badge classes, per-project-type content, and what to link out rather than inline. It is the single source. Read it with `canon standards readme`.

package/governance/rules/writing/891-standard-authoring.md

@@ -1,12 +0,0 @@
----
-description: Enforce shape, scope, and success criterion for authoring convention files
-paths:
-  - 'standards/**/*.md'
----
-
-# Standard authoring standards
-
-## Authority
-
-- Follow the standard-authoring standard for a standard's frontmatter, shape, scope, and success criterion. It is the single source. Read it with `canon standards standard`.
-- Read it before writing or editing a standard. Do not work the shape from memory.