@erclx/canon 4.0.0

package/claude/skills/migration-standards-drop/SKILL.md

@@ -0,0 +1,113 @@
+---
+name: migration-standards-drop
+description: Proposes the ordered drop of an installed `.claude/standards/` tree and the repoint of every citation at `canon standards <name>`, separating a toolkit copy from a file the project wrote and naming any runtime reader before a delete is proposed. Use when asked to "drop the standards tree", "repoint the standards citations", "my project still has .claude/standards/", or when a toolkit update leaves an installed standards copy no command refreshes. Do NOT delete the tree, run the sync, or rewrite a citation. Proposal only.
+---
+
+# Migration standards drop
+
+## Guards
+
+- If `.claude/` does not exist at `pwd`, stop: `❌ No .claude/ directory. Nothing here installed a standards tree.`
+- If `.claude/standards/` holds no markdown, that is the pass: `✅ No installed standards tree. Nothing to drop.`
+- If `canon` is not on `PATH`, stop: `❌ canon is not on PATH. Every citation this move writes names a verb the target has to run.`
+
+Detection is the directory read above and nothing else. No report names this tree, since the sync engine registers governance alone and the unmigrated scan covers a root layout an older toolkit wrote rather than a copy under `.claude/`. A session waiting for a command to raise the tree waits forever.
+
+## Step 1: read the version the sync would run from
+
+Run `canon sync --check . --json` and read its `skew` object. The sync in Step 5 installs the rules the running binary carries, so a binary predating the citation change installs rules naming the path this move removes, and the sweep then has more to fix than it started with.
+
+- `state` is `behind`: stop. `❌ The canon on PATH is <installed> against <latest> published. A gov sync from it installs rules citing the standards path. Update, then re-run.`
+- `state` is `unknown`: report the reason and continue. A version that could not be read is unread rather than stale.
+- `state` is `current`: continue.
+
+## Step 2: split the tree three ways
+
+Run `canon standards list --json`. Each entry carries `name` and `content`, so the comparison needs no second read. Match every `.claude/standards/<stem>.md` against `name`:
+
+- **Matched, content identical.** A toolkit copy the corpus still carries unchanged. The drop loses nothing.
+- **Matched, content differs.** A toolkit copy that has drifted, and the diff cannot say which side moved. Report it as a read the user owes rather than sorting it either way. All 20 files measured at one target on 2026-08-28 read as changed, because the corpus had moved on since the install, and none of them was project-authored.
+- **Unmatched.** No standard resolves under that name. Either the project wrote the file or the toolkit retired the name, and the catalog cannot separate the two.
+
+Report a project-authored file as one this move keeps. Its destination is `standards/<name>.md` at the project root, which `canon standards <name>` resolves ahead of the package corpus, so the citation form Step 4 gives every other file serves it too.
+
+`prose` is the recorded retirement. It split into `markdown.md` plus the `write-human` skill and resolves as no standard at all, so a citation repointed one-to-one from it names nothing. Report an unmatched name as the user's to place and name that split as the instance.
+
+## Step 3: name every runtime reader before naming a delete
+
+Run both from the project root, in parallel:
+
+- `git grep -ln 'claude/standards' -- '*.md'`: the citations Step 4 repoints
+- `git grep -ln 'claude/standards' -- . ':!*.md'`: the readers
+
+The extension is the split. Markdown cites the tree and a session reads the citation. A hook, a script, or a config opens a file under it at run time, and dropping the tree under one leaves a check whose input is gone reporting success. Two of the five targets in the 2026-08-28 census carried a reader, one of them a hook hand-parsing a standard for a banned-word set.
+
+Report each reader with what replaces it. A reader parsing a standard for a list the CLI now ships reads that list through the verb instead, which is `canon markdown audit <file> --json` for the banned-word case.
+
+When `pwd` is not a git work tree, say the reader search did not run rather than reporting no reader.
+
+## Step 4: give every citation one target
+
+Every citation repoints to `canon standards <name>`, whatever surface it sits on. One form rather than a choice per surface, which is the part a session gets wrong:
+
+- A rule under `.claude/rules/` is markdown a glob match loads, so `${CLAUDE_SKILL_DIR}` expands to nothing there
+- A project-local skill under `.claude/skills/<name>/` expands that variable to its own folder, so `${CLAUDE_SKILL_DIR}/../../standards/` resolves back into the tree being dropped
+- `CLAUDE.md` and a context entry expand no variable at all
+
+The plugin-root form belongs to a skill the toolkit ships beside its own corpus. Proposing it inside a target writes a path that resolves to the deleted tree.
+
+A citation naming a name Step 2 left unmatched carries no target. Report it under what the user supplies.
+
+## Step 5: output the ordered proposal
+
+The order is fixed and the reverse is the failure. Deleting before the sync lands the installed rules citing a path that is gone, and sweeping before the sync repoints citations the sync then rewrites. The sweep re-reads after the sync for that reason, since the sync fixes the rules it installed and leaves a project's own rules and prose alone.
+
+Take the drop command from whether the tree is tracked, read with `git ls-files .claude/standards`. A tracked tree goes out through `git rm -r` so the index moves with the files, and an untracked one through `rm -rf`. A tree holding both needs both commands, since `git rm -r` takes the tracked files, exits zero, and leaves every untracked one where it was.
+
+Print the blocks below, omitting any that is empty.
+
+````markdown
+## Drop
+
+`.claude/standards/` holds <n> files: <n> unchanged toolkit copies, <n> drifted, <n> matching no standard.
+
+## Read before dropping
+
+- `.claude/standards/<name>.md` drifted from the corpus copy. Confirm the project did not edit it.
+
+## Keep
+
+- `.claude/standards/<name>.md` matches no standard. Move it to `standards/<name>.md` at the project root, which `canon standards <name>` resolves first.
+
+## Runtime readers
+
+- `.claude/hooks/<file>.sh` parses a standard at run time. Route it through `canon markdown audit <file> --json` before the drop, or it reports a clean run having read nothing.
+
+## Citations to repoint
+
+- `CLAUDE.md:42` → `canon standards markdown`
+- `.claude/rules/core/<n>-<slug>.md:8` → `canon standards skill`
+
+## You supply
+
+- The destination for the `prose` citations. It split into `markdown.md` plus the `write-human` skill, so no single name replaces it.
+
+## Run in this order
+
+```bash
+canon gov sync
+git rm -r .claude/standards
+```
+
+Then re-read the citations and repoint what the sync left.
+
+## Confirm
+
+Run `canon standards <name>` from inside this project for every name the repointed citations carry, and confirm each resolves.
+
+## Reminder
+
+Nothing above was written or run. The tree holds files a delete cannot recover, so the drop and the sweep are yours to apply.
+````
+
+Run nothing and write nothing: not the sync, not a delete or a move under `.claude/standards/`, not a citation rewrite. The install stamp is out of scope too, and travels with whatever else reaches this target. The user applies the move after reviewing it.

