@erclx/canon 5.31.0 → 5.32.0

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

@@ -1,87 +0,0 @@
----
-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.
-metadata:
-  family: build
----
-
-# 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 `canon/context/` when it exists, and `canon/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 canon/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/repo-metadata/REQUIREMENT.md

@@ -1,37 +0,0 @@
----
-name: repo-metadata
-description: Why an About text nobody re-derives drifts from the README it summarizes, and why writing it stays a second, explicit step
----
-
-# Repo metadata requirement
-
-## Gap
-
-Without this skill, a repository's GitHub About description, homepage, and topics are set once by hand and never checked again. Nothing in either skill corpus reads or writes them, so a README rewrite carries no signal back to the three fields a stranger reads before the README, and they drift silently. That already happened here: the About text disagreed with the README's own opening line, and nobody noticed until someone read both side by side.
-
-A session that fixes this by hand skips the gate a repeatable proposal would have given it. It reads the README once, writes a description from memory, and never records what it compared against or gives anyone else a chance to see the diff before it goes out. The write is also public and immediate: `gh repo edit` changes what every visitor to the repository page sees, with no draft state and no second confirmation from GitHub itself.
-
-## Must
-
-- Compute the proposal from the tree alone, through `canon repo metadata propose`, and report the diff against the remote before any write is discussed
-- Route the choice of which fields to write through the structured question surface, since which field to accept is the operator's preference to decide
-- Run `canon repo metadata apply` only in a turn separate from the one that ran propose, carrying only the fields the operator answered in this conversation
-
-## Must not
-
-- Call apply in the same invocation that ran propose, whatever the operator's request already names
-- Write a field the operator has not answered in this conversation, even when the CLI's own proposal suggested a value for it
-- Read an absent field in the proposal as a suggestion to clear what the remote already carries
-- Edit `README.md` or any repository setting other than description, homepage, and topics
-- Fire from a request with no repository-metadata content, since a skill invoked on a vague signal risks presenting a write path the operator never asked for
-
-## Guards
-
-- No `gh` remote resolves. Stop, naming the refusal `canon repo metadata propose` reports, since a proposal with nothing to compare against is a suggestion nobody asked for.
-- `canon repo metadata propose` or `apply` does not resolve on an older install. Report that rather than proceeding, since the fix without the verb reintroduces the hand-written write this skill exists to gate.
-
-## Out of scope
-
-- Editing the README's own content, which is a request against that file rather than against repository metadata
-- Repository settings outside description, homepage, and topics, such as visibility or branch protection, which carry a different blast radius and no local source to propose from
-- Any repeat run outside a target project's own tree, since the proposal is computed from that tree's README and manifest rather than from this toolkit's shape

package/claude/skills/repo-metadata/SKILL.md

