@erclx/canon 4.116.0 → 4.118.0

package/docs/agents/context-audit-checks.md

@@ -43,7 +43,7 @@ Every entry past the checkpoint carries the three questions the standard asks of
 
 Only the third is mechanical, and it is the provenance check already reported below, so the length finding cites that count rather than measuring it again. What it cites is a count of change markers, which is why an entry recording what its own runs cost answers `no` there while carrying dates throughout. An entry outside the governed folder reads open there too, since provenance is scoped to the standard stating it and a clean list there is a scan that never ran. The other two stay open beside every entry, because whether a domain is still one domain is a judgment about its subject and recognizing reproduced content needs a reader who knows what those commands emit. Omitting them would read as an entry nothing found rather than one nothing checked.
 
-It reports and never gates, which the standard settles rather than the usual judgment-against-fact line: there is no hard cap, so an entry that answers all three and is still long is a correct outcome. The JSON record carries the joined findings as `length`, each with a `causes` array in the standard's order, and the jurisdiction the join reads as `entries[].governed`. That flag is what parts a provenance list measured and empty from one never scanned, which the count alone cannot say. The join is published rather than left to a consumer, since deriving it means restating which question the provenance count answers.
+It reports and never gates, which the standard settles rather than the usual judgment-against-fact line: the 150 checkpoint is diagnostic, so an entry that answers all three and is still long is a correct outcome. The one hard cap is the 300-line whole-document ceiling, which `canon markdown audit` and the Document ceiling gate stage read rather than this check. The JSON record carries the joined findings as `length`, each with a `causes` array in the standard's order, and the jurisdiction the join reads as `entries[].governed`. That flag is what parts a provenance list measured and empty from one never scanned, which the count alone cannot say. The join is published rather than left to a consumer, since deriving it means restating which question the provenance count answers.
 
 Depth and bullet weight are quoted from `standards/markdown.md`, which states both over every markdown file rather than over a context entry, so `canon markdown audit` measures them and this command no longer does. They share `renderedHeight` with the length measure, since the two checkpoints sit in one section of that standard and a reader compares them. What the split costs is that a session wanting both numbers for one entry runs two commands, and what it buys is that either number can be had for a file in a folder this audit refuses to resolve.
 
@@ -63,32 +63,6 @@ A release label reports with or without its leading `v` at three segments, since
 
 Fenced blocks are excluded, which keeps a pinned version in an install command from reading as a claim the entry makes. Frontmatter is excluded with them, since the content checks read the body alone, and that is what keeps a diagram entry's dated `verified` stamp a record of its last check rather than a marker to settle. Length is the exception, counting the whole file, so a reader applying the 150-rendered-line checkpoint against the body alone lands a few lines under what the tool reports.
 
-## Narration
-
-The narration check reports a bullet that states the design a sibling bullet replaced instead of rewriting it. `standards/context.md` asks for the rewrite because the subject is still live and two bullets on one subject leave a reader to work out which of them is current, and no other measure sees that shape.
-
-It reads structure rather than words, which the corpus decided. Measured across the 39 entries this toolkit held the day it shipped, the terms carrying clean signal for a supersession are too rare to catch anything: `superseded` appears twice, `previously` three times, and `formerly`, `originally`, and `at first` never. The one term that would have caught the case a review caught by hand is `now`, which appears 57 times across 24 entries in correct present-tense prose. A list including it reports 57 lines to catch one, and a list excluding it reports nothing.
-
-What it matches instead is a bullet doing three things at once: opening with a pronoun whose antecedent is the bullet above it, carrying a past-tense verb, and following another top-level bullet. All three are required. Eight bullets in the corpus open with a back-reference, and the verb set narrows those to one.
-
-The pronoun is matched cased and anchored to the opening, since a mid-sentence `this` is a determiner rather than a reference back. The verb is matched uncased anywhere in the bullet, and rejected when a copula sits in front of it, since `is used to resolve the folder` is the passive of `use` rather than the past habitual the set means.
-
-Both sets are published under `## Narration pronouns` and `## Narration verbs` in a governance rule and read at run time, so widening either costs a rule edit rather than a TypeScript change. The copula list stays in code, because it is English grammar rather than corpus vocabulary and a rule publishing two of three headings would be another absent state to carry. Discovery keys on the headings rather than the filename, because rules are numbered and a renumber would empty the sets while the check kept reporting clean. A run finding no rule that publishes both says it scanned nothing rather than reporting clean.
-
-A blank line does not end the run. Markdown reads the bullets around one as a single loose list, so a walker that broke there would leave the shape reachable by anyone who spaced their bullets out. What ends a run is content that is neither a bullet nor indented under one, which is what keeps the first bullet under a heading from reading as a reply to the last bullet above it.
-
-A fence answers that test for itself, because every scan here skips a fenced line before reaching it. An unindented fence ends the run, since CommonMark reads one at column zero as interrupting the list and the bullets around it are then two lists with no antecedent crossing between them. A fence indented under its bullet stays inside the item and leaves the run intact.
-
-The opening delimiter decides that for the whole block rather than each line deciding for itself. A blank line inside an indented fence carries no indentation to read, and a content line may sit at column zero inside one because CommonMark strips the fence's own indent and nothing further. Reading either as unindented ends a run that should have continued, which costs findings rather than inventing them, so no corpus count moves when it is wrong.
-
-Two fenced blocks with nothing between them are one contiguous run of fenced lines, so the mark alone cannot say where the first ends. The line walker reports which block each line sits in, and the boundary re-reads indentation whenever that number changes, so an unindented block written directly behind an indented one ends the run rather than inheriting the answer above it. No markdown file this repository tracks holds that shape, because a formatter inserts a blank line between two fences on contact, and a target running these commands over an unformatted tree still can.
-
-Precision is the whole value, so recall is the accepted exposure, and two shapes are knowingly out of reach. A narration written as one bullet carrying its own before and after slips through, and nothing else sees it either. So does the perfect passive, since `has been superseded` narrates a supersession and the copula guard rejects it with the passives it exists for.
-
-A rejected alternative is a back-reference in the past tense by construction, and the standard keeps what was tried and why it lost, so a legitimate hit exists and no measure separates it from a violation. The report states that on every run, which is why the finding names a line to read rather than a line to delete.
-
-The JSON record carries the findings per entry as `entries[].narration` and the sets as `checkpoints.narration`, which is absent under `--citations-only` where the run never loads them and null where no rule publishes both.
-
 ## The architecture record
 
 Four findings read `canon/ARCHITECTURE.md` rather than a folder, and only the first two are facts.