package/claude/skills/migration-superseded/REQUIREMENT.md

@@ -0,0 +1,44 @@
+---
+name: migration-superseded
+description: Why a retired file's split ships as a proposal read from the destination standard, and why detection stops rather than falling back to a listing
+---
+
+# Migration superseded requirement
+
+## Gap
+
+Without this skill, a target holding a retired `.claude/` file is told what replaced it and nothing else. The drift report names both halves and no command touches either, so the user hand-splits one file into a folder answering to a standard they have not read. The destination files land with frontmatter fields missing and filenames that sort out of order, which is the step the toolkit exists to remove.
+
+A second failure comes from the ordering nobody gets right unaided. A retired file committed before its ignore entry was written is tracked and ignored at once, and removing the entry first leaves the file tracked with nothing naming it. No report catches that state, so the mistake is discovered by whoever next wonders why a gitignored path keeps appearing in diffs.
+
+Two more follow from where a session looks when the report is thin. An uppercase stem under `.claude/` is not the test for a superseded file, so a session substituting a folder listing reaches `ARCHITECTURE.md`, `REQUIREMENTS.md`, and `DESIGN.md`, each a single file the layout intends to stay one, and proposes shredding three documents. A session falling back to the plugin's own copy of the destination standard proposes a shape the project never adopted, against content only the user can place.
+
+The last is the two-speed release skew arriving as a confident wrong answer. `superseded` reached a release in `0.46.0`, and an older CLI exits zero with a well-formed report that never mentions the field. A session reading that absent key as an empty array reports a clean layout to exactly the population holding the retired files.
+
+## Must
+
+- Take detection from the report's `superseded` array alone, and stop when the key is absent rather than treating it as empty
+- Resolve the governing standard by matching the replacement folder against the `appliesTo` the standards catalog declares, so a seed folder added later resolves without an edit to the body
+- Read the destination shape with `canon standards <name>`, report the root it answered from, and propose nothing for a folder the catalog names no standard for
+- Separate a folder no standard governs from one whose governing standard could not be read, since the catalog derives `appliesTo` from prose and answers an unparsed scope statement with an empty array
+- Name the untrack command ahead of the ignore entry whenever a retired file is both tracked and ignored, and say when the check could not run
+- Report what the destination standard leaves open, such as a phase label the retired file never recorded, rather than supplying a value for it
+- Report the measured empty case as a pass, since the guard is what proves the section ran
+
+## Must not
+
+- Write, move, or delete the retired file or its replacement, or create the destination folder
+- Run `git rm --cached` or edit the file carrying the ignore entry
+- Substitute a folder listing for the `superseded` array
+- Read the plugin's own copy of the destination standard when the target lacks that file
+
+## Guards
+
+- A directory with no `.claude/` stops, since nothing there was superseded and the report's sections would not be measured
+
+## Out of scope
+
+- Classifying `CLAUDE.md` sections into the three-tier model: `migration-claude-md`
+- Relocating `docs/` files by audience: `migration-context`
+- Reconciling a seed file against its source section by section, which diffs two files rather than splitting one into a folder: `claude-seed-sync`
+- Applying the split and running the untrack, which the user does after reviewing