@@ -1,54 +0,0 @@
----
-name: repo-metadata
-description: Proposes a GitHub About description, homepage, and topic set computed from the README's opening line and package.json, reports the difference against what the repository's remote already carries, and stops without writing. A later invocation, carrying the operator's answered fields, writes the change through gh repo edit. Use when asked to "propose repo metadata", "check the github description", "does our github about text match the readme", "sync github topics", "update the repo homepage", or "apply the repo metadata answers". Do NOT use to edit README.md itself, or to change a repository setting other than description, homepage, or topics.
-metadata:
-  family: setup
----
-
-# Repo metadata
-
-Reads what `canon repo metadata propose` computes locally and reports it against the remote. Writing is a separate step: `canon repo metadata apply` never runs in the same invocation that ran propose, whatever the operator answers in the same breath. The gate is the two invocations, not a prompt inside one.
-
-## Guards
-
-- Report it rather than proceeding silently when `canon repo metadata propose` or `canon repo metadata apply` does not resolve. Both ship with the CLI, so a project on an older install meets a missing subcommand rather than a refusal.
-- The propose read refuses when the repository has no remote `gh` can read. Report that refusal verbatim and stop. A proposal with nothing to compare against is a suggestion nobody asked for.
-- Never call apply in the same turn that ran propose, even when the operator's request already names the fields to write. Surface the proposal, get the answer, then run apply as its own step.
-- Never write a field the operator did not confirm in this conversation. A field the proposal computed and the operator has not answered stays unwritten, whatever the CLI's own suggestion for it was.
-- A field absent from the proposal has no local source and is never a suggestion to clear what the remote already carries. Report it as unchanged, not as a removal.
-
-## Propose
-
-1. Run `canon repo metadata propose --json`.
-2. Read `diff` and `repo` from the record. `repo` is the `--repo` value the later apply step must carry. An empty `diff` means the remote already matches what this run computed: report that and stop, since there is nothing to answer.
-3. When `diff` carries a `description` field, compress its proposed value, the raw opening line `canon repo metadata propose` computed, into a single short phrase. Leave the shape and length of the phrase to judgment on each run. No numeric target applies. Keep the raw proposed value beside the compressed phrase in what gets reported, so the operator can check the phrase against the README line it came from.
-4. For each field `diff` carries, put the change to the operator through the structured question surface: which of the differing fields to write. For `description`, the value offered to accept is the compressed phrase from step 3, not the raw line beside it. Rank accepting the proposed value first for a field whose current value is stale or wrong, and give the reject option the cost of leaving the remote as it stands. Never pre-select an answer for the operator.
-5. Report the fields the proposal left absent as unchanged, naming that neither the README nor `package.json` carried a source for them.
-6. Stop. Do not run apply here even when the operator answers immediately, since answering is not yet an apply invocation.
-
-## Apply
-
-1. Confirm every field about to be written was answered by the operator in this conversation. Carry no field forward unanswered. For `description`, the answered value is the compressed phrase Propose offered, never the raw README line reported beside it.
-2. Run `canon repo metadata apply`, always passing `--repo <owner/name>` from the propose record's `repo` field, plus the flags for the answered fields: `--description <text>`, `--homepage <url>`, `--topics <comma-separated list>`. `--topics` is the full desired set, and the command reads the current set itself to compute what to add and remove. The command refuses rather than writing when `--repo` does not match what `--root` resolves to, so never omit it and never guess it from anything but the propose record's `repo` field.
-3. Report the written state from the JSON record.
-
-## Output
-
-Propose:
-
-```plaintext
-📋 Repo metadata proposal
-description: "<current>" → "<compressed>" (derived from the README's opening line: "<raw>")
-homepage: unchanged, no local source
-topics: +<added>, -<removed>
-
-Answer which fields to write, then ask again to apply.
-```
-
-Apply:
-
-```plaintext
-✅ Applied: <fields written>
-```
-
-Omit a line from the proposal block for a field `diff` did not carry.

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

@@ -1,41 +0,0 @@
----
-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 characters, which `markdown.md` states and the audit gates

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

@@ -1,41 +0,0 @@
----
-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.
-metadata:
-  family: answer
----
-
-# 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/review-branch/REQUIREMENT.md

@@ -1,40 +0,0 @@
----
-name: review-branch
-description: What local review is for, the gaps it closes, and why it reports without fixing
----
-
-# Review branch requirement
-
-## Gap
-
-Without this skill, a branch ships on the confidence of the session that wrote it. Review happens in chat and evaporates, so the ship step has no receipt to gate on. What review does happen mixes style opinion with real defects at one severity, and a reader cannot tell which blocks the merge. Worst, a diff that resolves empty against a stale base reports a clean branch instead of admitting the skill could not see the work.
-
-## Must
-
-- Read the project's own context before the diff, so a decision already settled is not reported as a defect
-- Resolve the base ref once, preferring the remote over local `main`, and reuse it in the guard and the read
-- Say when the baseline is unusable and name the narrowed scope, rather than letting a clean summary read as a clean branch
-- Flag only what will cause incorrect behavior or break a documented rule
-- Apply `canon:review-craft`'s axes and evidence bar, rendered output included, rather than carrying an axis list of its own
-- Grade every finding, since the caller gates on the counts rather than on the prose
-- Write the report to disk under a branch-derived slug, so what the ship step reads outlives the session
-
-## Must not
-
-- Fix, rewrite, or suggest a refactor outside a finding. Reporting is the whole job.
-- Flag style, linter territory, or anything resting on unverified state. A false positive erodes trust in the pass.
-- Substitute the whole tree for a missing baseline
-- Repeat the full report in chat. The file is the report and a chat copy of it goes stale immediately.
-- Stage or commit the receipt, which is gitignored scratch
-- Auto-trigger on a vague signal. Require an explicit request or a pipeline invocation.
-
-## Guards
-
-- The staged set, the branch set, and the working set are all empty: stop with a pass
-- Baseline unusable: continue on the uncommitted set and lead the report with the warning
-
-## Out of scope
-
-- Reviewing an open pull request, which `review-pr` owns. The split is by vantage: this one reviews local work for the session that wrote it and writes to disk.
-- Deciding whether the findings block the ship. This skill grades and the caller gates.
-- Fixing anything it found, which `review-address` owns once the work is on a pull request

package/claude/skills/review-branch/SKILL.md

