@erclx/canon 4.0.0

package/claude/skills/git-stage/SKILL.md

@@ -0,0 +1,73 @@
+---
+name: git-stage
+description: Groups staged files by concern and generates one conventional commit per group. Use when asked to "group these changes into commits", or when staged changes span multiple concerns and need to ship as separate commits. Do NOT use on a single-concern staged set. That is `git-commit`, which also preserves a hunk-level selection this skill's unstage and restage over whole files would widen.
+---
+
+# Git stage
+
+Read these files in parallel:
+
+- `${CLAUDE_SKILL_DIR}/../../standards/commit.md`: format, types, scopes, and constraints
+- `${CLAUDE_SKILL_DIR}/../../standards/markdown.md`: banned words, punctuation, and formatting for all generated text
+- The `write-human` skill: voice, rhythm, and sentence construction for all generated text
+
+## Context
+
+Run these commands in parallel to gather git context:
+
+- `git diff --cached --name-status 2>/dev/null || echo "NO_STAGED_FILES"`
+- `git diff --cached -- . ':(exclude)*.lock' ':(exclude)*-lock.json' 2>/dev/null || echo "NO_DIFF"`
+
+## Guards
+
+- If staged files output is `NO_STAGED_FILES`, stop and output:
+  `❌ No staged files. Stage files first with git add before committing.`
+
+## Grouping rules
+
+- Analyze the diff to understand what each file changes and why.
+- Group files by shared concern. A group is a single commit.
+- Files belong together when they implement or modify the same logical unit.
+- A file that clearly stands alone is its own group.
+- Order commits by dependency: commit dependencies before the files that import them.
+- Prefix the full command sequence with `git restore --staged .` to unstage everything, then stage and commit each group in order.
+- For `D` status files, use `git rm <file>`. For `A` or `M` files, use `git add <file>`.
+- For `R<score>` status rows, `--name-status` emits three tab-separated fields: `R<score>\t<old>\t<new>`. Treat the pair as one file, keep both paths in the same group, and restage them together with `git add <old> <new>` so git detects the rename at commit time. Splitting the pair across groups produces an add-plus-delete pair instead of a rename.
+
+## Response format
+
+### Preview
+
+**Staged files:** <total count>
+**Proposed commits:** <group count>
+
+| #   | Commit                       | Files       | Count |
+| --- | ---------------------------- | ----------- | ----- |
+| 1   | `<type>(<scope>): <subject>` | <filenames> | <n>   |
+| 2   | `<type>(<scope>): <subject>` | <filenames> | <n>   |
+
+**All <total> files accounted for.**
+
+Count characters in each `<type>(<scope>): <subject>` line. Shorten any subject that exceeds 72 characters and update the table.
+
+After outputting the preview, execute the final command immediately. Claude Code's tool permission dialog is the confirmation gate. Do not wait for user input.
+
+### Final command
+
+```bash
+git restore --staged .
+# Commit 1: <subject>
+git add <file1> <file2> && git commit -m "<type>(<scope>): <subject>"
+# Commit 2: <subject>
+git rm <deleted1> && git add <file3> && git commit -m "<type>(<scope>): <subject>"
+# Commit 3 (rename): <subject>
+git add <old> <new> && git commit -m "<type>(<scope>): <subject>"
+```
+
+## After execution
+
+Respond with exactly one line:
+
+`✅ Committed: <n> commits`
+
+Do not add any other text.

package/claude/skills/git-worktree/REQUIREMENT.md

