@erclx/canon 4.0.0

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

@@ -0,0 +1,142 @@
+---
+name: claude-groundwork
+description: Opens and runs a numbered groundwork folder under `.claude/groundwork/<nn>-<slug>/` for a topic that has to be measured before it can be planned. Detects open, resume, and close from the folder itself. Use when asked to "research X", "dig into X", "work out what we should do about X", "measure this before we commit", or "open a groundwork folder". Do NOT use to write a feature plan or to implement. That is `claude-feature`.
+---
+
+# Claude groundwork
+
+Groundwork gathers and weighs. A plan commits. A groundwork folder costs nothing to throw away, which is what makes it the right container for a question nobody has answered yet.
+
+Read `${CLAUDE_SKILL_DIR}/../../standards/groundwork.md` before writing any file in the folder. It holds the reserved numbers, the frontmatter and dating rules, what each required file carries, the conventions, and the anti-patterns. Do not work them from memory.
+
+## Guards
+
+- If no topic is given, stop: `❌ No topic. Name what needs measuring.`
+- Apply the qualifying test in open mode alone, after Step 1 resolves the mode and before the folder is created. Two of these three must hold: the current state is not known, more than one approach is live, and committing wrong costs more than a day of measuring. When one or fewer holds, stop: `❌ Already decided enough to plan. Run /claude-feature instead.`
+- Resume and close are exempt from the test above. A track that has already been measured fails it by definition, since its current state is now known and its approaches have narrowed, so applying the test to either mode refuses the folder that same test admitted.
+- A refused topic that is a broad dump rather than one question routes to `claude-intake`, not to the planning skill the stop names. Intake dispositions many findings in breadth from what the repository already holds, and one folder holding dozens of unrelated threads is what forcing them past this guard produces.
+- Do not pause for approval between steps. The write scope below is what makes that safe.
+
+## Write scope
+
+- Write only inside `.claude/groundwork/<nn>-<slug>/`. A feature plan, source changes, a standard, a rule, and a reference doc all live outside that folder, so this one rule forbids every one of them.
+- One exception, at close only: write one task file recording what the track concluded.
+- A second exception, for what a spike reads: write an input under `.claude/.tmp/groundwork-fixtures/<slug>/`. Keep it out of `.claude/groundwork/` so mode detection never matches a fixture as a track. A fixture a headless run is pointed at goes outside the repository instead, per the rule in `## Running a spike`.
+- What a spike produces stays inside the track rather than joining the two exceptions above: write evidence a spike file cites under `.claude/groundwork/<nn>-<slug>/evidence/`, which the first rule already permits. Mode detection matches entries at the top level of the tracks directory, so the sibling the fixtures rule guards against cannot be a folder nested inside a track, and the scratch path holds only what can be deleted without loss, which a recording a finding rests on is not.
+- Reading is not restricted. External research is in scope, so read documentation, comparable projects, and papers whenever a live question needs them.
+- Every claim about a source outside the project carries a link to it. A source found and not read is listed as a lead and is never cited.
+- Treat the folder as gitignored and unbacked. It dies with the machine, so `07-next-session.md` repeats what it needs instead of pointing at its siblings.
+
+## Running a spike
+
+A track may run an experiment to settle an open question without stopping to ask. What it takes depends on what the experiment does.
+
+- Reading or computing: run it. Unrestricted reading already covers this, and it is what most spikes turn out to be.
+- Writing a fixture this session reads or provisions itself: run it, under the fixtures path above. Provisioning is the usual blocker rather than spend, and it costs nothing.
+- Spawning a billed headless session: run up to three, then ask before spawning more. The bound is a run count rather than a budget, because a headless run reports its total cost only after it finishes, so a dollar ceiling is reportable and not enforceable while a run count is checkable before spawning.
+
+A fixture a headless run is pointed at goes outside the repository, under `mktemp -d`, and never under `.claude/.tmp/`. A session started anywhere beneath the project root loads that project's `CLAUDE.md` and `.claude/rules/` through the ancestor chain, so an in-repo fixture measures the repository instead of the arm. Record the fixture as contaminated and re-run it outside if this is discovered after the fact, because the result reads as evidence either way.
+
+Record method, result, measured cost, and caveats in `08-spikes.md`. Put whatever the run produced that the record cites in `evidence/` beside it, so a reader checking a claim opens the artifact rather than taking the prose for it. Reach for a test harness the project already carries before building one, and copy how it isolates its fixture rather than only what it asserts.
+
+## Step 1: detect the mode
+
+List `.claude/groundwork/` from the project root and match the topic against the slug half of each `<nn>-<slug>` folder already there before deriving anything. A resume pass rarely phrases the topic the way the folder was named, so a fresh slug derived from the wording would miss a live track and restart it.
+
+Never match against `.claude/` itself. That directory holds every other workflow surface, so a topic matched there lands on a folder that was never a track.
+
+With no match, derive a kebab-case slug named for the subject rather than the activity. Prefer `ts-migration` over `migration-research`. Also list `.claude/intake/` and take `<nn>` as the highest ordinal present across both listings, incremented, per `${CLAUDE_SKILL_DIR}/../../standards/groundwork.md`. Then route on `.claude/groundwork/<nn>-<slug>/`:
+
+- Folder absent: open
+- Folder present without `06-decision.md`: resume
+- Present folder the user judges ready: close
+
+Detect the mode from the folder. Do not ask which one to run.
+
+## Step 2: orient
+
+Read these in parallel from the project root, skipping any that do not exist:
+
+- `CLAUDE.md`: behavior rules, conventions, commands
+- `.claude/REQUIREMENTS.md`: scope and non-goals
+- `.claude/ARCHITECTURE.md`: decisions already made
+- `.claude/tasks/index.md`: what is already tracked, and what a prior track concluded. Open a task file only when its entry looks related.
+
+Then read only what a live question needs. Do not read entire directories speculatively. Where a folder carries an `index.md`, read it first and load only the files it points at.
+
+Do not dispatch subagents. A groundwork track is a conversation, and fanning out loses the reasoning that makes the folder worth keeping. A search too large to run inline is a finding that the question is too broad.
+
+## Open questions in chat
+
+The standard sets the open question format and requires it inside a topic file and in `00-scope.md`. Carry the same shape into the chat output, which sits outside the folder the standard governs. A bare numbered list hands the reader a quiz and defers the judgment the track exists to inform.
+
+## Open mode
+
+1. Create `.claude/groundwork/<nn>-<slug>/`, with `<nn>` and `<slug>` as derived in Step 1.
+2. Write `README.md` first. Writing it first forces the question of what the track is for.
+3. Write `01-current-state.md` by measuring now. Never carry a figure from a previous session or from recall without re-measuring it. Measure only what an open question in the folder needs. A number with no question attached is how groundwork turns into the work.
+4. Write `00-scope.md` when the track is large enough to run away. Skip it on a small track.
+5. Add topic files at `02` through `05` as the subject demands. Close each one with its open questions in the standard's format.
+6. Keep going. Revise, reframe, and take correction as the questions move. The folder is meant to be rewritten.
+
+## Resume mode
+
+1. Read `README.md` and its file map first, then the numbered files in order.
+2. Do not re-measure what `01-current-state.md` holds unless the project moved under it. When it did move, re-measure and mark what changed.
+3. Continue from the open questions carried at the end of each file. Add or rewrite files as those questions move.
+4. Update the file map in `README.md` whenever a file is added or retired.
+
+## Close mode
+
+1. Write `06-decision.md`. It states the problem once, names the goal, lists what to do, and lists what was considered and dropped.
+2. Write `07-next-session.md` self-contained, so it survives a compaction that loses the conversation.
+3. Update the file map in `README.md`.
+4. Write one task file in `.claude/tasks/` recording what the track concluded, even when the conclusion is to do nothing. Follow `${CLAUDE_SKILL_DIR}/../../standards/tasks.md` for the filename and frontmatter. Aside from an experiment fixture, this and the routing in Step 5 are the only ways close mode reaches outside the folder.
+5. When the task written in Step 4 does not cover every finding the track surfaced, route what it leaves out through `claude-intake`. Skip this step when it does.
+6. Report uncited external claims. Closing already reads every file in the folder, so list any statement about a source outside the project that carries neither a link nor a lead entry. Report and do not block, because judging whether a sentence makes an external claim is the call a checker gets wrong.
+
+Do not close while an open question quietly fails an outcome. Resolve it, or record it in `06-decision.md` as knowingly accepted.
+
+## Output
+
+Emit the full relative path from the project root for every file written or updated. A bare filename names a file the reader cannot open.
+
+Open and resume:
+
+```plaintext
+📂 Opened .claude/groundwork/<nn>-<slug>/
+
+**Written:**
+
+- `.claude/groundwork/<nn>-<slug>/README.md`
+- `.claude/groundwork/<nn>-<slug>/01-current-state.md`
+
+**Open questions:**
+
+1. <question>
+   - Leaning: <where the evidence currently points>
+   - Overturned by: <the finding that would change it>
+```
+
+Use `📂 Resumed` in place of `📂 Opened` on a resume pass.
+
+Close:
+
+```plaintext
+✅ Closed .claude/groundwork/<nn>-<slug>/
+
+**Written:**
+
+- `.claude/groundwork/<nn>-<slug>/06-decision.md`
+- `.claude/groundwork/<nn>-<slug>/07-next-session.md`
+
+**Uncited external claims:** <count, or none>
+
+- `<file>`: <the claim>
+
+<the decision in one line>
+
+Next: /claude-feature
+```
+
+Omit the uncited-claims block when the count is zero.

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