@@ -127,9 +101,9 @@ All three wireframe findings are printed under a bare run. The states-mismatch f
 
 ## Which folders each check reaches
 
-The provenance and narration checks cover `canon/context/` alone, the reference-form check covers the split folders inside it, the required-section check covers `canon/context/` and `canon/wireframes/`, length and the table finding reach every audited folder, and the wireframe states check covers `canon/wireframes/` alone.
+The provenance check covers `canon/context/` alone, the reference-form check covers the split folders inside it, the required-section check covers `canon/context/` and `canon/wireframes/`, length and the table finding reach every audited folder, and the wireframe states check covers `canon/wireframes/` alone.
 
-What narrows the first two is stated in `standards/context.md`, which opens its scope by handing diagrams and wireframes to `diagrams.md` and `wireframes.md`, and the sibling standards do not restate it. A marker reported in a diagram entry would cite a rule that entry's own standard routes elsewhere, and a diagram entry carries a heading per kind rather than a run of bullets deciding anything. The split is between kinds of rule rather than kinds of folder, and what decides it is which tier states the rule rather than what the check measures.
+What narrows the provenance check is stated in `standards/context.md`, which opens its scope by handing diagrams and wireframes to `diagrams.md` and `wireframes.md`, and the sibling standards do not restate it. A marker reported in a diagram entry would cite a rule that entry's own standard routes elsewhere. The split is between kinds of rule rather than kinds of folder, and what decides it is which tier states the rule rather than what the check measures.
 
 Length and the table finding generalize as judgments about how far a reader travels, so both reach wherever the audit is pointed. Required sections narrow for a plainer reason: each list is one standard's own, so it reaches the folder that standard governs. The context and wireframe standards each state a set, and the diagram standard states none.
 

package/docs/agents/context-audit.md

@@ -41,7 +41,7 @@ Exit codes are `0` for a clean run, `1` for a refusal, and `2` for a gating find
 
 `bun run check` in the toolkit repository reads both limits through its own Architecture record stage rather than through this verb, since the verb's only gating stage there runs `--citations-only` and never opens the record.
 
-Entry length, reference form, table, provenance, narration, the record's claim classification, and every word figure print and return `0` under every mode, because each is a judgment or a weight read alongside one, and failing a push on either would make the check something to route around. Narration is the weakest of the printed measures, since whether two bullets share a subject is a call the measure approximates from structure alone, and one of the shapes it matches is the rejected alternative the standard asks an entry to keep.
+Entry length, reference form, table, provenance, the record's claim classification, and every word figure print and return `0` under every mode, because each is a judgment or a weight read alongside one, and failing a push on either would make the check something to route around.
 
 Required-section, index, and wireframe-states findings sit between the two. All three are answerable from the file rather than weighed, so `--gate` promotes them to failing codes while a bare run leaves them advisory. Sketch-with-evidence sits with the printed measures instead, for the reason `context-audit-checks.md` states: it reads a whole entry against whether any of its states has evidence, not one layout against its own evidence, so a conforming file can still trip it. The toolkit runs the bare form against itself and the widened form against the seed tree, described below.
 

package/docs/agents/install-and-sync.md

@@ -17,22 +17,26 @@ matched, or reported on, which is how project-authored rules survive. It also
 removes a stale `.claude/GOV.md` from the retired build. Use
 `canon gov install` to add rules.
 
-A rule under `.claude/rules/canon/` that the toolkit finds no source for is
-reported orphaned with no destination offered. The toolkit cannot tell a rule
-a project dropped there from one it shipped and later renamed, and a
-destination nested inside `canon/` would be wrong for the first case
-regardless, since that folder is replaced wholesale on sync.
-
-Nothing is moved either way, because a rule's installed path is one the
-project's own rules, skills, and docs may cite. `canon standards rule` carries
-the reserved number bands behind the three-way split, where `900-999` under
-`.claude/rules/project/` is what a project-authored rule takes and everything
-under `.claude/rules/canon/` belongs to the toolkit.
-
-`canon sync --check` does not report an orphaned entry. It skips every one, so
-the destination reaches `canon gov sync` alone among the two per-file domain
-syncs, since design's own orphans are the target's overrides and are meant to
-stay where they are.
+Everything under `.claude/rules/canon/` belongs to the toolkit, so a rule
+there that the toolkit no longer ships is deleted on sync, edited or not. That
+is how a retired or renamed rule stops loading in a target. The sync lists each
+deletion by path before it applies, and the target's git diff is the record
+afterwards. `canon sync --check` lists the same file as `retired` before any
+sync runs. A project's own rules belong under `.claude/rules/project/`, where
+`canon standards rule` reserves `900-999` for them, and a rule placed under
+`canon/` instead is lost on the next sync.
+
+A sync never deletes a rule that a newer canon release installed. The stamp
+records the newest release that synced governance, and an older binary holds
+every rule it finds no source for, naming both releases and asking for an
+upgrade, rather than deleting what it cannot recognize.
+
+A renamed rule loses its old file and gains nothing under the new name unless
+the target's stamp records the stack it installed, in which case the new name
+shows as `missing` and `canon gov install <stack>` adds it.
+
+Design's own orphans are the target's overrides and are meant to stay where
+they are, so `canon design sync` deletes nothing it finds no source for.
 
 `canon design install` copies one toolkit-owned file to
 `.claude/design/base.css` and creates no override. A project overrides a value
