@erclx/canon 4.0.0

package/claude/skills/claude-markdown-propose/references/format.md

@@ -0,0 +1,107 @@
+# Proposal format reference
+
+Governs the proposal `claude-markdown-propose` writes before it edits anything. The concern being screened is an input and does not change the format.
+
+## Folder
+
+- One folder per screening pass at `.claude/proposals/<slug>/`, where the slug names the subject rather than the activity
+- One proposal file per source file, named `<nn>-<source filename, its own extension dropped>.md`, so a source already named `CLAUDE.md` becomes `01-CLAUDE.md` rather than `01-CLAUDE.md.md`
+- `00-overview.md` when the pass spans more than two source files, holding the cross-file pattern, the change counts, and the settle order
+- `applied.md` once the first change lands, holding every applied change with its reason and the answer it carried
+
+The name carries both structures the folder has. The basename pairs a proposal to its source so a reader opens the two side by side, and the number is the settle order, which is a dependency rather than a preference: a file other files quote is settled first. Do not group proposals by theme.
+
+A proposal opened after the initial pass takes the next free number, and the folder is never renumbered. Its number records when the site was found rather than where it belongs in the dependency order. Renumbering to restore the order would rewrite the names of files already carrying answers, which costs more than the ordering is worth once applying has started.
+
+Settle a late proposal ahead of any unapplied proposal quoting the surface it covers, whatever the two numbers say. A proposal already applied is past the question, since the file it governs is committed.
+
+## Change format
+
+Each proposal file opens with `# Proposal: <source path>`, one line naming the concern, the settle order, and the full surface the pass screened, then one `###` heading per change, ending with a `## Left alone` section. A change never sits at `##`, which the closing section reserves, and a variant never sits at `###`, which the change heading reserves. Skipping from `#` straight to `###` is deliberate: the file has exactly one layer of change between its title and its variants.
+
+Naming the surface on every file, not only the first, is what lets Applying's cross-surface grep run cold. The Propose and Apply invocations are typically separate sessions days apart, so the surface the operator named has to survive on the file rather than in a conversation neither session shares.
+
+A change carries an `###` heading, a fenced `diff` block holding the current text against the proposed, the reason beneath it, and its own answer slot.
+
+- Heading: `### N. The sentence or section it sits in`
+- Body: a `diff` fence, `-` for current and `+` for proposed
+- `- **Why:** the reason, naming what the change fixes`
+- `- **Open:** only where the replacement was drafted rather than corrected`
+- `- **Recommended:** only where a pick is proposed ahead of the answer, directly above the slot`
+- `- **You:**` last on every change, shipped empty
+
+### Variants
+
+A corrected change carries one replacement. A drafted one carries three, because the intent behind invented prose is not recoverable from the source text and a single draft turns the answer slot into a veto.
+
+- Ship three variants on any change carrying `Open:`, labelled `#### A`, `#### B`, `#### C`
+- Make them differ in approach rather than in wording. Three phrasings of one bet are one variant.
+- State the bet each one makes in a line above its block, so the choice is between strategies and not between paragraphs
+- Ship one replacement everywhere else. A word swapped for the recorded fact has no second option worth reading.
+
+Three is the cap as well as the count. A fourth splits attention without widening the space.
+
+### Placement
+
+- Title a change by the section or sentence it sits in, never by its position in the file
+- Quote text from another file in a `markdown` block rather than citing a line number, which goes stale on the first applied change
+- Split a `Why:` into labelled halves when one change fixes two things (`**Why, the date:**`)
+- Carry an `Open:` on any change whose replacement text was written rather than corrected, so a blanket answer cannot swallow it
+
+Close each file with what it leaves alone. A pass reporting only what it would change reads as one that found everything wanting.
+
+## The answer contract
+
+`You:` belongs to the operator and ships empty on every change. Empty means unread and never agreement, matching the intake contract in `${CLAUDE_SKILL_DIR}/../../standards/intake.md` rather than the plan file's, which reads a blank slot as accepting the suggestion above it. State the inversion at the top of `00-overview.md` when the folder spans more than one file, since a contract read from the wrong surface gets applied to the wrong document.
+
+- One `You:` per change, last in its bullet list, so an answer lands where the change is read
+- Never fill a `You:` slot and never infer a disposition from an empty one
+- The slot takes free text, not only `ok`. A rejection, a caveat, or a rewrite of the proposed line are all valid answers and a later pass reads them correctly.
+- A pick made on the operator's behalf goes on a `- **Recommended:**` line directly above the slot, never inside it, and states which variant it takes and why. The slot below it still ships empty, so a count of unread changes still reads the change as unread.
+
+An answer rejecting the draft reopens the change rather than closing it. Move that answer to a `- **Answered:**` line above the variants it produced, and ship a fresh empty `- **You:**` beneath them. The change reads as unread again, which is what it is.
+
+Per-change slots do not license a partial sweep. Answering a change records one decision, and the applying rule below is what holds the set together.
+
+The overview file carries no slot, since it proposes no changes.
+
+## Applying
+
+- Apply one file at a time, in the folder's settle order
+- Apply every change in that file that carries an answer, and nothing that does not
+- Re-grep each change's anchor against its source before applying it, and again after a rebase
+- Grep the other named surfaces for the same claim before committing the file
+- Write every hit that grep returns onto the proposal owning the file it sits in, as a change with its own answer slot, and open a proposal for a surface the pass has none for
+- Commit the file once its own answered changes are applied. A hit in a sibling never holds it.
+- Move an applied change into `applied.md` beside the proposals, carrying its reason and its answer
+
+A partial pass is worse than none, and a file is the unit that can be finished. Settling one claim across every file at once touches all of them and closes none, so each file ends the pass looking reviewed while other changes in it sit answered and unapplied. The surface grep is what covers the cross-file half a per-file pass would otherwise miss.
+
+Recording a hit rather than acting on it is what keeps the grep from rebuilding the whole-set gate. A sibling holding the same claim is a change nobody has answered yet, and holding this file until it is answered makes every file wait on the slowest one, which is the shape the per-file unit replaced.
+
+A proposal outlives its own diff. The source moves under it, so an approved change stops matching while the defect it names survives in fresh wording. The anchor re-grep is the only thing that catches that.
+
+## After
+
+- Strip the `diff` blocks
+- Keep the files, their headings, their reasons, and the answers
+
+What remains is the record of what changed and why, which is the half no commit message holds. The folder stays where it is, beside every earlier pass, so a later one reads what an earlier one settled instead of asking it again.
+
+The folder is gitignored and unbacked. It carries decision state rather than generated data, which is why `src/records/backup.ts` names it in `BACKED_FOLDERS`, but nothing else about its contents is enforced.
+
+## Retrieval
+
+Count the unread changes per file:
+
+```bash
+grep -c '^- \*\*You:\*\*$' .claude/proposals/<slug>/*.md
+```
+
+Report every answer given, against the change it sits under:
+
+```bash
+awk '/^### /{h=FILENAME": "$0} /^- \*\*You:\*\*./{print h; print "   "$0}' .claude/proposals/<slug>/*.md
+```
+
+Both walk `###` headings, which is the mechanical reason an answer typed anywhere else is lost.

