@erclx/canon 5.38.0 → 5.39.0

package/claude/skills/canon-feedback/SKILL.md

@@ -19,8 +19,8 @@ Format a `## Toolkit feedback` block from the current session, then open it as a
 
 From the conversation so far, identify:
 
-- Target project name or kind, never its full path. The path names a folder on one machine and says nothing a triage session can route on, where the project's own name does. Name a private project by its kind instead, such as `a Next.js app`, since the report leaves the machine.
-- Toolkit surface and its type (plugin skill, tooling config, governance rule, seed, or CLI). The type leads the `### Surface` field, ahead of the first comma, because the CLI picks the issue's domain labels from that text alone.
+- Target project name or kind, never its path, which names one machine's folder and nothing triage routes on. Name a private project by kind, such as `a Next.js app`, since reports leave the machine.
+- Toolkit surface and its type (plugin skill, tooling config, governance rule, seed, or CLI). The type leads `### Surface`, ahead of the first comma, since the CLI labels from it alone.
 - Specific toolkit file or name when the session cites one
 
 ### Behavior and fix
@@ -40,14 +40,22 @@ From the same conversation, identify:
 
 Format as a single fenced markdown block, one `###` heading per field. Read `${CLAUDE_SKILL_DIR}/references/template.md` on reaching this point for the block and each field's fallback.
 
-`canon feedback` refuses a report missing `### Surface`, `### Observed`, or `### Proposed fix`, naming the one it did not find. `### From project`, `### Expected`, and `### Repro` are optional, so write the literal fallback the template shows rather than dropping the heading, which is what keeps a field the session cannot fill reading as absent instead of unreported.
+### Required and optional fields
 
-`### Suggested shape`, `### Why`, and `### Links` are optional the other way. Omit the heading when the session has nothing for it and write no fallback, since a report filed without them is complete and a placeholder would read as a reporter who had nothing to say.
+The fields fall into three groups, and each treats a missing value differently.
 
-Headings rather than bold labels, because a GitHub issue form renders a submitted field as `### <label>`. One shape reaches the toolkit whichever route a report takes, and the CLI parses both with one parser. The retired `**Surface:**` form is refused rather than accepted, so a block carrying it has to be rewritten.
+| Fields                                            | When the session has nothing                                                        |
+| ------------------------------------------------- | ----------------------------------------------------------------------------------- |
+| `### Surface`, `### Observed`, `### Proposed fix` | Required, and `canon feedback` refuses a report missing one, naming it              |
+| `### From project`, `### Expected`, `### Repro`   | Write the template's literal fallback, so the field reads as absent, not unreported |
+| `### Suggested shape`, `### Why`, `### Links`     | Omit the heading with no fallback, since a placeholder reads as nothing to say      |
 
 Keep Observed and Expected to one or two lines each, so the report scans. Length belongs in Proposed fix, Suggested shape, and Why.
 
+### Headings, not bold labels
+
+A GitHub issue form renders a submitted field as `### <label>`, so one shape reaches the toolkit whichever route a report takes, and the CLI parses both with one parser. The retired `**Surface:**` form is refused, so a block carrying it has to be rewritten.
+
 The issue body is the request. Put everything the toolkit needs to act on it there, since a comment is easy to miss and a body and a comment that differ leave triage choosing. A comment carries only what happens after filing.
 
 ## Step 2: ship to the toolkit
@@ -70,12 +78,14 @@ cat <<'EOF' | canon feedback
 EOF
 ```
 
-The CLI opens a GitHub issue on the toolkit repo, labeled `feedback` and each domain label the surface type names, such as `skills` for a plugin skill, and prints the issue URL, which this skill reports back on its own line. It needs `gh` authenticated. `git-issue` is not the route, since it files on the current repository and this report belongs on the toolkit's.
+The CLI opens a GitHub issue on the toolkit repo, labeled `feedback` and each domain label the surface type names, such as `skills` for a plugin skill, and prints the issue URL for this skill to report on its own line. It needs `gh` authenticated, and `git-issue` is not the route, since it files on the current repository.
+
+### Reading the outcome
 
 Read the outcome off stdout, never off the exit code, since a shell wrapper can flatten it. Stdout takes one of three shapes:
 
 - A line opening with `https://` is the filed issue. Report the URL.
-- A block opening with `## Toolkit feedback` is a failed call. The reason is on stderr, so show the block in chat with it and `📋 Paste this into an issue at https://github.com/erclx/canon/issues/new`.
+- A block opening with `## Toolkit feedback` is a failed call. Show it in chat with the stderr reason and `📋 Paste this into an issue at https://github.com/erclx/canon/issues/new`.
 - Empty stdout is a refusal. Step 3 says how to repair it from stderr.
 
 If `canon` is not on PATH, fall back: print the block in chat and tell the user `📋 Copy the block above into a toolkit-repo session.`