@@ -79,7 +83,7 @@ no copy to reconcile. `canon snippets list --json` carries the catalog and
 
 `canon tooling diff <stack> [target]` is the read-only comparison, and a session asking what differs reaches for it by default. It writes nothing and exits 1 when anything differs and 0 when nothing does, so it gates CI. `--json` adds the scan record on stdout with `ok: true`, and the frame goes to stderr. A refusal such as an unknown stack, an excluded stack, or a toolkit-root target still exits 1 and answers `{ ok: false, reason, message }`, so a caller branches on the record and reads a typo'd stack name as a refusal rather than as drift.
 
-The record carries a `withheld` array beside `configs`, each entry `{ rel, stack, present }`. It fills only when the target sits below its git root: every `.github/` config moves there rather than into `configs`, and none of them counts toward the exit, since GitHub never reads a workflow outside the root. `present` marks a copy an earlier sync already left in the subfolder, which the sync reports and never deletes. At a root, and for a target outside any repository, `withheld` is empty.
+The record carries a `withheld` array beside `configs`, each entry `{ rel, stack, present }`. It fills only when the target sits below its git root: every `.github/` config or seed moves there rather than into `configs` or `seeds`, and none of them counts toward the exit, since GitHub never reads a workflow outside the root. `present` marks a copy an earlier sync already left in the subfolder, which the sync reports and never deletes. At a root, and for a target outside any repository, `withheld` is empty.
 
 `canon tooling sync <stack> [target] --check` reports the same list and always exits 0. It stays for scripts that already call it. `sync` itself writes only under `--write`, and a headless run with neither flag reports and exits 1.
 
@@ -160,7 +164,9 @@ matches what the toolkit installed, `customized` when the project edited it,
 `stranded` when it sits at a path the toolkit no longer installs to, `orphaned`
 when the project authored it, or `drifted` when no stamp covers it. Governance
 also reports `missing`, for a rule the target's recorded stack lists that its
-tree does not hold at all.
+tree does not hold at all, and `retired`, for a rule under
+`.claude/rules/canon/` the toolkit no longer ships, which the next sync
+deletes. A `retired` file counts toward `--exit-code`, since one sync clears it.
 
 Use `--json` for the machine-readable report and `--exit-code` to fail a CI job. Orphaned
 and missing files are both excluded from that exit code: a project-authored

package/docs/agents/markdown-audit.md

@@ -27,9 +27,9 @@ A bare run measures every markdown file git lists, tracked plus untracked-and-no
 
 ## Where the rules come from
 
-The three ban sets and all nine checkpoints ship with the `canon` package as data, in `src/markdown/bans.ts` and `src/markdown/structure.ts`. Every project is measured against the same sets whether or not it installed any standards, and no file has to resolve for a run to mean something.
+The three ban sets and all ten checkpoints ship with the `canon` package as data, in `src/markdown/bans.ts` and `src/markdown/structure.ts`. Every project is measured against the same sets whether or not it installed any standards, and no file has to resolve for a run to mean something.
 
-Six of the nine are stated in `markdown.md` and the three cadence numbers are stated in the `write-human` skill. That split is the content boundary rather than an accident: `markdown.md` carries the enforced rules a scan can decide, and the skill carries the rhythm rules a ban list cannot express. A cadence number moved in the skill and left in the code drifts the same way, so move both.
+Seven of the ten are stated in `markdown.md` and the three cadence numbers are stated in the `write-human` skill. That split is the content boundary rather than an accident: `markdown.md` carries the enforced rules a scan can decide, and the skill carries the rhythm rules a ban list cannot express. A cadence number moved in the skill and left in the code drifts the same way, so move both.
 
 Reading them out of the standards per run was the original design. It put a parser contract on a document authored for people, and the standard had to carry a paragraph of its own warning an author that a one-word backticked example in a `- Do not use ` bullet would be lifted into a literal ban set and ban that word everywhere. A rule existing to protect a parser from the prose it parses is the argument for separating them.
 
@@ -128,9 +128,13 @@ Two of the rules `write-human` states are deliberately not implemented. A senten
 
 The condition on that was something identifying a finite verb rather than guessing at one, and two parsers have now been run against it over 11,389 paragraph sentences. They disagree by a factor of four. `compromise` reports 2 percent and reads a fronted past participle as a finite verb, so `Measured at <sha> on <date>.` counts as carrying one. `wink-pos-tagger` reports 9 percent, fixes that class, and is still wrong on roughly three in four, because an imperative's verb tags as a proper noun and a noun-ambiguous predicate tags as a noun, which makes `Each maps to a skill.` read verbless. Separating those needs to know which token is the predicate, and that is syntax rather than a tag. The measure stays unimplemented, now against a mechanism rather than against the idea of one.
 
+### Length
+
+The Length step sums rendered lines over the whole source, frontmatter and fenced blocks included, and lists each document past the 300-line ceiling, longest first. A changelog and a document carrying a whole-line `<!-- canon-length-exempt: <reason> -->` outside a fence are counted in one line rather than listed. Each `--json` entry carries `renderedLines` and `exempt`, the stated reason or `null`, and `checkpoints` carries `ceiling`.
+
 ## Exit codes
 