package/claude/skills/migration-superseded/SKILL.md

@@ -0,0 +1,115 @@
+---
+name: migration-superseded
+description: Proposes how to split a retired `.claude/` file into the folder that replaced it, reading the destination shape from the standard that folder answers to. Use when asked to "split TASKS.md", "my .claude/DIAGRAMS.md was replaced by a folder", "migrate the superseded file", or after a drift report names a superseded artifact. Do NOT write to the retired file or to its replacement, and do NOT run the untrack command. Proposal only.
+---
+
+# Migration superseded
+
+## Guards
+
+- If `.claude/` does not exist at `pwd`, stop: `❌ No .claude/ directory. Nothing here was superseded.`
+
+The guard is also what makes the report's `superseded` section measured. Every section is gated on the target being toolkit-managed, and a `.claude/` directory satisfies that gate, so the empty case below is a measured empty rather than a section that never ran.
+
+## Step 1: read the report
+
+Run `canon sync --check . --json` from the project root. Its `superseded` array is the detection. Each entry carries `rel`, the retired file, and `replacedBy`, the folder that took its job.
+
+An empty array is the pass: `✅ No superseded artifact. Every .claude/ file the seeds replaced is already a folder.`
+
+### When the report is unavailable
+
+Stop on any of three conditions, naming which one fired:
+
+- `canon` is not on `PATH`: `❌ canon is not on PATH. The superseded section is the only detection this skill has.`
+- The command exits non-zero: `❌ canon sync --check failed. Fix the report before proposing a split.`
+- The report parses and carries no `superseded` key at all: `❌ This canon predates the superseded field, which reached a release in 0.46.0. Upgrade, then re-run.`
+
+Test for the key rather than for emptiness. A current CLI reporting `"superseded": []` has looked and found nothing, which is the pass above, and reading an absent key as an empty answer reports a clean layout to the projects this skill exists for.
+
+No listing substitutes for the field. The pairing runs against the seed folder names the toolkit ships, and an uppercase stem is not the test, so a listing of `.claude/*.md` also reaches `ARCHITECTURE.md`, `REQUIREMENTS.md`, and `DESIGN.md`. Each of those is a single file the layout intends to stay one. A fallback that proposed splitting them would shred three documents to avoid reporting a stale CLI, which is why this skill stops where its siblings degrade.
+
+## Step 2: resolve the destination standard
+
+### Match the folder against the catalog
+
+Run `canon standards list --json` and match each entry's `replacedBy` against the `appliesTo` array the catalog declares. Resolve from the catalog rather than from the folder stem, so a seed folder the toolkit adds later resolves without an edit here.
+
+Compare on the folder rather than on the exact string. An `appliesTo` value matches when it equals `replacedBy` or begins with `replacedBy` followed by a slash. The report spells the folder `.claude/tasks` and the catalog spells it `.claude/tasks/`, and `memory` declares a filename pattern beneath its folder rather than the folder itself, so string equality matches nothing the catalog actually carries and sends every entry to a decline below.
+
+### Read the standard through the verb
+
+A match resolves to that standard's `name`. Read it with `canon standards <name>`, which writes the document to stdout and the root it answered from to stderr.
+
+The verb is the one route. It resolves `standards/<name>.md` at the project root first, which is where a project that authors standards of its own keeps them, and falls back to the corpus inside the canon package. No toolkit standard installs into a project, so there is no third path to test and no case where the shape is unreachable while the catalog names it.
+
+Report the root the frame named beside the proposal. A shape read from the project's own `standards/` is the project's stated agreement, and one read from the package is the toolkit's default, which is a difference the user weighs rather than a reason to refuse.
+
+### The states that end an entry
+
+Four states end an entry with no proposal. Name whichever one fired rather than collapsing them, because two of them are unmeasured and two are answers:
+
+- The catalog carries no `appliesTo` key: `⚠️ This canon emits no appliesTo, so which standard governs <replacedBy> is unread.`
+- No value covers `replacedBy` and some entry carries an empty `appliesTo`: an empty array is a scope statement that did not parse, so a no-match verdict is unread rather than negative. Name the standards that did not parse.
+- No value covers `replacedBy` and every array is populated: `⚠️ The toolkit ships no standard for <replacedBy>. Nothing states the destination shape.` No command fixes it, so name none.
+- The standard resolved in the catalog and `canon standards <name>` exits non-zero: name the standard and the exit, since the catalog and the read disagree and only one of them can be right.
+
+## Step 3: read the shape and map the file onto it
+
+Read the resolved standard and take four things from it: the filename convention, the required frontmatter, the required sections, and anything the folder holds that is not an item, such as a generated `index.md` no proposal may claim.
+
+Then read the retired file and split it at the boundary the standard implies, one destination file per item. Propose a filename per item from the convention, and name the frontmatter and sections each destination file owes.
+
+Report what the standard leaves open rather than inventing a value for it. A convention carrying a field the retired file never recorded, such as a phase label or a verified SHA, is the user's to supply, and a proposal that fills one in reads as a decision the split already made.
+
+## Step 4: check the ignore ordering
+
+Run both against each `rel`, in parallel:
+
+- `git ls-files --error-unmatch <rel> 2>/dev/null`: whether the file is tracked
+- `git check-ignore -v --no-index <rel> 2>/dev/null`: whether it is ignored, and which file and line names it
+
+`--no-index` is what makes the second read answer the question. `git check-ignore` consults the index by default and reports a tracked path as not ignored, so the flagless form returns nothing in exactly the tracked-while-ignored state this step exists to find, and the run reads a clean result off the one case that is not clean.
+
+A file that is both tracked and ignored carries an ignore entry added after the commit. Take it out of the index first, then remove the entry `check-ignore` named:
+
+```bash
+git rm --cached <rel>
+```
+
+Reversing the two leaves the file tracked with nothing naming it, and no report catches that state. Name both steps in that order and run neither. `git rm --cached` writes the index, which is a change to the project's own history even though no content moves.
+
+When `pwd` is not a git work tree, say the tracked check did not run rather than reporting the ordering as clear.
+
+## Step 5: output
+
+Print one block per superseded entry, then the shared reminder. Omit empty groups.
+
+```markdown
+## Split
+
+`.claude/TASKS.md` → `.claude/tasks/`, shaped by `canon standards tasks`
+
+## Proposed files
+
+- `.claude/tasks/vXX.Y-<slug>.md` ← the "<heading>" section
+- `.claude/tasks/vXX.Y-<slug>.md` ← the "<heading>" section
+
+Each carries `title` and `description` frontmatter, an `## Outcomes` heading, and a `## Findings` heading.
+
+## You supply
+
+- The phase label on each filename. The retired file records no version.
+
+## Untrack before editing the ignore entry
+
+git rm --cached .claude/TASKS.md
+
+Then remove the `.claude/TASKS.md` line from `.gitignore:12`.
+
+## Reminder
+
+Nothing above was written or run. The retired file holds content the project authored, so the split is yours to apply and the destination folder shape is what this proposal supplies.
+```
+
+Do not create the destination folder. Do not write, move, or delete the retired file. Do not run `git rm --cached`. The user applies the split after reviewing it.

package/claude/skills/project-commands/REQUIREMENT.md

@@ -0,0 +1,42 @@
+---
+name: project-commands
+description: Why running a documented command stops at the report, and what a single-file read buys over framework inference
+---
+
+# Project commands requirement
+
+## Gap
+
+Without this skill, a session asked to start the app infers a command from a framework it recognizes or a script name it likes the look of, and a project whose dev loop differs from the convention gets the convention anyway. The user cannot see it was a guess, because a guess and a read produce the same first line.
+
+The larger failure is the one past the launch. A session that starts a server keeps going into log reading, browser checks, and defects it noticed on the way, so a request that was one command becomes an open-ended investigation nobody asked for and the answer arrives buried. A request covering a frontend and a backend gets one of the two, which reports success on half an app.
+
+Two more failures are mechanical. A command that stays up run in the foreground blocks until the tool timeout, which reports as a service that never came up while nothing is left running. And a command whose effect outlives the process, such as a deploy or a migration, is not undone by stopping it, so running it to see what happens is not available.
+
+## Must
+
+- Read the documented dev loop and treat it as the only source, since a second file is a discovery chain and this skill has none
+- Match the request against the stated purpose rather than the command name, since a project documenting two similar commands means the distinction
+- Resolve every documented command the request covers, not the first one that matches
+- Background a command that stays up, and read its output back before checking anything against it
+- Report the port, URL, or exit status per command, then end the turn
+
+## Must not
+
+- Infer a command from a filename, a framework, or a second file
+- Stop, restart, or reconfigure a process the skill did not start, or tear down one it did
+- Continue past the report into a second check, a screenshot, or a defect report. Say in one line that one looks warranted and let the user decide.
+- Abandon the remaining commands when one fails
+
+## Guards
+
+- No documented dev loop stops by naming the missing file, since a reconstruction the user cannot see through is worse than a stop
+- A request matching nothing documented lists what is documented instead of inferring
+- A command whose effect outlives the process prints for the user to run rather than running, judged on the effect rather than the name
+
+## Out of scope
+
+- Confirming a change works in the running app, which is a verification request and needs the steps this skill refuses
+- Deploying, publishing, releasing, migrating, and resetting
+- Running the scaffold verification chain against `package.json` scripts: `setup-verify`
+- Writing the entry it reads, which belongs to the project's own development docs

package/claude/skills/project-commands/SKILL.md

@@ -0,0 +1,85 @@
+---
+name: project-commands
+description: Runs a command the project documents in its development context entry and stops there. Use when asked to "start the app", "start the dev server", "run the checks", "run the build", "spin it up", or "what commands does this project have". Do NOT use to confirm a change works in a running app, which needs verification past the launch. Do NOT use to deploy, publish, or release.
+---
+
+# Project commands
+
+Read the project's development context entry, run the command the user named, report where it landed, and stop.
+
+The value is the stop. A launch that continues into log inspection, browser checks, or unrelated defects is the failure this skill exists to avoid.
+
+## Guards
+
+- Resolve the entry before anything else. Take the flat `development.md` under `.claude/context/` when it exists, and `.claude/context/development/overview.md` when the domain outgrew one file and split into a folder, which is where the `## Scripts` table lands in a split. Test both paths, then read one. If neither resolves, stop with the line below and let the user decide.
+- If the entry documents no command matching the request, stop and list what it does document. Do not infer a command from a filename or a framework.
+- If the resolved command has an effect that outlives the process and stopping it does not undo, print it for the user to run and stop. Deploying, publishing, releasing, migrating, and resetting are the common shapes, and the test is the effect rather than the name. A script called `infra:apply` or `promote` qualifies.
+
+Do not read another file to reconstruct an entry that did not resolve, because a guess is worse than a stop when the user cannot see it was a guess.
+
+The stop names the flat path in both cases, since a project carrying neither has no entry to point at and the flat one is where a project without a split keeps it:
+
+```plaintext
+❌ No .claude/context/development.md. This project has no documented dev loop.
+```
+
+## Step 1: read the entry
+
+Read the path the guard resolved, from the project root, the whole entry rather than a named section. That file and no others. A second file is a discovery chain, and this skill has none. Testing two candidate paths is not one, since the test happens before any read and exactly one file is opened.
+
+A split domain keeps its other sub-area files out of reach on purpose. `overview.md` carries the run commands, and the siblings beside it cover verification stages, hooks, and scratch, none of which this skill runs.
+
+## Step 2: resolve the command
+
+Match the request against what the entry documents, reading the stated purpose and not only the command name. A project that documents two similar commands separately means the distinction, and the purpose column is where it says which is which.
+
+When the request maps to more than one documented command, resolve all of them. A project that starts as a frontend and a backend has two rows in the table and one request covering both, and running one of the two reports success on half an app.
+
+State the resolved command before running it. One line, no rationale.
+
+## Step 3: run it
+
+Run each resolved command as the entry writes it, from the project root. When a command only works from a subdirectory, the entry has to say so, since the table gives the skill nothing else to go on.
+
+A command that terminates runs in the foreground. A command that stays up runs in the background, by setting the Bash tool's `run_in_background` parameter on the call. Nothing backgrounds a process on its own, and a foreground dev server blocks until the tool timeout kills it, which reports as a command that never came up and leaves nothing running.
+
+Decide from what the entry says the command does, not from its name. When the entry does not say, treat a server, watcher, or preview as staying up.
+
+- Read a backgrounded command's output back before checking anything against it. The call that starts it returns immediately and carries no port.
+- Report the port or URL each command prints, and the log location when one exists
+- Confirm a service came up with one check against what it reports listening on
+- Leave a process the skill did not start alone. Never stop, restart, or reconfigure one.
+- Do not tear down what the skill started. A session that starts a server and stops it has not done what was asked.
+
+If a command fails or never comes up, report the failure and the last output. Do not retry with a different command, and do not abandon the others.
+
+An exit status here is part of the report rather than the basis for one. Step 3 confirms a service came up against what it printed, so the number is passed through to the reader and decides nothing. A documented command reaching `canon` is the case worth naming, since an operator's shell profile may wrap the binary in a function that takes its status from a later command, and judging that run by its exit would call a refusal a success.
+
+## Step 4: stop
+
+Report and end the turn. Specifically do not:
+
+- Run a second check after the first one passed
+- Read the startup log for anything beyond a failure
+- Open a browser, take a screenshot, or drive the running app
+- Report a defect noticed while starting up, however real
+
+Those belong to a verification request, which is a different ask. When one of them looks warranted, say so in one line and let the user decide.
+
+## Output
+
+```plaintext
+▶️ <resolved command>
+
+<what it reported: port, URL, or exit status>
+```
+
+One block per command when the request resolved to more than one.
+
+For a request with no command to run, list what the entry documents instead:
+
+```plaintext
+📋 Documented in <the entry path the guard resolved>
+
+- `<command>`: <purpose as the entry states it>
+```

