@erclx/canon 5.41.0 → 5.42.0

package/claude/skills/teach-workspace/references/promotion-fold.md

@@ -7,23 +7,29 @@ description: How teach-workspace's fold mode lands each page a teach promotion h
 
 The fold mode of `teach-workspace`, run from a branch in a worktree. The session reads this file when the invocation asks to fold confirmed promotions in.
 
-Derive `<slug>` per `${CLAUDE_SKILL_DIR}/../git-branch/references/slug.md`, falling back to `latest` on an empty result, and read `.canon/tmp/handoff/teach-promotion/<slug>.md` at the main worktree root. `teach-workspace` writes it, one H2 per destination naming the path, with a source line under the heading and the page body in a fenced block below that. Read the body out of the fence rather than off the heading level, since a reference page carries headings of its own and only the fence separates them from the next destination. Stop when the file is absent, reporting `❌ No promotion handoff at .canon/tmp/handoff/teach-promotion/<slug>.md. Run the promotion step from the workspace first.`
+## Read the handoff
 
-Each block is a page an operator already confirmed a destination for, so this step lands it rather than judging it again. Write to the destination the heading names, at `pwd` rather than at the main root, since every destination here is a tracked file that commits with the branch:
+Derive `<slug>` per `${CLAUDE_SKILL_DIR}/../git-branch/references/slug.md`, falling back to `latest` on an empty result, and read `.canon/tmp/handoff/teach-promotion/<slug>.md` at the main worktree root.
 
-- A wiki page and a public doc arrive as a whole file. Write it as the block gives it, and stop with the block unfolded when the destination path already holds a file, since overwriting a page someone else wrote is not a fold.
-- A context entry is merged into rather than created. Fold the body into the sections it belongs under, and never add an entry the catalog does not already carry.
+- `teach-workspace` writes it, one H2 per destination naming the path, a source line under the heading, and the page body fenced below that
+- Read the body out of the fence rather than off the heading level, since a reference page carries headings of its own and only the fence separates them from the next destination
+- Stop when the file is absent, reporting `❌ No promotion handoff at .canon/tmp/handoff/teach-promotion/<slug>.md. Run the promotion step from the workspace first.`
 
-Then delete the handoff file so a later run does not fold it twice, and regenerate the index of any folder that carries one.
+## Land each block
 
-Output one line per page landed:
+Each block is a page an operator already confirmed a destination for, so this step lands it rather than judging it again. Write to the destination the heading names at `pwd` rather than the main root, since every destination is a tracked file that commits with the branch.
 
-`✅ Promoted: <destination path>`
+- A wiki page and a public doc arrive as a whole file. Write it as the block gives it, and leave the block unfolded when the destination holds a file, since overwriting another's page is not a fold.
+- A context entry is merged into rather than created. Fold the body into the sections it belongs under, and never add an entry the catalog does not already carry.
 
-Add a line naming the handoff when one was consumed:
+Then delete the handoff file so a later run does not fold it twice, and regenerate the index of any folder that carries one.
 
-`🧹 Folded: .canon/tmp/handoff/teach-promotion/<slug>.md`
+## Output
 
-Report a block left unfolded rather than dropping it:
+One line per page landed, one naming the handoff when one was consumed, and one per block left unfolded rather than dropped.
 
-`⚠ Skipped: <destination path> already exists. Merge by hand.`
+```plaintext
+✅ Promoted: <destination path>
+🧹 Folded: .canon/tmp/handoff/teach-promotion/<slug>.md
+⚠ Skipped: <destination path> already exists. Merge by hand.
+```

package/claude/skills/teach-workspace/references/promotion.md

@@ -6,9 +6,11 @@ Which surface a durable page from a learning workspace belongs to, and what to d
 
 Only the durable half. A reference page under `reference/` and `GLOSSARY.md` carry no learner and are ordinary reference prose about a subject, so they sort under the routing test like anything else.
 
-A lesson is never promoted, at any age and on any request. It is generated markup written to be worked through once, it carries a quiz and a second person, and nothing downstream cites it. Promoting one puts ungated markup into a corpus every other page passed a gate to enter.
+A lesson is never promoted, at any age and on any request. It is generated markup worked through once, carrying a quiz and a second person, and nothing downstream cites it.
 
-A reference page that reads like a lesson is a lesson wearing the wrong extension. Where a page under `reference/` carries a quiz, a second person, or an instruction to the learner, say so and propose rewriting it in place before promotion rather than promoting it and repairing it at the destination.
+- Promoting one puts ungated markup into a corpus every other page passed a gate to enter
+- A reference page carrying a quiz, a second person, or an instruction to the learner is a lesson wearing the wrong extension
+- Say so, and propose rewriting that page in place before promotion rather than repairing it at the destination
 
 ## The routing test
 