-Exit codes are `0` for a completed run with no gating finding, `1` for a refusal, `2` for a ban hit or a dead relative link, and `3` for a shipped ban set that arrived empty. A banned character, word, or spelling and a relative link resolving to nothing on disk each fail the run, both facts a scan settles rather than a reader judging. Bullet, paragraph, and depth weight are judgments a reader settles, and cadence is a distribution whose healthy range moves with the surface, so all four report under every code.
+Exit codes are `0` for a completed run with no gating finding, `1` for a refusal, `2` for a ban hit or a dead relative link, and `3` for a shipped ban set that arrived empty. A banned character, word, or spelling and a relative link resolving to nothing on disk each fail the run, both facts a scan settles rather than a reader judging. Bullet, paragraph, and depth weight are judgments a reader settles, and cadence is a distribution whose healthy range moves with the surface, so all four report under every code. Length reports the same way, since the audit also runs on a plan kept out of version control, and the Document ceiling stage in `canon gate run` owns that verdict instead.
 
 `3` is separate from `1` because the two want different responses from a caller. A refusal means no corpus was built, and the `Markdown bans` stage in `canon gate run` is right to report it as unmeasured rather than as a pass. An empty set means the corpus was walked and nothing was looked for, so that stage fails the push on `3` rather than skipping.
 

package/docs/agents/skills-audit.md

@@ -35,18 +35,25 @@ Each check traces to a line in the standard.
 - No `README.md` inside a skill folder
 - Folder name in kebab-case
 - Each `REQUIREMENT.md` declaring `Gap` and `Must`, matched at any heading level
+- No ISO date in `SKILL.md` or any file under `references/`, reported as `datedProvenance` in the JSON record's `findings`
 
 A body whose frontmatter does not parse reports as declaring neither field rather than ending the run, so one malformed file cannot hide the corpus behind it. A key present with an empty value reads as absent, since a blank `name` would otherwise report as a name disagreeing with every folder. A folder carrying no requirement is reported once under presence rather than counted again for the sections it therefore lacks.
 
+The date check reads prose alone. A date inside a fence or a code span is example data, such as a sample frontmatter block, and a date in the body's own frontmatter is metadata, so neither reports. `REQUIREMENT.md` and `EVAL.md` are not read, since the requirement's `Gap` is where the standard sends the incident and the date that earned a rule.
+
+Each finding names the file and the line, such as `claude/skills/<name>/references/<file>.md  line 12: <date>`. A date after "measured" or "verified" reports like any other, unlike the context audit, because a skill body states the rule a session follows today rather than a reading of the tree.
+
 ## What it leaves alone
 
 The report names its own blind spots on every run, including the run where everything passed. Whether each `Must` traces to a stated gap is the rule in that standard worth the most and no parser reads it. Whether a gap states an observed failure rather than an intent, and whether a description routes, are the same kind of judgment. The 150-line body checkpoint is the one mechanical rule still absent here, and adding it would print a count rather than a defect, since the standard makes it a prompt to look with nothing enforcing it.
 
+The date check reads ISO dates alone. A date written in words, a month with no day, and provenance carrying no date at all pass it.
+
 A check with no rule behind it prints an opinion as a defect, which is where the list stops.
 
 ## Exit codes
 
-Exit codes are `0` for a clean run, `1` for a refusal, and `2` for a skill folder carrying no `REQUIREMENT.md`. Only presence sets a failing code. Name, description, folder, and requirement-section findings print and return `0`, because each is a judgment a reader settles and failing a push on one would make the check something to route around.
+Exit codes are `0` for a clean run, `1` for a refusal, and `2` for a skill folder carrying no `REQUIREMENT.md`. Only presence sets a failing code. Name, description, folder, requirement-section, and dated-provenance findings print and return `0`, because each is a judgment a reader settles and failing a push on one would make the check something to route around.
 
 ## The requirement gate
 

package/docs/target-projects.md

@@ -118,7 +118,7 @@ The plugin corpus carries runtime behavior rather than reference prose alone, be
 When a new need appears after scaffold, install the one domain without re-running `canon init`.
 
 - Governance rule for a newly adopted library: invoke `canon:target-setup gov`, or run `canon gov install <stack> --add <rule> <path>`
-- Project-specific rule the toolkit does not ship: invoke `canon:create-rule`. It scaffolds a rule into `.claude/rules/` with a non-colliding number, and `canon gov sync` leaves it untouched.
+- Project-specific rule the toolkit does not ship: invoke `canon:create-rule`. It scaffolds a rule into `.claude/rules/project/` with a non-colliding number, and `canon gov sync` leaves it untouched. A rule placed under `.claude/rules/canon/` instead is deleted on the next sync, since that folder belongs to the toolkit.
 - Index.md system for a markdown-heavy folder that emerged: invoke `canon:target-setup indexes`
 
 Standards and snippets are not on that list, and there is nothing to add for either. Neither installs into a project, by default or by flag, so a session reads a standard with `canon standards <name>` and a snippet through its `@` reference off the live plugin symlink, both resolving against the toolkit rather than a project copy. A project holding a `.claude/standards/` or `.claude/snippets/` folder from an older toolkit is carrying a stale artifact nothing reads, and deleting it is safe.
@@ -225,7 +225,7 @@ The report opens by naming the binary running it. The installed version reads ag
 
 #### Then the causes
 