@@ -85,4 +95,4 @@ If `canon` is not on PATH, fall back: print the block in chat and tell the user
 A report that was not filed reads one of two ways on stdout, and stderr carries the reason in both:
 
 - Empty stdout, with a named missing field on stderr. Add that heading with a real value or its stated fallback, then re-run. Do not report the defect as filed.
-- The block on stdout, with `gh` absent or its call failed on stderr. The stderr names which, since installing `gh` and fixing an authenticated call are different repairs. Show the block in chat with the reason and the paste line from Step 2.
+- The block on stdout, with `gh` absent or its call failed on stderr, which names which, since the two repairs differ. Show the block in chat with the reason and the paste line from Step 2.

package/claude/skills/canon-feedback-triage/SKILL.md

@@ -11,17 +11,20 @@ Consume the feedback queue that `canon feedback` fills. Each open `feedback` iss
 
 The record is an ordinary intake folder at `.canon/intake/<nn>-feedback-triage/`. Read `${CLAUDE_SKILL_DIR}/../plan-intake/references/intake.md` before writing any file in it, since it holds the item format, the frontmatter, the index shape, and the answer contract this skill is bound by.
 
-Run from the toolkit repo root. This skill reads GitHub issues and writes only inside its claimed folder. It posts no comment, close, or label to GitHub.
+- Run from the toolkit repo root
+- Read GitHub issues and write only inside the claimed folder, posting no comment, close, or label to GitHub
 
 ## Guards
 
-- Resolve `.canon/tasks/` and `.canon/intake/` at the main worktree root, not `pwd`. Run `git worktree list --porcelain | grep -m 1 '^worktree ' | cut -d' ' -f2-`, falling back to `pwd` outside a git repo.
+- Resolve `.canon/tasks/` and `.canon/intake/` at the main worktree root, from `git worktree list --porcelain | grep -m 1 '^worktree ' | cut -d' ' -f2-`, falling back to `pwd` outside git
 - If `gh` is not on PATH, stop: `❌ gh CLI not found. Install it to read feedback issues.`
 - If `gh auth status` fails, stop: `❌ gh is not authenticated. Run gh auth login.`
 - If no open `feedback` issues exist, stop: `✅ No open feedback issues.`
 
 ### Slots and records
 
+Two more guards hold through every step.
+
 - Never fill a `You:` slot, and never read an empty one as agreement. Answering runs through `plan-intake-answer` or the operator's own edit.
 - Branch on each `canon` record's `ok` and `reason` rather than on the exit code, which a shell function wrapping `canon` can flatten to zero.
 