@@ -31,9 +33,13 @@ The folder has two spellings and a project carries whichever its scaffold wrote:
 
 Read which one exists rather than composing either. A project carrying both keeps its pages at the root, so propose the root spelling and say the other folder is there.
 
+### Neither spelling
+
 A project carrying neither gets a refusal rather than a scaffold:
 
-`❌ No wiki folder. Run canon wiki init to create one, then promote again.`
+```plaintext
+❌ No wiki folder. Run canon wiki init to create one, then promote again.
+```
 
 Creating the folder as a side effect of promoting one page hands the project a surface it never chose, and the refusal is one command from resolved.
 
@@ -63,7 +69,11 @@ Still owed:    <what the destination expects that the page does not carry yet>
 
 Then stop and let the operator strike, redirect, or confirm each block.
 
-Write nothing to a destination here. One skill owns the durable writes, and two skills editing one file at one step is the failure that rule exists against. Record each confirmed block in `.canon/tmp/handoff/teach-promotion/<slug>.md` at the main worktree root instead, appending when the file exists, with one H2 per destination naming its path, the source page beneath it, and the page body fenced:
+### Record the handoff
+
+Write nothing to a destination here. One skill owns the durable writes, and two skills editing one file at one step is the failure that rule exists against.
+
+Record each confirmed block in `.canon/tmp/handoff/teach-promotion/<slug>.md` at the main worktree root instead, appending when the file exists. Each destination takes one H2 naming its path, the source page beneath it, and the page body fenced:
 
 ````markdown
 ## <destination path>
@@ -75,13 +85,26 @@ Source: .canon/teach/<nn>-<topic>/reference/<slug>.md
 ```
 ````
 
-The body is fenced rather than written bare because a reference page carries headings of its own, and the reader splits this file on its H2 lines. An unfenced body turns every section heading in the page into a destination naming no path. Open the body fence with four backticks so a page carrying a fenced code block of its own still closes where it should, and widen both fences together if it carries a four-backtick fence.
-
 Derive `<slug>` per `${CLAUDE_SKILL_DIR}/../git-branch/references/slug.md`. Fall back to `latest` on an empty result.
 
-The handoff is its own file rather than a shared one. The routed-facts file another skill writes is deleted by whichever pass folds it, so a second producer's unread work goes with it, and a sibling path costs the folding skill one more read and removes the interaction.
+### Why the fence
+
+A reference page carries headings of its own, and the reader splits this file on its H2 lines. An unfenced body turns every section heading in the page into a destination naming no path.
+
+- Open the body fence with four backticks, so a page carrying a fenced code block still closes where it should
+- Widen both fences together if the page carries a four-backtick fence
+
+### Why a file of its own
+
+The routed-facts file another skill writes is deleted by whichever pass folds it, so a second producer's unread work would go with it. A sibling path costs the folding skill one more read and removes the interaction.
+
+### Sending and reporting
+
+An append is a whole-file operation, so send it as a heredoc, per the skill's Step 0. Then tell the operator that `/teach-workspace fold` folds the file in from a branch.
+
+The proposal costs nothing tracked and runs anywhere. The page it describes is a tracked file, so the fold is a worktree operation and the workspace it came from is not.
 
-An append is a whole-file operation, so send it as a heredoc, per the skill's Step 0. Then tell the operator that `/teach-workspace fold` folds the file in from a branch. The proposal costs nothing tracked and runs anywhere, while the page it describes is a tracked file, so the fold is a worktree operation and the workspace it came from is not.
+### Output
 
 A promotion pass reports this shape in place of the skill's Output block, one line per page the operator confirmed and one naming the handoff:
 

package/claude/skills/teach-workspace/references/revisit.md

@@ -15,8 +15,14 @@ Then write `## Revisit`, one bullet per item, in the shape `${CLAUDE_SKILL_DIR}/
 - **<what comes back up>**: due <YYYY-MM-DD>, rung <n>
 ```
 
-Take both the date and the rung from the `due` entry Step 1 already read, copying `hit` for an item the learner retrieved unaided and `miss` for one they did not, with the rung stepped the same way. Do not compute a date from the ladder. A session told to widen a gap still picks the number by judgment, which is the reason the verb reports both dates at all.
+## Where the date comes from
 
-An item the records have never scheduled has no `due` entry to copy from. Open it at rung 1, dated the day after this session, which is the ladder's floor and the one number this body states. Every later date for it comes from the verb.
+Take both the date and the rung from the `due` entry Step 1 already read. Copy `hit` for an item the learner retrieved unaided and `miss` for one they did not, with the rung stepped the same way.
+
+- Do not compute a date from the ladder. A session told to widen a gap still picks the number by judgment, which is why the verb reports both dates.
+- An item never scheduled has no `due` entry. Open it at rung 1, dated the day after this session, the ladder's floor and the one number this body states.
+- Every later date for that item comes from the verb
+
+## Writing the shape exactly
 
 An entry outside this shape schedules nothing and nothing reports that it was skipped, so write the shape exactly. A later record naming the same item supersedes an earlier entry, so revise a schedule by writing the new bullet rather than editing the record it was set in.

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

@@ -73,7 +73,10 @@ A workspace failing these is non-conforming even when it satisfies every shape r
 | `lessons/`              | Numbered lessons, generated and disposable                              | Optional |
 | `assets/`               | Files several lessons share, including the stylesheet                   | Optional |
 
-Only the markdown half answers to a conformance check: `MISSION.md`, `RESOURCES.md`, `GLOSSARY.md`, `NOTES.md`, the markdown under `reference/`, and `learning-records/`. A lesson is generated markup that nothing downstream cites, so this standard fixes its filename and its location and says nothing about what it contains. A rendered reference page is the same kind of output, rewritten from its markdown on every `nav` run.
+Only the markdown half answers to a conformance check: `MISSION.md`, `RESOURCES.md`, `GLOSSARY.md`, `NOTES.md`, the markdown under `reference/`, and `learning-records/`.
+
+- A lesson is generated markup nothing downstream cites, so this standard fixes its filename and location and nothing about its contents
+- A rendered reference page is the same kind of output, rewritten from its markdown on every `nav` run
 
 ## Frontmatter
 
@@ -125,15 +128,18 @@ Write one bullet per item, in this shape and no other:
 - **<what comes back up>**: due <YYYY-MM-DD>, rung <n>
 ```
 