@@ -0,0 +1,38 @@
+---
+name: git-worktree
+description: What worktree listing and cleanup is for, the gaps it closes, and why entry lives elsewhere
+---
+
+# Git worktree requirement
+
+## Gap
+
+Without this skill, linked worktrees accumulate past the point where any of them is remembered. Merge state does not appear in the worktree list, so a cleanup either removes a worktree still holding unmerged work or, lacking a way to tell, removes nothing. Removing a worktree also leaves its local branch behind, so the branch list keeps growing even when cleanup runs.
+
+## Must
+
+- Resolve merge state per branch from the pull request first, and fall back to local ancestry when no pull request exists
+- Match the ancestry fallback against the branch name alone. `git branch --merged` decorates the current branch and every branch checked out in a linked worktree, which is the whole set this skill enumerates.
+- Remove the worktree and its local branch together, since either one left alone is the state the skill exists to prevent
+- Exclude five kinds of row from the remove set: the main root, the current session's worktree, any dirty tree, any worktree registered from outside the path prefix `claude-worktree` creates under, and any worktree a live session is occupying
+- Give every skipped row a one-word reason, so the skip is a decision the user can overturn rather than a silence
+- Pick exactly one mode. Listing and removing are different requests and inferring both from one invocation removes worktrees the user meant to read about.
+
+## Must not
+
+- Enter or create a worktree. The description states the boundary so the model routes entry elsewhere rather than discovering it here.
+- Remove a worktree with uncommitted work, whatever its merge state
+- Remove a worktree a live session is occupying, whatever its merge state
+- Remove the worktree the session is currently running in
+- Emit anything after the result line
+
+## Guards
+
+- Not a git repository: stop
+- Remove set is empty: stop and say why every row was held back
+
+## Out of scope
+
+- Entering a worktree, which `claude-worktree` owns. That skill derives the name and aligns the branch, and this one never creates.
+- Deciding which features can run in parallel, which is a planning call rather than a git operation
+- The pull request lifecycle, which `git-pr` and `git-followup` own. This skill reads pull request state and never writes it.

package/claude/skills/git-worktree/SKILL.md