package/claude/skills/claude-memory-capture/REQUIREMENT.md

@@ -0,0 +1,50 @@
+---
+name: claude-memory-capture
+description: Which surface a session fact is owed to, what earns a memory file once routing has run, and why capture never edits a context entry itself
+---
+
+# Claude memory capture requirement
+
+## Gap
+
+Without this skill, what a session learned dies with it, and the correction the user made in message four is re-earned next week. What does get written is a narrative of how the session went wrong rather than a rule that fires again, so a reader gets a story and no instruction. A new file lands beside one already holding the same topic, and the folder grows two entries per subject until nothing in it can be trusted as current.
+
+Writing every fact to one folder is the deeper gap, because the folder has no reader. A fact about a domain has an owning surface already, the context entry the three-tier model loads on demand, and filing it in memory instead puts it where only a deliberate sweep will ever find it. The measured outcome is a store that grows on every ship and is drained by nothing.
+
+The threshold is what the remaining folder lives or dies on. A first-occurrence slip saved as feedback is noise that costs every later session a read, and a fact the repository already records is worse, because it duplicates a source that will be updated without it. From a linked worktree, writes resolved against `pwd` land in a second memory folder nothing else reads.
+
+## Must
+
+- Resolve every read and write at the main worktree root, so parallel worktrees write one folder
+- Classify each candidate as feedback, project, user, or reference before routing or writing
+- Route a project candidate whose subject names an entry in `.claude/context/index.md` to that entry, and hand it off as a file rather than an edit
+- Keep a candidate that matches no entry, or two entries with no clear owner, as a memory file
+- Apply the save threshold, firing feedback only on an explicit correction or a pattern that repeated twice
+- Grep the folder for an existing file on the topic and update it in place rather than adding a second
+- Keep a feedback or project body to the rule, one line of why, and one line of when it fires next
+- Write frontmatter the index renderer can read, so the generated catalog stays current
+- Report that nothing was worth capturing rather than manufacturing an entry to show work
+
+## Must not
+
+- Edit a context entry, which `claude-docs` owns
+- Route a feedback, user, or reference candidate, since no context entry owns how to work or who to ask
+- Route anything when the caller does not commit, because a context entry is a tracked file
+- Hand-append a row to the memory index, which is generated from sibling frontmatter
+- Write a session narrative or a recovery account in place of the pattern
+- Save a first-occurrence slip as feedback
+- Create a second file on a topic the folder already holds
+- Save what the repository already records in code, git history, or its instruction files
+- Curate, promote, or delete an existing entry
+
+## Guards
+
+- No correction, confirmation, or context disclosure worth persisting: stop with a pass
+- Memory folder absent at the main root: create it rather than stopping
+- Session in the main worktree, or a caller that does not commit: skip routing and write every candidate as a memory file
+
+## Out of scope
+
+- Editing the context entries themselves, which `claude-docs` owns on its own pass
+- Curating what is already in the folder, which `claude-memory-review` owns
+- Promoting an entry into an instruction file or a skill body, which mutates how the agent operates and ships as its own change