-A `stale` file still matches what the toolkit installed, so the update is mechanical. A `customized` file carries local edits, so taking the upstream version is a decision and `canon:seed-sync` is the tool for it. A `stranded` file sits where an older toolkit installed it and the toolkit has since moved, which is a relocation the report names but no command runs.
+A `stale` file still matches what the toolkit installed, so the update is mechanical. A `customized` file carries local edits, so taking the upstream version is a decision and `canon:seed-sync` is the tool for it. A `stranded` file sits where an older toolkit installed it and the toolkit has since moved, which is a relocation the report names but no command runs. A `retired` rule is one under `.claude/rules/canon/` the toolkit no longer ships, and the next `canon gov sync` deletes it.
 
 That attribution comes from `canon/config/config.json`, which every install and sync now writes, falling back to `.claude/canon/config.json` for a target stamped before that move. A target stamped before that path shipped is read from the retired `.claude/canon.json` instead, reported rather than migrated. Governance records a hash per installed file, plus the stack `canon gov install` was given, and tooling records the stack chain it resolved instead of any file hash, since its install runs no per-file walk to attribute.
 

package/docs/workflow/ai-workflow.md

@@ -273,15 +273,15 @@ This section is the corpus the coverage claim is measured against: every name `c
 
 ### Run several tracks at once
 
-| Skill                     | When to use                                                                                          |
-| ------------------------- | ---------------------------------------------------------------------------------------------------- |
-| `canon:role-orchestrator` | To assert the control session that owns the queue and reviews each worker's PR                       |
-| `canon:role-planner`      | To assert the thinking role for a cold session writing a plan, a groundwork track, or an intake pass |
-| `canon:role-worker`       | To assert the worker role for a cold session building one branch under one plan                      |
-| `canon:session-relay`     | When this session owes another session a message, with or without a role                             |
-| `canon:session-resume`    | At the start of a session, to pick up what a previous one left                                       |
-| `canon:session-compact`   | Before a compaction, to write a plain session's handoff note outside the board                       |
-| `canon:session-map`       | At the close of an orchestrating session, to write its board-side handoff                            |
+| Skill                     | When to use                                                                                                 |
+| ------------------------- | ----------------------------------------------------------------------------------------------------------- |
+| `canon:role-orchestrator` | To assert the control session that owns the queue and reviews each worker's PR                              |
+| `canon:role-planner`      | To assert the thinking role for a cold session writing a plan, a groundwork track, or an intake pass        |
+| `canon:role-worker`       | To assert the worker role for a cold session building one branch under one plan                             |
+| `canon:session-relay`     | When this session owes another session a message, with or without a role                                    |
+| `canon:session-resume`    | At the start of a session, to pick up what a previous one left                                              |
+| `canon:session-compact`   | Before a compaction or a move to another machine, to write a plain session's handoff note outside the board |
+| `canon:session-map`       | At the close of an orchestrating session, to write its board-side handoff                                   |
 
 ### Keep the project current with the toolkit
 

package/docs/workflow/operating-model.md

@@ -263,4 +263,4 @@ port-collision detail.
 
 - [Claude Code and git worktrees](../../wiki/claude/claude-worktrees.md) for the isolation and fan-out mechanics
 - [Claude Code subagents](../../wiki/claude/claude-subagents.md) for in-session parallelism without worktrees
-- `canon/context/claude-plugin/skill-strategy.md` for how the skills in the loop are categorized
+- `canon/context/claude-plugin/skill-strategy/overview.md` for how the skills in the loop are categorized

package/docs/workflow/visual-design-workflow.md

@@ -150,7 +150,7 @@ Resist over-tiering early. Moving up is cheap because tiers stack. Moving down m
 ## References
 
 - [Claude Design](../../wiki/claude/claude-design.md): first-party hosted design product and handoff bundle
-- `canon/context/claude-plugin/skill-strategy.md`: how to decide between workflow and domain-knowledge skills
+- `canon/context/claude-plugin/skill-strategy/overview.md`: how to decide between workflow and domain-knowledge skills
 - [`microsoft/playwright-mcp`](https://github.com/microsoft/playwright-mcp): browser automation MCP used in tier 1 and tier 2
 - [`ChromeDevTools/chrome-devtools-mcp`](https://github.com/ChromeDevTools/chrome-devtools-mcp): live frontend debugging MCP used in tier 1 and tier 2
 - [`yctimlin/mcp_excalidraw`](https://github.com/yctimlin/mcp_excalidraw): community MCP server behind the tier 1 wireframe companion

package/governance/rules/claude/510-context.md

@@ -12,18 +12,6 @@ paths:
 - 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.
 
-## Narration pronouns
-
-Do not open a bullet with one of these where the antecedent is the bullet above it.
-
-- `It`, `That`, `This`, `These`, `Those`, `They`
-
-## Narration verbs
-
-Do not put a sibling bullet's design in the past with one of these.
-
-- `was`, `were`, `became`, `replaced`, `superseded`, `used to`
-
 ## 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/core/005-behavior.md

@@ -13,8 +13,7 @@ description: Handle judgment calls, scope discipline, and file-editing mechanics
 - When facing a judgment call with 2-3 reasonable options mid-flow, pick one and state the tradeoff in one sentence. Enumerate options only when the user's preference is the deciding factor.
 - Put a call the user's preference decides through the structured question surface, such as `AskUserQuestion` in Claude Code, and fall back to a numbered list in one message where none exists. Rank the recommendation first and mark it, order the rest behind it, and give each option its cost, since an option with no stated cost is picked blind.
 - Author the real choices only. A structured surface appends its own trailing escapes for a free-text answer and for reopening the question as conversation, so never write either as an option. On the numbered-list fallback, say that answering outside the list is fine.
-- Answer from the artifact when one already put the question in writing with a suggestion, rather than re-asking it. A blank `- Answer:` slot in a plan accepts the `- Suggested:` line above it, per the plan standard, which your toolkit resolves by name.
-- Rewrite the `- Suggested:` line rather than the blank `- Answer:` slot when execution decides against an unanswered plan question's suggestion, per the plan standard, which your toolkit resolves by name.
+- Answer from the artifact when one already put the question in writing with a suggestion, rather than re-asking it.
 
 ## Scope discipline
 

package/governance/rules/core/015-output.md

@@ -11,9 +11,7 @@ description: Report file paths correctly for the reading surface and group them
 - When it reads `claude-desktop`, emit each path as a markdown link carrying the path as its text and an absolute `file://` URI as its target, resolving a relative path against the main project root to build that target. The desktop file tree hides dotted folders, so a bare path into one names a file the reader cannot reach.
 - On every other value, including unset, emit the path bare. A terminal emulator makes it clickable through its own path detection, and link markup defeats that.
 - Both forms govern a path emitted in a response. A path written into a markdown file follows the markdown standard instead, which your toolkit resolves by name, and which backticks a file reference and never repeats it as a link label.