@@ -1,137 +0,0 @@
----
-name: review-branch
-description: Reviews all changes since main for bugs, edge cases, and logic flaws. Reads CLAUDE.md, REQUIREMENTS.md, and ARCHITECTURE.md for context, then applies a structured review to the full diff and outputs a findings report. Coding standards from `.claude/rules/` are auto-loaded by Claude Code. Use when asked to review changes, run a code review, or check the current branch. Do NOT auto-trigger on vague signals like "looks good" or "can you check this". Require an explicit review request or an autoship invocation.
-metadata:
-  family: check
----
-
-# Review branch
-
-## Guards
-
-- Resolve the base ref first, per Diff baseline below. If `git diff <base>` and the untracked listing are both empty, stop: `✅ No changes to review.` Those two are the sets Step 2 reads, and the range already carries the staged and the unstaged work the guard used to test on its own. A guard reading bare local `main` stops the skill on `main` before it ever reaches Step 2.
-
-## Diff baseline
-
-Resolve the base ref once and reuse it in the guard and in Step 2:
-
-```bash
-git merge-base HEAD origin/main 2>/dev/null || git merge-base HEAD main 2>/dev/null
-```
-
-Prefer `origin/main` over local `main`. On `main` itself the local ref resolves to HEAD, so every committed change drops out of the set and the skill reports a clean branch rather than admitting it cannot see the work.
-
-The baseline is unusable in one case: no merge base resolves against either ref. Substitute `HEAD` and lead the report with `⚠ Baseline unusable. Reviewed the uncommitted set only.`, so a clean summary is never read as a clean branch. That substitution costs the committed half, because `git diff HEAD` reaches the staged and the unstaged work and nothing behind it.
-
-The base equalling HEAD is a usable baseline rather than the second case it used to be. It means nothing is committed ahead of the base, which is the ordinary shape on `main` and on a feature branch before its first commit, and `git diff <base>` degenerates there to `git diff HEAD` and reads the branch whole. Warning on it would tell a reader their review was partial when it had covered everything.
-
-## Step 1: read context
-
-Read these in parallel from the project root, skipping any that do not exist:
-
-- `CLAUDE.md`: project type, conventions, and commands
-- `canon/REQUIREMENTS.md`: feature scope and non-goals
-- `canon/ARCHITECTURE.md`: technical design decisions
-
-Coding standards from `.claude/rules/` are auto-loaded by Claude Code. Always-on rules apply every session. Path-scoped rules apply to files matching their `paths:` glob.
-
-## Step 2: get the diff and changed files
-
-Resolve the base ref per Diff baseline above, then run these in parallel from the project root:
-
-```bash
-git diff <base>
-```
-
-```bash
-git diff --name-only <base>
-```
-
-```bash
-git ls-files --others --exclude-standard
-```
-
-Use `git diff <base>` as the diff scope. It compares the base against the working tree, so the committed, staged, and unstaged halves arrive in one range and no selection between them is made. Take the file list as the name-only output plus the untracked listing, which covers a file git has never tracked and therefore no diff can reach.
-
-When the baseline is unusable, substitute `HEAD` for `<base>` in both diff commands. Never substitute the whole tree for a missing baseline.
-
-## Step 3: read changed files
-
-Read each file from the changed file list. Skip deleted files. Run reads in parallel.
-
-## Step 4: review and persist
-
-Invoke `canon:review-craft` before reading the diff for findings, whatever the diff's size. It carries what to look for and the evidence bar, rendered output included, and this step carries no axis list of its own to fall back on. Report it rather than proceeding silently when the skill does not resolve.
-
-Review the full diff and changed file contents for:
-
-1. Every axis `canon:review-craft` states, held to its evidence bar
-2. Violations of rules from `.claude/rules/` that apply to the changed files
-3. When the diff touches a file this project ships to a target holding none of its own history: a repository-relative path, a phase label naming a gitignored board, a same-repository pull request or commit reference, or a layout, stack, or config-path claim true of this checkout but stated as if it were general
-
-Use `CLAUDE.md`, `canon/REQUIREMENTS.md`, `canon/ARCHITECTURE.md`, and the auto-loaded `.claude/rules/` as project context to inform what is intentional vs problematic. Do not fix, rewrite, or suggest refactors outside the scope of a finding.
-
-### High-signal filter
-
-Flag only issues that will definitely cause incorrect behavior or break a documented rule. Skip:
-
-- Code style or quality concerns
-- Subjective suggestions
-- Linter territory
-- Issues that depend on unverified state
-
-A comment that makes a false claim about the code is a correctness finding, not a style one. Flag it past the exclusions above and let the severity ladder rank it.
-
-If uncertain, do not flag. False positives erode trust.
-
-### Severity
-
-- **critical**: blocks the feature. Broken in production if shipped.
-- **should-fix**: fix in same session while context is fresh. Not a blocker.
-- **minor**: not worth fixing now. Include for visibility.
-
-### Report format
-
-Start with a summary line. Group findings by file. Within each file, list findings sorted by severity (critical first, then should-fix, then minor). Omit files with no findings.
-
-```markdown
-X critical, Y should-fix, Z minor across N files.
-
-File: path/to/file.ext
-
-- **critical**: finding
-- **should-fix**: finding
-- **minor**: finding
-
-File: path/to/other.ext
-
-- **critical**: finding
-- **minor**: finding
-```
-
-If nothing is wrong, use: `✅ No findings.`
-
-### Persist
-
-Derive `<slug>` per `${CLAUDE_SKILL_DIR}/../../standards/slug.md`. Fall back to `latest` on an empty result.
-
-Write the full report directly to `.canon/review/branch-<slug>.md` at the main worktree root, not the current worktree. Resolve that root the way `session-worktree` does. Create the directory if it does not exist. Always overwrite.
-
-The report is a main-root write, so it goes out as a heredoc, routed the way `session-worktree` states.
-
-If there are no findings, write `✅ No findings.` to the file with a timestamp.
-
-The `.canon/review/` directory is gitignored. Do not stage or commit the file.
-
-The report is disposable. It outlives the ship chain that reads it, and `context-fold` sweeps it once the branch it names is gone, because the durable record of what a review found is the comment `review-pr` posts on the pull request. A review run on a branch that never opens one leaves nothing behind once that branch is gone, so fold anything worth keeping into the pull request body or a task finding while the report is still on disk.
-
-### Chat output
-
-Output only the summary line and the file path. Do not repeat the full report in chat.
-
-```plaintext
-X critical, Y should-fix, Z minor across N files.
-📝 Wrote .canon/review/branch-<slug>.md
-```
-
-If no findings: `✅ No findings. Wrote .canon/review/branch-<slug>.md`

