@erclx/canon 5.5.0 → 5.6.0

package/claude/.claude-plugin/plugin.json

@@ -1,7 +1,7 @@
 {
   "name": "canon",
   "description": "Automated governance, versioning, and discovery tools for Claude Code.",
-  "version": "5.5.0",
+  "version": "5.6.0",
   "author": {
     "name": "Eric Le",
     "url": "https://github.com/erclx"

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

@@ -13,6 +13,8 @@ The failure is measured on a real target. Two source folders grew from 11 files
 
 Sharpening the rules does not reach the decision. Both were loaded and neither was applied, since an always-loaded line competes with everything else a session holds and a path-scoped rule fires on a read of an existing file rather than on a path written into a plan.
 
+A placement rule in front of the session is also one it can argue past. Each flat file in that target landed for a reason that sounded fine in the moment, such as the neighbors already being flat or a split reading as scope creep, and nothing answered the reason before the path was written.
+
 ## Must
 
 - Be loaded by `plan-feature` whenever a plan names a path that does not exist yet, so the guidance is in front of the planner at the moment it writes the path
@@ -23,6 +25,7 @@ Sharpening the rules does not reach the decision. Both were loaded and neither w
 - State that a file is named for what it covers inside its folder, never repeating the folder's name as its stem or its prefix, since a name placed beside its neighbor copies the neighbor's prefix along with its folder
 - Hold the stack-neutral core in the body and defer category specifics to a reference loaded only when a new path falls in that category
 - Record the external layouts adopted and declined with the reason for each, so a later session extends the position instead of re-deriving it
+- Close with a table of the excuses a session gives for placing a file beside its neighbor, each with its rebuttal, the red flags a session can see while writing a path, and a checklist each new path passes before the plan is handed over
 - Fire on a direct question about placement as well, such as where a file goes or whether a flat folder should split, since a session outside any plan still places files
 
 ## Must not

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

@@ -55,6 +55,34 @@ Read the reference matching what the new paths hold, and skip the rest.
 
 Read `${CLAUDE_SKILL_DIR}/references/adopted.md` only when extending this guidance or arguing against a rule in it. It records which external layouts were adopted, which were declined, and why.
 
+## Excuses and rebuttals
+
+| Excuse                                                    | Rebuttal                                                                                                   |
+| --------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------- |
+| The neighbors are flat, so one more flat file fits        | The neighbors are how the folder got to 46. Ask whether this file brings a second role.                    |
+| The folder is under ten files, so it does not need a look | Ten is a prompt, not a gate. A second role splits a folder at six.                                         |
+| Splitting now is a refactor outside this plan's scope     | Splitting before the file lands touches a handful of paths. Splitting later touched 98.                    |
+| A `utils` folder is where shared code goes                | Shared code needs a second consumer. Until then the file sits with the one it serves.                      |
+| The worker can decide where the file goes                 | The worker copies the path the plan gives it. A path left loose in the plan is placed beside its neighbor. |
+
+## Red flags
+
+- A new path's only reason is that a similar file sits in the same folder.
+- A new file's name repeats its folder as its stem or its prefix.
+- A new folder is named for a technical kind alone, such as `helpers/` or `common/`.
+- A shared module is about to import from a feature.
+- The plan writes a file into a folder that does not exist without naming the folder.
+
+## Before handing over
+
+Check every new path the plan or the change names against each line, and fix the path rather than noting it.
+
+- It follows the strategy the project already uses, or the plan proposes the change as its own decision.
+- It carries a one-clause reason naming its role, its consumer, or the strategy it follows.
+- Its folder holds one role after it lands.
+- Its stem names what it covers without repeating its folder.
+- A file with one consumer sits beside it, and a file with two sits in shared code.
+
 ## What this delegates
 
 - Which layer a test belongs at: `test-craft`. This skill decides where the test file sits once its layer is chosen.

package/claude/skills/codebase-layout/references/adopted.md

@@ -9,6 +9,8 @@ External sources were read and filtered rather than imported. This file is the r
 
 ## Adopted
 
+### Placing files
+
 **Group what changes together.** Robert Martin's restatement of the single responsibility principle: "Gather together the things that change for the same reasons. Separate those things that change for different reasons" ([The Single Responsibility Principle](https://blog.cleancoder.com/uncle-bob/2014/05/08/SingleReponsibilityPrinciple.html)). It gives "split by role" a test a planner can apply to a folder: would these files change together?
 
 **Name folders for the domain rather than the framework.** Martin's Screaming Architecture argues the top level should tell readers "about the system, not about the frameworks you used in your system" ([Screaming Architecture](https://blog.cleancoder.com/uncle-bob/2011/09/30/Screaming-Architecture.html)). It is the root of naming a folder for what it holds rather than its technical kind.
@@ -21,6 +23,10 @@ External sources were read and filtered rather than imported. This file is the r
 
 **Fixtures in modules, page objects on their own.** Playwright defines fixtures in dedicated modules that extend the base test, merges them into one module the specs import, and keeps page objects as their own modules ([fixtures](https://playwright.dev/docs/test-fixtures)). Adopted in `tests.md` as the split between specs and support.
 
+### Closing the body
+
+**Excuses, red flags, and a closing checklist.** From `addyosmani/agent-skills@2686b620`, [`docs/skill-anatomy.md`](https://github.com/addyosmani/agent-skills/blob/2686b620fc1fed2e8f60c704839c766b8594c6b6/docs/skill-anatomy.md): Common Rationalizations, Red Flags, and Verification. Adopted as the three closing sections every practice skill carries. Each excuse row rebuts a reason a flat folder stayed flat in the target this skill's requirement measures, rather than an objection nobody raised.
+
 ## Declined
 
 **Deep modules and seams.** Matt Pocock's codebase-design skill covers a lot of behavior behind a small interface placed at a clean seam ([codebase-design](https://github.com/mattpocock/skills/blob/main/skills/engineering/codebase-design/SKILL.md)). It answers where a boundary goes in code, not where a file goes on disk, and absorbing it doubles the skill's scope before the placement problem is shown solved. It becomes a reference only when a plan places files well and still draws a boundary badly.

package/claude/skills/plan-feature/REQUIREMENT.md

@@ -12,6 +12,9 @@ Without this skill, implementation starts before anyone knows what it touches. A
 ## Must
 
 - Read the project's own Claude setup before scanning source, so the plan inherits decisions already made instead of reopening them
+- Reframe a vague ask as observable, checkable success criteria before listing any file, and carry each criterion into the plan's verification, so a plan never ships a check with nothing measurable to prove
+- Slice batches by a user-visible path rather than by layer, and sequence the riskiest batch first while a sweep stays last, so the batch most likely to change the plan lands while later ones can still move
+- Predict the operator's answers to the next three questions about the ask's success criteria, proceed on the ones it can predict, and ask when it can predict none, since a plan built on a guessed goal proves the wrong thing
 - Name every file the work touches with the reason it is touched
 - Place each new path against the layout guidance with a one-clause reason, loading that guidance only when the plan creates a file or folder, since the planner decides placement and the worker copies whatever path it is given
 - Name how each outcome is proven and which input or state would break the change, so the executing session has a check to run and the reviewer has a place to look
@@ -30,6 +33,7 @@ Without this skill, implementation starts before anyone knows what it touches. A
 ## Guards
 
 - No feature description: stop and ask for one
+- No predictable success criterion: ask before planning rather than guessing the goal
 
 ## Out of scope
 

package/claude/skills/plan-feature/SKILL.md

@@ -10,6 +10,7 @@ description: Plans a feature by reading the project's Claude setup and scanning
 - If no feature description is provided, stop: `❌ No feature description. Describe what you want to add.`
 - Do not implement anything. Output the plan and stop.
 - When the feature description spans two or more independent concerns, write one plan file per concern. Do not bundle them under a single slug.
+- Before Step 3, name the next three questions you would ask about what the ask must achieve, and predict the operator's answer to each from the ask and the project context. An answer you can predict settles its criterion, which Step 3 writes as a `**Verification:**` bullet rather than a question. Only a prediction still open goes under `**Questions:**` with a `- Suggested:` line, so a fully specified ask carries none and Small mode stays reachable. When you can predict none of the three, so no checkable success criterion can be stated, ask before Step 3 through whatever route reaches the operator, including a message to a dispatching session. The test reads the ask's success criteria, never the plan's open questions, which a `- Suggested:` line answers.
 
 ## Step 1: read the Claude setup
 
@@ -43,6 +44,7 @@ The section list, what each section holds, the suggested-and-answer contract, an
 
 What this skill adds on top of the standard:
 
+- Reframe a vague ask as success criteria before writing `**Files to touch:**`. Each criterion names something observable and a check that decides it, such as a measure and the threshold it must stay under, drawn from the ask or the project context. "Make it faster" names no criterion, while a stated budget for one path does. Each criterion becomes one `**Verification:**` bullet.
 - Apply senior judgment to every `- Suggested:` line. Pick the best option and state it in one line with its reason or main tradeoff. No padding, no alternatives unless they change the pick.
 - Suggest a real default when best practice, the codebase, or prior context points to one.
 - Load the `canon:codebase-layout` skill before writing the `**Files to touch:**` entries when any of them names a file or folder that does not exist yet, and give each new path its placement reason in its entry. Skip the load when every entry edits an existing file. Report it rather than proceeding silently when the skill does not resolve.
@@ -57,6 +59,8 @@ A plan sequencing its work into batches declares where one pull request ends, he
 - One batch is one pull request, and one pull request is one plan file, named for its own concern rather than a numeric suffix. `canon tasks plan-branch` derives one branch from one plan filename, so a `**Batch N**` sub-heading inside one file's `**Files to touch:**` shares that one branch across every batch, and the batch that merges first strands every batch behind it with nothing left to open a pull request against. Write a plan opening five batches as five files before the first line of any of them.
 - State a dependent batch's dependency on the ones before it in its own `**Constraints:**`, naming the earlier batch's slug and stacking rather than merging into it. The batches are built in order and depend on each other in that order, which is what a stack expresses, so the dependency argues for stacking and never for collapsing two batches into one file or one review.
 - Mark each batch dependent or independent by comparing the file sets rather than the descriptions. A batch sharing no file with another is independent and earns its own branch even where both arrived in one request. One run measured at 68 files carried three such batches into a single review because nothing drew the boundary.
+- Slice a batch by one user-visible path end to end rather than by layer, so each batch ships something a person can exercise. The slice decides what a batch contains, and the file-set comparison above still decides whether two batches depend on each other, so two slices sharing a file stay marked dependent and stacked.
+- Sequence the riskiest batch first, so the batch most likely to change the plan is built while every later batch can still move. A sweep is the one exception and stays last even when it is the riskiest, per the next bullet.
 - Sequence a sweep last. A batch deliberately rewriting files earlier batches touched is coherent as the final one and forces every batch behind it into one review anywhere else.
 - Keep each batch's commits contiguous once the work starts. A later fix to an earlier batch belongs on that batch's own commits, since a batch interrupted by another cannot be lifted onto its own branch afterward.
 

package/claude/skills/teach-workspace/REQUIREMENT.md

@@ -13,6 +13,8 @@ It picks the next topic from the subject's own order rather than from what the l
 
 It also produces one output where two are needed. A page written to be worked through once and a page written to be looked up later have different lifetimes and different readers, and merging them yields material that is disposable and gets kept, or durable and carries a quiz nobody can promote. Writing the durable half in a format the authoring gates do not read costs a conversion at the moment it matters most, which is the moment someone tries to promote it.
 
+A lesson on a structure can also point at one and draw none. Nothing asks the author whether the subject is a relationship, boundary, path, or before-and-after, so a lesson on layers and ports tells the learner to draw arrows and ships none, and nothing records whether prose was a choice or an omission.
+
 A session that does record something records the wrong thing. It writes what was taught rather than what the learner retrieved, and a tally of errors carries none of the misconception a later session would work against.
 
 The lesson then reaches nobody. It is a page carrying a stylesheet and a script, and the only thing a session hands over is a file path, which an editor preview opens with neither. The learner reads unstyled markup and takes it for the lesson, or opens nothing at all, and either way the session reports the lesson as delivered. A path is also the wrong unit once a workspace holds several pages, since the learner wants the one they are on rather than the folder it sits in.
@@ -31,6 +33,7 @@ Two failures land specifically on where the folder sits. A workspace resolved ag
 - Place each lesson from the learning records rather than from the subject's order, and open with retrieval on the last wrong answer
 - Split the output by lifetime, sending the worked-through half to lessons and the looked-up half to reference pages in the format the authoring gates read
 - Record the wrong answer itself rather than the count, since that is what the next session places the learner from
+- Decide each lesson's figure before writing its body, drawing it or recording in the reply the one-line reason prose carries it, so a structure lesson never ships with neither
 - Report progress against the mission's success lines, so a mission can be called finished
 - Hand the learner a link that opens the workspace in a real browser on every run, reading it back from the verb that served it rather than composing one, since the port a preview lands on is not the port it asked for
 - Propose a destination for each durable page by who owns its subject, and wait for the operator rather than routing on the session's own reading

package/claude/skills/teach-workspace/SKILL.md

@@ -105,7 +105,7 @@ Write the correct option first, then present the options in the order `order` re
 
 ### The quiz, the teach-back block, and the lesson body
 
-Read `${CLAUDE_SKILL_DIR}/references/lesson-craft.md` before writing the lesson. `## Quiz construction` and `## Teach back` there fix the markup `canon teach nav`'s stepper gates on, so a quiz in any other shape shows every question at once and nothing reports it. `## Building the lesson body` carries the four marker pairs, the render, nav, stylesheet, and glossary verbs, and the rule against composing any of them by hand when a verb does not resolve. Keep every quiz answer the same length, so formatting leaks no clue about which one is correct.
+Read `${CLAUDE_SKILL_DIR}/references/lesson-craft.md` before writing the lesson. `## Quiz construction` and `## Teach back` there fix the markup `canon teach nav`'s stepper gates on, so a quiz in any other shape shows every question at once and nothing reports it. `## Building the lesson body` carries the four marker pairs, the render, nav, stylesheet, and glossary verbs, and the rule against composing any of them by hand when a verb does not resolve. Keep every quiz answer the same length, so formatting leaks no clue about which one is correct. Decide the figure first, by `## Diagrams` there.
 
 ### Hand over a link, never a path
 
@@ -158,6 +158,7 @@ Read `${CLAUDE_SKILL_DIR}/references/promotion.md` first. It carries what may be
 Lesson:    .canon/teach/<nn>-<topic>/lessons/<nnnn>-<slug>.html
 Reference: .canon/teach/<nn>-<topic>/reference/<slug>.md
 Record:    .canon/teach/<nn>-<topic>/learning-records/<nnnn>-<slug>.md
+Figure:    <drawn through draft-figure, or the one-line reason prose carries it>
 Progress:  <n> of <m> success lines met
 Open:      [<the url the serve verb reported>](<the same url>)
 ```

package/claude/skills/teach-workspace/references/lesson-craft.md

@@ -36,7 +36,14 @@ Every element competes with the material for attention.
 
 ## Diagrams
 
-Follow `${CLAUDE_SKILL_DIR}/../../standards/figures.md` for when a diagram earns its place, the render-first policy between Mermaid and freehand SVG, and the wrapping, color, and accessibility rules every figure carries. A lesson reaching for a diagram on every section is the failure the neighboring `## Restraint` section already guards against.
+Decide the figure once per lesson, before writing the body.
+
+1. Name the one relationship, boundary, path, or before-and-after the lesson is about. A lesson about none ends here, with `Figure: none, <why it names no structure>` on the reply.
+2. Hold it against the bar in `${CLAUDE_SKILL_DIR}/../../standards/figures.md`, which also carries the drawing rules.
+3. Draw it through `canon:draft-figure` into a `raw` block in the body, before the quiz entry and never inside it or after its feedback, which breaks the stepper's gating. Report it, never hand-draw, when that skill does not resolve.
+4. Or write one line on why prose carries it better, such as a structure an earlier lesson gave.
+
+A structure lesson takes step 3 or 4, never neither. Put the outcome on the reply's `Figure:` line, off the lesson page. Never draw to satisfy the step, or on every section (`## Restraint`).
 
 ## Quiz construction
 

package/claude/skills/test-craft/REQUIREMENT.md

@@ -13,6 +13,8 @@ The one surface that did pick a layer picked the expensive one. The UI test skil
 
 The failure is measured on a real target. A single-page portfolio site carried 219 end to end tests against 4 unit test files, an inverted pyramid. Its suite could not raise its worker count without failing between 11 and 24 tests on every retry, because timing-sensitive assertions sat at the layer where CI load decides the result. One copy edit failed three engines because the copy was asserted in a browser run.
 
+A stated rule is also one a session can talk itself out of. Each test in that suite sat where it did for a reason that sounded fine at the time, such as the end to end spec already being open or a pause quieting a run that flaked under load, and nothing in front of the session answered the reason.
+
 Moving the guidance into a path-scoped rule does not reach the session that needs it. A path-scoped rule loads when a session reads a matching file and not when it creates one, measured in three headless runs, so a rule scoped to test files is silent on the first test of every feature.
 
 ## Must
@@ -25,6 +27,7 @@ Moving the guidance into a path-scoped rule does not reach the session that need
 - Promise a middle layer for behavior a simulated DOM cannot render, naming the real-browser component runners, so a static site is not left choosing between a simulated DOM that computes no layout and a whole-site run
 - Repeat in the end to end reference the two floors a session writing its first spec never loads through the path-scoped rule, being the `scrollend` settle and motion reduced by default
 - Record the external patterns adopted and declined with the reason for each, so a later session extends the position instead of re-deriving it
+- Close with a table of the excuses a session gives for the wrong layer or a weak test, each with its rebuttal, and the red flags a session can see mid-work, so the reasons that produced the inverted pyramid meet an answer before the test lands
 - Trigger on writing or changing any test, after implementing as well as before, since regression tests and end to end tests are mostly written after the code exists
 
 ## Must not
@@ -34,7 +37,7 @@ Moving the guidance into a path-scoped rule does not reach the session that need
 - Restate the structure floors the testing rule already carries, such as arrange, act, assert, one behavior per test, isolation, and no snapshots
 - Restate the settle, guard, and run-scope rules the end to end rules carry, beyond the two floors named above
 - Run the red, green, refactor procedure or decide its order, which `test-first` owns
-- Import an external skill's tone, such as a law stated as absolute or a table of rationalizations with rebuttals
+- Import an external skill's tone, such as a law stated as absolute, or an excuse row rebutting an objection no session has raised
 - Be reached only by an author typing its name. The intended non-author callers are `test-first`'s first step and a description matching any request to write or change a test. A test written in a session that never loaded this skill is the evidence the trigger is too weak, and nothing answers that before the skill has run.
 
 ## Guards

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

@@ -57,9 +57,27 @@ Read the one reference matching the layer the table picked, before writing the f
 
 Read `${CLAUDE_SKILL_DIR}/references/adopted.md` only when extending this guidance or arguing against a rule in it. It records which external patterns were adopted, which declined, and why.
 
-## Run the final filter before handing tests over
+## Excuses and rebuttals
 
-Check every test written this session against each line. A test that fails one is rewritten or cut, never kept with a note.
+| Excuse                                                     | Rebuttal                                                                                                         |
+| ---------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------- |
+| The end to end spec is already open, so add the case there | An open file is not a layer. Read the row off the behavior, and a loading, empty, or error state is a component. |
+| The test is small, so its layer does not matter            | A small test at the wrong layer is run by every later pass, and moving it costs a second test.                   |
+| The copy is what the user sees, so assert it in a browser  | Copy asserted in a browser run fails every engine on one wording change. Assert copy at unit.                    |
+| It only flakes under CI load, so add a pause               | A pause hides the condition the run is waiting on. Settle on the condition, or move the assertion down a layer.  |
+| A mock is quicker to set up than the real collaborator     | A mock proves how the code is built. Take a real collaborator or a fake first.                                   |
+
+## Red flags
+
+- You are opening an end to end spec to add a state rather than a journey.
+- The expected value comes from calling the function under test.
+- A sleep, a timeout, or a retry count is going in to make a run pass.
+- The only assertion is that a double was called.
+- You picked the layer before naming what production change makes the test fail.
+
+## Before handing over
+
+Run the final filter over every test written this session, checking each line. A test that fails one is rewritten or cut, never kept with a note.
 
 - **Mirror assertion.** The expected value is computed by the code under test. Write the literal the behavior should produce.
 - **Change detector.** The assertion pins a constant, a message's wording, or a markup shape no caller depends on.

package/claude/skills/test-craft/references/adopted.md

@@ -25,6 +25,8 @@ External sources were read and filtered rather than imported. This file is the r
 
 **Kent Beck's desiderata as background.** The twelve properties at [testdesiderata.com](https://testdesiderata.com/) trade against each other. "Behavioral" and "structure-insensitive" together are the whole of "test behavior, not implementation", which is why the body states that pair as asserting through the public surface.
 
+**Excuses, red flags, and a closing checklist.** From `addyosmani/agent-skills@2686b620`, [`docs/skill-anatomy.md`](https://github.com/addyosmani/agent-skills/blob/2686b620fc1fed2e8f60c704839c766b8594c6b6/docs/skill-anatomy.md): Common Rationalizations, Red Flags, and Verification. Adopted as the three closing sections every practice skill carries, with the final filter as the closing checklist. This reverses an earlier decline of the excuses table. That decline objected to arguments against imagined objections, so each row here rebuts an excuse this skill's requirement records a session acting on, such as extending the open end to end spec or adding a pause for a run that flakes under load.
+
 ### Per layer
 
 **Component query and wait rules.** Role queries first, user events over synthetic ones, one assertion per wait, no side effects inside a wait ([Common mistakes](https://kentcdodds.com/blog/common-mistakes-with-react-testing-library)). Adopted in `component.md` with the library names removed from the rules.
@@ -37,7 +39,7 @@ External sources were read and filtered rather than imported. This file is the r
 
 **Delete the code written before its test.** `superpowers`'s test-driven skill tells a session to delete implementation written ahead of a failing test. Declined: this toolkit audits the order after the fact with its test-order verb and reports rather than destroys, since deleting working code punishes the session without restoring the evidence the red run would have given.
 
-**Rationalization tables and an iron law.** Both external test-driven skills carry an "Iron Law" and a table of excuses with rebuttals. Declined for tone: this toolkit states a rule once with its reason, and a table of arguments against imagined objections costs a read on every load and adds no constraint.
+**An iron law.** Both external test-driven skills carry an "Iron Law" stated as absolute. Declined for tone: this toolkit states a rule once with its reason.
 
 **One skill per layer.** A unit skill, a component skill, and an end to end skill each loaded on its own trigger. Declined because the layer has to be chosen before the right skill can load, so the choice ends up restated in all three or in a fourth skill that is this one.
 

package/claude/skills/ui-checklist/REQUIREMENT.md

@@ -21,6 +21,7 @@ The automatable half has its own gap, and it is no longer this skill's to close
 
 - Split every change into visual-only and automatable before writing anything
 - Write the checklist for the visual-only half, each item an action and the result a person is looking for
+- Give each item what a driver needs to run it without guessing: the route, the width where the change can differ by width, an action verb to open on, a `(taste)` marker on a judgment of look or feel, and the setup or a `(local only)` marker for a state the page does not open in
 - Name every automatable change shipping with no test, with the layer `test-craft` would place it at, as a section of the same file
 - Write the file to the `.canon/tmp/handoff/ui-checklist/<slug>.md` handoff at the main worktree root, overwriting
 - Report that there is nothing to verify rather than manufacturing a checklist to show work

package/claude/skills/ui-checklist/SKILL.md

@@ -28,9 +28,19 @@ Group visual items by feature area. Use `- [ ]` checkbox syntax, and write each
 
 **<Feature area>**
 
-- [ ] <action> → <expected visual result>
+- [ ] <route>[, <width>]: <verb> <target> → <expected visual result>
 ```
 
+Write each box so a session driving the running app can run it without guessing:
+
+- **Route.** Name where the box is driven, as a path or the control that reaches it. A box naming no route is driven from the address the driver opens, so a single-page app with no routing needs no invented path. Write "from the page the app opens on" when a state is reached by a sequence rather than a URL.
+- **Width.** Name the width a box is driven at only when the change can make it differ by width, the same test the widths block below uses for omission. A box about copy or color renders the same everywhere, so leave the width off rather than inventing one.
+- **Verb.** Open on an action a driver performs, such as "scroll to", "click", "resize to", or "tab to". Never open on "read" or "look at", which name no action.
+- **Taste.** End the line with `(taste)` when the result is a judgment of look or feel rather than a fact a driver can observe. A driver reports such a box as needing a person's eyes instead of passing it.
+- **Setup.** A box needing a state the page does not open in states the setup inline. When a hosted preview cannot reach that state, such as a stopped service or a seeded record, end the line with `(local only)` instead.
+
+The checkbox stays `- [ ]` followed by the action and the result, since the evidence comment carries ticked boxes forward by that shape.
+
 ## The widths block
 
 A screenshot shows one width, so a reviewer cannot tell from the picture alone whether any other width was looked at. When a change touches layout, spacing, or anything responsive, put this block above the visual items, since it frames what the screenshots beside it can support:

package/docs/agents/index.md

@@ -50,7 +50,7 @@ CLI catalog and invocation rules for agents, split by command domain. Start with
 - [Scripting](scripting.md): The runtime catalogs that replace hardcoded names, what each carries, and a headless invocation per domain
 - [Sessions transfer](sessions-transfer.md): Moving a session to another machine, the export bundle and its manifest, placing it with import, the refusal reasons, and what a resume on the target depends on
 - [Sessions](sessions.md): Resolving live peer sessions to the worktree and branch each holds, reading which row is the caller, the liveness confidence field, what each session surface can see, and where moving a session to another machine is described
-- [Skill audit](skills-audit.md): Measuring both skill corpora against standards/skill.md, the checks it reads, the requirement gate that is the only failing one, and the drift verb that names bodies rewritten since a ref
+- [Skill audit](skills-audit.md): Measuring both skill corpora against the skill standards, the checks it reads, the requirement gate that is the only failing one, and the drift verb that names bodies rewritten since a ref
 - [Citation reach](skills-reach.md): Reporting the skill bodies that cite a path no target project receives, which corpus the verb reads, the ownership key that decides what counts, the one-word qualifier that marks a citation as decided, and why the verb reports instead of gating
 - [Standard success criteria](standards-audit.md): Reading the corpus against the success-criterion gate, the two headings it accepts, why the check scopes to arrival rather than the whole corpus, and the exit codes it sets
 - [State-scoped risk](state-scoped-risk.md): Reading committed state rather than an arriving change, the shipped-tree corpus the secret scan reads, what it keys on and how a deliberate value is exempted, the advisory check and its network failure mode, and why one gates while the other reports

package/docs/agents/skills-audit.md

@@ -1,11 +1,11 @@
 ---
 title: Skill audit
-description: Measuring both skill corpora against standards/skill.md, the checks it reads, the requirement gate that is the only failing one, and the drift verb that names bodies rewritten since a ref
+description: Measuring both skill corpora against the skill standards, the checks it reads, the requirement gate that is the only failing one, and the drift verb that names bodies rewritten since a ref
 ---
 
 # Skill audit
 
-`canon claude skills audit [path]` reports both skill corpora against the rules `standards/skill.md` and `standards/skill-requirement.md` state mechanically. It reads and reports. Fixing what it finds is separate work.
+`canon claude skills audit [path]` reports both skill corpora against the rules `standards/skill.md`, `standards/skill-requirement.md`, and `standards/skill-practice.md` state mechanically. It reads and reports. Fixing what it finds is separate work.
 
 ```bash
 canon claude skills audit
@@ -36,6 +36,7 @@ Each check traces to a line in the standard.
 - Folder name in kebab-case
 - Each `REQUIREMENT.md` declaring `Gap` and `Must`, matched at any heading level
 - No ISO date in `SKILL.md` or any file under `references/`, reported as `datedProvenance` in the JSON record's `findings`
+- Each listed practice skill closing with `## Excuses and rebuttals`, `## Red flags`, and `## Before handing over`, and carrying `references/adopted.md`, reported as `practiceShape`
 
 A body whose frontmatter does not parse reports as declaring neither field rather than ending the run, so one malformed file cannot hide the corpus behind it. A key present with an empty value reads as absent, since a blank `name` would otherwise report as a name disagreeing with every folder. A folder carrying no requirement is reported once under presence rather than counted again for the sections it therefore lacks.
 
@@ -43,6 +44,8 @@ The date check reads prose alone. A date inside a fence or a code span is exampl
 
 Each finding names the file and the line, such as `claude/skills/<name>/references/<file>.md  line 12: <date>`. A date after "measured" or "verified" reports like any other, unlike the context audit, because a skill body states the rule a session follows today rather than a reading of the tree.
 
+The practice check reads only the skills the audit lists, which the JSON record carries as `checkpoints.practiceSkills`. The list names folders under the toolkit's shipped `claude/skills/` corpus alone, so a project's own skill is never read as a practice skill and a same-named folder under `.claude/skills/` produces no finding. Where `claude/skills/` resolves, a listed folder it does not hold reports as a missing skill, so a renamed or misspelled entry cannot pass unread. Each closing section matches only as an exact H2 outside a fence, so an H3 or a heading carrying more words reports as missing.
+
 ## What it leaves alone
 
 The report names its own blind spots on every run, including the run where everything passed. Whether each `Must` traces to a stated gap is the rule in the requirement standard worth the most and no parser reads it. Whether a gap states an observed failure rather than an intent, and whether a description routes, are the same kind of judgment. The 150-line body checkpoint is the one mechanical rule still absent here, and adding it would print a count rather than a defect, since the standard makes it a prompt to look with nothing enforcing it.
@@ -53,7 +56,7 @@ A check with no rule behind it prints an opinion as a defect, which is where the
 
 ## Exit codes
 
-Exit codes are `0` for a clean run, `1` for a refusal, and `2` for a skill folder carrying no `REQUIREMENT.md`. Only presence sets a failing code. Name, description, folder, requirement-section, and dated-provenance findings print and return `0`, because each is a judgment a reader settles and failing a push on one would make the check something to route around.
+Exit codes are `0` for a clean run, `1` for a refusal, and `2` for a skill folder carrying no `REQUIREMENT.md`. Only presence sets a failing code. Name, description, folder, requirement-section, dated-provenance, and practice shape findings print and return `0`, because each is a judgment a reader settles and failing a push on one would make the check something to route around. In the toolkit, two `bun run check` stages read the same report in-process and fail a push on dated provenance and on practice shape, since its own corpus is held at zero on both.
 
 ## The requirement gate
 

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@erclx/canon",
   "type": "module",
-  "version": "5.5.0",
+  "version": "5.6.0",
   "description": "Infrastructure and quality tooling for developer workflows",
   "license": "MIT",
   "bin": {

package/src/claude/skills-audit.ts

@@ -12,16 +12,40 @@ export const DESCRIPTION_LIMIT = 1024
 /** The two headings the requirement template declares, matched at any level. */
 export const REQUIREMENT_SECTIONS: readonly string[] = ['Gap', 'Must']
 
+/** The one tree that ships to a target, and the only one the practice list names. */
+export const SHIPPED_CORPUS = join('claude', 'skills')
+
 /**
  * Both trees the standard governs. `claude/skills/` ships to a target and
  * `.claude/skills/` stays here, and every rule measured below applies to each,
  * so a corpus reading one of them reports a pass over half the subject.
  */
 export const CORPORA: readonly string[] = [
-  join('claude', 'skills'),
+  SHIPPED_CORPUS,
   join('.claude', 'skills'),
 ]
 
+/**
+ * The practice skills `standards/skill-practice.md` describes, keyed by corpus-relative
+ * folder rather than by name, so a target's own `.claude/skills/` folder that
+ * shares a name is never swept in. The list lives here rather than in a skill's
+ * frontmatter because a skill declaring its own kind could exempt itself.
+ */
+export const PRACTICE_SKILLS: readonly string[] = [
+  join(SHIPPED_CORPUS, 'codebase-layout'),
+  join(SHIPPED_CORPUS, 'test-craft'),
+]
+
+/** The closing H2s a practice skill carries, matched exactly outside fences. */
+export const PRACTICE_SECTIONS: readonly string[] = [
+  'Excuses and rebuttals',
+  'Red flags',
+  'Before handing over',
+]
+
+/** The source ledger every practice skill carries beside its body. */
+export const PRACTICE_LEDGER = join('references', 'adopted.md')
+
 /**
  * The one reason this audit refuses. A project carrying neither corpus is the
  * ordinary state of a target that has not adopted either skills convention,
@@ -34,6 +58,8 @@ const KEBAB_CASE = /^[a-z0-9]+(?:-[a-z0-9]+)*$/
 
 const HEADING = /^#{1,6}\s+(.+?)\s*$/
 
+const SECTION = /^##\s+(.+?)\s*$/
+
 /**
  * An ISO date, read as provenance wherever a reader is told it. The context
  * audit's detector clears a date after "measured" or "verified", and a skill
@@ -69,6 +95,7 @@ export interface SkillsAudit {
   readonly longDescription: readonly SkillFinding[]
   readonly requirementSections: readonly SkillFinding[]
   readonly datedProvenance: readonly SkillFinding[]
+  readonly practiceShape: readonly SkillFinding[]
 }
 
 interface SkillSource {
@@ -79,6 +106,9 @@ interface SkillSource {
   readonly description: string | undefined
   /** Undefined when the folder carries no `REQUIREMENT.md` at all. */
   readonly requirementHeadings: readonly string[] | undefined
+  /** Every H2 in `SKILL.md` outside a fence, for the practice shape. */
+  readonly sections: readonly string[]
+  readonly hasLedger: boolean
   /**
    * `SKILL.md` and every reference below the folder, keyed by the path a
    * finding names. `REQUIREMENT.md` and `EVAL.md` are left out, since the
@@ -134,6 +164,13 @@ export async function auditSkills(root: string): Promise<SkillsAudit> {
     datedProvenance: sources.flatMap((source) =>
       source.bodies.flatMap(dateFindings),
     ),
+    practiceShape: [
+      ...missingPracticeSkills(
+        present.some((corpus) => corpus.rel === SHIPPED_CORPUS),
+        sources,
+      ),
+      ...sources.flatMap(practiceFindings),
+    ],
   }
 }
 
@@ -190,6 +227,11 @@ async function readSkill(
     description: declared(readField(fields, 'description')),
     requirementHeadings:
       requirement === undefined ? undefined : headings(requirement),
+    sections: bodyLines(body)
+      .filter((line) => !line.fenced)
+      .map((line) => SECTION.exec(line.text)?.[1])
+      .filter((text): text is string => text !== undefined),
+    hasLedger: existsSync(join(skillDir, PRACTICE_LEDGER)),
     bodies: [
       { rel: join(skillRel, 'SKILL.md'), text: body },
       ...references.map((path, index) => ({
@@ -252,6 +294,44 @@ function sectionFindings(source: SkillSource): SkillFinding[] {
   ]
 }
 
+/**
+ * A listed folder the shipped corpus does not hold, such as a renamed skill or
+ * a misspelled append, would otherwise read as a pass. Silent where the
+ * shipped corpus is absent, since a target carries none of the listed skills.
+ */
+function missingPracticeSkills(
+  hasShippedCorpus: boolean,
+  sources: readonly SkillSource[],
+): SkillFinding[] {
+  if (!hasShippedCorpus) return []
+  const found = new Set(sources.map((source) => source.rel))
+  return PRACTICE_SKILLS.filter((rel) => !found.has(rel)).map((rel) => ({
+    rel,
+    detail: 'missing skill: no folder under the shipped corpus',
+  }))
+}
+
+/**
+ * Matches each section as an exact H2, so a heading carrying trailing text or
+ * sitting at another level reads as missing rather than as a near match the
+ * standard never names.
+ */
+function practiceFindings(source: SkillSource): SkillFinding[] {
+  if (!PRACTICE_SKILLS.includes(source.rel)) return []
+
+  const sections = PRACTICE_SECTIONS.filter(
+    (section) => !source.sections.includes(section),
+  ).map((section) => ({
+    rel: source.rel,
+    detail: `missing section: ${section}`,
+  }))
+  const ledger = source.hasLedger
+    ? []
+    : [{ rel: source.rel, detail: `missing ledger: ${PRACTICE_LEDGER}` }]
+
+  return [...sections, ...ledger]
+}
+
 /**
  * A date inside a fence or a code span is example data a reader is shown, such
  * as a sample frontmatter block, so only prose outside both is read.

package/src/commands/claude.ts

@@ -26,7 +26,11 @@ import {
   auditSkills,
   CORPORA,
   DESCRIPTION_LIMIT,
+  PRACTICE_LEDGER,
+  PRACTICE_SECTIONS,
+  PRACTICE_SKILLS,
   REQUIREMENT_SECTIONS,
+  SHIPPED_CORPUS,
   type SkillFinding,
   type SkillsAudit,
   type SkillsAuditRefusal,
@@ -1398,6 +1402,7 @@ async function runSkillsAudit(
     reportFolder(report)
     reportRequirementShape(report)
     reportProvenance(report)
+    reportPracticeShape(report)
     reportUnmeasured()
     outro()
   }
@@ -1420,11 +1425,14 @@ async function runSkillsAudit(
           folderName: report.folderName,
           requirementSections: report.requirementSections,
           datedProvenance: report.datedProvenance,
+          practiceShape: report.practiceShape,
         },
         checkpoints: {
           descriptionLimit: DESCRIPTION_LIMIT,
           requirementSections: REQUIREMENT_SECTIONS,
           corpora: CORPORA,
+          practiceSkills: PRACTICE_SKILLS,
+          practiceSections: PRACTICE_SECTIONS,
         },
       })}\n`,
     )
@@ -1615,6 +1623,31 @@ function reportProvenance(report: SkillsAudit): void {
   reportFindings(report.datedProvenance)
 }
 
+/**
+ * Reports without failing the run for the reason provenance does. The list
+ * names shipped folders alone, which the step says so a target reading a pass
+ * knows its own skills were never in scope.
+ */
+function reportPracticeShape(report: SkillsAudit): void {
+  logStep('Practice shape')
+  logInfo(
+    `A listed practice skill closes with ${PRACTICE_SECTIONS.map((section) => `## ${section}`).join(', ')}, and carries ${PRACTICE_LEDGER}.`,
+  )
+  logInfo(
+    `The list is kept here and names ${plural(PRACTICE_SKILLS.length, 'shipped skill')}, so a skill outside ${SHIPPED_CORPUS} is never read.`,
+  )
+
+  if (report.practiceShape.length === 0) {
+    logInfo('Every listed practice skill carries its shape.')
+    return
+  }
+
+  logWarn(
+    `${plural(report.practiceShape.length, 'missing part')} across the listed practice skills`,
+  )
+  reportFindings(report.practiceShape)
+}
+
 /**
  * Stated on every run, including the run where everything above passed. A
  * report that lists only what it measured reads as a verdict on the standard

package/src/gate/measures.ts

@@ -13,7 +13,12 @@ import {
   measureArchitecture,
   missingRevisit,
 } from '@/context/architecture'
-import { auditSkills } from '@/claude/skills-audit'
+import {
+  auditSkills,
+  PRACTICE_LEDGER,
+  PRACTICE_SKILLS,
+  SHIPPED_CORPUS,
+} from '@/claude/skills-audit'
 import { listRepositoryFiles } from '@/git-files'
 import { ceilingFindings } from '@/markdown/ceiling'
 import { resolveMarkdown } from '@/markdown/files'
@@ -314,6 +319,43 @@ export const skillProvenance: Measure = async (ctx) => {
   }
 }
 
+/**
+ * Every listed practice skill against the closing sections and the ledger
+ * `standards/skill-practice.md` requires of one.
+ *
+ * Read in-process for the reason `skillProvenance` is, so the verb keeps its
+ * missing-requirement-only exit. The list names shipped folders alone, so a
+ * tree without `claude/skills/` reports unmeasured rather than a vacuous pass.
+ */
+export const skillPracticeShape: Measure = async (ctx) => {
+  const report = await auditSkills(ctx.root)
+  if (!report.corpora.some((corpus) => corpus.rel === SHIPPED_CORPUS)) {
+    return {
+      emissions: [],
+      unmeasured: `no skill corpus at ${SHIPPED_CORPUS} resolved, so no practice skill was read.`,
+    }
+  }
+
+  const found = report.practiceShape
+  if (found.length > 0) {
+    const where = found
+      .map((finding) => `${finding.rel} ${finding.detail}`)
+      .join(', ')
+    return {
+      emissions: [],
+      failure: `${plural(found.length, 'practice shape finding')}: ${where}. Add the closing H2 exactly as named, or the ledger at ${PRACTICE_LEDGER}.`,
+    }
+  }
+
+  return {
+    emissions: [
+      info(
+        `${plural(PRACTICE_SKILLS.length, 'practice skill')} carry every closing section and a ledger`,
+      ),
+    ],
+  }
+}
+
 /**
  * Every tracked markdown document against the whole-document ceiling.
  *

package/src/gate/stages.ts

@@ -14,6 +14,7 @@ import {
   seedStandards,
   rawFieldFileReference,
   shippedReferences,
+  skillPracticeShape,
   skillProvenance,
   standardCriteria,
   unreferencedRules,
@@ -486,6 +487,14 @@ export const STAGES: readonly Stage[] = [
     label: 'Skill provenance',
     checks: [{ kind: 'measure', measure: skillProvenance }],
   },
+  {
+    // The audit verb only reports a listed practice skill missing a closing
+    // section or its ledger, so a target is told without failing. The list
+    // names this repository's shipped skills, so the stage fails here alone.
+    id: 'skill-practice-shape',
+    label: 'Skill practice shape',
+    checks: [{ kind: 'measure', measure: skillPracticeShape }],
+  },
   {
     id: 'standard-criteria',
     label: 'Standard success criteria',

package/standards/index.md

@@ -31,6 +31,7 @@ Reference docs for consistent authoring across the toolkit and target projects.
 - [Requirements reference](requirements.md): Shape and content rules for canon/REQUIREMENTS.md
 - [Governance rule reference](rule.md): Rule frontmatter, body shape, and voice for .claude/rules files
 - [Session map reference](session.md): Filename and location, the sections a handoff carries, the write and read procedures, and how a role extends it
+- [Practice skill reference](skill-practice.md): Closing sections and source ledger for a skill carrying engineering practice
 - [Skill requirement reference](skill-requirement.md): Shape and content rules for the REQUIREMENT.md beside a skill
 - [Claude skill reference](skill.md): Claude skill structure and authoring rules
 - [Slug reference](slug.md): Transform from a git branch name to a slug, and the three responses to an empty result

package/standards/skill-practice.md

@@ -0,0 +1,51 @@
+---
+title: Practice skill reference
+description: Closing sections and source ledger for a skill carrying engineering practice
+---
+
+# Practice skill reference
+
+Applies to a practice skill, one carrying engineering judgment a session applies while it works, where the failure is skipping the practice or cutting it short rather than not knowing it. Its body takes the reference shape, and this file fixes how it closes and what it cites.
+
+## Scope
+
+Governs the closing sections of a practice skill's `skills/<name>/SKILL.md` and the source ledger at `skills/<name>/references/adopted.md` beside it.
+
+Does not govern:
+
+- The skill folder, its frontmatter, the body rules, and the choice between skill types: `skill.md`
+- The `REQUIREMENT.md` beside the body: `skill-requirement.md`
+- Voice, rhythm, and sentence construction: the `write-human` skill
+- Punctuation, formatting, and word choice: `markdown.md`
+
+## What a working practice skill looks like
+
+A practice skill works when a session about to cut the practice short meets the answer before it does:
+
+- Does every excuse row name a reason a session has actually given to skip the practice?
+- Can a session spot each red flag in its own work while it is still working?
+- Can a session run every line of the closing checklist against what it produced, and get a yes or a no?
+- Can a reader open each source the ledger names and find the version the body states?
+
+A practice skill failing any of these is non-conforming even when every heading below is present.
+
+## Closing sections
+
+- Follow every concern group with three H2s in this order: `## Excuses and rebuttals`, `## Red flags`, and `## Before handing over`. A section naming what the skill delegates comes after the three, and nothing else does.
+- Spell each heading exactly. An H3, or a heading carrying more words such as `## Red flags that mean start over`, reads as missing.
+- Write `## Excuses and rebuttals` as a two-column table pairing a reason a session gives to skip or shortcut the practice with the answer to it. Never write a row rebutting an objection nobody raised, since that row is ceremony. Revisit when a practice skill's table is observed failing to stop an excuse it names.
+- Write `## Red flags` as bullets naming signs a session can observe in its own work mid-task, never a restatement of a rule above.
+- Write `## Before handing over` as the exit checklist, each line a check against what the session produced.
+
+## Source ledger
+
+- Carry `references/adopted.md` in every practice skill, recording each external source the body draws on.
+- Link each source, or pin it to a commit, so a reader can open the version the body adopted.
+- State what was adopted, what was declined, and why for each, so a later session extends the position rather than re-deriving it.
+- Draw first from the default shelf, [Software Engineering at Google](https://abseil.io/resources/swe-book/html/toc.html) and [Google's engineering practices](https://google.github.io/eng-practices/), and record a source from elsewhere the same way.
+
+## Which skills are practice skills
+
+- `canon claude skills audit` keeps the list of practice skills and checks each listed one for the three closing sections and the ledger.
+- Never mark a skill as a practice skill in its own frontmatter, since a self-declared kind lets a skill exempt itself.
+- The list names this toolkit's shipped skills alone, so a project's own practice skill takes this shape with no check behind it.

package/standards/skill.md

@@ -16,6 +16,7 @@ Governs a skill folder under `skills/` as one artifact: `SKILL.md`, its siblings
 Does not govern:
 
 - What a `REQUIREMENT.md` must answer, its sections, and its template: `skill-requirement.md`
+- A practice skill's closing sections and ledger: `skill-practice.md`
 - Path-scoped coding rules, which load on a file match rather than on a request match: `rule.md`
 - Voice, rhythm, and sentence construction in a skill body: the `write-human` skill
 - Punctuation, formatting, and word choice in a skill body: `markdown.md`
@@ -45,6 +46,7 @@ Pick the type before writing. It decides the body shape.
 
 - Reference: conventions, patterns, and domain knowledge Claude applies inline. The body is rule bullets grouped by concern.
 - Task: step-by-step workflows Claude executes as actions. The body is numbered steps plus the rules constraining them.
+- Practice: judgment a session may skip, shaped by `skill-practice.md`.
 
 A task skill takes the template below. A reference skill takes the same frontmatter and replaces `## Steps` and `## Rules` with one H2 per concern group, each holding constraint bullets.
 
@@ -105,7 +107,7 @@ allowed-tools: <tools required>
 - Group bullets under H2 headings by domain concern. Keep dos and don'ts together under the topic they belong to rather than splitting them into flat rules and constraints sections.
 - One actionable constraint per bullet. Prefer the `X over Y` form for preferences.
 - Do not include code examples unless a one to three line inline snippet captures a pattern the model cannot infer.
-- Do not duplicate general knowledge the model already has. Focus on project-specific conventions and preferences. Revisit when removing a line of general knowledge from a skill is shown to change what the agent does.
+- Keep a statement only when removing it would change what the agent does, naming a principle as a few-word handle rather than explaining it. Revisit when a run shows the model ignoring a principle named only as a handle.
 
 ### Progressive disclosure