-- Use the path the user's editor can resolve. The editor is rooted at the main project root.
-- In the main worktree: relative from `pwd` works because `pwd` equals the editor root.
-- In a linked worktree (under `.claude/worktrees/<name>/`): use absolute paths. Relative paths from worktree `pwd` would not resolve against the editor's project root. A `PostToolUse` hook computes this form after each write and hands it back as additional context where it is installed. Prefer that form when it arrives, and fall back to computing the absolute path yourself when it does not.
+- In a linked worktree (under `.claude/worktrees/<name>/`), emit the absolute path, since the editor is rooted at the main project root and a path relative to the worktree resolves nowhere there. Prefer the form a `PostToolUse` hook hands back after a write where one is installed.
 
 ## Grouping multiple files
 

package/governance/rules/core/035-tasks.md

@@ -6,8 +6,6 @@ description: Scope, size, and link a task file correctly
 
 ## Task files
 
-- `.canon/tasks/` is gitignored local session scratch, one file per task. Edit freely. No staging or revert before commits.
 - Only create a task for work that spans multiple sessions or has real dependencies. Handle small edits immediately without a task entry.
 - Do not add tasks retroactively for work already completed. Completed work is visible in git.
-- When a task needs execution detail beyond its own file, create a plan in `.canon/plans/` and link to it from the task's intro paragraph. When that task ships, move its plan file to `.canon/plans/archive/`. Never delete it.
-- Write the plan in the same session as the task file. The session that executes the plan later inherits reasoning context it would otherwise have to re-derive.
+- When a task needs execution detail beyond its own file, write a plan in `.canon/plans/` in the same session as the task and link to it from the task's intro paragraph. The session that executes the plan later inherits reasoning context it would otherwise have to re-derive.

package/governance/rules/core/045-memory.md

@@ -9,4 +9,3 @@ description: Keep memory writes scoped to .canon/memory/ and out of context-owne
 - Write all memory files to `.canon/memory/`, not `~/.claude/projects/`
 - A fact about a domain goes to that domain's `canon/context/` entry, not to memory. `canon:memory-capture` routes it there and `canon:docs-fold` folds it in. Memory keeps only what no context entry owns. Report it rather than proceeding silently when either skill does not resolve. Both ship with the plugin and this rule ships with the CLI, so a project that installed governance alone does not have them.
 - Never delete a memory entry. Retire one by moving it to `.canon/memory/archive/`, which `canon records push` backs. A bulk retire runs through the shell, where no file edit fires a path-scoped rule.
-- Follow the memory standard for the filename and type prefix, the frontmatter, the body shape each type carries, and the lifecycle. Read it with `canon standards memory`. Check every entry in the pen against that standard and fix what breaks it, since nothing keeps the folder conforming on its own.

package/governance/rules/core/055-scratch.md

@@ -6,7 +6,5 @@ description: Write temporary files to the scratch folder structure
 
 ## Temporary files
 
-- Write temporary files to `.canon/tmp/<slug>/<file>.md` in the project root, a nested `<slug>/` folder with a kebab-slug tied to the topic, not a flat `<slug>-<file>.md`. The scratch-guard hook enforces the location.
-- Write to `.claude/.tmp/<slug>/` instead in a project that carries no `.canon/` root, which is one the record move has not reached. The hook accepts either, but the ignore file is the source: `.gitignore` and its manifest counterpart are what keep the fallback spelling out of `git status`, and the hook and this rule both defer to it. `canon migrate records` is what moves a project from this second spelling to the first. <!-- canon-keep-record-root -->
-- "The project root" above means the current worktree by default. `085-worktrees.md` states the same mixed default for `.canon/tmp/` and defers to each skill's own body for which write resolves at the main root instead.
-- `runs/`, `hooks/`, `handoff/`, `pr/`, and `render/` are reserved under `tmp/` for build and command output that can be regenerated, hook state, skill-to-skill handoff, pull request scratch, and render output. A session slug must not take one of these five names.
+- Write temporary files to `.canon/tmp/<slug>/<file>.md` at the current worktree's root, a nested folder with a kebab-slug tied to the topic rather than a flat `<slug>-<file>.md`. The slug must not take one of the five reserved names `runs`, `hooks`, `handoff`, `pr`, and `render`. A skill that resolves a write at the main root instead states so in its own body.
+- Write to `.claude/.tmp/<slug>/` instead in a project that carries no `.canon/` root, and `canon migrate records` moves it to the first spelling. <!-- canon-keep-record-root -->

package/governance/rules/core/070-planning.md

@@ -6,14 +6,11 @@ description: Enforce planning standards before implementation
 
 ## Planning
 