@@ -45,7 +48,11 @@ Run `canon records ordinal intake feedback-triage --claim --json` and take its `
 
 ## Step 4: measure each issue
 
-For each remaining issue, measure its claim against the tree during this pass. Grep for the construct its defect names and count the sites, check whether the behavior it asks for exists, and search the log for a commit or pull request that shipped it under another task. Never carry a figure from the issue forward as current, since it states what was true when it was filed.
+For each remaining issue, measure its claim against the tree during this pass, never carrying a figure from the issue forward, since it states what was true when filed.
+
+- Grep for the construct its defect names and count the sites
+- Check whether the behavior it asks for exists
+- Search the log for a commit or pull request that shipped it under another task
 
 Classify each against the toolkit's own surfaces:
 

package/claude/skills/canvas-board/SKILL.md

@@ -37,9 +37,11 @@ canon canvas serve --json
 
 Read `url` off the record rather than composing one, since the server walks past a port already in use. Report the refusal and its `reason` when `ok` is false, and stop there.
 
-Then fetch the printed address and check the shell itself, not a capture:
+### Check the shell
 
-- The body is non-empty and carries a `<script` tag. An empty `200` means the shell failed to build, usually a dependency missing from the canvas tool's install, and every capture still passes because captures go through the frame route alone. Report it as a blank shell and stop.
+Fetch the printed address and check the shell itself, not a capture, since every capture goes through the frame route alone and passes on a blank shell.
+
+- The body is non-empty and carries a `<script` tag. An empty `200` means the shell failed to build, usually a missing dependency, so report a blank shell and stop.
 - `<url>/api/pages` answers with JSON listing the pages.
 
 Hand the operator the address as a markdown link carrying the URL as its text and its target.
@@ -48,22 +50,36 @@ Hand the operator the address as a markdown link carrying the URL as its text an
 
 - Add a page for each decision being drafted: `canon canvas page add <page> --json`.
 - Follow the house style in `${CLAUDE_SKILL_DIR}/references/canvas.md` before drafting an explanation frame.
-- Add each frame through the verb, which writes the starting file and its box in one locked step: `canon canvas frame add <page> <frame> --width <px> --height <px> --json`. Give the width the frame should render at, since a capture and the canvas both render at it. The verb places the frame after the last one, and a position the operator asks for goes through `frame move`.
+- Add each frame with `canon canvas frame add <page> <frame> --width <px> --height <px> --json`, which writes the file and its box in one locked step
+
+Give each frame the width it should render at, since a capture and the canvas both render at it. The verb places the frame after the last one, and a position the operator asks for goes through `frame move`.
 
 ### Layout and naming
 
-- Lay frames out with `canon canvas frame move <page> <frame> --x <px> --y <px> --json` rather than writing `layout.json` by hand, since the operator's drags write the same file under a lock.
+Lay frames out through the verbs rather than by hand, since the operator's drags write the same `layout.json` under a lock.
+
+- Move a frame with `canon canvas frame move <page> <frame> --x <px> --y <px> --json`
 - Name pages and frames for what they hold, such as `pricing` and `pricing-dense`, so the operator can say which one by name.
-- After an insert or a resize, re-lay the page with `canon canvas arrange <page> --json`. It keeps the rows the operator dragged, places each on the standard gap, and drops layout entries whose frame file is gone. `--check` reports without writing.
+- After an insert or a resize, re-lay the page with `canon canvas arrange <page> --json`. It keeps dragged rows, sets the standard gap, and drops entries whose file is gone.
+- Run `arrange --check` to report without writing
 
 ## Step 3: edit a frame through its file
 
 Write the frame's whole document to the `path` the add verb reported. The open canvas reloads the frame when its file changes.
 
-- From a linked worktree, `Edit` and `Write` refuse a main-root path. Write the whole file through one plain `Bash` heredoc instead, the route `session-worktree` states for a main-root write, and never take the redirect to a worktree copy.
-- Change one property of one element with `canon canvas edit <page>/<frame> --element <index> --set <property>=<value> --json` when the set it accepts covers the change, since it leaves every other byte as it was.
-- Fit the box to the content once the write lands: `canon canvas fit <page>/<frame> --json`. Read each row's `wide` and `font`. A `wide` frame needs its box widened, which fit never does, and a `font` frame names a family the canvas does not serve, so set its text to a served face and fit again. A fit that grew a frame leaves the rows below overlapped until `canvas arrange` runs.
-- Use the project's custom properties for every value the token stylesheet defines. The record from `serve` names the token source under `tokens`, and a `none` source means frames render unstyled, so say so rather than inventing values to cover it.
+- From a linked worktree, `Edit` and `Write` refuse a main-root path. Write the whole file through one plain `Bash` heredoc, the route `session-worktree` states, never a worktree copy.
+- Change one property with `canon canvas edit <page>/<frame> --element <index> --set <property>=<value> --json` when its set covers the change, since it leaves every other byte as it was
+- Use the project's custom properties for every value the token stylesheet defines. The `serve` record names the source under `tokens`, and `none` means frames render unstyled, so say so.
+
+### Fit the box
+
+Fit the box to the content once the write lands, with `canon canvas fit <page>/<frame> --json`, and read each row's `wide` and `font`.
+
+- A `wide` frame needs its box widened, which fit never does
+- A `font` frame names a family the canvas does not serve, so set its text to a served face and fit again
+- A fit that grew a frame leaves the rows below overlapped until `canvas arrange` runs
+
+### Mark the frame
 
 Mark the frame before the first write, so the operator sees which frame is being worked on before anything lands, and clear the mark once the edits to it are done:
 
@@ -74,7 +90,7 @@ canon canvas editing <page>/<frame> --done --json
 
 - A mark lapses after five minutes, so mark the frame again during a longer edit.
 - Clear it on every exit from the edit, including one that stopped on a refusal. Clearing a frame that holds no mark succeeds.
-- When the mark call fails with `unknown command 'editing'`, the installed CLI predates the mark, so go on without it rather than stopping. Never run `canvas edit` in its place, whatever the error suggests, since that verb writes the frame.
+- On `unknown command 'editing'`, the CLI predates the mark, so go on without it. Never run `canvas edit` in its place, since that verb writes the frame.
 
 ## Step 4: read what the operator pointed at
 
@@ -85,7 +101,7 @@ canon canvas selection --json
 ```
 
 - `selection: null` means nothing is selected or the selected frame is gone. Ask which one rather than guessing.
-- An `element` carrying `stale: true` was picked against an earlier version of the file, so its `index` may now land on a different element. Treat the pick as unknown and ask the operator to pick again, rather than acting on the index or matching its `tag` and `text` by eye.
+- An `element` carrying `stale: true` was picked against an earlier file, so its `index` may land elsewhere. Ask the operator to pick again rather than matching its `tag` and `text` by eye.
 - A fresh `element` gives the `index` that `canvas edit` takes.
 
 ## Step 5: respect the operator's inspector edits