package/claude/skills/restate-plainly/REQUIREMENT.md

@@ -0,0 +1,41 @@
+---
+name: restate-plainly
+description: Why a plain restatement is asked for by name, and where its boundary sits against the skill that drafts and the command that measures
+---
+
+# Restate plainly requirement
+
+## Gap
+
+Without this skill, a reader who cannot follow a dense answer has to ask for it again in ordinary words, and the second answer is drafted by the same session that produced the first. Nothing tells that session which half of its own text carried the decision, so the rewrite shortens the passage and keeps the abstraction that made it hard to read.
+
+The corpus around it covers the neighboring jobs and not this one. `write-human` governs a passage being drafted or revised and arrives on a markdown edit, so it never sees an answer in chat and never reaches a document nobody is editing. `canon markdown audit` reports sentence spread and repeated openings against a stated range, which measures how a passage moves and says nothing about whether a reader can act on it.
+
+A restatement also fails in a way a rewrite does not. A run that compresses by dropping what supports a claim leaves a reader who acts on the plain version and meets a different answer in the source, and that failure is invisible in the restatement itself.
+
+## Must
+
+- Take a named markdown path or the preceding answer, resolving the path first, since a reader pointing at a file has already said which one they mean
+- Keep every point that changes a decision and cut what only supports one, which is the split that separates a restatement from a summary
+- Preserve a hedge the source carries, since dropping it manufactures a certainty
+- Cite the carrier of the rhythm and density rules rather than restating them, because a second copy drifts with nothing comparing the two
+- Fire on an explicit request and refuse the model's own judgment about its own output
+
+## Must not
+
+- Write a file. A restatement is read once to reach a decision, and a file makes a record nobody opens twice.
+- Add a fact, number, or name the source does not carry
+- Restate the voice, rhythm, or density rules, which live in the skill this body cites
+- Claim the restatement is verified. Nothing checks whether a plain version kept the deciding half, so the sandbox arm asserts what the run did rather than that the output is good.
+
+## Guards
+
+- A named path that does not resolve stops the run rather than falling back to the preceding answer, since the two inputs are different requests
+- A request with no path and nothing preceding it stops rather than restating the request itself
+
+## Out of scope
+
+- Drafting or revising a passage, which is `write-human` on a markdown edit
+- Measuring cadence in finished output, which `canon markdown audit` reports from package data
+- Rewriting a document into a file, which is a proposal against the source rather than a restatement of it
+- The banned words, characters, and spellings, which `markdown.md` states and the audit gates