package/claude/skills/seed-sync/REQUIREMENT.md

@@ -1,45 +0,0 @@
----
-name: seed-sync
-description: Scope boundary for section-granular seed reconciliation against the bulk install and sync commands
----
-
-# Seed sync requirement
-
-## Gap
-
-Without this skill, a project that edited a seed has no way to take an upstream change without losing something. No `canon` command touches a seed at all, so the only route is a hand copy that overwrites the file and takes the edits with it, unrecorded. Nothing can deliver one upstream section into a file the project has customized, which is the case a grown project is always in.
-
-A whole-file diff does not close it either. It cannot separate a section the user rewrote on purpose from a section the toolkit moved on without them, so the choice reaches the user as accept everything or lose everything, and the safe answer is always to skip.
-
-Naming the bulk command carries a failure of its own. This skill decides which files the bulk sync should take and then hands that command over without stating what it does to them, and the boundary line below names the reference holding that answer where no session reads it. Claude Code loads the skill entry alone, so a sibling named here reaches nobody.
-
-Two failures belong to the audit rather than to the diff. A decision taken in chat dies with the session, so an audit half applied cannot be resumed and the second run starts over. And a file the toolkit generates rather than ships, such as an index rebuilt from sibling frontmatter, is absent from every source catalog by design, so a naive comparison reports it as a local addition and invites the user to reconcile something nothing owns.
-
-## Must
-
-- Read seed content from the CLI rather than holding a copy, so the audit and the install cannot disagree
-- Diff per section, treating the preamble as a section of its own
-- Separate a customized section from a stale one by reading the attribution the drift report records, not by how the section looks, and default the customized one to no action
-- Fall back to appearance only when attribution is unavailable, and mark every verdict reached that way as unverified
-- Leave a file the report proves untouched to the bulk sync that owns it, rather than auditing what carries no edits
-- Route to the overwrite contract from the body, at the point the bulk command is named, since the boundary below is read by an author and never by a session
-- Persist the proposal and every decision to a review file that stays the source of truth across re-pings
-- Apply one section at a time, never by rewriting a file
-
-## Must not
-
-- Propose removing a section present only in the target. Those are the customizations the skill exists to preserve.
-- Write a target file before a decision is recorded against the item
-- Read an empty decision slot as consent
-
-## Guards
-
-- No `canon` on PATH, or no `.claude/` directory at the project root, stops before any read
-
-## Out of scope
-
-- Bulk install and sync of a whole domain, which `canon <domain> install` and `canon <domain> sync` own and `canon-cli` documents. Reach for this skill when the target holds edits worth keeping, and for those commands when it does not.
-- Golden configs, which overwrite by design and carry no section structure to diff
-- Governance rules: `canon gov sync`
-- First-time scaffold of a project that has installed nothing yet: `target-setup`
-- Public `README.md` and `docs/` prose: `docs-sync`