@@ -98,17 +114,20 @@ The operator restyles elements from the inspector, and each edit lands as inline
 
 ## Step 6: capture finished work
 
-- Capture a frame once it is finished: `canon canvas capture <page>/<frame> --json`. Each PNG is the frame's whole document, so its height follows the content rather than the box.
-- Capture a whole page once its frames are finished: `canon canvas capture <page> --composite --json`. The image shows each frame clipped to its box at its layout position.
-- Capture once per finished frame or page, not after every edit. The live canvas is the working view, and a capture is the record handed on.
+Capture once per finished frame or page, not after every edit. The live canvas is the working view, and a capture is the record handed on.
+
+- Capture a frame with `canon canvas capture <page>/<frame> --json`. Each PNG is the whole document, so its height follows the content rather than the box.
+- Capture a page with `canon canvas capture <page> --composite --json`, which shows each frame clipped to its box at its layout position
 - Read each `path` off the record rather than composing one.
-- A capture refused because a font is not installed names the family it read off the frame's text. Set that text's `font-family` to a named family the machine has, never a generic keyword such as `sans-serif`, and capture again, rather than reporting the frame as captured.
+
+A capture refused because a font is not installed names the family it read off the frame's text. Set that text's `font-family` to a named family the machine has, never a generic keyword such as `sans-serif`, and capture again rather than reporting the frame as captured.
 
 ## Step 7: carry a picked direction back
 
-When the operator picks a frame, the decision leaves the canvas.
+When the operator picks a frame, the decision leaves the canvas. Leave structure and layout on the canvas, and name the frame in the plan that builds it.
 
-- Carry visual values, being color, type, spacing, and radius, into the stylesheet the design document's lead names, and the intent behind them into the document's sections under the `design.md` standard. A project with no stylesheet yet takes the values under `.claude/design/project/` after `canon design install`, and the lead names that path. Leave structure and layout on the canvas, and name the frame in the plan that builds it.
+- Carry color, type, spacing, and radius into the stylesheet the design document's lead names, and their intent into its sections under the `design.md` standard
+- A project with no stylesheet yet takes the values under `.claude/design/project/` after `canon design install`, and the lead names that path
 - Name the frame the decision came from in the reply, and leave the frame on the canvas until the operator clears it.
 - Never cite a frame path from a tracked file. The folder is gitignored, so the citation resolves on this machine alone.
 

package/claude/skills/ci-workflow/SKILL.md

@@ -11,7 +11,8 @@ Generate GitHub Actions workflow files for CI pipelines. Enforce parallel job ex
 
 ## Guards
 
-- A request for what runs inside a deploy, publish, or release job stops at the gate. Credentials, environments, and deploy targets are invisible to this skill, so emit the job with its `needs` wiring and a placeholder step, then name what the caller fills in. Never guess a deploy command.
+- A request for what runs inside a deploy, publish, or release job stops at the gate, since credentials, environments, and targets are invisible here. Never guess a deploy command.
+- Emit such a job with its `needs` wiring and a placeholder step, then name what the caller fills in
 - The build, test, and deploy commands belong to the project. Read them from its scripts rather than asserting a second copy in the workflow.
 
 ## Workflow setup
@@ -26,9 +27,9 @@ Generate GitHub Actions workflow files for CI pipelines. Enforce parallel job ex
 
 ## Job granularity
 
-- Start a new pipeline with the checks that share setup in one job: static analysis, unit tests, and build. A project with no run history has nothing to measure, and one job is the shape that costs least to reverse.
-- Keep them in one job while the gate runs under roughly two minutes end to end. Each extra job repays checkout, dependency install, and toolchain setup before it reaches a stage, so a split at that duration costs more than the parallelism returns.
-- Split once a run log puts the gate past that, then apply the dependency rules below. The run log is the revision trigger rather than the entry condition, since repository size and stage count answer nothing.
+- Start a new pipeline with static analysis, unit tests, and build in one job, since they share setup. A project with no run history has nothing to measure, and one job costs least to reverse.
+- Keep them in one job while the gate runs under roughly two minutes. Each extra job repays checkout, dependency install, and toolchain setup, so a split at that duration costs more than it returns.
+- Split once a run log puts the gate past that, then apply the dependency rules below. The run log is the trigger, since repository size and stage count answer nothing.
 - Give E2E, release, and deploy their own jobs from the start. Each carries a data dependency or a gate, so this rule never folds them into the check job.
 
 ## Job dependencies

package/claude/skills/code-craft/SKILL.md

@@ -7,7 +7,7 @@ metadata:
 
 # Code craft
 