-- Analyze requests and output a numbered implementation plan before execution.
+- Confirm a numbered implementation plan before a change whose diff cannot be described in one sentence.
 - Challenge ambiguous or over-engineered requests before implementation.
 - Search the project, its dependencies, and the standard library for an existing implementation before writing new code.
 - State where the search ran and why each candidate was rejected. Do not assert a search without naming its results.
 - Propose the simplest solution that satisfies the requirement before implementing complex patterns.
 - Write or update tests as part of every implementation plan.
 - Write the test for a behavior before the code that implements it. Confirm visual output after implementing it, not before.
-- Load the `canon:test-first` skill before writing the implementation for a behavior whose test does not exist yet, and report it rather than proceeding silently when the skill does not resolve.
 - Run `canon gov test-order` before shipping a branch. Fix what it names as reaching history ahead of its test.
-- Load the `canon:systematic-debugging` skill before proposing a fix for a failing test, a surfaced bug, or behavior nobody has explained yet, and report it rather than proceeding silently when the skill does not resolve.
-- Do not modify code without a confirmed plan.

package/governance/rules/core/087-git.md

@@ -1,5 +1,5 @@
 ---
-description: Route every git operation through the canon git skills, and run one only when something actually calls for it
+description: Route every git operation through the canon git skills, which choose the surface and never authorize the operation
 ---
 
 # Git standards
@@ -12,4 +12,4 @@ description: Route every git operation through the canon git skills, and run one
 
 ## Whether to act
 
-- A git operation runs only when the user asked for it, a task states it, or it executes as a step of a chain the user invoked. The bullets above decide which surface performs an operation already decided, never whether to take one.
+- The bullets above decide which surface performs an operation already decided, never whether to take one.

package/governance/rules/core/090-code-comments.md

@@ -36,4 +36,4 @@ paths:
 
 Do not write a comment carrying any of these terms.
 
-- `FIXED`, `BUGFIX`, `HACK`, `XXX`, `NOTE:`, `TODO`, `FIXME`, `don't remove`, `previously`, `used to`, `workaround`
+- `TODO`, `FIXME`, `HACK`, `XXX`

package/governance/rules/ui/440-surface-capture.md

@@ -44,5 +44,7 @@ paths:
 - Commit a flagged case's evidence output so the pull request carries the comparison, rather than attaching it by hand.
 - A project whose own established convention already commits that same comparison may route a flagged case's evidence there instead of a separate evidence folder. Only an established convention already committing the same comparison qualifies, not a preference for skipping a second folder.
 - Commit an evidence case for the first time only after running the capture twice with no code change between the runs and confirming the two outputs are byte-identical.
+- Mask the element carrying a value that moves between runs, such as an elapsed-time counter, a clock, or a relative date, in the state's capture case before the double capture, so the check still runs on everything else in the frame. Mask the smallest element holding the value, never the state.
+- Do not commit the state as evidence when the masked outputs still differ, which happens when the value's width reflows its neighbors. Name the variance in the pull request instead, and never re-run toward a match.
 - Recommitting an unbounded sweep on every run reaches a gigabyte of repository history inside a hundred merges. A small, committed evidence set is what a reviewer needs and what lets GitHub draw its own before-and-after comparison on the pull request.
 - `git-pr` and `git-followup` maintain a comparison comment on the pull request automatically once a case is committed, so a reviewer never has to open Files Changed to see it.

package/governance/rules/ui/460-design-taste.md

@@ -11,19 +11,4 @@ paths:
 ## Authority
 
 - Load the `canon:design-taste` skill for which design decision settles first, what must stay constant across a surface, and the defaults to reach past. It is the single source for all three.
-- Load it before drafting, not after revising. A revision recovers a color and never recovers the composition a draft already settled.
 - Report it rather than proceeding silently when the 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.
-- Do not work the layer ordering or the coherence locks from memory.
-
-## When this fires and when it does not
-
-- This rule scopes to the files where an undecided visual choice lands, which is the stylesheet and the design document. Building a surface somebody already decided is implementation rather than design, and the rules below carry what implementation owes.
-- Load the skill by name when a component edit makes a visual choice nobody has taken yet, such as a new section's shape, a spacing relationship, or a radius. The glob cannot see that intent and no glob can.
-- Do not load it to ship a decided design. A worker wiring a picked composition pays the read and gets nothing back.
-
-## Boundaries
-
-- Accessibility, keyboard interaction and ARIA are a separate topic. `410-a11y` routes them, on every rendered path.
-- States, empty and loading coverage, and destructive confirmation are a separate topic. `430-ux-completeness` routes them.
-- Rendered copy casing is a separate topic. `465-interface-casing` routes it. Button labels and error wording are separate too, and `400-ui` routes them.
-- The floor those three carry is not restated in the skill, and it is not traded against a preference where the two collide.

package/package.json

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

package/scripts/core/check-capability-seeding.sh

@@ -60,7 +60,8 @@ check_capability "Hooks" "$PROJECT_ROOT/.claude/hooks" \
   "$PROJECT_ROOT"/tooling/claude/seeds/.claude/hooks/*
 
 check_capability "Workflows" "$PROJECT_ROOT/.github/workflows" \
-  "$PROJECT_ROOT"/tooling/*/configs/.github/workflows/*
+  "$PROJECT_ROOT"/tooling/*/configs/.github/workflows/* \
+  "$PROJECT_ROOT"/tooling/*/seeds/.github/workflows/*
 
 check_capability "Husky" "$PROJECT_ROOT/.husky" \
   "$PROJECT_ROOT"/tooling/base/configs/.husky/*
@@ -90,7 +91,8 @@ check_orphans() {
 check_orphans "Hooks" "$PROJECT_ROOT/.claude/hooks" \
   "$PROJECT_ROOT/tooling/claude/seeds/.claude/hooks"
 
-for dir in "$PROJECT_ROOT"/tooling/*/configs/.github/workflows; do
+for dir in "$PROJECT_ROOT"/tooling/*/configs/.github/workflows \
+  "$PROJECT_ROOT"/tooling/*/seeds/.github/workflows; do
   check_orphans "Workflows" "$PROJECT_ROOT/.github/workflows" "$dir"
 done
 

