@erclx/canon 4.0.0

package/standards/publish.md

@@ -0,0 +1,51 @@
+---
+title: Publish reference
+description: Scan an author runs against finished text, the cross-reference form each destination takes, and the response to an unreadable source
+---
+
+# Publish reference
+
+## Scope
+
+Governs the scan an author runs against finished text on its way out, the form a pull request or issue reference takes in every destination, and the responses available when a source it reaches for cannot be read. It is an attribute standard rather than a document-type one, so it applies wherever no automated check covers the text, whether that text is leaving through a channel or sitting in the repository, and it carries no template because a scan has no document to shape.
+
+Does not govern:
+
+- Which characters are banned, and the formatting the text carries: `markdown.md`
+- The voice and rhythm the text is written in: the `write-human` skill
+- The phase-label rule and the table of surfaces each namespace may appear on: `versioning.md`
+- Which gap a given surface has, and what it publishes through, which that surface names for itself
+
+## When it runs
+
+Wherever text leaves through a channel no automated check covers, the author is the only gate and runs this scan. Text sent to another service, written to a path the project's checks exclude, and text inside a fenced block are the usual cases. The surface that publishes the text is what knows which gap applies, so it names its own rather than reading one here.
+
+Run the scan as an explicit step against the finished text. Having read the underlying rules before drafting does not cover it, because the check has to happen after the text exists.
+
+## Banned characters
+
+`markdown.md` holds the character bans and the banned words alike. Read it at scan time rather than working the sets from memory, then scan the drafted text and rewrite each occurrence.
+
+Restructure the sentence rather than substituting the character. A semicolon swapped for a period leaves both clauses in the order the semicolon chose, which is the shape the ban exists to remove.
+
+## Phase labels
+
+`versioning.md` holds the label rule and the table of surfaces. Read it at scan time rather than working the format from memory.
+
+Scope this check by destination. Text published to a remote takes it. Text scanned on its way into the repository, where the reader has the task board, skips it.
+
+## Cross-reference form
+
+A number referring to a pull request or an issue takes the form its destination renders. Write it bare where the destination auto-links it, and in backticks where it does not. Both spellings are correct, each in one place, so a reference moved from one destination to the other is rewritten rather than copied.
+
+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.
+
+A commit message takes the bare form even though it is also read through the log, where nothing links. The remote is what the form is chosen for, since a reader in the log loses only a link that plain text never carried.
+
+Text quoted from another surface keeps the spelling it arrived with. A reference inside a quotation belongs to what is being quoted rather than to the text doing the quoting, so rewriting it reports the source as having said something it never said.
+
+## An unreadable source
+
+Stop and name the source when one this scan reaches for cannot be read. Do not scan what resolved and report the result.
+
+A run that covers half its sources and says nothing is worse than one that visibly did not happen, because the surfaces running this scan are the ones that describe themselves as the only gate. A clean result from a half-run scan is read as coverage.

package/standards/readme.md