package/claude/skills/restate-plainly/SKILL.md

@@ -0,0 +1,39 @@
+---
+name: restate-plainly
+description: Restates a dense answer or a named markdown document in plain language, cutting jargon and keeping only what changes a decision. Use when asked to "restate that in plain language", "say that plainly", "what does this actually mean", "cut the jargon", "give me the plain version", or "restate this document". Do NOT use to draft or revise prose, which is `write-human`, and do NOT fire on the model's own judgment that its own output was dense.
+---
+
+# Restate plainly
+
+Return the plain version of something already written. The reader asked because they stopped to decode rather than to decide, so the restatement earns its place by getting them to the decision.
+
+## What to restate
+
+- Restate the file when the request names a markdown path, and the preceding answer in the conversation when it names none. A named path wins over an answer sitting in the same turn.
+- Stop when the request names a path that does not resolve: `❌ No file at <path>. Name a path that exists, or ask for the preceding answer instead.`
+- Stop when nothing precedes the request and no path is named: `❌ Nothing to restate. Name a markdown path, or ask right after the answer you want in plain words.`
+- Refuse a request to restate output on the model's own initiative. A person asks for this by name.
+
+## What survives
+
+- Keep every point that changes a decision, and cut every point that only supports one. A reader who acts on the restatement and is surprised by the original has been given the wrong half.
+- Name the thing the source names. Replace a term of art with its plain equivalent, and keep the term where the reader has to search for it later.
+- Say what is uncertain where the source hedges, and say it plainly. Dropping a hedge invents a certainty the source does not carry.
+- Introduce no fact, number, or name the source lacks. A restatement changes wording and never claims.
+- Report the reasoning, not the metaphor. An abstraction standing in for a mechanism is what made the source dense.
+
+## How it reads
+
+Load the `write-human` skill before writing the restatement. Compression is where a plain version turns into a list of verbless fragments, and that skill states the rhythm and density rules this one does not copy.
+
+## Output
+
+Answer in chat. Write no file, since a restatement is read once to reach a decision.
+
+Lead with the plain version in prose. Close with one line naming what was cut and why, so the reader can go back for it:
+
+```plaintext
+Cut: <what left, and why it changes no decision>
+```
+
+Name the source path on its own line when the restatement came from a file.