@@ -0,0 +1,130 @@
+---
+name: git-worktree
+description: Lists linked worktrees with PR state and cleans up merged ones. Use when asked to "list worktrees", "clean up worktrees", or after shipping a PR to reclaim slots. Do NOT use to enter a worktree from scratch (use `claude-worktree`).
+---
+
+# Git worktree
+
+List linked worktrees with their PR state and remove the merged ones. For entry, use `claude-worktree`.
+
+## Shipping order
+
+- Merge the branch with the smallest shared-file footprint first. A branch touching `CLAUDE.md`, a Claude context entry, or a regenerated `index.md` merges last.
+- Rebase each sibling worktree on `origin/main` after a PR merges and before the next one merges. Never merge a stale branch.
+- Run `cleanup` once a PR merges, so the worktree and its local branch go together
+
+## Mode selection
+
+Pick exactly one mode from the user's request:
+
+- `list`: show every worktree with its branch, PR state, and dirtiness ("list worktrees", "what worktrees do I have")
+- `cleanup`: remove worktrees whose branches are merged, then prune local branches ("clean up worktrees", "reclaim worktree slots")
+
+## Context
+
+Run in parallel:
+
+- `git rev-parse --git-dir 2>/dev/null || echo "NO_REPO"`
+- `git rev-parse --git-common-dir 2>/dev/null || echo "NO_REPO"`
+- `git worktree list --porcelain 2>/dev/null || echo "NO_REPO"`
+- `git fetch --prune origin 2>/dev/null || echo "NO_REMOTE"`
+
+Resolve `MAIN_ROOT` from the first `worktree` line of `git worktree list --porcelain`.
+
+## Guards
+
+- If either `git-dir` command returned `NO_REPO`, stop: `❌ Not a git repository.`
+
+## Enumeration (list and cleanup)
+
+Parse `git worktree list --porcelain` into rows. Each row has `path`, `branch`, `head`. Skip the `bare` row if present.
+
+For each row, determine merge state of its branch:
+
+1. Skip the main-root row. Mark it `main` with no PR lookup.
+2. Try `gh pr view <branch> --json state,number,url 2>/dev/null`:
+   - `MERGED`: state is `merged`, record PR number and URL.
+   - `OPEN`: state is `open`, record PR number and URL.
+   - `CLOSED`: state is `closed` (not merged), record PR number.
+   - Command fails or returns no PR: fall through.
+3. Fallback: `git branch --merged main --format='%(refname:short)' 2>/dev/null | grep -qx "<branch>"` to detect linear-merge ancestry. On match, mark `merged (local)`. Otherwise `unmerged`. Match the name alone. Without `--format`, git decorates the current branch with `*` and every branch checked out in a linked worktree with `+`, which is the whole set being enumerated.
+
+Determine dirtiness: `git -C <path> status --porcelain` non-empty means `dirty`.
+
+Determine current: the row whose `path` equals `git rev-parse --show-toplevel`. Resolve the root rather than comparing `pwd`, which equals the worktree root only when the session sits at the top of it. A session in any subdirectory would match no row, and the current-worktree exclusion in `cleanup` would pass its own worktree into the remove set.
+
+Determine provenance: a non-main row is `foreign` when its `path` does not start with `<MAIN_ROOT>/.claude/worktrees/`. That prefix is the folder `claude-worktree` creates under, a convention of that skill rather than a fact this one owns. A tree an operator registered by hand anywhere else on disk reads as `foreign`. Step 1 has already marked the main row `main`, so it never reaches this test.
+
+Determine occupancy: run `canon sessions list --json` once for the whole enumeration, never once per row. Resolve each enumerated row's `path` and each live session's `worktree` field with `realpath` before comparing, since a session registered from a second clone of this repository reports a path under that clone rather than under `MAIN_ROOT`, and a raw string compare would hold nothing back. A row is `occupied` when a resolved `worktree` from any live session equals its resolved `path`. A resolved session `worktree` outside `MAIN_ROOT` names a different checkout, so it clears no row here and marks none as occupied.
+
+The roster is unreadable when the command exits non-zero, when its JSON carries a `reason` field instead of a populated `sessions` array, or when `sessions` is non-empty but no entry carries a `worktree` key at all, which is the shape an older binary prints and cannot be told apart from a roster answering that nothing is occupied. `list` leaves the Notes column silent on that failure rather than changing behavior beyond it. `cleanup` refuses instead, stated in its own section below.
+
+## `list` mode
+
+Print the enumeration as a table, then stop. `list` has no final command.
+
+```plaintext
+| #  | Path                               | Branch            | State    | PR     | Notes    |
+| -- | ---------------------------------- | ----------------- | -------- | ------ | -------- |
+```
+
+Notes column shows the first that applies of `current`, `occupied`, `foreign`, `dirty`, or empty. Show paths relative to `MAIN_ROOT` (`.claude/worktrees/<name>`). A `foreign` row sits outside `MAIN_ROOT`, so print its path in full.
+
+After the table, append a one-line hint:
+
+- If any row is `merged` and clean and not current and not `foreign`: `Hint: /git-worktree cleanup to remove <count> merged worktrees.`
+- Otherwise: `Hint: no worktrees ready for cleanup.`
+
+## `cleanup` mode
+
+If Enumeration marked the roster unreadable, stop: `❌ Session roster unreadable, so occupancy cannot be checked. Resolve the canon sessions list failure, then re-run cleanup.` Hold every non-main row rather than computing the remove set from the other five tests alone, since removing a tree a live session holds is the failure this skill exists to prevent and a sweep that removes nothing costs one re-run.
+
+From the enumeration, include a worktree in the remove set when all hold:
+
+- Not the main row.
+- Not the current session's worktree.
+- Not occupied by a live session.
+- Not a `foreign` tree.
+- State is `merged` or `merged (local)`.
+- Working tree is clean.
+
+Every other non-main row goes to the skip set with a one-word reason, the first that applies in this order: `current`, `occupied`, `foreign`, `dirty`, `open`, `closed`, `unmerged`. A `foreign` tree that is also dirty reports `foreign`, since `dirty` is a state the operator can clear and `foreign` is not. Leading with the transient reason invites a commit or stash that changes nothing, after which the row reports `foreign` and holds back anyway.
+
+### Preview
+
+```plaintext
+**Removing:** <count>
+
+| Path | Branch | PR |
+| ---- | ------ | -- |
+
+**Skipping:** <count>
+
+| Path | Branch | Reason |
+| ---- | ------ | ------ |
+```
+
+If the remove set is empty, stop with `❌ Nothing to remove. All linked worktrees are current, dirty, unmerged, or foreign.`
+
+### Final command
+
+After the preview, execute immediately. Claude Code's tool permission dialog is the confirmation gate. Do not wait for user input.
+
+```bash
+git -C <MAIN_ROOT> worktree remove <path1> \
+  && git -C <MAIN_ROOT> branch -D <branch1> \
+  && git -C <MAIN_ROOT> worktree remove <path2> \
+  && git -C <MAIN_ROOT> branch -D <branch2> \
+  && git -C <MAIN_ROOT> worktree prune
+```
+
+Chain one `worktree remove` + `branch -D` pair per row in the remove set, then a single `worktree prune` at the end.
+
+## After execution
+
+Respond with exactly one line:
+
+- `list`: `✅ <n> worktrees listed`
+- `cleanup`: `✅ Removed: <count> worktrees, <count> branches pruned`
+
+Do not add any other text.

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