-A session writing code takes its shape from whatever sits nearby. It copies a function rather than changing the one it found, spreads one decision across the files it happened to open, and adds a class hierarchy for a second case that may never come. Each choice reads fine in the diff and costs the next change. This skill carries the judgment at the moment the shape is chosen, before the body exists.
+A session writing code takes its shape from what sits nearby. It copies a function rather than changing it, spreads one decision across the files it opened, and builds a hierarchy for a case that may never come. Each reads fine in the diff and costs the next change. This skill carries the judgment as the shape is chosen, before the body exists.
 
 Load it before writing a new function, class, or module, and before extracting, abstracting, or copying existing code. Skip it for a change that fills in a body whose shape is already fixed.
 
@@ -24,7 +24,7 @@ Good design is design that makes the likely change cheap. Judge a shape by the c
 A unit is worth having when its interface is much simpler than what it does, so a caller learns a little and gets a lot.
 
 - Add a function or a class only when its name and parameters are easier to hold than its body. One that forwards its arguments to another call with nothing added is a pass-through, so inline it.
-- Split a module by the decision it hides, such as a file format, a storage choice, or a pricing rule, rather than by processing step. A split by step makes every change to one decision touch every step.
+- Split a module by the decision it hides, such as a file format, a storage choice, or a pricing rule, not by processing step, which makes one decision's change touch every step
 - Keep a decision in one unit, so changing it opens one file. A decision whose details leak into its callers is not hidden, whatever the folder says.
 - Prefer one longer function a reader can follow top to bottom over many tiny ones they have to stitch back together.
 
@@ -32,9 +32,9 @@ A unit is worth having when its interface is much simpler than what it does, so
 
 Each principle below has a case where the other side wins. State which case you are in before following either.
 
-- **One piece of knowledge, one place, against false sharing.** Merge two copies when they encode the same rule, so changing the rule means changing both. Leave them apart when they only look alike and would change for different reasons, since merging them couples two things that drift.
-- **Build only what is asked, against seams that ease change.** Build no capability for a feature nobody has asked for. A refactor, a test, or a parameter that makes the asked-for code easier to change is not speculative, and building it is not a breach.
-- **One reason to change, against too many pieces.** Split a unit when two unrelated changes would both land in it. Stop splitting when the pieces only make sense read together, since a reader then rebuilds the whole across files.
+- **One piece of knowledge, one place, against false sharing.** Merge two copies encoding one rule, so a change never misses one. Leave apart two that only look alike, since merging couples them.
+- **Build only what is asked, against seams that ease change.** Build no capability nobody asked for. A refactor, test, or parameter easing change to the asked-for code is not speculative.
+- **One reason to change, against too many pieces.** Split a unit two unrelated changes would both land in. Stop when the pieces only make sense together and a reader rebuilds the whole.
 
 ## Reach for a pattern only past its wrong case
 
@@ -51,7 +51,7 @@ A pattern earns its indirection only when the problem it solves is present now.
 
 ## Pass hidden inputs in
 
-- Pass the clock, the environment, randomness, and any global into the code that reads them, rather than reaching for them inside. A function that reads the time itself cannot be tested at a chosen time.
+- Pass the clock, the environment, randomness, and any global into the code that reads them, rather than reaching for them inside, since a function reading the time cannot be tested at a chosen one
 - Keep business rules free of transport and storage code, so a rule can be read and tested without a request or a database.
 - Skip ports and adapters for an application that only reads and writes records. The layers cost more than the change they protect against.
 
@@ -86,6 +86,8 @@ Read `${CLAUDE_SKILL_DIR}/references/adopted.md` only when extending this guidan
 
 ### Defaults and fixes
 
+Defaults and fixes carry their own signs.
+
 - You wrote a default value, a threshold, or a fallback the task never named.
 - A fix is adding a special case, a catch, or a disabled check rather than changing the code that misbehaved.
 - The code reads the current time, an environment variable, or a global from inside a rule.
@@ -101,6 +103,8 @@ Check each line against the code the change produced. A line answering no is fix
 
 ### Inputs, scope, and fixes
 
+Check the inputs, the scope, and the fixes the same way.
+
 - Clock, environment, and global reads are passed in rather than taken inside a rule.
 - The diff holds no feature, option, or default the task did not ask for or state.
 - Every fix changes the code that misbehaved rather than silencing it.

package/claude/skills/codebase-layout/SKILL.md

@@ -7,11 +7,9 @@ metadata:
 
 # Codebase layout
 
-A session placing a new file copies the folder next to it, so a flat folder stays flat until a refactor pays to split it. In one target, two source folders grew to 46 and 36 flat files under installed rules against it, and the split cost a pull request touching 98 files. This skill carries the placement call to the moment the path is written, which is the one moment it is cheap.
+A session placing a new file copies the folder next to it, so a flat folder stays flat until a refactor pays to split it. In one target, two folders grew to 46 and 36 flat files under rules against it, and the split touched 98 files. This skill carries the placement call to the moment the path is written, the one moment it is cheap.
 