package/claude/skills/session-map/REQUIREMENT.md

@@ -0,0 +1,57 @@
+---
+name: session-map
+description: Why the write procedure needs a route any session can take, why the door carries the drift step and its ref recovery, and why it states none of the shape the standard already fixes
+---
+
+# Session map requirement
+
+## Gap
+
+Without this skill, the standard governing the pre-compaction handoff carries a complete numbered write procedure and nothing routes a session to it. The reading half already works, since the resume path opens the newest map and leads its report with it, so a file nobody is routed to write is read by a surface built to find it.
+
+The only routed writer belongs to the orchestrator role. It disables model invocation, asserts that role on invocation, and adds a section for decisions taken under delegated authority, so a plain feature session that reaches it receives a section it cannot fill and a review poll it does not run.
+
+The nearest description by wording writes a different artifact. Capture routes facts to a context entry and writes memory files, and a request naming the session and the moment matches it, so the map goes unwritten while a session believes it has handed off.
+
+The drift step is the one most specific to session length and the easiest to skip. It reads the commit the session started from, nothing on the machine records that commit, and a route that names the step without naming how to recover the ref ships an instruction nobody can follow.
+
+A step that reads a surface a project may not carry gets skipped on the reasoning that it has nothing to act on. A cold session run against a project with no `.claude/` tree skipped both the capture and the drift step and wrote its own rationale into the map, so the step the route exists to carry did not run on the first test from outside. The skip is worst where it looks most defensible, and a session that takes it quietly leaves a map indistinguishable from a conforming one.
+
+A capture fired the same way for every caller breaks the one caller the split leaves. An orchestrating session may write no tracked file, so its capture has to skip routing, and a route offering no way to say so leaves that reader running capture twice or routing facts the role forbids it to fold.
+
+A body that restates the sections, the frontmatter, or the numbered steps becomes a second source that drifts from the standard, which is the failure the split between the role writer and the core was made to remove rather than move.
+
+## Must
+
+- Write from any session whatever role it holds, without asserting one
+- Cite the standard for the filename, the frontmatter, the sections, the numbered procedure, and the citation rule rather than restating any of them
+- Run the drift step and state how to recover the ref it reads from how long the session has run
+- Record what the drift verb names, and read a refusal as the boundary of what the verb can read
+- Resolve the folder at the main worktree root, and write the file whole from the shell where the editing tools refuse that root
+- Fall back to the branchless filename on an empty slug rather than stopping
+- Leave model invocation enabled, so a session that has dropped its routing still reaches this by description
+- Take a caller's statement that the session does not commit and pass it to capture, so no fact this route fires is routed into a tracked file
+- Report the map alone, plus the line capture returns when a fact routed, since a fold left unreported is a fold nobody runs
+
+## Must not
+
+- Restate the standard's sections, frontmatter, or numbered steps
+- Skip a step by predicting what its skill or verb would have answered, rather than running it and recording what came back
+- Assert a role, or add a role's section to a map written by a session holding no such role
+- Fold the capture step's output into this skill's report
+- Take the worktree-local copy the editing tools offer in place of the main-root path
+- Summarize the board, the task files, or the work that shipped, each of which is carried by an artifact a compaction leaves standing
+
+## Guards
+
+- Not a git repository: stop, since the filename comes from the branch
+- Empty slug: fall back rather than stop, since the reasoning is worth more than the name
+- The drift verb refusing: record the boundary under standing cautions and keep writing
+
+## Out of scope
+
+- Reading a handoff back at the start of the next session: `session-resume`
+- Routing a session fact to the context entry that owns it, and writing what no entry owns to the memory folder: `claude-memory-capture`
+- The sections a role adds over the core three, which belong to that role's own surface. `claude-orchestrate` owns the orchestrator's and cites this route for the generic half.
+- Validating a written map against the standard, which no record kind covers, so a conforming shape rests on the standard being followed
+- Firing the write without being asked, which is a question about what the harness supports and is measured on its own track