@@ -0,0 +1,40 @@
+---
+name: migration-claude-md
+description: Why a bloated CLAUDE.md is rebalanced by proposal rather than by edit, and what the seed baseline settles
+---
+
+# Migration claude md requirement
+
+## Gap
+
+Without this skill, a session asked to slim `CLAUDE.md` deletes sections it judges stale and writes the rest into files it creates in the same pass, so a classification the user disagrees with is no longer one command to undo. The file is always-load context, so a wrong move costs every later session rather than one.
+
+Three more failures share a cause. The session has no baseline for what belongs in `CLAUDE.md`, so it reads toolkit-seeded always-load behavior as bloat and proposes moving it, and the next seed sync puts it back. A section carrying a rule and a narrative together gets sorted whole into one bucket, which loses half of it either way. And a target that already exists gets written over, since a proposal blind to the folder cannot tell a create from a collision.
+
+The skill also writes into `.claude/context/`, a folder `migration-context` moves files into. A proposal drafted before those moves land cannot see the entries they create, so a move that should have resolved to an append reads as a create.
+
+## Must
+
+- Classify every `##` section against the three tiers in a fixed order, so the same section lands the same way twice
+- Treat a section matching the seed baseline as always-load by definition and propose no move for it
+- Read the existing rules and context folders before resolving a target, so an existing entry resolves to an append and a taken rule slot resolves to a conflict
+- Derive a rule's glob from the scope the section names rather than from the folder it describes
+- Propose and stop, leaving every file write and the `CLAUDE.md` edit to the user
+- Report the already-lean case as a pass rather than manufacturing moves to justify the run
+
+## Must not
+
+- Sort a section holding both a rule and a narrative into either bucket. Flag it for a manual split.
+- Create a rule file, create a context entry, or edit `CLAUDE.md`
+- Propose a move onto an existing rule path. Report it as a conflict and skip it.
+
+## Guards
+
+- No `CLAUDE.md` at the project root stops before any classification runs
+- Fewer than three `##` sections reports the file already lean, since a rebalance needs something to rebalance
+
+## Out of scope
+
+- Relocating `docs/` files, which `migration-context` proposes into this same `.claude/context/` folder. Run that skill first when both apply, so Step 3 reads a folder its moves have already populated.
+- Scaffolding the rule files it proposes, which `create-rule` does with the numbering and frontmatter
+- Regenerating `.claude/context/index.md`, which `canon indexes regen` does once the user has applied the moves

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