@@ -0,0 +1,49 @@
+---
+name: claude-intake
+description: Why a brain dump gets a filed inventory rather than ten plans, and why an empty operator slot means unread
+---
+
+# Claude intake requirement
+
+## Gap
+
+Without this skill, a brain dump reaches a session that has nowhere to put it. `claude-feature` answers with one plan per independent concern, so forty findings produce ten plan files before anything has been measured. `claude-groundwork` refuses a breadth pass outright, since its qualifying test asks whether the current state is unknown and most items are knowable by grep. What gets filed instead is a list of opinions, because nothing forces a count against the tree and a complaint reads the same whether it covers three sites or three hundred.
+
+Two failure modes cost more than the rest. An operator's silence on an item reads as consent when the folder borrows the plan file's blank-means-accept contract, which ships changes nobody approved across a folder read over weeks. And a report naming only a path cannot distinguish three new items from one reworded sentence in a file that holds a dozen items, so every reader diffs it against memory to find out what moved.
+
+Four more are cheaper to name than to rediscover. A question filed without a pick comes back unresolved, measured across one folder's 19 open items, where every one carrying a suggestion resolved on a bare `ok` and the five carrying none did not.
+
+A session with no numbering convention re-decides the folder shape per dump, so no two intakes are readable the same way and the second one has to be learned from scratch. A question answerable both in the index and on its item resolves to whichever a reader opens first, with no rule saying which wins. And a pass with no write scope starts fixing what it files, which turns a triage into a branch nobody asked for and nobody reviewed.
+
+## Must
+
+- Route each item on whether the repository can answer it today, sending what needs an experiment or an outside source to the groundwork skill and what is already decided to the planning skill
+- Measure every problem line against the tree during this pass, carrying a number or a file path rather than a figure from recall
+- Close every item with a verdict, and pair every open question with a suggested pick
+- Treat an empty operator slot as unread rather than as agreement
+- Reserve the index number and carry the domain in every other filename, leaving the rest of the numbering as read order
+- Name a newly opened folder with a two-digit ordinal ahead of the slug, taken from the highest one already present across intake and groundwork
+- Keep answers on items alone, with the index pointing at them
+- Name the heading and the act beside every path the pass wrote
+- Confine writes to the intake folder
+
+## Must not
+
+- Write a plan, a task file, a standard, a rule, or a source change
+- Fill an operator's answer slot, or infer a disposition from an empty one
+- Replace a verdict with an overlap line, which drops the call on exactly the items where a live board task might be the thing that is wrong
+- Reserve mid-range numbers, which would force every future intake into one dump's shape
+- Date every file, since the first edit to one leaves the rest stale
+- Open a folder for a single question, which is either a groundwork track or a plan
+
+## Guards
+
+- No dump given: stop rather than inferring one
+- One question rather than a set of findings: stop and route to the groundwork or planning skill
+
+## Out of scope
+
+- Measuring one question in depth, which `claude-groundwork` owns
+- Planning a promoted item, which `claude-feature` owns
+- Promoting an item onto the board, which `claude-tasks` owns
+- Enforcing any of this. The folder is gitignored, so no check reaches its contents and every rule holds only while a session reads it.

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