package/claude/skills/claude-memory-capture/SKILL.md

@@ -0,0 +1,101 @@
+---
+name: claude-memory-capture
+description: Extracts durable patterns from the current session, routes a domain fact to the context entry that owns it, and writes the residue to `.claude/memory/` as feedback, project, user, or reference files. Use when asked to "capture memory", "capture lessons", "wrap up the session", "end of session memory", or as a step in autoship. Do NOT use to curate existing memory. Use `claude-memory-review` for that.
+---
+
+# Claude memory capture
+
+Scan the current session for patterns worth persisting, send each to the surface that owns it, and leave in `.claude/memory/` only what no surface owns. Pair with `claude-memory-review` for later curation.
+
+A fact about a domain belongs in that domain's context entry, which the three-tier model already loads on demand. Writing it to memory instead puts it in a folder nothing opens. Routing is therefore the point of this skill and the memory file is the fallback.
+
+The filename and its type prefix, the frontmatter, the body shape each type carries, and the lifecycle are fixed by `${CLAUDE_SKILL_DIR}/../../standards/memory.md`. Read it before writing an entry and follow it rather than working the shape from memory.
+
+## Guards
+
+- All `.claude/memory/` reads and writes resolve at the main worktree root, not the current worktree. See Worktrees in `CLAUDE.md`.
+- From a linked worktree the file-editing tools refuse every path below, so each write in this skill goes out through `Bash` as a plain single command. A memory entry holds one fact and this session has read it, so an update rewrites the whole file with a heredoc rather than editing a line inside it.
+- If `.claude/memory/` does not exist at the main worktree root, create it, along with an `index.md` carrying `title` and `subtitle` frontmatter. `canon claude init` seeds both, and a project predating that seed has neither. Regeneration errors without the index, so the first write into a bare folder would report a frontmatter failure against a file that is fine.
+- If the session produced no user corrections, confirmations, or context disclosures worth persisting, stop: `✅ Nothing worth capturing.`
+- Routing edits a tracked file, so it runs only where the caller commits. When the session is in the main worktree, or the caller states it does not commit, skip Step 3 and write every candidate as a memory file. `claude-orchestrate` is the caller this covers.
+
+## Step 1: read context
+
+Read in parallel, skipping any that do not exist:
+
+- `${CLAUDE_SKILL_DIR}/../../standards/memory.md`: the filename, frontmatter, body shape, and lifecycle every entry follows
+- `CLAUDE.md`: the project's write location and any rule it states over the folder
+- `.claude/memory/index.md`: existing index, to avoid duplicates
+- `.claude/context/index.md`: the domain catalog Step 3 routes against
+- `${CLAUDE_SKILL_DIR}/../../standards/markdown.md`: banned words, punctuation, and formatting applied to memory file bodies
+- The `write-human` skill: voice, rhythm, and sentence construction applied to memory file bodies
+
+## Step 2: classify candidates
+
+Scan the session and group candidate patterns as `feedback`, `project`, `user`, or `reference`. What each type holds and what makes one fire are the Types table in `${CLAUDE_SKILL_DIR}/../../standards/memory.md`. Read the table and classify against it rather than against a recollection of the four names.
+
+Scan the whole session rather than its last exchange. A rule the user stated early and you followed since reads as settled and is exactly the one no file records.
+
+## Step 3: route what a context entry owns
+
+Only a **project** candidate is routable. Feedback, user, and reference describe how to work or who to ask rather than how a domain behaves, and no context entry owns them.
+
+For each project candidate, match its subject against `.claude/context/index.md`. The test is a named entry, not a judgment about fit: the fact names a surface that already has an entry in the catalog. Route it to that entry.
+
+Fail closed. A project candidate matching no entry stays a memory file, and so does one matching two entries where neither is clearly the owner. The residue is what the folder is for, and a fact filed under the wrong entry is worse than one in memory because a context entry is a surface sessions trust.
+
+Do not edit a context entry here. `claude-docs` owns those edits and folds the routed facts in on its own pass, or two skills write one file at the same step. Write each routed fact to `.claude/.tmp/memory-routing/<slug>.md` at the main worktree root instead, appending when the file exists. An append is a whole-file operation the shell does directly, so send it as a plain single `Bash` command carrying a heredoc:
+
+```markdown
+## .claude/context/<domain>.md
+
+<the fact in one or two sentences, stated as a fact about the domain rather than as a session narrative>
+```
+
+Derive `<slug>` per `${CLAUDE_SKILL_DIR}/../../standards/slug.md`. Fall back to `latest` on an empty result.
+
+The handoff is a file rather than a spoken result so the routed fact survives a compaction between this step and the `claude-docs` pass, and so the standalone caller leaves something behind for a later `/claude-docs` to consume.
+
+## Step 4: dedupe
+
+For each remaining candidate, grep `.claude/memory/` for an existing file on the same topic. If one exists, update it in place rather than create a new file. Read it first and write the whole file back, since the guard above rules out editing a line inside it.
+
+## Step 5: write the residue
+
+Write each remaining candidate to `.claude/memory/<type>-<slug>.md`, following the template and the shape rules in `${CLAUDE_SKILL_DIR}/../../standards/memory.md`. Copy the shape from there rather than from this body, so one edit to the standard moves every entry.
+
+Two of its rules are the ones a capture pass gets wrong under time pressure. State the rule rather than the incident that produced it, since the session ending is the only reader who has the narrative. Write the `title` as the rule itself, never as the filename stem.
+
+Do not edit the index. `.claude/memory/index.md` is generated from sibling frontmatter by a `PostToolUse` hook, the same way the task board's index is, so a hand-appended row is drift the next regeneration discards.
+
+The hook matches `Write|Edit|MultiEdit`, so nothing fires on the shell writes a linked worktree makes. Regenerate the index once after the last write when the entries went out through `Bash`:
+
+```bash
+canon indexes regen --no-stage --root <main-root> <main-root>/.claude/memory/index.md
+```
+
+Run `canon records validate memory` when the writes are done and fix what it names. It reads the whole pen rather than this session's writes, so treat a finding on a carried entry as one to fix in place rather than as a reason to stop.
+
+## Output
+
+Respond with one line per fact routed, written, or updated:
+
+- `➡️ Routed: <fact subject> → .claude/context/<domain>.md`
+- `✅ Wrote: .claude/memory/<file> (<type>)`
+- `✏️ Updated: .claude/memory/<file> (<type>)`
+
+When anything routed, add a line naming the handoff so the caller knows a `claude-docs` pass is owed:
+
+`→ Routed facts wait at .claude/.tmp/memory-routing/<slug>.md. Run /claude-docs to fold them in.`
+
+Omit that line when the caller runs `claude-docs` itself later in its own chain.
+
+When at least one memory file was written or updated, add a closing line so the standalone caller proposes fixes while context is fresh:
+
+`→ Run /claude-memory-review to propose fixes for the pen before the session ends.`
+
+The ship skills run review Propose themselves, so this line is for the standalone `/claude-memory-capture` path.
+
+If nothing was captured, output:
+
+`✅ Nothing worth capturing.`