@@ -0,0 +1,208 @@
+---
+title: Readme reference
+description: Readme voice, structure, and content conventions
+---
+
+# Readme reference
+
+Applies to every `README.md`. The `## Voice` section states the voice for a repository's root README, so the `write-human` skill yields to it there. The yield covers voice alone. The rhythm and density rules that skill carries stay in force, as do the spelling rules, banned words, punctuation, and formatting in `markdown.md`, so the warmer register ships with the same hygiene: no em dashes, no semicolons, no buzzwords.
+
+The reader is what changes. Reference prose serves someone who already committed to the project and is scanning for a fact. A root README meets someone deciding whether to commit at all, and it is often the only file they read.
+
+## Scope
+
+Governs every `README.md`: voice, heading structure, required and optional sections, badge selection, and what the page links out to instead of carrying.
+
+Does not govern:
+
+- Rhythm and sentence construction in README prose: the `write-human` skill, which yields the voice and keeps the rest
+- Spelling, banned words, punctuation, and formatting in README prose: `markdown.md`, which yields nothing
+- Product scope and goals: `requirements.md`
+
+## Voice
+
+Scoped to the README at a repository root. A nested README documenting a folder, a harness, or an internal tool keeps the reference voice the `write-human` skill carries, since its reader has already committed and arrived looking for a fact.
+
+- Address the reader in second person. First-person plural needs an authoring organization as its antecedent, so a single-maintainer project has none to use.
+- Use contractions wherever the sentence reads better for one. Do not force them in.
+- Write with a point of view. State what the project chose and why, not a neutral survey of the options it passed over.
+- Ground a claim in something concrete rather than an adjective. A command, a number, or a named constraint carries more than a description of quality.
+- Be honest about limits. Naming what the project does not do reads as more credible, not less.
+
+## Structure
+
+- H1 title, H2 major sections, H3 subsections. Maintain proper hierarchy for GitHub's auto-generated table of contents.
+- Use sentence case for all headings (proper nouns and product names retain their casing)
+- Project description in plain text directly under H1. Keep it to 2-3 sentences.
+- Do not create deeply nested heading structures that harm scannability
+- Do not use horizontal rules or dividers (`---`)
+
+## Sections
+
+- Required: project description, installation/setup, usage examples, support/help resources
+- Optional: badges (at top, before description), features, contributing (link to `CONTRIBUTING.md`), license (link to `LICENSE`)
+- Do not include full API documentation. Link to separate docs instead.
+- Do not include license text. Reference the `LICENSE` file.
+- Do not include detailed contribution guidelines. Reference `CONTRIBUTING.md`.
+- Do not include extensive troubleshooting guides. Use a wiki or separate documentation.
+
+### Badges
+
+A badge earns its place by carrying a fact the reader cannot get from the page they are already on. Three classes pass that test.
+
+- Package version, which reports what the registry actually published rather than what the working tree claims
+- Build or CI status, which reports whether the checks are currently passing
+- License, which passes because a README rendered on a registry page has no host sidebar stating it
+
+Stars, forks, download counts, language chips, and "made with" badges fail. The first three restate what a repository host already renders above the README, and the rest decorate.
+
+- Cap the block at four. A fifth costs more scanning than any badge repays.
+- Give each badge alt text naming what it reports rather than the service that renders it. Write `npm version`, not `shields.io`.
+- Link each badge to the page a doubting reader would check next, which is the registry listing for a version badge and the run history for a status badge. A red badge with no route to the failing run reports a problem and withholds the only thing the reader wants.
+- Pin a status badge to the branch whose health it claims to report, and confirm the workflow actually runs on that branch. A workflow triggered by pull requests alone never runs on the default branch, so an unpinned badge reports whichever branch ran last and a pinned one reports nothing at all. Fix the trigger, or drop the badge under the rule below.
+- Verify a badge by the value it renders, not by its status code. A badge service answers 200 for a query it cannot satisfy, so a blank badge and a working one look identical to a status check.
+- Zero badges is a correct answer. A private project with no registry presence and no CI has nothing that passes the test, and an empty block beats a padded one.
+
+## Content
+
+- Open public-facing READMEs with universal problems any reader recognizes, not repo-specific artifact names. Save artifact names for feature or "What is inside" sections.
+- Use relative paths for repository files. Use absolute URLs for external resources.
+- Include practical usage snippets for core functionality
+- For libraries/tools: include API quickstart
+- For applications/products: include usage instructions and configuration options
+- For CLI tools: include command examples with flags
+- For agent-facing repositories: name the file an agent loads first and the command that lists what the project exposes
+- For marketplace-distributed plugins: give the install command for every channel the project publishes to
+
+A project is often several of these at once. Cover every type that applies rather than picking the closest one. A repository that ships a CLI, distributes a plugin, and holds agent conventions owes its reader all three.
+
+## Examples
+
+### Template
+
+````markdown
+# Project Name
+
+Brief description of what the project does in 2-3 sentences.
+
+## Features
+
+- Key feature highlighting user benefit
+- Key feature highlighting user benefit
+
+## Installation
+
+```bash
+npm install project-name
+```
+
+## Usage
+
+```javascript
+import { feature } from 'project-name'
+
+feature.doSomething()
+```
+
+## Documentation
+
+See the [full documentation](https://docs.example.com) for detailed API reference.
+
+## Support
+
+- Open an issue for bug reports
+- Check [existing issues](../../issues) before creating new ones
+
+## Contributing
+
+See the [contributing guidelines](CONTRIBUTING.md).
+
+## License
+
+[MIT](LICENSE)
+````
+
+### Correct
+
+````markdown
+# Auth SDK
+
+Lightweight authentication library for Node.js with OAuth2 and JWT support.
+
+## Features
+
+- OAuth2 provider integration (Google, GitHub, Azure)
+- JWT token generation and validation
+- Session management with Redis support
+- TypeScript support with full type definitions
+
+## Installation
+
+```bash
+npm install auth-sdk
+```
+
+## Quick start
+
+```javascript
+import { AuthClient } from 'auth-sdk'
+
+const client = new AuthClient({
+  provider: 'google',
+  clientId: process.env.CLIENT_ID,
+})
+
+const user = await client.authenticate(code)
+```
+
+## Documentation
+
+Visit [docs.auth-sdk.dev](https://docs.auth-sdk.dev) for full API reference.
+
+## Support
+
+- Report bugs via [GitHub Issues](../../issues)
+- Community support on [Discord](https://discord.gg/example)
+
+## License
+
+[MIT](LICENSE)
+````
+
+### Incorrect
+
+````markdown
+# Auth SDK
+
+This is a seamless and powerful authentication library that allows developers to easily integrate robust OAuth2 functionality.
+
+## Why Use This?
+
+Basically, this library is just amazing and will revolutionize how you handle auth.
+
+## Installation
+
+Simply run the following command to install:
+
+```bash
+npm install auth-sdk
+```
+
+## API Documentation
+
+### AuthClient Class
+
+#### Constructor
+
+constructor(options: AuthOptions)
+
+[...full API docs inline, should link to external docs...]
+
+## License
+
+MIT License
+
+Copyright (c) 2026 Example Corp
+
+[...full license text, should reference LICENSE file...]
+````

package/standards/requirements.md

@@ -0,0 +1,70 @@
+---
+title: Requirements reference
+description: Shape and content rules for .claude/REQUIREMENTS.md
+---
+
+# Requirements reference
+
+Applies to `.claude/REQUIREMENTS.md`. Describes what the product does and why, not how it works. Update when scope changes, goals shift, or a non-goal is promoted to a feature.
+
+## Scope
+
+Governs the product-scope document at `.claude/REQUIREMENTS.md`: problem, goals, non-goals, MVP features, distribution, stack, and constraints.
+
+Does not govern:
+
+- Rationale for a technical choice: `architecture.md`
+- Execution order across the work the scope generates: `tasks.md`
+- Per-domain structure and narrative: `context.md`
+
+## What goes in
+
+- The problem being solved and for whom
+- User-facing goals stated as outcomes, not implementation
+- Explicit non-goals that prevent feature creep. Mark deferred items "(deferred)" so they read as paused, not excluded.
+- MVP features as a numbered list: feature name and one-line description
+- Tech stack as a plain list of tools
+- Hard constraints that shape every decision
+
+## What does not go in
+
+- Implementation details, API names, or internal component references
+- Anything that describes how a feature is built rather than what it does
+
+## Sections
+
+Use `## Problem`, `## Goals`, `## Non-goals`, `## MVP features`, `## Tech stack`, and `## Constraints`. Add `## Distribution` when the rule below applies. Drop a section rather than pad it with filler.
+
+## Lifecycle
+
+The MVP list is a historical record of the original scope. Once those features ship it stays as written. Do not renumber it, do not append to it, and do not annotate entries with status. A reader telling the original scope apart from what followed depends on the first one staying legible.
+
+Later scope arrives as a new section rather than as an extension of the MVP list. Name the section for what it delivers and state its entries as outcomes, the same way the goals are stated. Nothing sequences either list into versions. Work reaches the board as discrete tasks under `tasks.md`, which orders them by readiness, so a section here states what is wanted and never when it lands.
+
+## Distribution
+
+Include `## Distribution` only when the project ships to consumers outside its own repository. An internal service or a monorepo application has nothing to put in it, and a section every project is told to fill is one most projects pad. Place it after `## MVP features`.
+
+State each entry as an outcome the consumer reaches, never as the mechanism that delivers it. A registry name, a manifest format, a version scheme, or a release tool is implementation and belongs in `.claude/ARCHITECTURE.md`. Distribution pulls harder toward mechanism than any other section, which is why the rule is repeated here.
+
+## Template
+
+```markdown
+# Requirements
+
+## Problem
+
+## Goals
+
+## Non-goals
+
+## MVP features
+
+1. Feature: description
+
+<!-- ## Distribution: include only when shipping outside the repository -->
+
+## Tech stack
+
+## Constraints
+```

package/standards/rule.md

@@ -0,0 +1,118 @@
+---
+title: Governance rule reference
+description: Rule frontmatter, body shape, and voice for .claude/rules files
+---
+
+# Governance rule reference
+
+## Overview
+
+Rules give Claude Code coding constraints scoped to file paths. Claude Code discovers `.claude/rules/**/*.md` at session start.
+
+A rule with no `paths:` field always applies, at the same priority as `CLAUDE.md`. A rule with `paths:` applies when Claude reads a file matching the glob. Author one rule per topic so the scope stays precise.
+
+## Scope
+
+Governs governance rules under `.claude/rules/`: their location, numbering, frontmatter, and body shape.
+
+Does not govern:
+
+- Authoring conventions for a document type, which are standards rather than rules. A rule points at the standard that owns one and never restates it.
+- Skill folders and skill frontmatter: `skill.md`
+- Cross-domain behavior rules, which live in `CLAUDE.md` at the project root
+
+## Whether a skill belongs behind the rule
+
+A rule fires on a path match with no decision from the session, which is what makes it a floor. Every bullet is one directive and nothing else, so an invariant needing procedure, worked cases, or a branch on project state has no room in the body.
+
+Run the two-part test in reverse before calling the rule finished. The rule already holds what fires on a path edit and ships silently when violated. Ask what a session still needs past the directive, and give that to a skill the rule points at, because a rule that grows a procedure has become a skill body wearing rule frontmatter.
+
+Write both when both apply. A rule stating the directive and a skill stating how to carry it out are one invariant at two depths rather than two copies of it, and `skill.md` carries the same checkpoint for a session arriving from the other side. Nothing checks either one.
+
+## Location
+
+- Rules live at `.claude/rules/<subdirectory>/<n>-<slug>.md`
+- Subdirectories group by domain: `core/`, `lang/`, `framework/`, `lib/`, `ui/`, `claude/`, `snippets/`, `ci/`
+- `<n>` is a number from the band reserved for the rule's source and `<slug>` is a one-to-three-word kebab topic
+- A rule the project authored itself lives at `.claude/rules/project/<subdirectory>/<n>-<slug>.md`, keeping the same subdirectory names
+- Give every rule a numeric prefix. A bare-word filename reads as a folder name where a stack names its rules, so a rule without one is unreachable from a stack entry.
+
+## Reserved numbers
+
+`000-899` is reserved for a rule set that ships to targets. `000-599` is what the first six subdirectories above already divide, at 100 per subdirectory. `ci/` was the first to draw from the headroom past that, taking `700-799`, and `600-699` with `800-899` is what remains for a subdirectory a shipped set has not added yet.
+
+A project-authored rule takes `900-999`, one sequence across every subdirectory under `.claude/rules/project/`. Scanning for a free number instead is what fails, because a shipped set fills its own band release by release, so what reads as free today is what a later release lands on. One target authored `claude/561-self-check.md` on a day nothing shipped at 561, met `claude/561-teach.md` on its next install, and now reads two numbers differently from everywhere else.
+
+The cost is that a project-authored rule's leading digit stops naming its domain. Its subdirectory names it instead, and install preserves that either way. What a shared band costs is worse: a session that loads two rules reading as one number, with nothing in the folder to say which is which.
+
+`canon gov sync` reports a rule it finds no toolkit source for, outside `.claude/rules/project/`, and offers the path under it. The offer is conditional on the project having authored the rule, because a rule the toolkit shipped and later renamed looks identical from the outside and moving one there would mark it the project's for good. Nothing is moved either way, since a rule's installed path is one the project's own rules, skills, and docs may cite.
+
+## Two sources numbering into one folder
+
+The reservation above divides one pair, being a shipped set against the rules a project wrote for itself. A third source numbering into the same folder needs its own division, which is the case for a rule set held back from targets and installed only where it was authored. Divide by source rather than by topic: one source takes the top of each subdirectory's band and the other takes the gaps between the tens.
+
+The collision this prevents is silent. Two rules that resolve to the same `<n>-<slug>` path leave one file in the installed folder, and neither the install nor the session that reads it reports which source lost. Nothing checks a division outside the reserved bands, so it holds only while both sources follow it.
+
+State that division where the rule sources are described, not inside the rules it divides. A rule states its own topic, and a numbering convention spanning two sources belongs to whatever documents the pair.
+
+## Frontmatter
+
+- `description` (required): one line naming what the rule enforces and where
+- `paths` (optional): one glob per entry, for a rule scoped to a file set
+- Omit `paths` for an always-on rule that states a global principle with no file scope
+- Do not emit the legacy Cursor keys `globs`, `alwaysApply`, or `priority`. They are not read.
+
+```yaml
+---
+description: Enforce strict Python type hints, casing, and import patterns
+paths:
+  - '**/*.py'
+---
+```
+
+## Body
+
+- Open with an H1 `# <Topic> standards` in sentence case, then group rules under H2 sections. Proper nouns keep their casing (`# TypeScript standards`, `# Next.js standards`).
+- Use imperative voice for every rule (`Prefix booleans with is`, not `Booleans should be prefixed`)
+- State one rule per bullet as a single directive line
+- State what to do and what not to do. Do not explain the reasoning behind a rule.
+- Phrase a rule as a ban on the forbidden shape when it could otherwise enumerate allowed options, so it stays stable as categories grow
+- Cut any rule that resists crisp one-line phrasing. Vague guidance is worse than none.
+- Keep the file to one topic. A second topic is a second rule file.
+- Do not restate a rule that a sibling rule or `CLAUDE.md` already owns. Point once, never duplicate.
+
+## Examples
+
+### Correct
+
+```markdown
+---
+description: Enforce naming conventions for functions, booleans, and collections
+paths:
+  - '**/*.ts'
+---
+
+# Naming standards
+
+## Semantics
+
+- Prefix booleans with `is`, `has`, `should`, or `can`
+- Name functions as actions describing what they do
+- Name collections as plurals and items as singulars
+```
+
+### Incorrect
+
+```markdown
+---
+description: Naming
+globs: '**/*.ts'
+alwaysApply: false
+---
+
+# Naming
+
+Good naming matters because it makes code easier to read and maintain, so you
+should always pick descriptive names. Booleans are usually prefixed with is or
+has, and it can also be a good idea to think about collections too.
+```

package/standards/session.md

@@ -0,0 +1,109 @@
+---
+title: Session map reference
+description: Filename and location, the sections a handoff carries, the write and read procedures, and how a role extends it
+---
+
+# Session map reference
+
+Applies to `.claude/tasks/session-<slug>.md`. A session writes one before a compaction, because a compaction keeps conclusions and drops the reasoning that produced them. It is rewritten whenever the session that owns it learns something the next session would otherwise re-derive, and it is optional: a project whose sessions never approach a compaction carries none.
+
+Any session writes one. The role a session holds decides which sections it adds on top of the core, never whether it may write at all.
+
+## Scope
+
+Governs the pre-compaction handoff at `.claude/tasks/session-<slug>.md`: its filename, its sections, what a writer puts in each, and how a reader picks one up.
+
+Does not govern:
+
+- The task board the file sits beside, its filenames, and its archiving: `tasks.md`
+- The transform from a branch name to the slug in the filename: `slug.md`
+- The role-specific sections a caller adds over the core, which belong to that caller
+- Which memories a session captures before writing, which is the capture surface's own subject
+
+## What a working session map looks like
+
+A session map works when the session reading it can act on the reasoning without asking the session that wrote it:
+
+- What is clean, what is running, and what is open right now?
+- Which mistake already made would this session repeat?
+- Which command, tool, or held instruction lies about the tree?
+- Where did each claim come from, so a reader can tell a read from a recall?
+
+A session map failing these is non-conforming even when it satisfies every shape rule below.
+
+## Filename and location
+
+- Write one file per session, named `session-<slug>.md`, where `<slug>` is the branch-derived slug
+- Fall back to `session-latest.md` when the branch resolves empty, since a handoff is scratch rather than a commit and a stop would lose the reasoning it exists to save
+- Resolve the containing folder at the main worktree root, never inside a linked worktree
+- Overwrite the file the writing session already owns. A stale entry read as current is worse than no handoff.
+- Never write into a file another session owns. One file per session is what keeps two sessions closing near each other from each writing the whole file, where the loser leaves no trace.
+
+## Frontmatter
+
+- `title` (required): `Session map`, so every handoff reads the same in a generated catalog
+- `description` (required): what the board cannot show, and the date the file was written
+
+## Sections
+
+Three sections form the core, in this order, and every session fills all three.
+
+- `## State`: what is clean, what is running, what is open, and any untracked file that needs committing
+- `## Mistakes worth not repeating`: what went wrong and the rule it yields
+- `## Standing cautions`: commands that lie, tools that measure the wrong tree, and anything unbacked
+
+Add a section only for content that fits none of the three and would otherwise be lost.
+
+## Writing one
+
+The `session-map` skill is the invocable route onto this procedure and holds no role, so a session reaching for a handoff without knowing this document exists still lands here. A session that arrives at this document directly follows the steps below unchanged.
+
+1. Capture what the session learned first, so the map cites what was written instead of restating the same lesson in prose.
+2. Run `canon claude skills drift <the commit this session started from>` and record what it names under `## Standing cautions`. A skill body enters a session once and re-invoking the skill does not re-read the file, so the drift is worst at exactly this moment and a name here is a body the session has been following out of date. Recording a name is not acting on it, and the verb misses a body this session edited and has not committed. This step belongs to session length rather than to any role, so every writer runs it, and a refusal names the boundary of what the verb can read rather than a fault.
+3. Recover that commit from how long the session has been running with `git log -1 --format=%H --before='<duration> ago'`, rounding the duration up rather than down. Nothing on the machine records it. A ref older than the oldest load over-reports, and confirming a name costs one read of the body, so the generous end is the safe one and a guess at the exact commit is not worth making. An empty result means no commit predates the window, so take the oldest commit the history holds and say which of the two the ref came from.
+4. Write only what a compaction destroys and no other artifact already carries. The board holds the ordering and what each task waits on, a task file holds its own findings, and a measurement folder holds its track.
+5. Cite a commit, a task, or a file and line for every claim, so the next session can tell a read from a recall.
+6. Fill a section from reasoning the session actually holds. A session with no cross-feature picture that fills `## State` from what is already in git has written a summary of the tree, which the reader can produce faster than they can read it.
+
+Do not restate the board, and do not summarize the work that shipped, since version control already carries it.
+
+## Reading one back
+
+- Read the newest map in the folder, by modification time, and treat it as the previous session's scratch rather than as a source
+- Say nothing when no map exists. Absence is the common case, and a line reporting it every run is the noise that makes the present case unnoticeable.
+- Re-measure every count, size, and cost the map states, since each was true when written
+
+## Extending it
+
+- Carry every core section whatever else a role adds, and state in the surface that adds a section why the core cannot carry it
+- Let the adding surface fix where its own section sits, so a role can place one between core sections where that reads better. The core order holds among the core sections alone.
+- Keep a section out of the core when a session holding no such role would leave it unfilled. An unfilled section teaches a reader to skip the file.
+- Cite the route onto `## Writing one` rather than restating the procedure, so the extension is the only thing the adding surface carries and the two cannot fall out of step
+- Carry a resume instruction inside the map itself when the routing to that instruction is what a compaction takes. The map survives what the instruction was loaded from, so each reaches a reader the other cannot.
+
+## Template
+
+```markdown
+---
+title: Session map
+description: <what the board cannot show, and the date it was written>
+---
+
+# Session map
+
+<one line marking the file throwaway and naming the board as the real source>
+
+## State
+
+<what is clean, what is running, what is open, and any untracked file that needs committing>
+
+## Mistakes worth not repeating
+
+<what went wrong and the rule it yields>
+
+## Standing cautions
+
+<commands that lie, tools that measure the wrong tree, and anything unbacked>
+```
+
+A role-specific section is placed by the surface that adds it, so the skeleton above shows the core alone.