-The rung is where the item sits on the spacing ladder, and it travels in the record rather than being counted from how many records name the item, since a miss drops it back and a count only climbs. A later record naming the same item supersedes an earlier one, so revise the schedule by writing the new entry rather than editing the old record.
+The rung is the item's place on the spacing ladder. It travels in the record rather than being counted from records naming the item, since a miss drops it back and a count only climbs.
 
-Take the date and the rung from what the surface driving the workspace reports rather than picking either. An entry outside this shape schedules nothing, and nothing reports that it was skipped.
+- A later record naming the item supersedes an earlier one, so revise by writing a new entry rather than editing the old record
+- Take the date and rung from what the driving surface reports. An entry outside this shape schedules nothing, silently.
 
 ## GLOSSARY.md
 
-Required in every workspace, holding one entry per term the subject defines. The glossary reference the `canon:teach-workspace` skill carries fixes what an entry looks like, how the file orders and groups them, and which terms it carries, so this standard states only that the file exists and sits at the workspace root. That reference ships with the plugin rather than installing here, because a promoted glossary keeps its shape wherever it lands and no project folder covers every destination. Say so and stop rather than working the shape from memory when the project has no plugin to read it from.
+Required at the root of every workspace, one entry per term the subject defines. The glossary reference the `canon:teach-workspace` skill carries fixes the entry shape, order, grouping, and which terms it holds.
 
-Name the lesson or reference page a term first appears in as that reference requires. A workspace is the case it was written for, so a glossary here has a first appearance to name.
+- That reference ships with the plugin rather than installing here, since a promoted glossary keeps its shape wherever it lands
+- With no plugin to read it from, say so and stop rather than working the shape from memory
+- Name the lesson or reference page a term first appears in, which a workspace always has
 
 ## RESOURCES.md
 
@@ -143,7 +149,7 @@ Splits what was read from what was found.
 - List under a leads heading any source found and not opened, and never cite one
 - Say which claims in the workspace rest on which source
 
-A source found and not read is listed as a lead because a link attached to a page nobody opened is worse than no link. Listing it still pays, since it stops a later session searching for what this one already surfaced.
+An unread source is a lead because a link to a page nobody opened is worse than none. Listing it stops a later session searching again.
 
 ### Choosing sources
 
@@ -155,6 +161,8 @@ Rest each general claim on the highest rung that covers it:
 
 A subject nobody owns, such as a mathematical topic or a craft, has no first rung, so its list starts at the second and is not missing anything. Record a third-rung source with the claim it covers and why no higher rung does, since that reason is what a later session checks the choice against.
 