package/claude/skills/claude-memory-review/REQUIREMENT.md

@@ -0,0 +1,50 @@
+---
+name: claude-memory-review
+description: What memory review is for, the gaps it closes, and why every action waits on approval
+---
+
+# Claude memory review requirement
+
+## Gap
+
+Without this skill, the memory folder grows and never drains. Entries pile up restating rules a durable surface already carries, nothing decides which memory has earned a place in one, and a rule that does get promoted arrives verbatim in a file whose voice it does not match. The folder then reads as a second source of truth that no surface points at.
+
+A pen the caller cannot face is the same gap wearing a different shape. Routing at capture takes the domain facts and whatever the ownership test leaves stays, in whatever mix of types that is, so the folder still reaches a size nobody reads in one sitting. A ship-time run is scoped to the entries that session captured for exactly that reason, and the full sweep is what an operator asks for when the cross-session duplicates are the point. An entry leaving the pen is archived rather than deleted, because a folder git does not hold gives a wrong bulk call no undo.
+
+## Must
+
+- Treat the folder as a holding pen, so every entry in scope leaves it as a promotion, a handoff, or an archive rather than surviving by default
+- Archive an entry out of the pen rather than deleting it, since nothing recovers a file from a gitignored folder
+- Hand a fact a context entry owns to `claude-docs` through the routing file, rather than editing the entry here
+- Verify the rule is not already stated or implied in the target before proposing a promotion, by reading the target rather than trusting the memory's claim about it
+- Rewrite a rule into the destination's voice instead of moving it unchanged
+- Write the proposal to a receipt on disk and take no action until the user decides per item
+- Route every decision channel through the receipt, writing a decision given in chat into its item's slot before the parse reads the file, so a channel the skill advertises drains the pen rather than passing over it
+- Keep a promotion on its own commit, since a change to how the agent operates should not ride inside a feature a reviewer is vetting for something else
+- Collect a receipt as soon as its last item resolves, rather than waiting for an operator to ask, since a collection nobody triggers is a folder that only grows
+- Fold each declined item into its memory entry before the receipt goes, because a promoted item survives in its target and in git while a decline is recorded nowhere else
+- Record that decline by rewriting the entry rather than appending to it, so the file states one current claim
+- Confine the pass that runs after application to the one receipt it tested, so tidying up removes a file whose decisions are known to be resolved and leaves every untested receipt alone
+
+## Must not
+
+- Apply anything the user has not approved by item
+- Author a governance rule inline. Coding-standards rules have an owner and a scaffolding path, and a rule written here bypasses both.
+- Mutate tracked files from the main worktree
+- Answer a question raised in a decision slot while applying. Discussion and application are separate passes so an approval is never inferred from a reply.
+- Delete a memory entry at all. Every exit from the pen is a move into the archive.
+- Move an entry out of the pen outside the approved-per-item pass. The folder is gitignored with no history behind it, so a removal any other phase makes leaves no record of what it took.
+- Edit a context entry, or hand-edit the generated memory index
+
+## Guards
+
+- No memory folder at the main root: stop
+- The folder holds only its index: stop with a pass, not an error
+- Apply invoked from the main worktree: stop and name the worktree command
+- Cleanup invoked with no receipt on disk: stop with a pass, not an error
+
+## Out of scope
+
+- Writing memories, which `claude-memory-capture` owns
+- Judging whether an entry should have been captured. That is a gate at capture time, and re-deciding it here would delete evidence the capture rule is wrong.
+- Editing the governance rules a handoff points at

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