-Load it before writing a new path into a plan, not after. A worker copies the path the plan gives it, so the placement is settled once the plan is.
-
-Skip it when every path the work names already exists.
+Load it before writing a new path into a plan, not after, since a worker copies the path the plan gives it. Skip it when every path the work names already exists.
 
 ## Read the project's strategy first
 
@@ -33,7 +31,7 @@ Skip it when every path the work names already exists.
 
 ## Split before the file lands
 
-- Split a folder when the new file brings a second role into it, before the file lands rather than in a later refactor. The split that touched 98 files would have touched a handful when the folder held eleven.
+- Split a folder when the new file brings a second role into it, before the file lands rather than in a later refactor. The 98-file split would have touched a handful when the folder held eleven.
 - Treat roughly ten files as a prompt to look, not a gate. A folder holding one role can stay flat at any size, and a folder mixing two roles is worth splitting at six.
 - Give a new role a named folder in the plan, rather than dropping its first file beside the nearest neighbor.
 

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

@@ -7,7 +7,7 @@ description: What the context-entry fold is for, the gaps it closes, and why it
 
 ## Gap
 
-Without this skill, the context entries describe the repository the session opened with. A decision a plan settled mid-cycle lives only in the conversation and dies with it, and an entry naming a module the diff rewrote keeps stating what the module used to do.
+Without this skill, the context entries describe the repository the session opened with. An entry keeps listing a folder the diff moved and a trap the diff fixed, so it states what the repository used to be.
 
 The trigger side carries a gap of its own. "Sync the docs" names either corpus to the person saying it, so a description leaving its corpus to the opening clause alone competes with its public-facing sibling on nothing the routing field states, and the context folder the request was about goes untouched.
 
@@ -20,9 +20,9 @@ This skill writes canonical docs at the end of a long build. An appended figure,
 ## Must
 
 - Name the context entries in a trigger phrase rather than in the opening clause alone, so a bare request to sync the docs separates this skill from `docs-sync` on something both descriptions state
-- Take decisions from the session and the refresh scope from the diff
+- Take the refresh scope from the diff, and from the session only the requirements or direction change the report names
 - Write tracked docs at the current worktree root, since only that copy commits with the branch
-- Write a decision to the domain context entry it constrains, whatever other domains its reasoning touches, so a decision has one home that loads on demand
+- Write an entry only when the diff adds, moves, or removes a folder, makes a folder's bullet untrue, or changes a trap, and never write a decision, which the pull request records
 - Report a requirements or direction change in one line naming `document-health`, rather than writing it, so the identity record changes only when the operator reviews it
 - Close on an audit of what the fold touched, running `canon context audit` and reporting the findings on files this run wrote or the diff carries
 - Classify the fold's whole diff baseline through `canon context classify diff`, calling the verb rather than reimplementing its pattern or its prompt in the skill body, since an earlier commit on the branch carries a doc edit the fold is equally responsible for
@@ -48,7 +48,7 @@ This skill writes canonical docs at the end of a long build. An appended figure,
 ## Guards
 
 - Neither a `canon/` nor a `.claude/` directory: stop and name the command that sets one up
-- No session divergence and no diff a context entry could describe: stop with a pass, since both conditions have to hold
+- No direction change in the session and no diff a context entry could describe: stop with a pass, since both conditions have to hold
 
 ## Out of scope
 

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

@@ -1,6 +1,6 @@
 ---
 name: context-fold
-description: Folds a session's decisions and its diff into the project's context entries, then audits what it touched. Use when asked to "fold the session into context", "update the context entries", "refresh the context folder", when design or requirements changed mid-cycle, after a pivot, or before shipping. Do NOT use for `README.md` or `docs/`, which is `docs-sync`, or to mark a shipped task's outcomes on the board, which is `task-complete`.
+description: Folds a branch's diff into the project's context entries, rewriting a folder or a gotcha the diff left untrue, then audits what it touched. Use when asked to "fold the session into context", "update the context entries", "refresh the context folder", when design or requirements changed mid-cycle, after a pivot, or before shipping. Do NOT use for `README.md` or `docs/`, which is `docs-sync`, or to mark a shipped task's outcomes on the board, which is `task-complete`.
 metadata:
   family: ship
 ---
@@ -23,58 +23,77 @@ git merge-base HEAD origin/main 2>/dev/null || git merge-base HEAD main 2>/dev/n
 
 Take the union of `git diff --name-only <base> HEAD`, `git diff --name-only HEAD`, and `git ls-files --others --exclude-standard`. Read content with `git diff <base> HEAD` and `git diff HEAD`.
 