@@ -0,0 +1,76 @@
+---
+name: migration-claude-md
+description: Classifies each section of a target project's bloated `CLAUDE.md` into the three-tier context model and proposes moves to path-scoped rules or context entries, keeping only always-load behavior in `CLAUDE.md`. Use when asked to "slim CLAUDE.md", "migrate CLAUDE.md to rules", "rebalance CLAUDE.md", or when a project's `CLAUDE.md` has grown large. Do NOT move `docs/` files (that is `migration-context`) and do NOT auto-execute. Proposal only.
+---
+
+# Claude md migrate
+
+Rebalance a large `CLAUDE.md` so only always-load behavior stays in it, path-scoped behavior becomes a rule, and domain narrative becomes a context entry. Every move is a proposal the user applies by hand.
+
+Run `migration-context` first when both apply. Its moves populate `.claude/context/`, and Step 3 has to read the folder those moves left so an existing entry resolves to an append rather than blocking the move that should have created it.
+
+## Guards
+
+- If no `CLAUDE.md` exists at `pwd`, stop: `❌ No CLAUDE.md found at the project root.`
+- If `CLAUDE.md` has fewer than three `##` sections, stop: `✅ CLAUDE.md is already lean. Nothing to rebalance.`
+
+## Step 1: discover
+
+Run these in parallel from `pwd`:
+
+- Read `CLAUDE.md`
+- `ls .claude/rules/ 2>/dev/null`: existing rule subdirs and numbers for placement
+- `ls .claude/context/ 2>/dev/null`: existing context entries for conflict checks
+- `canon claude seeds list --json 2>/dev/null`: the base seed set. Read the `CLAUDE.md` entry's `content` as the always-load baseline. Skip this input when `canon` is not installed.
+
+## Step 2: classify each section
+
+Split `CLAUDE.md` by `##` heading. Score each section against this order:
+
+1. **Always-load.** Stays in `CLAUDE.md`. Signals: cross-cutting behavior that applies every session, output and formatting rules, project-wide invariants, conventions with no file scope. A section that matches the seed baseline is always-load by definition. Keep it and propose no move.
+2. **Path-scoped.** Propose a rule. Signals: behavior that only applies when working in a folder (`frontend/`, `backend/`) or on a file type, framework-specific conventions, "when editing X do Y" phrasing. Derive the glob from the named scope.
+3. **Domain narrative.** Propose a context entry. Signals: prose describing how a system or domain is built, decisions, gotchas, structure. Not do-or-do-not rules.
+4. **Mixed.** Both rule and narrative in one section. Flag as "needs manual split". Do not propose a single target.
+
+## Step 3: resolve targets
+
+For each section proposed for a move:
+
+- Path-scoped: propose `.claude/rules/<subdir>/<n>-<slug>.md` with a `paths:` glob. Pick the subdir and a free number the way `create-rule` does. If `.claude/rules/<subdir>/` already holds a rule on the topic, mark as "conflict" and skip.
+- Domain narrative: propose `.claude/context/<domain>.md`. If the entry already exists, propose appending rather than creating.
+
+## Step 4: output
+
+Print one grouped proposal block. Omit empty groups.
+
+```markdown
+## Keep in CLAUDE.md
+
+- `## <heading>` (<one-line reason: always-load behavior>)
+
+## Extract to a path-scoped rule
+
+- `## <heading>` → `.claude/rules/<subdir>/<n>-<slug>.md`, paths `<glob>` (<reason>)
+
+## Extract to a context entry
+
+- `## <heading>` → `.claude/context/<domain>.md` (<reason>)
+
+## Needs manual split
+
+- `## <heading>` (rule and narrative mixed)
+
+## Conflicts
+
+- `## <heading>` → `.claude/rules/<subdir>/<n>-<slug>.md` already exists. Skipping.
+
+## Reminder
+
+Scaffold each rule with create-rule, which carries the rule standard.
+Follow the context standard for each new context entry.
+Run canon indexes regen after adding context entries.
+```
+
+If every section classified as always-load, output: `✅ CLAUDE.md holds only always-load behavior. No moves proposed.`
+
+Do not edit `CLAUDE.md`, and do not create the rule or context files. The user reviews the proposal, then applies each move by hand.

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

@@ -0,0 +1,36 @@
+---
+name: migration-context
+description: Scope boundary for the docs audience split and its ordering against the other two migrations
+---
+
+# Migration context requirement
+
+## Gap
+
+Without this skill, a session judges a `docs/` file agent-facing, moves it, and rewrites the inbound links in the same pass, so a classification the user rejects is no longer one command to undo.
+
+Three more failures share a cause. The skill reads a folder two other surfaces also write, and a proposal blind to them destroys work.
+
+A seed-derived `development.md` moved out of `docs/` comes back on the next seed sync. A move onto an existing `.claude/context/` filename overwrites the entry sitting there. A proposal drafted while `migration-claude-md` is proposing entries into the same folder cannot see those targets, and running the two in the wrong order turns a legitimate move into a skipped conflict.
+
+## Must
+
+- Classify by audience signal in the file rather than by its name or its folder position
+- Propose and stop. The `git mv` commands and the link fixes stay the user's to run.
+- Report every inbound reference to a moved path as a TODO line, leaving the reference itself untouched
+- Defer a seed-derived file to the seed sync path rather than proposing a move for it
+- Skip a move whose destination already exists and report it as a conflict
+
+## Must not
+
+- Sort a file carrying both audiences into either bucket. Flag it for a manual split, since a whole-file move and a silent split are both wrong.
+- Descend into `docs/` subfolders. List them for manual review and leave them alone.
+
+## Guards
+
+- A missing `docs/` directory, or one holding no top-level markdown, stops before any classification runs
+
+## Out of scope
+
+- Classifying `CLAUDE.md` sections, which `migration-claude-md` proposes into this same `.claude/context/` folder. Run this skill first when both apply, so that skill's append-or-create check reads a folder the moves have already populated.
+- Regenerating `.claude/context/index.md`, which `canon indexes regen` does once the user has applied the moves

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

@@ -0,0 +1,95 @@
+---
+name: migration-context
+description: Classifies markdown files in a target project's `docs/` folder and proposes `git mv` commands to relocate agent-flavored content to `.claude/context/`. Use when asked to "migrate docs to context", "move docs to context", "split docs", or to align an existing project with the three-tier context model. Do NOT auto-execute moves or rewrite inbound links. Proposal only.
+---
+
+# Claude context migrate
+
+Run this skill before `migration-claude-md` when both apply. That skill proposes entries into the same `.claude/context/` folder, and an entry landing there first makes the corresponding move here read as a conflict and get skipped, which loses the richer `docs/` file.
+
+## Guards
+
+- If no `docs/` directory exists at `pwd`, stop: `❌ No docs/ directory found.`
+- If `docs/` contains no `.md` files at the top level, stop: `❌ No markdown files in docs/.`
+- This skill operates on flat `docs/*.md` only. Subfolders under `docs/` are listed in the output as "manual review needed" and skipped.
+
+## Step 1: discover
+
+Run these in parallel from `pwd`:
+
+- `ls docs/*.md 2>/dev/null`: list flat markdown files
+- `ls docs/*/ 2>/dev/null`: detect subfolders for the manual-review note
+- `ls .claude/context/ 2>/dev/null`: detect already-migrated content for conflict checks
+- `canon claude seeds list --json 2>/dev/null`: get the canonical seed list to identify seed-derived files
+
+Read each discovered `docs/*.md` file in parallel.
+
+## Step 2: classify
+
+For each file, score against this rule order:
+
+1. **Seed-derived.** Filename matches `development.md` or `ci.md` and content shape resembles the toolkit's base seed (frontmatter plus a Setup or Triggers section plus tables for scripts or checks). These belong to the seed-migration path. Do not propose a move here.
+2. **Agent-flavored.** Score the following signals. Classify as agent-flavored when two or more match:
+   - Dense file paths in code fences
+   - Sections titled "Anti-patterns", "Layer responsibilities", "Conventions", or "Commands"
+   - Tables of CLI commands
+   - Explicit "do not" rules
+3. **Human-only.** Default fallback when no agent signals match. Typical signals:
+   - Tutorial prose
+   - Sections titled "Welcome", "Getting started", "Contributing", or "Installation"
+   - Second-person narrative aimed at new contributors
+4. **Mixed.** Both agent and human signals present. Flag as "needs manual split". Do not propose a move.
+
+## Step 3: check conflicts and inbound links
+
+For every file proposed for a move:
+
+- If `.claude/context/<filename>` already exists, mark as "conflict" and skip the move.
+- Run `git grep -n "docs/<filename>"` (or grep equivalent) to list inbound references in `CLAUDE.md`, `README.md`, and other markdown. Report each as a TODO line. Do not rewrite.
+
+## Step 4: output
+
+Print one grouped proposal block. Omit empty groups.
+
+```markdown
+## Move to .claude/context/
+
+- docs/<file>.md → .claude/context/<file>.md (<one-line reason>)
+
+## Keep in docs/
+
+- docs/<file>.md (<one-line reason>)
+
+## Defer to claude-seed-sync
+
+- docs/<file>.md (matches toolkit base seed)
+
+## Needs manual split
+
+- docs/<file>.md (mixed agent and human signals)
+
+## Conflicts
+
+- docs/<file>.md → .claude/context/<file>.md already exists. Skipping.
+
+## Subfolders (manual review)
+
+- docs/<subfolder>/
+
+## Suggested git mv commands
+
+git mv docs/<file>.md .claude/context/<file>.md
+
+## Inbound links to fix after moves
+
+- CLAUDE.md:42 references docs/<file>.md
+- README.md:17 references docs/<file>.md
+
+## Reminder
+
+Run canon indexes regen to update .claude/context/index.md.
+```
+
+If every file classified as "Keep in docs/", output: `✅ All docs/ content is human-facing. No moves proposed.`
+
+Do not execute the `git mv` commands. Do not edit `CLAUDE.md` or `README.md`. The user runs the commands and fixes the links manually after reviewing.

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

@@ -0,0 +1,55 @@
+---
+name: migration-standards-drop
+description: Why the standards-tree drop ships as an ordered proposal, what the two pre-delete reads catch, and why one citation form serves every surface inside a target
+---
+
+# Migration standards drop requirement
+
+## Gap
+
+Without this skill, nothing names the tree. The sync engine registers governance alone and the unmigrated scan carries an empty root-layout set, both by decision rather than by omission, so a target holding 21 installed standards files reports clean and the drop runs off whoever remembers to look. The census that found the population walked one folder on one machine and moved the count from four to seven.
+
+The order is the second failure and it has two halves. A session that deletes before syncing lands the installed rules citing a path it removed, and one that sweeps before syncing repoints citations the sync then rewrites.
+
+The delete otherwise runs blind in two directions. Two of the five targets measured on 2026-08-28 carried a runtime reader, one a hook hand-parsing a standard for its banned-word set, and a hook whose input is gone audits nothing while reporting a clean run. In the other direction, nothing separates a file the project wrote from a toolkit copy by name, and the corpus had moved on from all 20 files at one target, so a content diff sorts every file as changed and a session reading that diff either keeps everything or loses the one file no corpus carries.
+
+The repoint form is the fourth. A session applying the citation rule it knows from a shipped skill writes `${CLAUDE_SKILL_DIR}/../../standards/<name>.md`, which from a project-local skill at `.claude/skills/<name>/` resolves back into the tree the same pass deleted, and reports the sweep finished.
+
+The last is the name map. `prose` split into `markdown.md` plus the `write-human` skill and resolves as no standard, so a mechanical one-to-one repoint produces a citation to nothing and every check on it passes.
+
+## Must
+
+- Detect from a read of `.claude/standards/` itself, since no report names the tree and a session waiting for one waits forever
+- Report the state a binary behind the published version puts the sync in, before naming a sync a stale binary would run
+- Split the tree against `canon standards list --json` three ways, separating an unchanged toolkit copy from a drifted one and from a name that resolves to no standard
+- Name every runtime reader ahead of any delete, splitting a reader from a citation by whether the file is markdown, and say when the search could not run
+- Give every citation inside a target one target form, `canon standards <name>`, and say why the plugin-root form fails there
+- Order the proposal sync, drop, sweep, and state that the sweep re-reads after the sync rather than before it
+- Report an unmatched name as the user's to place, naming the `prose` split as the recorded instance
+- Report the measured empty case as a pass, since the guard is what proves the read ran
+
+## Must not
+
+- Run the sync, delete or move a file under the tree, or rewrite a citation
+- Sort a drifted file as project-authored or as toolkit-owned on a content diff alone
+- Propose the plugin-root citation form for a surface inside a target
+- Relocate the install stamp. One visit per target is cheaper than two and a skill is not a visit, so the stamp rides with whatever else reaches the target.
+- Stay in the catalog on the author typing its name alone. Nothing can answer that before the skill has run, so read the census back once it has and retire it if the answer is nobody.
+
+## Guards
+
+- A directory with no `.claude/` stops, since nothing there installed a tree
+- A `.claude/standards/` holding no markdown is the pass rather than a refusal
+- No `canon` on `PATH` stops, since every citation this move writes names a verb the target has to run
+
+## Out of scope
+
+- Classifying `CLAUDE.md` sections into the three-tier model: `migration-claude-md`
+- Relocating `docs/` files by audience: `migration-context`
+- Splitting a retired `.claude/` file into the folder that replaced it, which pairs one file against one folder rather than dropping a corpus: `migration-superseded`
+- Reconciling a seed file against its source section by section: `claude-seed-sync`
+- Applying the drop and the sweep, which the user does after reviewing
+
+## Why it ships while its consumer row is parked
+
+The one task performing this move is parked on the operator declining outside-repository work, so the skill arrives with three known consumers and no live instance. It ships anyway, because the parked row is about who is authorized to visit a target rather than about the move being wrong, and the skill is what makes the move repeatable by whoever is authorized. The evidence behind it comes from the census rather than from a run, which is the weaker of the two and is recorded here as such.