@@ -0,0 +1,210 @@
+---
+name: claude-memory-review
+description: Reviews `.claude/memory/` and proposes per-entry actions (promote to `CLAUDE.md`, move into a skill body, route to a context entry, hand off to governance, or retire as stale). Also runs the discuss, challenge, apply, and cleanup phases on an existing review file. Use when asked to "review memory", "discuss memory questions", "challenge the promotes", "apply memory decisions", "cleanup memory review", "promote memory", or "consolidate memories". Do NOT auto-apply. Output a grouped proposal and wait for block-by-block approval.
+---
+
+# Claude memory review
+
+This skill drives the full memory review lifecycle in five phases. Pick the phase from what the user said and whether a review receipt already exists at `<main-root>/.claude/review/memory/memory-review-*.md`.
+
+What an entry looks like and why a retired one is moved rather than deleted are fixed by `${CLAUDE_SKILL_DIR}/../../standards/memory.md`. Read it before rewriting an entry, since a promotion rewrites the rule and a rewrite has to leave the entry conforming.
+
+| User intent                                                            | Phase     | Mutates                      |
+| ---------------------------------------------------------------------- | --------- | ---------------------------- |
+| "review memory", "promote memory", "sweep stale memories" (no receipt) | Propose   | review file only             |
+| "challenge the promotes" (receipt exists)                              | Challenge | review file only             |
+| "discuss", "respond to questions"                                      | Discuss   | review file only             |
+| "apply decisions", "commit", "ship the review"                         | Apply     | tracked files + memory files |
+| "cleanup", "delete the receipt"                                        | Cleanup   | one receipt + its skips      |
+
+If the user re-pings the skill with no new phrase and a receipt exists, default to Discuss when any `Decision:` contains `?`, otherwise Apply.
+
+## Guards
+
+- All `.claude/memory/` reads, edits, and archive moves resolve at the main worktree root, not the current worktree. See Worktrees in `CLAUDE.md`.
+- If no `.claude/memory/` directory exists at the main worktree root, stop: `❌ No .claude/memory/ directory found.`
+- If `.claude/memory/` contains no `*.md` entries other than `index.md`, stop: `✅ No memory entries to review.`
+- Cleanup is exempt from the two stops above. It works on receipts in `.claude/review/`, and a drained pen is the normal state once Apply has run, so a pen-shaped stop would strand the receipt it exists to delete.
+- Resolve the main root via `git worktree list --porcelain | grep -m 1 '^worktree ' | cut -d' ' -f2-`, falling back to `pwd`. All review and memory reads anchor here.
+- From a linked worktree the file-editing tools refuse every main-root path, so each write below goes out through `Bash` as a plain single command. The receipt and a memory entry are both short and this session has read them whole, so a rewrite replaces the file with a heredoc rather than editing a line inside it. Promotion targets are tracked files at `pwd` and keep taking `Edit`.
+
+## Propose phase
+
+Propose is the ship-time entry point. The ship skills run it right after capture, so the fix is written while session context is fresh.
+
+### Scope
+
+- **Ship-scoped:** when a ship caller (`git-ship`, `claude-autoship`) names the entries captured this session, classify only those entries. Read the full pen for merge and absorbed comparison, but do not propose actions on carried entries the captures do not touch. Each carried entry was already proposed on in its own ship cycle.
+- **Full sweep:** when invoked standalone with no named set, classify every entry in the pen, including entries carried from earlier sessions, so cross-session duplicates merge into one rule.
+
+### Step 1: read the memory folder
+
+Read in parallel from the project root:
+
+- `.claude/memory/index.md`: the generated index
+- every other `*.md` file under `.claude/memory/`: individual entries with frontmatter (`title`, `description`, `category`)
+
+### Step 2: read promotion targets
+
+Read in parallel from the project root. Skip any file or folder that does not exist.
+
+- `CLAUDE.md`: project behavior rules and Content ownership section
+- every `SKILL.md` under `.claude/skills/`: domain-scoped internal skill bodies
+- every `SKILL.md` under `claude/skills/`: plugin skill bodies
+- every `*.md` under `${CLAUDE_SKILL_DIR}/../../standards/`: authoring references
+- every `*.md` under `governance/rules/` in the toolkit repo, or `.claude/rules/` in a target project: coding-standards rules
+
+### Step 3: classify each entry
+
+`.claude/memory/` is a holding pen. Default every entry to promote or retire on review. Skip is the rare exception, reserved for active task overlap or user-type memories with no in-repo target.
+
+`claude-memory-capture` routes a project fact naming a domain with a context entry to that entry, so a pen filled since routing shipped is mostly feedback: rules about how to work, which no context entry owns. Propose against what the pen holds rather than expecting the older mix. An entry carried from before routing may still name a domain that has a context entry, and that entry's action is **Promote to a context entry**, which hands it to `claude-docs` the same way capture does rather than editing the entry here.
+
+For each in-scope entry (see Scope), pick one action:
+
+- **Promote to `CLAUDE.md`**: the rule is cross-domain behavior or a design principle applied across the whole project.
+- **Promote to a skill body**: the rule fires only when editing a specific path-scoped domain. Name the target skill.
+- **Promote to a standards file**: the rule is an authoring reference that belongs in the project's own standards folder as `<domain>.md`.
+- **Promote to a context entry**: the entry states a fact about a domain carrying an entry in `.claude/context/index.md`. Append it to `.claude/.tmp/memory-routing/<slug>.md` in the format `claude-memory-capture` writes, and tell the user to run `/claude-docs` from a branch. Do not edit the context entry here.
+- **Hand off to governance**: the rule is coding-standards class (typescript, testing, naming, error-handling, performance, logging, concurrency, planning). Do not author the rule file inline. Never edit the synced `.claude/rules/` copies of toolkit rules, because `canon gov sync` overwrites them. Stop at handoff.
+  - In the toolkit repo, point the user at `internal-governance` and `${CLAUDE_SKILL_DIR}/../../standards/rule.md`, which own the source-of-truth rules under `governance/rules/`.
+  - In a target project, point the user at the `create-rule` skill, which scaffolds a project-local rule under `.claude/rules/`.
+- **Retire**: the rule is stale, already absorbed into a durable surface, too vague to phrase as a rule, or a one-time incident narrative. Apply moves the file to `.claude/.tmp/memory-archive/` rather than deleting it.
+
+Retire is an archive, not a deletion, which `${CLAUDE_SKILL_DIR}/../../standards/memory.md` states as the rule and this skill executes. The archive is worth less than a plan's, since a promoted entry survives in its destination and a stale one is discarded on purpose, which is why the move is cheap rather than free.
+
+When two or more memories collapse into one rule on the same target, propose them as a single merged edit under the matching promote category. The consolidate case is a variant of promote, not a separate action.
+
+#### Absorbed-already check
+
+Before proposing promote, grep the target surface for the rule's keywords. If the rule is already stated there, the action is **Retire**, not promote. Do not rely on memory-file claims that a rule is documented elsewhere. Verify.
+
+The check covers implication, not only keyword match. If an adjacent bullet in the target section already implies the rule, merge into that bullet rather than append a second.
+
+#### Crispness check
+
+Rules that resist crisp one-line phrasing default to **Retire** over promote. Never promote a memory unchanged. Rewrite to match the destination surface's tone. Use terser phrasing for `CLAUDE.md` and imperative phrasing for skill bodies.
+
+### Step 4: write the proposal to the review file
+
+Derive `<slug>` per `${CLAUDE_SKILL_DIR}/../../standards/slug.md`. Fall back to `latest` on an empty result.
+
+Write the full proposal to `.claude/review/memory/memory-review-<slug>.md` at the main worktree root. Do not print it inline. Read `${CLAUDE_SKILL_DIR}/references/receipt-format.md` for the file structure, the item template, and how each action type varies the body. The four phases below rewrite items inside an existing receipt rather than authoring one, so none of them opens it.
+
+A phase changing items reads the receipt, applies every change for that phase, and writes the whole file back in one command. Batching is what keeps a per-item rewrite from costing a full read each time, and it is the only route from a linked worktree, where the guard above rules out editing a line in place.
+
+Tell the user `✅ Wrote proposal to .claude/review/memory/memory-review-<slug>.md`. Ask them to fill in `Decision:` per item, then re-ping with "discuss" for question rounds or "apply" to commit.
+
+Rewrite the review file in place whenever the proposal changes mid-review. The file stays the source of truth for the current decisions.
+
+## Challenge phase
+
+Trigger: user says "challenge the promotes", "challenge before apply", or asks for a high-bar pass. Run before Apply. No mutations to memory files or promotion targets. Review file only.
+
+1. Read the latest `.claude/review/memory/memory-review-*.md` at the main root.
+2. For each promote item, apply three tests:
+   - **Absorbed**: grep the target surface for the rule's keywords. If already stated or implied, flip to retire.
+   - **Delta**: if the rule is a nice-to-have next to existing bullets, flip to retire.
+   - **Generality**: if the rule fires only on one literal trigger phrase, rewrite broader or flip to retire.
+3. Rewrite the review file in place with the updated actions and a one-line reason under each flip.
+
+## Discuss phase
+
+Trigger: user says "discuss", "respond to questions", or any `Decision:` value contains `?` or an unrecognized verb. No mutations to memory files or targets. Review file only. Multi-round.
+
+1. Read the latest `.claude/review/memory/memory-review-*.md` at the main root.
+2. For each item whose `Decision:` contains `?` or any unrecognized verb (anything other than `apply`, `skip`, `defer`):
+   - Write a `Take:` line under `Decision:`, separated by exactly one blank line. If a `Take:` line already exists, overwrite it.
+   - Format: pick + one-line reason. Max 2 sentences. Decision-help style. State the recommendation (`apply` / `skip` / `retire` / specific alternative) first, then the reason. Do not enumerate tradeoffs unless one changes the call.
+   - Leave the H2 emoji as 📝 pending.
+3. Skip items whose `Decision:` is `apply`, `skip`, `defer`, or empty.
+4. End with: `💬 Discussed: <nums> | ⏩ Skipped (committed or empty): <nums>`. Remind the user to refine `Decision:` lines and re-ping with "discuss" for another round, or "apply" when ready to commit.
+
+Do not act on any item. Do not archive memory files. Do not edit promotion targets. Discuss only.
+
+## Apply phase
+
+Trigger: user says "apply", "commit", "ship the review", or re-pings with no question items remaining. Mutates tracked promotion targets and moves memory files into the archive.
+
+Before applying any item, check the worktree state:
+
+```bash
+[ "$(git rev-parse --git-dir 2>/dev/null)" = "$(git rev-parse --git-common-dir 2>/dev/null)" ] && echo "MAIN" || echo "LINKED"
+```
+
+If the result is `MAIN`, stop and tell the user: `❌ Apply phase mutates tracked files. Run /claude-worktree first.` Discuss and Challenge phases only touch `.claude/review/` scratch and run from anywhere.
+
+Before applying a promote to root `CLAUDE.md`, load `internal-claude` so its seed-mirror rule fires on the edit.
+
+Promotions are a separate concern from any feature in flight. Keep the promoted edits on their own commit. Do not fold a `CLAUDE.md` or skill-body change into a feature's commits, because a feature reviewer should not have to vet a change to how the agent operates.
+
+For each item, parse the `Decision:` line:
+
+- `apply` (or affirmative): run the proposed action, flip emoji to ✅.
+- `skip`: leave the memory in place, flip emoji to ⏭.
+- `defer` or empty: leave 📝 pending, take no action.
+- Contains `?` or unrecognized verb: leave 📝 pending, take no action. Do not respond. Discussion is the Discuss phase's job.
+
+Free-form text after the verb is a reason. Capture it in the receipt but do not let it change the action. When committing an item, strip any empty `Take:` line so the receipt stays clean. `Take:` lines with content stay as discussion history.
+
+Action by action type:
+
+- **Promote**: use `Edit` to insert the rewritten rule into the target surface, then archive the memory file.
+- **Promote to a context entry**: append the fact to `.claude/.tmp/memory-routing/<slug>.md`, then archive the memory file. `claude-docs` folds it in on its next run from a branch, which is what keeps one skill writing context entries.
+- **Hand off**: do not edit governance. Archive the memory file only if the user confirmed the handoff explicitly. Otherwise leave it in place.
+- **Retire**: archive the memory file.
+
+Archiving means creating `.claude/.tmp/memory-archive/` at the main worktree root and moving the file there under its original name, overwriting any file already at that name. Send the `mkdir -p` and the `mv` as two plain commands rather than joining them with `&&`, which is refused as compound from a linked worktree. Never delete a memory entry. Nothing recovers one from a gitignored folder.
+
+Do not hand-edit `.claude/memory/index.md`. Once every archive move is done, regenerate it instead:
+
+```bash
+canon indexes regen --no-stage --root <main-root> <main-root>/.claude/memory/index.md
+```
+
+The `PostToolUse` hook that keeps the index current matches `Write|Edit|MultiEdit`, and an archive move is a shell `mv`, so nothing fires on it. Without this call the index keeps a row per archived entry and drifts exactly the way the hand-appended one did. Run it once after the last move rather than per item.
+
+Apply promotion edits one at a time via `Edit`. Claude Code's tool permission dialog is the confirmation gate per edit. Never rewrite a whole promotion target.
+
+This governs the tracked surfaces a promote lands in, which sit at `pwd` and take `Edit` from anywhere. The receipt and the memory entries are main-root scratch and follow the guard instead.
+
+As each item resolves, update its status in the review file: flip the H2 emoji from 📝 to ✅ for applied, ⏭ for skipped, 📦 for retired, or 🤝 for handed off. Refresh the summary block counts at the top. Do not delete the file here. The sweep below decides whether it goes.
+
+**Chat shortcut:** the user replies with `all`, `none`, a comma-separated list of numbers, or `skip <nums>`. Write the matching verb into the `Decision:` slot of every item the reply names, `apply` for `all` or a bare list and `skip` for a `skip` reply, then run the parse above against the file. A reply of `none` writes nothing. A slot the reply does not name keeps its own value, so the receipt stays the source of truth and an empty slot still means take no action.
+
+### Sweep the receipt
+
+Count the items still 📝 pending once the parse above has run. Apply leaves one pending on `defer`, on empty, and on any unrecognized verb, so a receipt reaching this point may still be holding decisions.
+
+Leave the receipt in place when any remain. When none do, collect it per the collection rule in `${CLAUDE_SKILL_DIR}/../../standards/memory.md`, which owns what a fold writes and which entry types take one.
+
+`claude-docs` Step 10 sweeps the same folder on the same rule once per shipped branch, and either may reach a receipt first. Whichever does, the other finds no file and moves on.
+
+End with: `✅ Applied: <nums> | ⏭ Skipped: <nums> | 📝 Pending: <nums>`. Omit empty buckets. If anything is pending, remind the user they can refine `Decision:` lines and re-ping, run "discuss" for question items, or commit a skip with `skip <nums>` in chat.
+
+## Cleanup phase
+
+Trigger: user says "cleanup" or "delete the receipt" after Apply has run.
+
+Cleanup folds one receipt's skips and removes that receipt, and does nothing else. It is the fallback route now that Apply and `claude-docs` Step 10 each collect a resolved receipt on their own, so it reaches a file those two left behind rather than being the only collector. Apply is still the only phase that moves a memory entry out of the pen, and it does so per approved item into `.claude/.tmp/memory-archive/`. A user asking to sweep stale memories wants Propose, which classifies entries and writes a decision slot per entry.
+
+If no `.claude/review/memory/memory-review-*.md` exists at the main root, stop: `✅ No review receipt to clean up.` Every other refusal in this skill carries a message, and the phase reads a receipt before it does anything else.
+
+1. Read the latest `.claude/review/memory/memory-review-*.md` at the main root and confirm Apply has run against it. If any item is still 📝 pending, stop and name the pending numbers.
+2. Collect it per the collection rule in `${CLAUDE_SKILL_DIR}/../../standards/memory.md`, folding each ⏭ skipped item before the file goes. The fold happens wherever a receipt is collected, so this phase runs the same rule the Apply sweep does.
+3. Delete that one file. Leave every other receipt beside it in place, because the pending test above covers the file it read and nothing has tested the rest.
+4. Leave every memory entry in the pen. A skip records the decline on the entry and keeps the file, and applied promotions, governance handoffs, and user-type memories each stay as the review left them.
+
+Do not promote or archive a memory entry. The skip fold is the one rewrite this phase makes, and it records a decline on an entry that stays in the pen.
+
+## After completion
+
+Output one line per action taken in the most recent phase:
+
+- `✅ Promoted: .claude/memory/<memory-file> → <target>`
+- `✅ Handed off: .claude/memory/<memory-file> → governance`
+- `📦 Retired: .claude/memory/<memory-file> → .claude/.tmp/memory-archive/`
+- `🗑  Swept: .claude/review/<review-file>, folded <n> skips`
+- `⏭ Kept: .claude/review/<review-file>, <n> items pending`
+
+If the user accepted nothing, output: `✅ No changes applied.`