-Prefer `origin/main` over local `main`. On `main` itself the local ref resolves to HEAD, so every committed change drops out of the set and the skill goes blind to the work it is meant to read.
-
-The baseline is unusable when no merge base resolves against either ref, or when the base came from local `main` and equals HEAD. On an unusable baseline, read `${CLAUDE_SKILL_DIR}/references/unusable-baseline.md` before Step 3 for the set that step takes instead.
+- Prefer `origin/main` over local `main`. On `main` itself the local ref resolves to HEAD, so every committed change drops out of the set and the skill goes blind to its work.
+- The baseline is unusable when no merge base resolves against either ref, or when the base came from local `main` and equals HEAD
+- On an unusable baseline, read `${CLAUDE_SKILL_DIR}/references/unusable-baseline.md` before Step 3 for the set that step takes instead
 
 ## Step 1: read the context catalog
 
-Read `canon/context/index.md` from the current worktree root (`pwd`), not the main worktree root, to see which domain entries exist. Entries are tracked files and edits must commit with the branch. A project the surface move has not reached holds the folder under `.claude/` rather than `canon/`, so read and write it at whichever root already carries it.
+Read `canon/context/index.md` from the current worktree root (`pwd`), not the main worktree root, to see which domain entries exist.
+
+- Entries are tracked files, so edits must commit with the branch
+- A project the surface move has not reached holds the folder under `.claude/` rather than `canon/`, so read and write it at whichever root already carries it
 
 Read `canon/REQUIREMENTS.md` beside it when it exists, for the direction a session decision is measured against. This skill never writes it.
 
 ## Step 2: identify what changed
 
-Two sources feed this step. The session carries judgments no diff can show. The diff carries facts about the repository the session may never have mentioned.
-
-Review the session for decisions that diverged from the original plan:
+Review the session for requirements added, removed, or changed in scope, which After completion reports and this skill never writes. Then resolve the diff baseline and keep the changed paths for Step 3.
 
-- Requirements added, removed, or changed scope
-- Technical decisions made or revised
-- Design or UX decisions that differ from what the context entries state
+Stop when both of these hold, since a session-only skip would drop the diff-driven refresh for a mechanical change nobody narrated:
 
-Then resolve the diff baseline and keep the changed paths for Step 3.
+- The session shows no direction change
+- The diff carries no path a context entry could describe, being a change confined to the task board, scratch, or files outside source and docs
 
-Stop when the session shows no divergence **and** the diff carries no path a context entry could describe, being a change confined to the task board, scratch, or files outside the repository's source and docs. Report `✅ No context updates needed. Session matched the original plan.` Both conditions have to hold, since a session-only skip would drop the diff-driven refresh for a mechanical change nobody narrated.
+Report `✅ No context updates needed. Session matched the original plan.`
 
 ## Step 3: refresh context entries
 
-Skip this step silently when `canon/context/` does not exist or its catalog lists no entries.
+Skip this step silently when `canon/context/` does not exist or its catalog lists no entries. Otherwise read `${CLAUDE_SKILL_DIR}/references/context-refresh.md` for the diff it reads, the widening a removed capability takes, when a new entry is created, and the output lines.
 
-Otherwise read `${CLAUDE_SKILL_DIR}/references/context-refresh.md` for the diff it reads, the widening a removed capability takes, when a new entry is created, and the output lines.
-
-Write a session decision into the entry for the domain it constrains, under that entry's `## Decisions`, whatever other domains its reasoning touches. Every write follows these rules:
+Write an entry only when the diff adds, moves, or removes a folder, makes a folder's existing bullet untrue, or adds, fixes, or removes a trap, and skip the step otherwise. Never write a decision, which the pull request records. Every write follows these rules:
 
 - Never write `canon/REQUIREMENTS.md`. Report a requirements change in After completion.
-- Update only the sections affected by session decisions or the diff, and leave unrelated sections alone.
-- Rewrite a restated or superseded statement in place rather than appending the replacement beside it. State the fact that stands and keep the earlier reasoning only where it is the alternative that lost, per `${CLAUDE_SKILL_DIR}/references/context.md`.
+- Update only the Layout H3 or the gotcha the trigger names, and leave unrelated sections alone.
+- Edit the bullet that went untrue in place, and never append a correction beside it, per `${CLAUDE_SKILL_DIR}/references/context.md`
 - Follow `${CLAUDE_SKILL_DIR}/../markdown-craft/references/markdown.md` and the `write-human` skill for all edits.
 
 Write each updated file immediately. Claude Code's tool permission dialog is the confirmation gate. Do not wait for user input.
 
 ## Step 4: audit what the fold touched
 
-Run the structural audit, then the content classifier, and answer both before the report.
+Run the structural audit, the markdown audit, and the content classifier, and answer each before the report. Findings never stop the fold.
+
+### Structural audit
+
+`canon context audit --json` takes a project root rather than a file list, so it reports the whole folder.
 
 ```bash
 canon context audit --json
 ```
 