@@ -0,0 +1,114 @@
+---
+name: claude-intake
+description: Files a raw brain dump into a numbered intake folder under `.claude/intake/<nn>-<slug>/`, one item per finding carrying a measured problem, a proposed fix, and a verdict. Use when asked to "file this dump", "triage my notes", "work through this list", "sort out this brain dump", or "run an intake pass". Do NOT use for one question that has to be measured before anyone can plan it. That is `claude-groundwork`.
+---
+
+# Claude intake
+
+Intake dispositions many findings in breadth. A dump goes in, an inventory comes out, and every item carries a problem measured against the tree, one proposed fix, and a verdict. The item that turns out to be already settled is the highest-value output, and it is the one thing neither a plan nor a groundwork track has anywhere to put.
+
+Read `${CLAUDE_SKILL_DIR}/../../standards/intake.md` before writing any file in the folder. It holds the numbering, the file map, the frontmatter and dating rules, the item format, and the answer contract. Do not work them from memory.
+
+## Routing
+
+The test is one question. Can the item be answered by reading the repository today?
+
+- Yes: intake owns it, and the cost is a session of grepping
+- No, because it needs an experiment or a source outside the project: route it to `claude-groundwork`, where the cost is measured in runs and days
+- Already decided, with only the work left: route it to `claude-feature`
+
+Apply the test per item rather than per dump. A dump of forty items typically yields one groundwork candidate, so routing the whole dump on its worst item buys a folder nobody can close.
+
+Using the wrong one fails in two shapes. Intake on a question that needs measuring yields a confident verdict with nothing behind it. Groundwork on a brain dump is refused by its own qualifying guard, and forcing past that refusal gives one folder holding dozens of unrelated threads and a decision file that can close one of them.
+
+## Guards
+
+- If no dump is given, stop: `❌ No dump to file. Paste the notes or name what to triage.`
+- If the dump is one question rather than a set of findings, stop: `❌ One question, not a dump. Run /claude-groundwork to measure it or /claude-feature to plan it.`
+- Do not pause for approval between steps. The write scope below is what makes that safe.
+
+## Write scope
+
+- Write only inside `.claude/intake/<nn>-<slug>/`. A plan file, a task file, a source change, a standard, and a rule all live outside that folder, so this one rule forbids every one of them.
+- There is no exception. Promoting an item onto the board runs through `claude-tasks` after the operator has answered, which is a separate invocation.
+- Reading is unrestricted inside the project. Measuring is the work.
+- Treat the folder as gitignored and unbacked. No check reaches its contents, so every rule stated here holds only while a session reads it.
+
+Nothing outside this body carries the write-scope floor, and no path-scoped rule can. A misrouted write lands on a path the folder's glob never matches, so the rule that ships beside the intake standard carries the item format and the answer contract instead, for a session editing the folder with this skill unloaded.
+
+## Step 1: detect open or resume
+
+List `.claude/intake/` from the project root and match the topic against the slug half of each `<nn>-<slug>` folder already there before deriving a slug. A second pass over the same subject rarely phrases the topic the way the folder was named, so a fresh slug would open a duplicate beside a live folder.
+
+Never match against `.claude/` itself. That directory holds every other workflow surface, so a topic matched there lands on a folder that was never an intake.
+
+With no match, derive a kebab-case slug named for the subject rather than the activity. Prefer `toolkit-overview` over `august-triage`. Also list `.claude/groundwork/` and take `<nn>` as the highest ordinal present across both listings, incremented, per `${CLAUDE_SKILL_DIR}/../../standards/intake.md`. An absent folder opens, and a present one resumes by appending items and revising verdicts the tree has moved under.
+
+## Step 2: orient
+
+Read these in parallel from the project root, skipping any that do not exist:
+
+- `CLAUDE.md`: behavior rules, conventions, commands
+- `.claude/REQUIREMENTS.md`: scope and non-goals
+- `.claude/ARCHITECTURE.md`: decisions already made
+- `.claude/tasks/index.md`: what is already tracked. Open a task file whose entry looks related to an item.
+
+Then read only what a live item needs. Do not read entire directories speculatively. Where a folder carries an `index.md`, read it first and load only the files it points at.
+
+## Step 3: measure against the tree
+
+Grep for each construct an item names and count the sites. Every problem line carries a number or a file path taken during this pass.
+
+Never carry a figure from an earlier session, a summary, or another document. The dump states the complaint and the tree states the size of it, and that measurement is the whole difference between an inventory and a list of opinions. Confirm that any work an item sequences behind is still open, so no item leads with something that already shipped.
+
+Name the commit the pass measured against in the overview body. It is the half a later reader can check.
+
+## Step 4: cluster
+
+Split items by domain, one file per cluster, and let the file count follow the number of separable domains rather than the size of the dump. An item belongs to the domain its fix touches, not the domain the complaint arrived from.
+
+Two heading levels is the right depth. A third means the cluster should have been split into its own file.
+
+## Step 5: disposition each item
+
+Write every item in the standard's item format, in the cluster file its fix belongs to. Close each item with a verdict and an empty operator slot, and never fill that slot or read an empty one as agreement.
+
+Where an item's call is the operator's, pair it with a suggestion rather than a bare question. The toolkit's `decision-help` snippet writes the same shape for chat use, and the standard's item format is the whole spec.
+
+## Step 6: write the index
+
+Write `00-overview.md` last, once the clusters are filed and the counts are real. It carries the cluster table, the verdict counts, the ready list, and the open questions.
+
+Each open question in the index is a labeled markdown link to its owning item's heading anchor. The index points and the item owns, so no answer slot appears in the index. One question in two answerable places has no rule for which wins, and retrieval walks item headings, so an answer typed into the index is found by nothing and lost silently.
+
+Add `99-next-session.md` only where the pass ends holding context no cluster file carries, such as a dump half filed or a measurement that has to be redone. Write it self-contained, since the folder is unbacked and the conversation behind it compacts away.
+
+## Output
+
+Emit the full relative path from the project root for every file written, and name the heading and the act beside it. A path alone cannot distinguish three new items from one reworded sentence in a file that holds a dozen items and lives for weeks, so a bare path sends the reader to diff it against memory. This overrides the paths-only reporting the project states generally, which stays right wherever the reader is about to see a diff.
+
+A file the pass only read gets no line, which is what keeps the block short.
+
+```plaintext
+📂 Opened .claude/intake/<nn>-<slug>/
+
+**Filed:**
+
+- `.claude/intake/<nn>-<slug>/05-coverage.md` gains items 6 to 8 under a new `## What the merge gate covers`
+- `.claude/intake/<nn>-<slug>/00-overview.md` cluster rows and verdict counts updated
+
+**Routing:** <N> plan-ready, <N> groundwork candidates, <N> already settled
+
+**Open questions:** <N> awaiting your call
+
+Next: /claude-intake-answer to answer the `You:` slots from here, or type them
+into the files, then /claude-tasks to promote what is ready
+```
+
+Use `📂 Resumed` in place of `📂 Opened` on a resume pass.
+
+## Answering what this pass wrote
+
+The slots this pass leaves empty are answered by editing each cluster file, or from chat through `claude-intake-answer`, which walks the unread items in batches and writes each selection back onto the item it answers. Name that route in the closing line so the operator finds it where they look for it.
+
+Do not invoke it from here. It is operator-triggered, and a pass that files a dump and answers it in the same run decides items on silence.

package/claude/skills/claude-intake-answer/REQUIREMENT.md

@@ -0,0 +1,48 @@
+---
+name: claude-intake-answer
+description: Scope boundary for answering a filed intake from chat, and the write-back contract that keeps the file rather than the conversation as the record
+---
+
+# Claude intake answer requirement
+
+## Gap
+
+Without this skill, an operator answers a filed intake by opening each cluster file and typing under each item, so a dump spanning six clusters is six files navigated in turn and the cost scales with how well the pass split the domains. The folders that go unanswered are the large ones, which are the ones a breadth pass exists to produce.
+
+A session asked to help with that fails in shapes the intake standard already names. It reads an empty slot as agreement and reports items decided that nobody reached. It writes an answer into the conversation and never into the file, so the record still reads as unread and the next session re-asks. It types the answer into `00-overview.md`, where retrieval walks item headings and finds nothing. It overwrites a slot the operator already filled, discarding a decision already made.
+
+The write itself fails a fourth way that no prose rule prevents. Every worker runs in a linked worktree where the file-editing tools refuse a main-root path, and a stream editor expands an unescaped ampersand in the replacement to the whole match and exits zero when it matches nothing. A body instructing either route reports success and loses the answer.
+
+The batching fails a fifth way. A folder holding thirty unread items put as thirty questions is unanswerable, and put as one flat batch it hides which cluster the operator is in and leaves a file half answered when attention runs out.
+
+## Must
+
+- Offer every item carrying an empty answer slot, not only the ones carrying an open question, since the standard's one-token accept exists for a verdict with no question attached
+- Batch by cluster in the folder's own numbering, so the operator has a stopping point that leaves whole clusters unread rather than a file half answered
+- Cap a batch at four items, which is what a structured question tool takes
+- Rank the item's own suggestion or verdict first and give every option what it costs, since the pass already made a recommendation and burying it asks the operator to re-derive it
+- Land every selection through a verb that resolves the root in-process and rewrites the whole line, which is the only route that works from a linked worktree
+- Write one cluster per call, since concurrent calls against one file race on the read and keep only the last answer
+- Carry the cluster and the label together, because items are labeled per file and a label alone names an item in every cluster at once
+- Pass a label exactly as its heading spells it, letter suffix included, since a pass that splits a finding after the fact labels the halves rather than renumbering the file
+- Report what stays unread by count after each cluster
+
+## Must not
+
+- Fill a slot the operator did not answer, including the remainder of a batch they abandoned
+- Infer an answer from the conversation having happened, which is the inversion the intake standard states against the plan standard
+- Overwrite a slot already carrying an answer, which is a decision already made
+- Write anywhere in the folder but an item's answer slot, and never into the index, which carries none
+
+## Guards
+
+- No intake folder at all, stop and name the skill that files one
+- The named folder carrying no unread item, stop rather than re-asking answered items
+
+## Out of scope
+
+- Filing a dump and writing the items, which is `claude-intake` and owns every other write into the folder
+- Promoting an answered item onto the board, which is `claude-tasks` and runs after the answers land
+- The item format, the answer contract, and retrieval, which the toolkit's `standards/intake.md` owns and this skill cites
+- The comparable answer slots in groundwork and feature plans, which carry their own contracts and are a separate measurement
+- Deciding when to fire. The skill is user-invoked through `disable-model-invocation`, so answering is the operator's call rather than a description match.

package/claude/skills/claude-intake-answer/SKILL.md

@@ -0,0 +1,90 @@
+---
+name: claude-intake-answer
+description: Walks an intake folder's unread items and puts them as batched questions in chat, writing each selection back onto the item it answers. Use when asked to "answer the intake", "work through the open items", "answer my intake questions", "go through the dump", or "let me answer these from here". Do NOT use to file a dump or write new items, which is `claude-intake`.
+disable-model-invocation: true
+---
+
+# Claude intake answer
+
+Put an intake folder's unread items as batched questions, then land each selection in the slot it answers.
+
+A folder is answered by opening each cluster file and typing under the item, which on a dump spanning six clusters means navigating to each in turn. This walks the same items in chat and writes the answers back, so the file rather than the conversation stays the record.
+
+Read `${CLAUDE_SKILL_DIR}/../../standards/intake.md` before writing anything. It holds the item format and the answer contract this skill is bound by.
+
+## Guards
+
+- If `canon intake list --json` reports no folder, stop: `❌ No intake to answer. Run /claude-intake to file a dump first.`
+- If the named folder has no unread item, stop: `❌ Every item in <slug> carries an answer. Nothing to ask.`
+- Never fill a slot the operator did not answer. An abandoned batch leaves every unreached item unread, which is what the empty slot already means.
+- Never infer an answer from the conversation having happened. A selection reaches the file through the verb or not at all.
+- Do not promote an item, edit a verdict, or write outside the answer slots. Promoting runs through `claude-tasks` after the answers land.
+
+## Step 1: pick the folder
+
+Run `canon intake list --json` and read the per-folder counts. With one folder carrying unread items, take it. With several, put the folders as one question carrying each slug and its unread count, and let the operator pick.
+
+Never guess from the topic of the conversation. A session resuming against the wrong folder answers items nobody asked about.
+
+## Step 2: collect one cluster
+
+Run `canon intake list <slug> --unread --json`. It returns the unread items grouped by the cluster file holding them, each carrying its label, title, open question, and suggestion.
+
+Work one cluster at a time, in the order the folder numbers them. A dump of six clusters holding five items each is thirty questions, and a surface putting all of them at once is unusable. The cluster boundary is also where an operator who runs out of attention stops cleanly, leaving whole clusters unread rather than one file half answered.
+
+## Step 3: put the batch
+
+Cap each batch at four items, which is what a structured question tool takes. A cluster carrying more than four unread items takes several batches in file order.
+
+Every item with an empty slot is offered, not only the ones carrying an open question. An item with a verdict and no question is still asking whether the verdict stands, and the standard's one-token accept exists for exactly that case.
+
+Shape each question from what the item carries:
+
+- The item's label and title name the question, so the operator knows which item is being asked about
+- An item carrying `Open:` puts that question with its `Suggested:` line ranked first and marked as the suggestion
+- An item carrying no `Open:` puts its verdict, with accepting it ranked first as `ok` and the alternatives drawn from what the verdict could otherwise be
+
+Give every option what it means and what it costs. An option with no stated cost is not an option, since the operator picks it without knowing what the other one buys.
+
+Send the whole batch in one turn. When the session runs on a surface carrying a structured question tool, such as `AskUserQuestion` in Claude Code, send it through one call with one entry per item. Otherwise write it as a numbered list in one message with the suggestion marked.
+
+## Step 4: write the batch back
+
+Land every answered item in the cluster with one call:
+
+```bash
+canon intake answer <slug> --cluster <file> --set <label>=<answer> --set <label>=<answer>
+```
+
+One call per cluster, never one per item. Items are labeled per cluster file, so the label alone does not identify an item and the cluster travels with it. Four separate calls against one file also race on the read and drop every answer but the last.
+
+Pass the label exactly as the heading spells it, including a letter suffix such as `3a`. Write the operator's selection as the answer, using `ok` for a verdict accepted as it stands.
+
+The verb refuses an item that already carries an answer rather than overwriting it, and refuses the whole batch when any item in it is filled. A filled slot is a decision already made. On that refusal, drop the named item from the batch and send the rest.
+
+An item the operator left unanswered is omitted from the call entirely. Do not pass it with an empty value, which writes a slot that reads as answered.
+
+## Step 5: continue or stop
+
+After each cluster, state how many clusters still carry unread items and continue to the next. Stop when the operator says to stop, and report what is left rather than pressing on.
+
+Answers are on disk as each cluster completes, so a session ending mid-folder loses nothing.
+
+## Output
+
+Report per cluster as it lands, then close with the folder's state:
+
+```plaintext
+✅ <N> answered in <file>
+<label>. <answer>
+
+📋 <N> cluster(s) still carrying unread items in <slug>
+```
+
+Close the run with the path so the reader can open what changed:
+
+```plaintext
+✅ <N> answered across <N> cluster(s) in <slug>
+<M> item(s) left unread
+.claude/intake/<slug>/
+```

package/claude/skills/claude-markdown-propose/REQUIREMENT.md

@@ -0,0 +1,48 @@
+---
+name: claude-markdown-propose
+description: Why a markdown rewrite is proposed per file and answered before anything applies, rather than edited live or argued in chat
+---
+
+# Claude markdown propose requirement
+
+## Gap
+
+Rewriting a passage in a governing document today means editing it live or arguing in chat, and three surfaces sit near this moment without covering it. `claude-standards-audit` maps changed markdown to the standards claiming it and reports violations, ending on its own description: `Do NOT fix violations. Reporting only.` `canon markdown audit` measures bans and structural checkpoints from package data.
+
+`claude-review` reports findings on a diff someone already wrote. None of the three drafts a replacement, carries an answer slot, or waits.
+
+A review delivered in chat gets applied from memory across files nobody reopened, and nothing records which changes the operator approved. A change nobody agreed to either lands unreviewed, because the session acting on a chat review cannot tell an approved line from an inferred one, or never gets written down at all, because a finding with no draft behind it hands the rewrite back to whoever reads it next.
+
+A second failure compounds the first. A claim copied across several files is corrected in the one a session happened to open, and the copies elsewhere now read as freshly reviewed while still disagreeing, since nothing reconciles a restatement against the source it was drawn from.
+
+## Must
+
+- Take the concern and the surface as inputs and run one procedure against them, so a second concern reuses this skill rather than forking it
+- Grep the named surface for the concern before proposing, so a defect's site count is measured rather than assumed
+- Draft the replacement text, not only the finding
+- Carry three labelled variants on a change whose replacement was invented, and one on a change that corrects text to a recorded fact
+- Write one proposal file per source file under `.claude/proposals/<slug>/` and stop, leaving `You:` empty on every change
+- Apply only a change carrying an answer, one file at a time, and re-grep its anchor before applying it
+- Name a folder that does not collide with `.claude/audits/`, which holds generated data rather than decision state
+- Report what each file leaves alone, so a proposal cannot be read as finding everything wanting
+
+## Must not
+
+- Edit a source file during the Propose phase
+- Apply an unanswered change, or a subset of a file's answered changes while leaving the rest for later
+- Fill a `You:` slot, or infer a disposition from an empty one
+- Name a specific concern in this skill's own procedure. A concern belongs in the invocation, and hardcoding one narrows the skill to the day it was written.
+- Assume the skill earns its place because the gap is real. Whether anything invokes it beyond the operator typing its name has no answer at creation time, and is a review criterion to read against a later usage census rather than a gate this file can pass on its own.
+
+## Guards
+
+- No concern named and none derivable: stop rather than inferring one
+- No surface named and none derivable: stop rather than screening the whole tree
+- The concern resolves to one file: stop and say a single-file change needs no proposal folder
+
+## Out of scope
+
+- Reporting a violation with no drafted replacement, which `claude-standards-audit` and `canon markdown audit` already own
+- Reviewing a diff someone already wrote, which `claude-review` owns
+- Filing a raw brain dump as findings, which `claude-intake` owns
+- Reviewing `.claude/memory/` and proposing promote-or-retire actions per entry, which `claude-memory-review` owns on a different subject with a different answer contract

package/claude/skills/claude-markdown-propose/SKILL.md

@@ -0,0 +1,118 @@
+---
+name: claude-markdown-propose
+description: Reviews a named markdown surface against a named concern, drafts a per-file proposal under `.claude/proposals/<slug>/` carrying a diff and a reason for each change, and stops without editing a source file. Takes the concern and the surface as inputs, such as a claim stated stronger than the record, a fact gone stale, two files disagreeing, or a passage duplicated without derivation. A later invocation applies what the operator answered. Use when asked to "propose a change to CLAUDE.md", "draft a rewrite of this standard", "propose fixes to this doc", "draft alternatives for this passage", or "apply the answered proposals". Do NOT use to report without drafting a replacement (`claude-standards-audit` or `canon markdown audit`), to review a diff already made (`claude-review`), or to file a raw brain dump as findings (`claude-intake`).
+---
+
+# Claude markdown propose
+
+Reviews what a markdown surface says against a named concern and proposes what it should say instead. Writes proposals and stops. The operator answers per change, and a later invocation applies the answered set.
+
+The value is the gate. A rewrite delivered in chat gets applied from memory across files nobody reopened, and nothing records what was approved.
+
+## Guards
+
+- No concern named and none derivable from the conversation. Stop: `❌ No concern to screen for. Name what looks wrong, or the surface to review.`
+- No surface named and none derivable. Stop: `❌ No surface to review. Name the files, or the folder, to screen.`
+- The concern resolves to one file only. Stop and say so: a single-file change needs no proposal folder.
+- A named file cannot be read. Stop and name it. Do not screen what resolved and report a partial result.
+
+## Phase detection
+
+Two phases share this body, picked by whether a proposal folder already exists for the request's slug.
+
+Derive `<slug>` from the concern and the surface, kebab-case, naming the subject rather than the activity. List `.claude/proposals/` at the main worktree root and match the topic against the folders already there before deriving a fresh one, the same way `claude-intake` matches its own folder. Never match against `.claude/` itself.
+
+- No matching folder, or the operator names a concern and a surface: **Propose**.
+- A matching folder exists and the operator says apply, ship, or commit the answers: **Apply**.
+
+All `.claude/proposals/` reads and writes resolve at the main worktree root, not the current worktree. See Worktrees in `CLAUDE.md`.
+
+## Write scope
+
+Write only inside `.claude/proposals/<slug>/`. A source file, a standard, a rule, and a plan all live outside that folder, so this one rule forbids every one of them during the Propose phase. The Apply phase is the one exception, and only for a change carrying a `You:` answer.
+
+## Concerns
+
+The concern is an input, not a flow toggle. The passes below are one procedure and the concern decides what pass 1 looks for.
+
+| Concern       | What it looks like                                                   |
+| ------------- | -------------------------------------------------------------------- |
+| Inflation     | a claim stated stronger than the record supports                     |
+| Staleness     | a fact correct when written and wrong now, usually a date or a count |
+| Contradiction | two files, or two sections, asserting incompatible things            |
+| Duplication   | one passage copied across files with no derivation, drifting apart   |
+
+The operator may name a concern outside this table. Run the same procedure against it.
+
+## Propose phase
+
+Read `${CLAUDE_SKILL_DIR}/references/format.md` before writing anything. Do not work the proposal format from memory.
+
+### 1. Find the sites
+
+Grep the named surface for the concern and its near-variants. A defect rarely repeats verbatim, so search the habit rather than the string.
+
+Count hits per file before reading them. A file with one hit and a file with eight are different problems.
+
+### 2. Find what it should say
+
+Read whatever the operator names as the authoritative source for the concern. Absent one, grep the rest of the tree for a passage already stating the corrected form, since a correct version often already exists somewhere the defect has not reached.
+
+Report a file that contradicts itself. A file holding both the defect and its corrected form is the strongest finding available, because the replacement is already drafted somewhere in the tree and needs no invention.
+
+### 3. Judge per line, not per match
+
+A matched string means different things in different registers. A word describing a mechanism is a fact about how something works. The same word describing reach is a claim about who relies on it. Sweeping both because they share a string is what makes the next pass harder to trust.
+
+### 4. Write the proposals
+
+One file per source file under `.claude/proposals/<slug>/`, per `${CLAUDE_SKILL_DIR}/references/format.md`.
+
+Draft the replacement text. A proposal reporting a problem without a replacement hands the work back rather than doing it.
+
+Carry an `Open:` on any change whose replacement was written rather than corrected, and give it three variants per the format reference. Correcting an overstatement to the recorded fact has one answer. Inventing a paragraph has no right answer, and one draft asks the operator to veto instead of to choose, which costs a round every time the intent lands wrong.
+
+Separate the two kinds before drafting. A change that deletes a claim the record does not support is cheap and rarely argued. A change that writes new prose is where the effort belongs.
+
+Close each file with what it leaves alone, and say why those lines survived.
+
+### 5. Report
+
+Name the count, the files, and the single highest-value change. Point at the folder and stop.
+
+Do not edit a source file. Do not fill a `You:` slot.
+
+Propose in dependency order and state it in `00-overview.md` when the surface spans more than two files. A file other files quote is settled first, otherwise the same wording gets decided twice.
+
+## Apply phase
+
+Read `${CLAUDE_SKILL_DIR}/references/format.md` before applying anything, if this session has not already read it this pass.
+
+Follow the Applying section there: one file at a time in settle order, every answered change in that file and nothing unanswered, re-grepping each anchor before applying it, sweeping the other named surfaces for the same claim before committing, and moving an applied change into `applied.md`.
+
+Report the counts once the pass stops: files committed, changes applied, changes still carrying an empty `You:`. Leave the folder in place. Neither phase deletes it.
+
+## Output
+
+Chat output is the report. This skill persists only the proposal folder itself.
+
+```plaintext
+📂 Opened .claude/proposals/<slug>/
+
+**Screened:** <N> files, <N> changes proposed, <N> carrying three variants
+
+**Highest value:** <the single strongest change, one line>
+
+Next: answer the `You:` slots in the files under .claude/proposals/<slug>/,
+then re-invoke this skill to apply what you answered.
+```
+
+Use `📂 Resumed` in place of `📂 Opened` on a resume pass. The Apply phase reports instead:
+
+```plaintext
+✅ Applied .claude/proposals/<slug>/
+
+**Committed:** <N> files, <N> changes
+
+**Still open:** <N> changes with an empty `You:`
+```