+### What never counts
+
 The learner's own projects and material specific to one employer or organization are never a source for a general claim. Either may appear in the workspace as a worked application labeled with whose it is, and neither stands in `RESOURCES.md` as proof of what the subject says.
 
 A source reachable only through a paywall or a summary stays a lead until it is opened. A review or summary of a book is a different source from the book, so list the summary as read on its own rung and the book as a lead.
@@ -170,9 +178,9 @@ A source reachable only through a paywall or a summary stays a lead until it is
 - **The mission with no test.** Success stated as understanding rather than as a task leaves nothing able to say the mission is finished.
 - **The lesson filed as reference.** A page written to be worked through once sits in `lessons/`, and putting it in `reference/` puts disposable output in the half that gets promoted.
 - **The record that counts errors.** A tally of how many were missed carries none of the misconception, which is the only part a later session can act on.
-- **The revisit note with no date.** A line naming what to come back to and not when is read by nothing and schedules nothing, so the next session picks from the last record alone, which is the state the section exists to end.
-- **The date left in the body.** A frontmatter field and a sentence both claiming the opening date resolve to whichever a reader happens to hit, and only one of them is readable by a walker.
-- **The first search result as the source list.** A workspace resting on whatever a search returned first teaches the weakest account of the subject, and nothing in the folder says a stronger one was never looked for.
+- **The revisit note with no date.** A line naming what to come back to and not when schedules nothing, so the next session picks from the last record alone, the state the section exists to end.
+- **The date left in the body.** A frontmatter field and a sentence both claiming the opening date resolve to whichever a reader hits, and a walker reads only one.
+- **The first search result as the source list.** A workspace resting on the first search hit teaches the weakest account of the subject, and nothing in the folder says a stronger one went unsought.
 - **The renumbered folder.** Closing a gap in the ordinals moves every name a reader or a record already cited.
 
 ## Template

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

@@ -11,36 +11,70 @@ External sources were read and filtered rather than imported. This file is the r
 
 ### Choosing the layer
 