-The verb takes a project root rather than a file list, so it reports the whole folder. Report only the findings whose `rel` names a file Step 3 wrote this run or a file the diff carries, one line each as `⚠ Audit: <rel>, <finding>`, and leave the rest unreported, since a finding in an entry this run never touched belongs to whoever next edits it. Repair a finding in a file Step 3 wrote this run when the fix is inside what it already rewrote, such as a bare reference or a missing section it dropped. Report a missing subcommand or a refusal as `⚠ Audit: <message>` and continue.
+- Report only the findings whose `rel` names a file Step 3 wrote this run or a file the diff carries, one line each as `⚠ Audit: <rel>, <finding>`
+- Leave the rest unreported, since a finding in an entry this run never touched belongs to whoever next edits it
+- Repair a finding in a file Step 3 wrote this run when the fix is inside what it already rewrote, such as a bare reference or a missing section it dropped
+- Report a missing subcommand or a refusal as `⚠ Audit: <message>` and continue
+
+### Markdown audit
+
+Run `canon markdown audit <path>` over every entry Step 3 wrote this run, and fix each ban and density finding it reports per the markdown standard Step 3 follows.
+
+- Fix a finding inside a section Step 3 rewrote, then re-run the audit on that entry until it reports none there
+- Report a finding in a section Step 3 left alone as `⚠ Audit: <rel>, <finding>`, since the rule above keeps unrelated sections as they are
+- Report a refusal as `⚠ Audit: <message>` and continue
+
+### Classify
+
+Skip the classifier only when the Diff baseline section could not resolve a base ref at all, reporting `⚠ No diff to scope against. Skipped the classify check.` The verb needs a resolvable ref, which is the one condition it cannot answer for itself.
 
-Then classify. Skip the classifier only when the Diff baseline section could not resolve a base ref at all, reporting `⚠ No diff to scope against. Skipped the classify check.` The verb needs a resolvable ref to run against, which is the one condition it cannot answer for itself.
+Otherwise read `${CLAUDE_SKILL_DIR}/references/classify.md` for the invocation, its scope, the record fields, applying a finding, the one-line keep reason, the unreachable and missing-subcommand lines, and the report shape.
 
-Otherwise read `${CLAUDE_SKILL_DIR}/references/classify.md` for the invocation, its scope, the record fields, applying a finding, the one-line keep reason, the unreachable and missing-subcommand lines, and the report shape. `${CLAUDE_SKILL_DIR}` names this skill's own directory, resolved once when the skill loaded. Read the reference by that resolved path rather than guessing a `.claude/skills/context-fold/references/classify.md` path from the toolkit's install-time layout, which is a different root than the one this skill's own files live under. The invocation is `canon context classify diff --base <base> --json`, and it runs whether or not that reference resolves. Findings never stop the fold.
+- `${CLAUDE_SKILL_DIR}` names this skill's own directory, resolved once when the skill loaded, so read the reference by that resolved path
+- Never guess a `.claude/skills/context-fold/references/classify.md` path from the install-time layout, which is a different root than this skill's own files
+- The invocation is `canon context classify diff --base <base> --json`, and it runs whether or not that reference resolves
 
 ## After completion
 

package/claude/skills/context-fold/references/context-refresh.md

@@ -13,9 +13,10 @@ When the baseline is unusable, scope this step to the working tree and untracked
 
 Reuse the diff from the baseline above, names and content both. For each domain listed in `canon/context/index.md`, read its own entry: a flat `canon/context/<domain>.md`, or, for a domain split into a folder, its `canon/context/<domain>/index.md` and every sibling file that index links. Follow the index rather than globbing the folder, since a folder can hold a file the index does not list yet.
 
-- Map the entry's section headings, whether they sit in one flat file or spread across a nested domain's sibling files, to the changed files. An entry is relevant when its prose references files, modules, or decisions touched by the diff.
-- For each relevant entry, rewrite only the sections affected by the diff. Same pattern as `docs-sync`. Do not touch unrelated sections. Never rewrite a split domain's own `index.md` directly, since a regen overwrites it the same way it overwrites the top-level catalog. Rewrite the sibling file the affected section actually lives in instead.
-- Rewrite a restated or superseded statement in place rather than appending beside it, the same rule the body states for a session decision.
+- Treat an entry as relevant only when the diff adds, moves, or removes a folder its Layout lists, makes a folder's bullet untrue, or changes a trap it names
+- For each relevant entry, rewrite only the H3 or the gotcha the trigger names, and leave unrelated sections alone
+- Never rewrite a split domain's own `index.md`, which a regen overwrites, and rewrite the sibling file the section lives in instead
+- Edit the bullet that went untrue in place and never append one beside it, the same rule the body states.
 - Write a reference to another entry as the path that entry sits at, rather than as its bare filename. `${CLAUDE_SKILL_DIR}/references/context.md` states the form, and a bare name strands the reference once a domain splits into subfolders.
 
 ## When the diff removes a capability