package/src/claude/cases/misc.ts

@@ -36,6 +36,11 @@ export const MISC_CASES: readonly SkillCase[] = [
       "We're about to hit the context limit, write the handoff before we lose state.",
     expect: 'session-compact',
   },
+  {
+    prompt:
+      "I'm moving this session to another machine, write the handoff before I pack it up.",
+    expect: 'session-compact',
+  },
   {
     prompt:
       'I am the orchestrating session and about to compact, so write the board handoff as a session map on the task board.',

package/src/claude/skills-audit.ts

@@ -1,6 +1,7 @@
 import { existsSync } from 'node:fs'
 import { dirname, join } from 'node:path'
 import { parseFrontmatter, readField } from '@/indexes/frontmatter'
+import { bodyLines, maskDisplayed } from '@/markdown/scan'
 
 /** Returned when a skill folder carries no `REQUIREMENT.md`, the gating check. */
 export const EXIT_MISSING_REQUIREMENT = 2
@@ -33,6 +34,14 @@ const KEBAB_CASE = /^[a-z0-9]+(?:-[a-z0-9]+)*$/
 
 const HEADING = /^#{1,6}\s+(.+?)\s*$/
 
+/**
+ * An ISO date, read as provenance wherever a reader is told it. The context
+ * audit's detector clears a date after "measured" or "verified", and a skill
+ * body keeps no such carve-out, since the standard sends every incident and its
+ * date to the requirement's Gap or to git.
+ */
+const ISO_DATE = /\b\d{4}-\d{2}-\d{2}\b/g
+
 export interface SkillFinding {
   readonly rel: string
   readonly detail: string
@@ -59,6 +68,7 @@ export interface SkillsAudit {
   readonly nameMismatch: readonly SkillFinding[]
   readonly longDescription: readonly SkillFinding[]
   readonly requirementSections: readonly SkillFinding[]
+  readonly datedProvenance: readonly SkillFinding[]
 }
 
 interface SkillSource {
@@ -69,6 +79,17 @@ interface SkillSource {
   readonly description: string | undefined
   /** Undefined when the folder carries no `REQUIREMENT.md` at all. */
   readonly requirementHeadings: readonly string[] | undefined
+  /**
+   * `SKILL.md` and every reference below the folder, keyed by the path a
+   * finding names. `REQUIREMENT.md` and `EVAL.md` are left out, since the
+   * requirement is where the standard sends a date.
+   */
+  readonly bodies: readonly SkillText[]
+}
+
+interface SkillText {
+  readonly rel: string
+  readonly text: string
 }
 
 /**
@@ -110,6 +131,9 @@ export async function auditSkills(root: string): Promise<SkillsAudit> {
     nameMismatch: sources.flatMap(nameFindings),
     longDescription: sources.flatMap(lengthFindings),
     requirementSections: sources.flatMap(sectionFindings),
+    datedProvenance: sources.flatMap((source) =>
+      source.bodies.flatMap(dateFindings),
+    ),
   }
 }
 
@@ -138,23 +162,41 @@ async function readSkill(
   const skillDir = join(dir, folder)
   const requirementPath = join(skillDir, 'REQUIREMENT.md')
 
-  const [body, requirement] = await Promise.all([
+  const references = [
+    ...new Bun.Glob('references/**/*.md').scanSync({
+      cwd: skillDir,
+      onlyFiles: true,
+    }),
+  ].sort()
+
+  const [body, requirement, referenceTexts] = await Promise.all([
     Bun.file(join(skillDir, 'SKILL.md')).text(),
     existsSync(requirementPath)
       ? Bun.file(requirementPath).text()
       : Promise.resolve(undefined),
+    Promise.all(
+      references.map((path) => Bun.file(join(skillDir, path)).text()),
+    ),
   ])
 
   const fields = parseFrontmatter(body)
+  const skillRel = join(rel, folder)
 
   return {
-    rel: join(rel, folder),
+    rel: skillRel,
     folder,
     hasReadme: existsSync(join(skillDir, 'README.md')),
     name: declared(readField(fields, 'name')),
     description: declared(readField(fields, 'description')),
     requirementHeadings:
       requirement === undefined ? undefined : headings(requirement),
+    bodies: [
+      { rel: join(skillRel, 'SKILL.md'), text: body },
+      ...references.map((path, index) => ({
+        rel: join(skillRel, path),
+        text: referenceTexts[index] ?? '',
+      })),
+    ],
   }
 }
 
@@ -209,3 +251,18 @@ function sectionFindings(source: SkillSource): SkillFinding[] {
     },
   ]
 }
+
+/**
+ * A date inside a fence or a code span is example data a reader is shown, such
+ * as a sample frontmatter block, so only prose outside both is read.
+ */
+function dateFindings(source: SkillText): SkillFinding[] {
+  return bodyLines(source.text)
+    .filter((line) => !line.fenced)
+    .flatMap((line) =>
+      [...maskDisplayed(line.text).matchAll(ISO_DATE)].map((match) => ({
+        rel: source.rel,
+        detail: `line ${line.number}: ${match[0]}`,
+      })),
+    )
+}