-**The smallest-layer rule.** Fowler: "Push your tests as far down the test pyramid as you can", and write a lower test when a higher one catches what no lower one did ([Practical Test Pyramid](https://martinfowler.com/articles/practical-test-pyramid.html)). It is the body's layer rule and the reason for the decision table.
+Three sources settle which layer a test belongs at and how the decision table reads.
 
-**Sizing by what a test touches.** Google's small, medium, and large sizes name what a test may touch rather than what it covers ([Software Engineering at Google, ch. 11](https://abseil.io/resources/swe-book/html/ch11.html)). The decision table reads the same way, keyed on what the behavior touches, so it transfers across stacks without naming a runner. The scope names unit, component, and end to end stay as the labels, since those are the names a reader and a file suffix already use.
+| Adopted                                | Source                                                                                                                                                                          |
+| -------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| The smallest-layer rule                | Fowler, "push your tests as far down the test pyramid as you can" ([Practical Test Pyramid](https://martinfowler.com/articles/practical-test-pyramid.html))                     |
+| Sizing by what a test touches          | Google's small, medium, and large sizes ([Software Engineering at Google, ch. 11](https://abseil.io/resources/swe-book/html/ch11.html))                                         |
+| The component layer carrying UI weight | Kent C. Dodds's trophy ([Write tests](https://kentcdodds.com/blog/write-tests)) and Testing Library's [guiding principles](https://testing-library.com/docs/guiding-principles) |
 
-**The component layer carrying UI weight.** Kent C. Dodds's trophy ([Write tests](https://kentcdodds.com/blog/write-tests)) and Testing Library's principle that tests resembling use give more confidence ([guiding principles](https://testing-library.com/docs/guiding-principles)). The pyramid and the trophy are one rule applied to different code: a component's logic is its rendered behavior, so its lowest layer is a rendered test.
+- Fowler writes a lower test when a higher one catches what no lower one did. It is the body's layer rule and the decision table's reason.
+- Google's sizes name what a test may touch rather than cover. The table keys on the same, so it transfers across stacks without naming a runner.
+- Testing Library holds that tests resembling use give more confidence
+
+The scope names unit, component, and end to end stay as the labels, since a reader and a file suffix already use them. The pyramid and the trophy are one rule applied to different code, since a component's logic is its rendered behavior and its lowest layer is a rendered test.
 
 ### Judging a test
 
-**The opening question and the final filter.** From `obra/superpowers@5bf4e78`, `skills/test-driven-development/writing-good-tests.md`: name the production change that makes a test fail and whether it is a bug or a decision, then cut mirror assertions, change detectors, assertions on mocks, framework tests, and run the mutation check. Adopted as the body's opening question and final filter, with the fixed pause added from the end to end incidents.
+The opening question and final filter come from `obra/superpowers@5bf4e78`, `skills/test-driven-development/writing-good-tests.md`. It names the production change that makes a test fail and whether it is a bug or a decision.
+
+- It then cuts mirror assertions, change detectors, assertions on mocks, and framework tests, and runs the mutation check
+- Adopted as the body's opening question and final filter, with the fixed pause added from the end to end incidents
+
+### Doubles in preference order and DAMP over DRY
+
+From `addyosmani/agent-skills@c004a74`, `skills/test-driven-development/SKILL.md`, which orders real, fake, stub, then mock, and prefers descriptive test bodies over shared helpers. Adopted in `unit.md`.
+
+### Kent Beck's desiderata
+
+The twelve properties at [testdesiderata.com](https://testdesiderata.com/) trade against each other and serve as background. "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.
 
-**Doubles in preference order and DAMP over DRY.** From `addyosmani/agent-skills@c004a74`, `skills/test-driven-development/SKILL.md`: real, fake, stub, mock, and descriptive test bodies over shared helpers. Adopted in `unit.md`.
+### Excuses, red flags, and a closing checklist
 
-**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.
+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.
 
-**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.
+This reverses an earlier decline of the excuses table, which objected to arguments against imagined objections. 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.
+Each layer reference takes its rules from the tool's own guidance.
 
-**Web-first assertions, actionability, config-wide reduced motion, sharding.** From Playwright's own pages ([best practices](https://playwright.dev/docs/best-practices), [actionability](https://playwright.dev/docs/actionability), [TestOptions](https://playwright.dev/docs/api/class-testoptions)). Adopted in `e2e.md`, where the runner is named because the reference is the per-layer home for runner specifics.
+| Reference      | Adopted                                                                                                    | Source                                                                                                                                                                                                      |
+| -------------- | ---------------------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `component.md` | 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)                                                                                                                   |
+| `e2e.md`       | Web-first assertions, actionability, config-wide reduced motion, sharding                                  | Playwright's [best practices](https://playwright.dev/docs/best-practices), [actionability](https://playwright.dev/docs/actionability), and [TestOptions](https://playwright.dev/docs/api/class-testoptions) |
+
+`component.md` states its rules with the library names removed. `e2e.md` names the runner, since the reference is the per-layer home for runner specifics.
 
 ## Declined
 
-**A numeric mix.** Google targets roughly 80% unit, 15% integration, 5% end to end ([same chapter](https://abseil.io/resources/swe-book/html/ch11.html)). A ratio is a codebase-wide target that a session writing one test cannot act on, and web.dev's point that the shape "should fit your architecture" ([Pyramid or Crab](https://web.dev/articles/ta-strategies)) is what a motion-heavy static site needs. The body states the rule and the budget in words instead.
+Each item below stays out of the skill for the reason given.
+
+### A numeric mix
+
+Google targets roughly 80% unit, 15% integration, 5% end to end ([same chapter](https://abseil.io/resources/swe-book/html/ch11.html)). A ratio is a codebase-wide target a session writing one test cannot act on.
+
+web.dev's point that the shape "should fit your architecture" ([Pyramid or Crab](https://web.dev/articles/ta-strategies)) is what a motion-heavy static site needs, so the body states the rule and the budget in words instead.
+
+### Delete the code written before its test
 
-**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.
+`superpowers`'s test-driven skill tells a session to delete implementation written ahead of a failing test. 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.
 
-**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.
+### Other declines
 
-**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.
+The remaining three were declined on tone or on shape.
 
-**A standard in place of a skill.** The guidance is judgment applied while writing, loaded on intent. A standard governs an artifact a reader checks afterwards, and nobody checks a test file against a layer rule after the fact.
+- **An iron law.** Both external test-driven skills carry an "Iron Law" stated as absolute. Declined for tone, since this toolkit states a rule once with its reason.
+- **One skill per layer.** 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.
+- **A standard in place of a skill.** The guidance is judgment applied while writing, loaded on intent. Nobody checks a test file against a layer rule after the fact, which is what a standard governs.

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

@@ -5,7 +5,9 @@ description: Render with real children, query by role, drive with user events, w
 
 # Component tests
 
-Read this before writing the first test at the component layer. A component's logic is its rendered behavior, so the lowest layer that catches a break in a loading state, an interaction, or a validation message is a rendered component test rather than a browser run across the whole site. Kent C. Dodds's testing trophy makes this the widest band for UI code ([Write tests](https://kentcdodds.com/blog/write-tests)), on the principle Testing Library states: "The more your tests resemble the way your software is used, the more confidence they can give you" ([guiding principles](https://testing-library.com/docs/guiding-principles)).
+Read this before writing the first test at the component layer. A component's logic is its rendered behavior, so the lowest layer catching a break in a loading state, an interaction, or a validation message is a rendered component test rather than a whole-site browser run.
+
+Kent C. Dodds's testing trophy makes this the widest band for UI code ([Write tests](https://kentcdodds.com/blog/write-tests)), on the principle Testing Library states: "The more your tests resemble the way your software is used, the more confidence they can give you" ([guiding principles](https://testing-library.com/docs/guiding-principles)).
 
 ## What belongs here
 
@@ -36,7 +38,8 @@ Read this before writing the first test at the component layer. A component's lo
 
 A simulated DOM computes no layout, no scroll position, and no animation frame. When the behavior under test is one of those, move to a runner that renders the component in a real browser rather than promoting the test to end to end.
 
-- Vitest browser mode runs tests "in the browser natively", with Playwright or WebdriverIO as the provider, and lists React, Vue, Svelte, Angular, Lit, Preact, and Qwik. Astro is not on the list ([Vitest browser mode](https://vitest.dev/guide/browser/)). For a static site, test the client module that drives the behavior against a fixture DOM here.
-- Playwright component testing is stable in plain `@playwright/test` through a mount fixture, and "if your dev server can render it, Playwright can test it" ([Playwright component testing](https://playwright.dev/docs/test-components)). The experimental `-ct-*` packages were removed after 1.62.
+- Vitest browser mode runs tests "in the browser natively" through Playwright or WebdriverIO, for React, Vue, Svelte, Angular, Lit, Preact, and Qwik ([Vitest browser mode](https://vitest.dev/guide/browser/))
+- Astro is not on that list. For a static site, test the client module driving the behavior against a fixture DOM in Vitest browser mode.
+- Playwright component testing is stable in plain `@playwright/test` through a mount fixture ([Playwright component testing](https://playwright.dev/docs/test-components)). The experimental `-ct-*` packages were removed after 1.62.
 
-Either runs in a real browser without navigating the whole site, which keeps the test at the component's cost while observing what only a browser computes.
+Playwright's own claim is that "if your dev server can render it, Playwright can test it". Either runs in a real browser without navigating the whole site, which keeps the test at the component's cost while observing what only a browser computes.

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

@@ -11,9 +11,9 @@ Read the settle, guard, and run-scope rules in the project's end to end reliabil
 
 ## What earns a browser run
 
-- A journey a user cannot lose without the product failing, crossing more than one route: sign up, check out, publish ([Practical Test Pyramid](https://martinfowler.com/articles/practical-test-pyramid.html)).
+- A journey across routes a user cannot lose without the product failing, such as sign up or check out ([Practical Test Pyramid](https://martinfowler.com/articles/practical-test-pyramid.html)).
 - Behavior only a real browser computes across the whole page: layout at a breakpoint, scroll position, focus crossing a route, motion.
-- Not a state a component test can reach. Loading, empty, and error states, a toggle, and a validation message belong one layer down, even when the component sits on a page with other end to end coverage.
+- Not a state a component test can reach. Loading, empty, and error states, a toggle, and a validation message belong one layer down, even on a page with other end to end coverage.
 - Not copy. Asserting exact wording in a browser run makes every copy edit a failure across every engine the gate runs.
 
 Suites dominated by end to end tests inflate both runtime and flake ([Google Testing Blog, 2015](https://testing.googleblog.com/2015/04/just-say-no-to-more-end-to-end-tests.html)). Nothing fixes a count ceiling, and the right shape depends on the architecture ([Pyramid or Crab](https://web.dev/articles/ta-strategies)). A site whose behavior is mostly layout and motion carries more browser tests than a form-heavy app, and each one still has to earn its place.
@@ -21,24 +21,42 @@ Suites dominated by end to end tests inflate both runtime and flake ([Google Tes
 ## Settle on conditions
 
 - Assert with a web-first assertion that retries until the condition holds. A manual visibility check reads once and does not retry ([best practices](https://playwright.dev/docs/best-practices)).
-- Lean on actionability for clicks and fills. An element counts as stable once it "has maintained the same bounding box for at least two consecutive animation frames", so an action waits out an animation on its own ([actionability](https://playwright.dev/docs/actionability)). A read does not wait, so poll it.
+- Lean on actionability for clicks and fills, which wait out an animation on their own ([actionability](https://playwright.dev/docs/actionability)). A read does not wait, so poll it.
 - Never pause for a fixed duration to stand in for a condition. Reserve a fixed window for asserting that nothing happened across it.
 - Settle a smooth scroll on the `scrollend` event. Fall back to a stillness window only when the target was already in view.
 
+An element counts as stable once it "has maintained the same bounding box for at least two consecutive animation frames", which is why an action needs no wait of its own.
+
 ## Motion off by default
 
 - Run with motion reduced unless the test asserts motion, and opt back in per test with `page.emulateMedia({ reducedMotion: 'no-preference' })`.
-- Set it once in the config's `use` block as `contextOptions: { reducedMotion: 'reduce' }` rather than per test, since the option defaults to `'no-preference'` ([BrowserContext options](https://playwright.dev/docs/api/class-browser#browser-new-context)). A top-level `use.reducedMotion` reaches no page and type-checks nowhere, so a spec asserting the media query is what catches it. A site honoring the reduced preference then has nothing to wait out in any test that does not opt back in.
+- Set it once in the config's `use` block as `contextOptions: { reducedMotion: 'reduce' }`, since the option defaults to `'no-preference'` ([BrowserContext options](https://playwright.dev/docs/api/class-browser#browser-new-context)).
+- A top-level `use.reducedMotion` reaches no page and type-checks nowhere, so a spec asserting the media query is what catches it
+
+A site honoring the reduced preference then has nothing to wait out in any test that does not opt back in.
 
 ## Isolation and speed
 
 - Give every test its own state: a fresh context, its own account or seed, nothing left behind for the next test.
-- Speed a slow suite with parallel workers and sharding across machines rather than by cutting waits ([best practices](https://playwright.dev/docs/best-practices)). A suite that fails once workers rise carries timing-sensitive assertions, and those are the tests to move down a layer.
+- Speed a slow suite with parallel workers and sharding rather than by cutting waits ([best practices](https://playwright.dev/docs/best-practices)).
+- A suite that fails once workers rise carries timing-sensitive assertions, and those are the tests to move down a layer
 - Capture a trace on the first retry rather than a video on every run ([best practices](https://playwright.dev/docs/best-practices)).
 - Count the cost before adding a test: its runtime, times every engine in the matrix, times every push. That product is what the gate charges each later change.
 
 ## Two worked failures
 
-**A copy assertion in a browser run.** A portfolio site's home spec asserted the exact wording of its about section. A one-line copy edit then failed three engines in continuous integration, and the deploy waited on it. The production change that broke the test was a decision rather than a bug, which makes the assertion a change detector. The copy belonged in a unit test beside the module that holds it, and the browser run needed at most the section's presence.
+Both failures were fixed by moving the assertion down a layer rather than by tuning the browser run.
+
+### A copy assertion in a browser run
+
+A portfolio site's home spec asserted the exact wording of its about section. A one-line copy edit then failed three engines in continuous integration, and the deploy waited on it.
+
+- The breaking change was a decision rather than a bug, which makes the assertion a change detector
+- The copy belonged in a unit test beside the module holding it, and the browser run needed at most the section's presence
+
+### A settle that narrowed a failure without removing it
+
+A focus-ring spec replaced a fixed pause with a condition wait on a scripted focus read. The next trunk push still failed one engine on every attempt with the condition timing out, and flaked a second test in the file, which skipped the deploy.
 
-**A settle that narrowed a failure without removing it.** A focus-ring spec waited on a scripted focus read with a condition wait, replacing a fixed pause. The next push to the trunk still failed one engine on every attempt with the condition timing out, and flaked a second test in the same file, which skipped the deploy. The settle was correct and the layer was wrong: an assertion whose result depends on how loaded the CI machine is keeps failing at the layer where load decides it. Moving the focus behavior to a real-browser component test takes it off the whole-site run.
+- The settle was correct and the layer was wrong. An assertion whose result depends on how loaded the CI machine is keeps failing at the layer where load decides it.
+- Moving the focus behavior to a real-browser component test takes it off the whole-site run

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

@@ -5,7 +5,9 @@ description: Doubles in preference order, descriptive over shared setup, table-d
 
 # Unit and integration tests
 
-Read this before writing the first test at the unit or integration layer. A unit test runs in one process with no network, no sleep, and no real I/O. An integration test may touch the local machine, such as a temporary directory or a local database, and nothing beyond it. Google's size vocabulary draws the same line by what a test may touch rather than what it covers ([Software Engineering at Google, ch. 11](https://abseil.io/resources/swe-book/html/ch11.html)).
+Read this before writing the first test at the unit or integration layer. A unit test runs in one process with no network, no sleep, and no real I/O.
+
+An integration test may touch the local machine, such as a temporary directory or a local database, and nothing beyond it. Google's size vocabulary draws the same line by what a test may touch rather than what it covers ([Software Engineering at Google, ch. 11](https://abseil.io/resources/swe-book/html/ch11.html)).
 
 ## Doubles
 

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

@@ -9,13 +9,21 @@ The loop predates this ledger, so this file records the sources it matches rathe
 
 ## Adopted
 
-**The loop itself.** Kent Beck's [Canon TDD](https://newsletter.kentbeck.com/p/canon-tdd) states it as turning one item into "an actual, concrete, runnable test", changing the code "to make the test (& all previous tests) pass", then refactoring. Adopted as steps 2, 4, 5, and 6, with the whole suite run after the pass rather than the new test alone.
+### The loop itself
 
-**Making it pass without designing.** The same post warns against "mixing refactoring into making the test pass", and keeps implementation design decisions for the refactor. Adopted as step 4's smallest change and step 6's cleanup of the shortcuts that change left.
+Kent Beck's [Canon TDD](https://newsletter.kentbeck.com/p/canon-tdd) states it as turning one item into "an actual, concrete, runnable test", changing the code "to make the test (& all previous tests) pass", then refactoring. Adopted as steps 2, 4, 5, and 6, with the whole suite run after the pass rather than the new test alone.
 
-**Never faking the pass.** The same post lists deleting assertions "so the test pretends to pass" and "copying actual, computed values & pasting them into the expected values" as mistakes. Adopted as step 5's rule that a pass must be the one the test was written to prove.
+### Making it pass without designing
 
-**Refactoring is a step, not an option.** Martin Fowler's [TestDrivenDevelopment](https://martinfowler.com/bliki/TestDrivenDevelopment.html) names "neglecting the third step" as the most common way to get the practice wrong. Adopted as step 6 being mandatory where Canon TDD writes "optionally refactor".
+The same post warns against "mixing refactoring into making the test pass", and keeps implementation design decisions for the refactor. Adopted as step 4's smallest change and step 6's cleanup of the shortcuts that change left.
+
+### Never faking the pass
+
+The same post lists deleting assertions "so the test pretends to pass" and "copying actual, computed values & pasting them into the expected values" as mistakes. Adopted as step 5's rule that a pass must be the one the test was written to prove.
+
+### Refactoring is a step, not an option
+
+Martin Fowler's [TestDrivenDevelopment](https://martinfowler.com/bliki/TestDrivenDevelopment.html) names "neglecting the third step" as the most common way to get the practice wrong. Adopted as step 6 being mandatory where Canon TDD writes "optionally refactor".
 
 ## Declined
 

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

@@ -33,7 +33,7 @@ The automatable half has its own gap, and it is no longer this skill's to close
 - Try to assert a visual property programmatically
 - Repeat the full checklist in chat, which is what made it evaporate
 - Stage or commit the checklist, which is gitignored scratch
-- Talk to GitHub directly. Posting the checklist belongs to `git-pr`, the sole consumer of the handoff file
+- Talk to GitHub directly. Posting the checklist belongs to `pr-evidence`, the sole consumer of the handoff file
 - Move the handoff path to match this skill's name, which strands a checklist an older binary wrote
 
 ## Guards

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

@@ -69,7 +69,7 @@ Derive `<slug>` per `${CLAUDE_SKILL_DIR}/../git-branch/references/slug.md`. Fall
 
 When a checklist is produced, write it to `.canon/tmp/handoff/ui-checklist/<slug>.md` at the main worktree root, resolved the way `session-worktree` does, creating the directory if needed and always overwriting.
 
-- It is a handoff file rather than a deliverable. `git-pr` renders it into the evidence comment once a pull request opens, then removes it, and nothing here calls `gh`.
+- It is a handoff file rather than a deliverable. `pr-evidence` renders it into the evidence comment once a pull request opens, then removes it, and nothing here calls `gh`.
 - The path names the artifact rather than this skill, so a rename moves nothing and an older binary's checklist lands where the consumer looks
 - The checklist is a main-root write, so it goes out as a heredoc, routed the way `session-worktree` states
 - Skip the write when there is nothing to verify visually and nothing shipping untested