package/claude/skills/claude-memory-review/references/receipt-format.md

@@ -0,0 +1,48 @@
+---
+title: Memory review receipt format
+description: The proposal file structure, its item template, and how each action type varies the body
+---
+
+# Memory review receipt format
+
+The shape Step 4 of the Propose phase writes to `.claude/review/memory/memory-review-<slug>.md`. Only Propose writes this file. Challenge, Discuss, and Apply rewrite items inside a receipt that already exists, and Cleanup deletes one, so none of the four needs this file.
+
+## Structure
+
+A summary block at the top, a legend, then one H2 per numbered item. Number items across all actions so the user can reference them by number. Fuse the status, action, and target into each H2. Put the memory filename on its own line, a one-line Why, the rewritten rule inline in a fenced `diff` block prefixed with `+` so reviewers see the additions in green, and a `Decision:` slot for the user.
+
+Do not include a `Take:` slot in the template. Discuss inserts one directly under `Decision:` only when responding to a question item. Status starts as 📝 pending for every item at proposal time.
+
+````plaintext
+# Memory review: <slug>
+
+**Pending:** <all numbers>
+
+Legend: ✅ applied · ⏭ skipped · 📦 retired · 🤝 handed off · 📝 pending
+
+How to respond: fill in `Decision:` per item (`apply`, `skip`, `defer`, or a question with `?`), then re-ping the skill. Say "discuss" for question rounds, "apply" to commit. Chat shortcut: `all`, `none`, or a list of numbers.
+
+## 1. 📝 Promote → `<target>`
+
+`<memory-file>`
+
+Why: <one-line pulled from the memory's Why>
+
+```diff
++ <rewritten rule text>
+```
+
+Decision:
+
+## 2. 📝 Retire
+
+`<memory-file>`
+
+Reason: <one-line reason>
+
+Decision:
+````
+
+## Variation by action
+
+For Hand off items, the body is a pointer to the governance target instead of a rewritten rule: `internal-governance` and `${CLAUDE_SKILL_DIR}/../../standards/rule.md` in the toolkit repo, or the `create-rule` skill in a target project. For Retire items, skip the rewrite block. Every item gets a `Decision:` slot regardless of action. `Take:` is added only when a question response is needed.