package/claude/skills/session-map/SKILL.md

@@ -0,0 +1,70 @@
+---
+name: session-map
+description: Writes the session map, the pre-compaction handoff at `.claude/tasks/session-<slug>.md`, from any session whatever role it holds, running the skill-drift step the write procedure opens with. Use when asked to "write the handoff", "write the session map", "save the session before it compacts", "we are about to compact", "hand off to the next session", or "leave a note for whoever picks this up". Do NOT use to route session facts to a context entry or the memory folder, which is `claude-memory-capture` and writes a different artifact, and do NOT use to read a handoff back, which is `session-resume`.
+---
+
+# Session map
+
+Write the pre-compaction handoff for the current session. `${CLAUDE_SKILL_DIR}/../../standards/session.md` fixes the filename, the frontmatter, the three core sections, the numbered write procedure, and the citation rule. Follow that document rather than this body, which states when the procedure runs and what it runs against and leaves the shape where it already lives.
+
+Any session writes one. Do not assert a role on invocation, and do not add a role's sections to a map written by a session holding no such role.
+
+Run every step rather than judging in advance that one has nothing to act on. The capture skill and the drift verb each answer for themselves, refusal included, and a refusal recorded is a result where a prediction of one is not. A project carrying none of the scaffolding either step reads is the case this fires on, and it is the case where skipping looks most defensible.
+
+## What fires this
+
+Being asked is one route. The other is a `PreCompact` hook registered against the `manual` matcher, which a project may install and which blocks the first `/compact` of a session with a message naming this skill. The block fires once, so the next `/compact` proceeds whether or not a map was written, and an automatic compaction is never blocked. A project that registered no such hook reaches this skill by being asked alone.
+
+Decline where the session holds no reasoning a reader could not get faster from git. Say so in one line and write nothing. The standard already names a `## State` filled from the tree as non-conforming, and the file that carries three such sections is worse than an absent one, because a reader who finds a map trusts it. Declining is a result the caller can act on, where a padded map is a result that misleads.
+
+## Guards
+
+- If `git rev-parse --git-dir` does not resolve, stop: `❌ Not a git repository. A session map takes its filename from the branch.`
+- Derive `<slug>` per `${CLAUDE_SKILL_DIR}/../../standards/slug.md`. An empty result falls back to `latest` rather than stopping, since a handoff is scratch and a stop loses the reasoning the file exists to save.
+- Resolve the containing folder at the main worktree root with `git worktree list --porcelain | grep -m 1 '^worktree ' | cut -d' ' -f2-`. The guard above already stopped where that read has no repository to answer from, so it takes no fallback.
+
+## Step 1: run the capture the procedure opens with
+
+Item 1 of `## Writing one` is a capture. Invoke `canon:claude-memory-capture` and let it return before writing, so the map cites what was written instead of restating the same lesson in prose.
+
+Pass on the caveat a caller states about committing. A caller that does not commit says so, and capture then skips routing and writes memory files alone, since a routed fact lands in a context entry and that is a tracked file. A caller stating nothing leaves capture to decide for itself, which is the ordinary run.
+
+Carry through the line capture returns when a fact routed, so the session knows a fold is still owed. Report nothing else about what it wrote. The map is this skill's output.
+
+## Step 2: recover the commit the drift step reads
+
+Item 2 runs `canon claude skills drift <ref>` against the commit this session started from, and nothing on the machine records that commit. Estimate how long the session has run, round the duration up, and read the ref item 3 recovers:
+
+```bash
+git log -1 --format=%H --before='<duration> ago'
+```
+
+Round up rather than down. A ref older than the oldest load over-reports, and confirming a name it raises costs one read of that body, so the generous end is the safe one.
+
+Record what the verb names under `## Standing cautions`. A refusal is the boundary of what the verb can read rather than a fault, since it answers where the working directory carries `claude/skills/` with history behind it and refuses in a project consuming the plugin from a cache. Record the boundary the verb reported and keep writing, rather than the one it looked likely to report.
+
+## Step 3: write the map
+
+Follow items 4 through 6. Write only what a compaction destroys and no other artifact already carries, and cite a commit, a task, or a file and line for every claim.
+
+The file sits at the main worktree root, which the file-editing tools refuse from inside a linked worktree while offering a copy under that worktree instead. Take neither the refusal nor the copy. The map is written whole every time, so send it out as one plain shell command carrying a heredoc.
+
+## Step 4: extend it only where a role is held
+
+`## Extending it` governs a section added over the core three. Add one only when this session holds the role and the surface owning that role states the section, since a section the writer cannot fill teaches its reader to skip the file. A session holding no role writes the core three and stops.
+
+## Output
+
+```plaintext
+✅ Session map written: .claude/tasks/session-<slug>.md
+<what the drift verb named, or the boundary it refused at>
+```
+
+A decline reports itself rather than falling silent, so a caller can tell it from a run that failed:
+
+```plaintext
+✅ No session map. <what the session holds that git does not, and why it is nothing>
+<what the drift verb named, or the boundary it refused at>
+```
+
+Emit the path from the project root. The `## Output` section of the project's instruction file sets the form it takes.