@erclx/canon 5.64.0 → 5.65.0

package/governance/ledger/skills/test-craft/SKILL.md

@@ -0,0 +1,67 @@
+---
+title: Test craft skill ledger
+description: Sources for claude/skills/test-craft/SKILL.md, one row per bullet in its concern groups
+---
+
+# Test craft skill ledger
+
+The field is software testing practice. Software Engineering at Google carries test sizes, clarity, and doubles, Fowler and Ham Vocke carry the pyramid, and `obra/superpowers` carries the opening question the body asks of every test. The closing sections and `## What this delegates` restate these rules or route, so they take no table.
+
+`references/adopted.md` stays the record of what was adopted and declined at the source level.
+
+## Open every test with one question
+
+| Bullet                             | Source                                                                                                                                                                                                                                                                            | Read       |
+| ---------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ---------- |
+| A bug is what the test is for      | [obra/superpowers, Writing Good Tests](https://github.com/obra/superpowers/blob/5bf4e78/skills/test-driven-development/writing-good-tests.md): "what production change should make this test fail", then whether "that change [is] a bug or a decision"                           | 2026-10-24 |
+| A decision makes a change detector | [obra/superpowers, Writing Good Tests](https://github.com/obra/superpowers/blob/5bf4e78/skills/test-driven-development/writing-good-tests.md): when "only intentional decisions can fail a test", such as "exact message wording", "it fires on redesign and sleeps through bugs" | 2026-10-24 |
+| No answer proves nothing yet       | [obra/superpowers, Writing Good Tests](https://github.com/obra/superpowers/blob/5bf4e78/skills/test-driven-development/writing-good-tests.md): "Cannot name one → redesign around an observable behavior"                                                                         | 2026-10-24 |
+| Cover the edges as their own cases | [Vocke, The Practical Test Pyramid](https://martinfowler.com/articles/practical-test-pyramid.html): unit tests "should ensure that all your non-trivial code paths are tested (including happy path and edge cases)"                                                              | 2026-10-24 |
+
+## Put the test at the smallest layer that can catch the break
+
+| Bullet                                     | Source                                                                                                                                                                                                                                                              | Read       |
+| ------------------------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ---------- |
+| The row read off the behavior              | [Software Engineering at Google, ch. 11](https://abseil.io/resources/swe-book/html/ch11.html): "small tests run in a single process, medium tests run on a single machine, and large tests run wherever they want", a size set by what the test touches             | 2026-10-24 |
+| Split a behavior that spans rows           | [Vocke, The Practical Test Pyramid](https://martinfowler.com/articles/practical-test-pyramid.html): "Push your tests as far down the test pyramid as you can"                                                                                                       | 2026-10-24 |
+| A red higher run names a missing lower one | [Vocke, The Practical Test Pyramid](https://martinfowler.com/articles/practical-test-pyramid.html): "If a higher-level test spots an error and there's no lower-level test failing, you need to write a lower-level test"                                           | 2026-10-24 |
+| Real-browser component before end to end   | [Vitest, Component Testing](https://vitest.dev/guide/browser/component-testing): component tests run "in real browser environments", which "provides the most accurate testing environment as your components run in real browsers with actual DOM implementations" | 2026-10-24 |
+
+## Spend end to end on journeys
+
+| Bullet                                | Source                                                                                                                                                                                                                                                                            | Read       |
+| ------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ---------- |
+| Journeys the product cannot lose      | [Vocke, The Practical Test Pyramid](https://martinfowler.com/articles/practical-test-pyramid.html): "Try to come up with user journeys that define the core value of your product and translate the most important steps of these user journeys into automated end-to-end tests." | 2026-10-24 |
+| No end to end for a component's state | [Vocke, The Practical Test Pyramid](https://martinfowler.com/articles/practical-test-pyramid.html): "UI tests don't have to be on the highest level of your pyramid - you're perfectly able to unit test your UI in all of these frameworks"                                      | 2026-10-24 |
+| Every later run pays for a new one    | [Vocke, The Practical Test Pyramid](https://martinfowler.com/articles/practical-test-pyramid.html): "Due to their high maintenance cost you should aim to reduce the number of end-to-end tests to a bare minimum."                                                               | 2026-10-24 |
+| No numeric mix                        | [web.dev, Pyramid or Crab?](https://web.dev/articles/ta-strategies): the strategy "should fir your architecture, your requirements, and last but not least, your users and their requirements", typo as published                                                                 | 2026-10-24 |
+
+## Keep test code readable over clever
+
+| Bullet                                  | Source                                                                                                                                                                                                                                               | Read       |
+| --------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ---------- |
+| A repeated arrange over a shared helper | [Software Engineering at Google, ch. 12](https://abseil.io/resources/swe-book/html/ch12.html): "A little bit of duplication is OK in tests so long as that duplication makes the test simpler and clearer."                                          | 2026-10-24 |
+| Test data through a factory or builder  | [Pryce, Test Data Builders](http://www.natpryce.com/articles/000714.html): "For each class you want to use in a test, create a Builder for that class", one that "Initialises its instance variables to commonly used or safe values"                | 2026-10-24 |
+| Assert through the public surface       | [Software Engineering at Google, ch. 12](https://abseil.io/resources/swe-book/html/ch12.html): tests should "make calls against its public API rather than its implementation details"                                                               | 2026-10-24 |
+| Real, then fake, then stub, mock last   | [addyosmani/agent-skills, Test-Driven Development](https://github.com/addyosmani/agent-skills/blob/c004a74/skills/test-driven-development/SKILL.md): "Preference order (most to least preferred): 1. Real implementation", then fake, stub, and mock | 2026-10-24 |
+
+## Hold the structure floors
+
+| Bullet                              | Source                                                                                                                                                                                                                                                                                                                                                                                                          | Read       |
+| ----------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ---------- |
+| Arrange, act, assert                | [Vocke, The Practical Test Pyramid](https://martinfowler.com/articles/practical-test-pyramid.html): "There's a nice mnemonic to remember this structure: “Arrange, Act, Assert”"                                                                                                                                                                                                                                | 2026-10-24 |
+| One behavior per test               | [Software Engineering at Google, ch. 12](https://abseil.io/resources/swe-book/html/ch12.html): "Each test should cover only a single behavior"                                                                                                                                                                                                                                                                  | 2026-10-24 |
+| No branches or loops in a test body | [Software Engineering at Google, ch. 12](https://abseil.io/resources/swe-book/html/ch12.html): "in test code, stick to straight-line code over clever logic"                                                                                                                                                                                                                                                    | 2026-10-24 |
+| No coverage percentage as a target  | [Fowler, Test Coverage](https://martinfowler.com/bliki/TestCoverage.html): "If you make a certain level of coverage a target, people will try to attain it. The trouble is that high coverage numbers are too easy to reach with low quality testing."                                                                                                                                                          | 2026-10-24 |
+| Nesting kept to two levels          | [Software Engineering at Google, ch. 12](https://abseil.io/resources/swe-book/html/ch12.html) groups tests "nested within one another and named using strings". The two-level cap is a House choice: deeper nesting spreads a test's setup across hooks, which [Dodds](https://kentcdodds.com/blog/avoid-nesting-when-youre-testing) names as "the number one reason I strongly recommend against nested tests" | 2026-10-24 |
+| Independent tests, state restored   | [Beck, Test Desiderata](https://testdesiderata.com/): Isolated tests "should return the same results regardless of the order in which they are run."                                                                                                                                                                                                                                                            | 2026-10-24 |
+| Await every async operation         | [Jest, Testing Asynchronous Code](https://jestjs.io/docs/asynchronous): "if you omit the return / await statement, your test will complete before the promise returned from fetchData resolves or rejects"                                                                                                                                                                                                      | 2026-10-24 |
+| Assertions, never a snapshot        | [Dodds, Effective Snapshot Testing](https://kentcdodds.com/blog/effective-snapshot-testing), quoting Justin Searls: "Snapshot tests lack (or at least, fail to encourage) expressing the author's intent as to what the code does (much less why)"                                                                                                                                                              | 2026-10-24 |
+
+## Read the reference for the layer
+
+| Bullet                         | Source                                                                                                                                                                | Read       |
+| ------------------------------ | --------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ---------- |
+| Unit and integration reference | House choice: a unit test written without `unit.md` reaches for a mock before a real collaborator or a fake, and skips the mutation check that finds its missing case | 2026-10-24 |
+| Component reference            | House choice: a component test written without `component.md` queries by test id and fires synthetic events, so it passes on markup a user cannot reach               | 2026-10-24 |
+| End to end reference           | House choice: a first spec written without `e2e.md` pauses for a fixed time and runs with motion on, the two causes of the flakes its worked failures record          | 2026-10-24 |

package/governance/ledger/skills/test-craft/component.md

@@ -0,0 +1,49 @@
+---
+title: Component tests reference ledger
+description: Sources for claude/skills/test-craft/references/component.md, one row per bullet
+---
+
+# Component tests reference ledger
+
+The field is UI testing, where Testing Library and Kent C. Dodds's guidance carry how a rendered component is queried, driven, and waited on. Vitest and Playwright carry the real-browser runners. Each row cites the bullet's own inline link where the reference carries one.
+
+## What belongs here
+
+| Bullet                                 | Source                                                                                                                                                                                                                                        | Read       |
+| -------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ---------- |
+| Every state a component shows          | [Vocke, The Practical Test Pyramid](https://martinfowler.com/articles/practical-test-pyramid.html): in a UI test, "data should be presented to the user, the UI state should change as expected"                                              | 2026-10-24 |
+| Every interaction that changes it      | [Vocke, The Practical Test Pyramid](https://martinfowler.com/articles/practical-test-pyramid.html): "User input should trigger the right actions"                                                                                             | 2026-10-24 |
+| Conditional rendering, keys, and focus | [Testing Library, user-event](https://testing-library.com/docs/user-event/intro): it "manipulates the DOM just like a user interaction in the browser would", and "wouldn't let a user click a hidden element or type in a disabled text box" | 2026-10-24 |
+| Not layout, scroll, or motion          | [Vitest, Why Browser Mode](https://vitest.dev/guide/browser/why): jsdom and happy-dom "only simulate a browser environment and not an actual browser, which may result in some discrepancies"                                                 | 2026-10-24 |
+
+## Render
+
+| Bullet                               | Source                                                                                                                                                                                                                    | Read       |
+| ------------------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ---------- |
+| Real children                        | [Dodds, Write tests](https://kentcdodds.com/blog/write-tests): "When you mock something you're removing all confidence in the integration between what you're testing and what's being mocked."                           | 2026-10-24 |
+| The network doubled at its edge      | [Mock Service Worker, Philosophy](https://mswjs.io/docs/philosophy): it intercepts "outgoing network traffic", which "means having zero changes to your code altogether"                                                  | 2026-10-24 |
+| Props and fixtures through a factory | [Pryce, Test Data Builders](http://www.natpryce.com/articles/000714.html): a builder "Has "chainable" public methods for overriding the values in its instance variables", so a test spells only the values it depends on | 2026-10-24 |
+
+## Query and act like a user
+
+| Bullet                            | Source                                                                                                                                                                                                                                             | Read       |
+| --------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ---------- |
+| Role and name first, test id last | [Dodds, Common mistakes with React Testing Library](https://kentcdodds.com/blog/common-mistakes-with-react-testing-library): "Which query should I use?" lists "the queries you should attempt to use in the order you should attempt to use them" | 2026-10-24 |
+| User events over synthetic ones   | [Dodds, Common mistakes with React Testing Library](https://kentcdodds.com/blog/common-mistakes-with-react-testing-library): user-event "provides several methods that resemble the user interactions more closely"                                | 2026-10-24 |
+| Assert what the user perceives    | [Testing Library, Guiding Principles](https://testing-library.com/docs/guiding-principles): a test "should deal with DOM nodes rather than component instances"                                                                                    | 2026-10-24 |
+
+## Wait on one condition
+
+| Bullet                         | Source                                                                                                                                                                                                                                           | Read       |
+| ------------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | ---------- |
+| One assertion inside each wait | [Dodds, Common mistakes with React Testing Library](https://kentcdodds.com/blog/common-mistakes-with-react-testing-library): "Advice: only put one assertion in a callback."                                                                     | 2026-10-24 |
+| No side effect inside a wait   | [Dodds, Common mistakes with React Testing Library](https://kentcdodds.com/blog/common-mistakes-with-react-testing-library): the callback runs "a non-deterministic number of times", so "your side-effect could run multiple times!"            | 2026-10-24 |
+| The query that waits           | [Dodds, Common mistakes with React Testing Library](https://kentcdodds.com/blog/common-mistakes-with-react-testing-library): "find* queries use waitFor under the hood), but the second is simpler and the error message you get will be better" | 2026-10-24 |
+
+## When a simulated DOM cannot render it
+
+| Bullet                          | Source                                                                                                                                                                                                                                                                                                  | Read       |
+| ------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ---------- |
+| Vitest browser mode             | [Vitest, Browser Mode](https://vitest.dev/guide/browser/): the feature "allows you to run your tests in the browser natively, providing access to browser globals like window and document"                                                                                                             | 2026-10-24 |
+| Astro through its client module | [Astro, Testing](https://docs.astro.build/en/guides/testing/): "Use Astro’s getViteConfig() helper in your vitest.config.ts configuration file to set up Vitest with your Astro project’s settings", while [Vitest's component list](https://vitest.dev/guide/browser/component-testing) names no Astro | 2026-10-24 |
+| Playwright component testing    | [Playwright, Components](https://playwright.dev/docs/test-components): "It is stable. Tests import test and expect from plain @playwright/test", and a user of the removed packages should "stay on Playwright 1.62 until you have followed the migration guide"                                        | 2026-10-24 |

package/governance/ledger/skills/test-craft/e2e.md

@@ -0,0 +1,55 @@
+---
+title: End to end tests reference ledger
+description: Sources for claude/skills/test-craft/references/e2e.md, one row per bullet
+---
+
+# End to end tests reference ledger
+
+The field is browser test automation. Playwright's own documentation carries the runner rules, at the version the reference states, and Ham Vocke's pyramid carries which journeys earn a browser run. Each row cites the bullet's own inline link where the reference carries one.
+
+The two worked failures report what one project's suite did, so each of their rows is a house choice naming the failure the incident shows rather than an outside citation.
+
+## What earns a browser run
+
+| Bullet                               | Source                                                                                                                                                                                                                                    | Read       |
+| ------------------------------------ | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ---------- |
+| A journey the product cannot lose    | [Vocke, The Practical Test Pyramid](https://martinfowler.com/articles/practical-test-pyramid.html): "your most valuable customer journey could be a user searching for a product, putting it in the shopping basket and doing a checkout" | 2026-10-24 |
+| What only a real browser computes    | [Vitest, Why Browser Mode](https://vitest.dev/guide/browser/why): "To achieve the highest level of confidence in our tests, it's crucial to test in a real browser environment."                                                          | 2026-10-24 |
+| Not a state a component test reaches | [Vocke, The Practical Test Pyramid](https://martinfowler.com/articles/practical-test-pyramid.html): end-to-end tests "are notoriously flaky and often fail for unexpected and unforeseeable reasons"                                      | 2026-10-24 |
+| Not copy                             | [obra/superpowers, Writing Good Tests](https://github.com/obra/superpowers/blob/5bf4e78/skills/test-driven-development/writing-good-tests.md): a test pinning "exact message wording" "fires on redesign and sleeps through bugs"         | 2026-10-24 |
+
+## Settle on conditions
+
+| Bullet                                 | Source                                                                                                                                                                                                                                                                           | Read       |
+| -------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ---------- |
+| Web-first assertions                   | [Playwright, Best Practices](https://playwright.dev/docs/best-practices): "By using web first assertions Playwright will wait until the expected condition is met."                                                                                                              | 2026-10-24 |
+| Actionability waits, a read does not   | [Playwright, Actionability](https://playwright.dev/docs/actionability): an element is "Stable , as in not animating or completed animation", while with "isVisible() the test won't wait a single second", per [Best Practices](https://playwright.dev/docs/best-practices)      | 2026-10-24 |
+| No fixed pause for a condition         | [Fowler, Eradicating Non-Determinism in Tests](https://martinfowler.com/articles/nonDeterminism.html): "Never use bare sleeps to wait for asynchonous responses: use a callback or polling.", typo as published                                                                  | 2026-10-24 |
+| A smooth scroll settles on `scrollend` | [MDN, Element: scrollend event](https://developer.mozilla.org/en-US/docs/Web/API/Element/scrollend_event): "The scrollend event fires when element scrolling has completed." The stillness fallback is a House choice: a target already in view never scrolls, so no event comes | 2026-10-24 |
+
+## Motion off by default
+
+| Bullet                                    | Source                                                                                                                                                                                                                                                                        | Read       |
+| ----------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ---------- |
+| Reduced unless the test asserts motion    | [Playwright, Browser](https://playwright.dev/docs/api/class-browser#browser-new-context): `reducedMotion` "Emulates 'prefers-reduced-motion' media feature", and a test opts back in through `page.emulateMedia()`                                                            | 2026-10-24 |
+| Set once in `use.contextOptions`          | [Playwright, Browser](https://playwright.dev/docs/api/class-browser#browser-new-context): `reducedMotion` "Defaults to 'no-preference'", and [TestOptions](https://playwright.dev/docs/api/class-testoptions) shows `use : { contextOptions : { reducedMotion : 'reduce' } }` | 2026-10-24 |
+| A top-level `use.reducedMotion` from 1.50 | [Playwright, TestOptions](https://playwright.dev/docs/api/class-testoptions): `testOptions.reducedMotion` was added in Playwright 1.50 and "Emulates 'prefers-reduced-motion' media feature", with `use : { reducedMotion : 'reduce' }` as its usage                          | 2026-10-25 |
+
+## Isolation and speed
+
+| Bullet                              | Source                                                                                                                                                                                                                                                  | Read       |
+| ----------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ---------- |
+| Every test its own state            | [Playwright, Isolation](https://playwright.dev/docs/browser-contexts): "Tests written with Playwright execute in isolated clean-slate environments called browser contexts."                                                                            | 2026-10-24 |
+| Workers and sharding over cut waits | [Playwright, Best Practices](https://playwright.dev/docs/best-practices): "Playwright runs tests in parallel by default", and "Playwright can shard a test suite, so that it can be executed on multiple machines"                                      | 2026-10-24 |
+| A suite failing as workers rise     | House choice: an assertion that passes on one worker and fails on four depends on machine load, and no settle at that layer removes the dependence                                                                                                      | 2026-10-24 |
+| A trace on the first retry          | [Playwright, Best Practices](https://playwright.dev/docs/best-practices): traces "are set to run on CI on the first retry of a failed test. We don't recommend setting this to on so that traces are run on every test as it's very performance heavy." | 2026-10-24 |
+| Count the cost before adding a test | House choice: a test's runtime multiplies by every engine and every push, so a suite grown one cheap-looking test at a time is what makes the gate slow                                                                                                 | 2026-10-24 |
+
+## Two worked failures
+
+| Bullet                                   | Source                                                                                                                                                               | Read       |
+| ---------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ---------- |
+| A copy edit was a decision, not a bug    | House choice: an assertion on exact wording in a browser run is a change detector, failing every engine on an edit nobody would call a bug                           | 2026-10-24 |
+| The copy belonged at unit                | House choice: a copy assertion run in a browser holds a deploy on every wording change, where a unit test beside the copy fails once and fast                        | 2026-10-24 |
+| The settle was right and the layer wrong | House choice: an assertion whose result depends on CI load keeps failing at the layer where load decides it, however correct its settle                              | 2026-10-24 |
+| The focus behavior moves down a layer    | House choice: a focus assertion on the whole-site run flakes its file and skips a deploy, where a real-browser component test observes focus without the site's load | 2026-10-24 |

package/governance/ledger/skills/test-craft/unit.md

@@ -0,0 +1,54 @@
+---
+title: Unit and integration tests reference ledger
+description: Sources for claude/skills/test-craft/references/unit.md, one row per bullet and ordered step
+---
+
+# Unit and integration tests reference ledger
+
+The field is unit testing practice. `addyosmani/agent-skills` and `obra/superpowers`, the two sources the reference cites inline, carry the doubles order, DAMP, and the mutation check. Software Engineering at Google, Fowler, and the Go wiki carry the rest.
+
+The four ordered steps under `## Doubles` and the three under `## The mutation check` each take a row, the way a bullet does.
+
+## Doubles
+
+| Bullet                                   | Source                                                                                                                                                                                                                                      | Read       |
+| ---------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ---------- |
+| Real first                               | [addyosmani/agent-skills, Test-Driven Development](https://github.com/addyosmani/agent-skills/blob/c004a74/skills/test-driven-development/SKILL.md): "1. Real implementation → Highest confidence, catches real bugs"                       | 2026-10-24 |
+| Fake second                              | [addyosmani/agent-skills, Test-Driven Development](https://github.com/addyosmani/agent-skills/blob/c004a74/skills/test-driven-development/SKILL.md): "2. Fake → In-memory version of a dependency (e.g., fake DB)"                          | 2026-10-24 |
+| Stub third                               | [addyosmani/agent-skills, Test-Driven Development](https://github.com/addyosmani/agent-skills/blob/c004a74/skills/test-driven-development/SKILL.md): "3. Stub → Returns canned data, no behavior"                                           | 2026-10-24 |
+| Mock last, when the call is the contract | [Software Engineering at Google, ch. 13](https://abseil.io/resources/swe-book/html/ch13.html): "interaction testing is useful in certain situations but should be avoided when possible because overuse can easily result in brittle tests" | 2026-10-24 |
+| Double only at an unowned boundary       | [addyosmani/agent-skills, Test-Driven Development](https://github.com/addyosmani/agent-skills/blob/c004a74/skills/test-driven-development/SKILL.md): "Mock only at boundaries where real deps are slow or non-deterministic"                | 2026-10-24 |
+| Never assert a mock exists               | [obra/superpowers, Writing Good Tests](https://github.com/obra/superpowers/blob/5bf4e78/skills/test-driven-development/writing-good-tests.md): "A mock assertion passes when the mock is present and fails when it is absent"               | 2026-10-24 |
+| Clock and randomness injected            | [Fowler, Eradicating Non-Determinism in Tests](https://martinfowler.com/articles/nonDeterminism.html): "always wrap the system clock with routines that can be replaced with a seeded value for testing"                                    | 2026-10-24 |
+
+## Descriptive over shared
+
+| Bullet                              | Source                                                                                                                                                                                                                                                     | Read       |
+| ----------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ---------- |
+| DAMP over DRY                       | [addyosmani/agent-skills, Test-Driven Development](https://github.com/addyosmani/agent-skills/blob/c004a74/skills/test-driven-development/SKILL.md): "each test should tell a complete story without requiring the reader to trace through shared helpers" | 2026-10-24 |
+| A factory with the key values shown | [Software Engineering at Google, ch. 12](https://abseil.io/resources/swe-book/html/ch12.html): a test is not complete when "important details are hidden away in helper methods that the reader can’t see"                                                 | 2026-10-24 |
+| No shared mutable state             | [Fowler, Eradicating Non-Determinism in Tests](https://martinfowler.com/articles/nonDeterminism.html): "If one test creates some data in the database and leaves it lying around, it can corrupt the run of another test"                                  | 2026-10-24 |
+
+## Table-driven cases
+
+| Bullet                                  | Source                                                                                                                                                                                                                 | Read       |
+| --------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ---------- |
+| One table for inputs differing by value | [Go wiki, TableDrivenTests](https://go.dev/wiki/TableDrivenTests): "Each table entry is a complete test case with inputs and expected results, and sometimes with additional information such as a test name"          | 2026-10-24 |
+| A row holds input and expected output   | [obra/superpowers, Writing Good Tests](https://github.com/obra/superpowers/blob/5bf4e78/skills/test-driven-development/writing-good-tests.md): "table-driven tests with literal `want` values are the preferred shape" | 2026-10-24 |
+| Split the table on a new assertion      | [Go wiki, TableDrivenTests](https://go.dev/wiki/TableDrivenTests): "the actual test simply iterates through all table entries and for each entry performs the necessary tests", one test body every row shares         | 2026-10-24 |
+
+## Integration at a boundary
+
+| Bullet                                 | Source                                                                                                                                                                                                                                      | Read       |
+| -------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ---------- |
+| Through the callers' interface         | [Vocke, The Practical Test Pyramid](https://martinfowler.com/articles/practical-test-pyramid.html): "Narrow integration tests live at the boundary of your service", "triggering an action that leads to integrating with the outside part" | 2026-10-24 |
+| A temporary directory or database each | [Fowler, Eradicating Non-Determinism in Tests](https://martinfowler.com/articles/nonDeterminism.html): tests need "a well-known state at the beginning of the test", and "Properly isolated tests can be run in any sequence."              | 2026-10-24 |
+| The failure path at the boundary       | [Software Engineering at Google, ch. 11](https://abseil.io/resources/swe-book/html/ch11.html): a review is easier with "thorough tests that demonstrate code correctness, edge cases, and error conditions"                                 | 2026-10-24 |
+
+## The mutation check
+
+| Bullet                              | Source                                                                                                                                                                                                                                                | Read       |
+| ----------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ---------- |
+| Name three to five breaks           | [obra/superpowers, Writing Good Tests](https://github.com/obra/superpowers/blob/5bf4e78/skills/test-driven-development/writing-good-tests.md): "mentally mutate the production code", and "at least one test should fail for each realistic mutation" | 2026-10-24 |
+| Say which test fails for each       | [Stryker, What is mutation testing?](https://stryker-mutator.io/docs/): "If your tests fail then the mutant is killed", and "If your tests passed, the mutant survived"                                                                               | 2026-10-24 |
+| An uncaught break is a missing case | [obra/superpowers, Writing Good Tests](https://github.com/obra/superpowers/blob/5bf4e78/skills/test-driven-development/writing-good-tests.md): "A mutation nothing catches marks the behavior as unprotected"                                         | 2026-10-24 |

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@erclx/canon",
   "type": "module",
-  "version": "5.64.0",
+  "version": "5.65.0",
   "description": "Runs your agent's work and keeps its code good, on one setup for every repo.",
   "license": "MIT",
   "bin": {
@@ -69,8 +69,8 @@
     "astro": "^6.1.9",
     "husky": "^9.1.7",
     "micromatch": "^4.0.8",
-    "oxfmt": "0.73.0",
-    "oxlint": "1.88.0",
+    "oxfmt": "0.74.0",
+    "oxlint": "1.89.0",
     "prettier": "^3.8.1",
     "prettier-plugin-astro": "^0.14.1",
     "prettier-plugin-tailwindcss": "^0.8.1",

package/src/claude/skills-audit.ts

@@ -113,6 +113,13 @@ export const BULLET_LEDGER_SKILLS: Readonly<Record<string, BulletLedgerScope>> =
       exempt: references('preflight', 'vocabulary'),
       body: true,
     },
+    [join(SHIPPED_CORPUS, 'review-craft')]: {
+      exempt: references('ui'),
+      body: true,
+    },
+    [join(SHIPPED_CORPUS, 'teach-craft')]: { exempt: [], body: true },
+    [join(SHIPPED_CORPUS, 'test-craft')]: { exempt: [], body: true },
+    [join(SHIPPED_CORPUS, 'codebase-layout')]: { exempt: [], body: true },
   }
 
 /** Where a per-bullet ledger lives, as `<skill>/<file>.md` below it. */

package/src/commands/sandbox.ts

@@ -1,5 +1,5 @@
 import { existsSync, readFileSync } from 'node:fs'
-import { join } from 'node:path'
+import { basename, dirname, join, relative, resolve } from 'node:path'
 import type { Command } from 'commander'
 import { checkoutMismatchWarning, PROJECT_ROOT } from '@/roots/project'
 import {
@@ -27,8 +27,24 @@ import {
 } from '@/sandbox/expect'
 import { runHeadless } from '@/sandbox/headless/run'
 import { runSandbox } from '@/sandbox/provision'
+import {
+  EXPECTED_FILE,
+  expectationOf,
+  judgeDrift,
+  readExpectation,
+  writeExpectation,
+  type ReplayExpectation,
+} from '@/sandbox/replay/expected'
+import {
+  checkoutRefusal,
+  hasFormatter,
+  listSnapshots,
+  replaySource,
+  type ReplayResult,
+  type ReplaySource,
+} from '@/sandbox/replay/run'
 import { listCategories, listScenarioFiles } from '@/sandbox/scenario'
-import { sandboxTree } from '@/sandbox/tree'
+import { assertSandboxDirSafe, sandboxRoots, sandboxTree } from '@/sandbox/tree'
 import {
   frameError,
   intro,
@@ -434,6 +450,194 @@ async function runEquivalence(
   process.exitCode = equivalenceExitCode(record)
 }
 
+interface ReplayOptions {
+  readonly json?: boolean
+  readonly record?: boolean
+}
+
+const REPLAY_FINDINGS_SHOWN = 5
+
+function refuseReplay(reason: string, message: string, json: boolean): void {
+  logError(message)
+  if (json)
+    process.stdout.write(`${JSON.stringify({ ok: false, reason, message })}\n`)
+  outro()
+  process.exitCode = 1
+}
+
+/**
+ * Replays each consumer through a sync with this checkout's CLI and judges
+ * the reads that follow. Bare, it replays the frozen snapshots, which is what
+ * the gate runs. Given paths, it copies each real checkout, the operator's
+ * step before a release. Every source is checked before any replay starts, so
+ * a refusal never arrives after half the runs. A snapshot is judged against
+ * the answer recorded beside it, since a frozen tree answers the same on every
+ * push, and `--record` rewrites that answer from a run that broke nothing.
+ */
+function runReplay(paths: string[], options: ReplayOptions): void {
+  if (reportAbsentScenarioTree()) return
+
+  intro('canon sandbox replay')
+  const json = options.json === true
+  const record = options.record === true
+
+  if (record && paths.length > 0) {
+    refuseReplay(
+      'record-checkout',
+      'A named checkout moves between runs, so --record pins snapshots only. Drop the paths.',
+      json,
+    )
+    return
+  }
+
+  if (!hasFormatter(PROJECT_ROOT)) {
+    refuseReplay(
+      'no-formatter',
+      'No oxfmt under node_modules, so the format step cannot run. Run bun install in this checkout.',
+      json,
+    )
+    return
+  }
+
+  let sources: ReplaySource[]
+  if (paths.length === 0) {
+    sources = listSnapshots(join(SANDBOX_DIR, 'fixtures', 'replay'))
+    if (sources.length === 0) {
+      refuseReplay(
+        'no-snapshots',
+        'No snapshot under sandbox/fixtures/replay/',
+        json,
+      )
+      return
+    }
+  } else {
+    sources = []
+    for (const raw of paths) {
+      const path = resolve(process.cwd(), raw)
+      const refusal = checkoutRefusal(path)
+      if (refusal !== undefined) {
+        refuseReplay(refusal.reason, refusal.message, json)
+        return
+      }
+      sources.push({ name: basename(path), path, kind: 'checkout' })
+    }
+  }
+
+  // Beside the provisioned tree rather than inside it, since `canon sandbox
+  // clean` wipes that one and a concurrent replay would lose its tree.
+  const tempRoot = join(dirname(sandboxTree()), 'replay')
+  const unsafe = assertSandboxDirSafe(
+    join(tempRoot, 'tree'),
+    sandboxRoots(PROJECT_ROOT),
+  )
+  if (unsafe !== undefined) {
+    refuseReplay('unsafe-root', unsafe, json)
+    return
+  }
+
+  const expectations = new Map<string, ReplayExpectation | undefined>()
+  if (!record)
+    for (const source of sources) {
+      if (source.kind !== 'snapshot') continue
+      try {
+        expectations.set(source.name, readExpectation(source.path))
+      } catch (error) {
+        refuseReplay('bad-expectation', (error as Error).message, json)
+        return
+      }
+    }
+
+  const replays: ReplayResult[] = []
+  for (const source of sources) {
+    const run = replaySource(source, {
+      checkoutRoot: PROJECT_ROOT,
+      tempRoot,
+    })
+    const result: ReplayResult =
+      source.kind === 'snapshot' && !record
+        ? {
+            ...run,
+            steps: judgeDrift(run.steps, expectations.get(source.name)),
+          }
+        : run
+    replays.push(result)
+
+    logStep(`${result.name} (${result.kind})`)
+    for (const step of result.steps) {
+      if (step.verdict === 'ok') logInfo(`${step.step}, exit ${step.exit}`)
+      else
+        logError(`${result.name}: ${step.step} ${step.verdict}: ${step.detail}`)
+      // A sync over an old layout prints a line per rule it moves, so the
+      // frame shows the first few and the record carries every one.
+      if (json) continue
+      for (const finding of step.findings.slice(0, REPLAY_FINDINGS_SHOWN))
+        logWarn(`${step.step}: ${finding}`)
+      const hidden = step.findings.length - REPLAY_FINDINGS_SHOWN
+      if (hidden > 0)
+        logWarn(`${step.step}: ${hidden} more, listed under --json`)
+    }
+  }
+
+  const failed = replays
+    .flatMap((r) => r.steps)
+    .filter((s) => s.verdict !== 'ok')
+
+  if (record) {
+    recordReplays(sources, replays, failed.length, json)
+    return
+  }
+
+  logStep('Replay')
+  const summary = `${replays.length} replayed, ${failed.length} failed steps`
+  if (failed.length === 0) logInfo(summary)
+  else logWarn(summary)
+
+  if (json)
+    process.stdout.write(
+      `${JSON.stringify({ ok: true, failed: failed.length, replays })}\n`,
+    )
+
+  outro()
+  process.exitCode = failed.length === 0 ? 0 : 2
+}
+
+/**
+ * Writes each snapshot's expectation from its run, or refuses and writes none
+ * when any step broke, since pinning a crash would make it the expected answer.
+ */
+function recordReplays(
+  sources: readonly ReplaySource[],
+  replays: readonly ReplayResult[],
+  broken: number,
+  json: boolean,
+): void {
+  if (broken > 0) {
+    refuseReplay(
+      'broken-run',
+      `${broken} steps broke, so nothing was recorded. Fix the run, then record it.`,
+      json,
+    )
+    return
+  }
+
+  logStep('Record')
+  const recorded: string[] = []
+  for (const [i, source] of sources.entries()) {
+    const replay = replays[i]
+    if (replay === undefined) continue
+    writeExpectation(source.path, expectationOf(replay.steps))
+    const path = relative(PROJECT_ROOT, join(source.path, EXPECTED_FILE))
+    recorded.push(path)
+    logInfo(path)
+  }
+
+  if (json)
+    process.stdout.write(`${JSON.stringify({ ok: true, recorded, replays })}\n`)
+
+  outro()
+  process.exitCode = 0
+}
+
 function runCheck(
   target: string,
   arm: string | undefined,
@@ -683,4 +887,45 @@ export function register(program: Command): void {
     .action((targets: string[], options: EquivalenceOptions) =>
       runEquivalence(targets, options),
     )
+
+  sandbox
+    .command('replay')
+    .description(
+      'Sync a copy of each consumer with this checkout and judge the reads that follow',
+    )
+    .argument(
+      '[paths...]',
+      'Consumer checkouts to copy, defaulting to every snapshot under sandbox/fixtures/replay/',
+    )
+    .helpOption('-h, --help', 'Show this help message')
+    .option('--json', 'Emit the record as JSON on stdout')
+    .option(
+      '--record',
+      `Write each snapshot's ${EXPECTED_FILE} from this run instead of judging against it`,
+    )
+    .addHelpText(
+      'after',
+      [
+        '',
+        'Examples:',
+        '  canon sandbox replay',
+        '  canon sandbox replay --record',
+        '  canon sandbox replay ../frameboard ../jobtriage --json',
+        '',
+        'Each replay copies the source to a temp tree outside the repository,',
+        'runs sync, then sync --check, context audit, markdown audit, and',
+        'migrate status, and checks what sync wrote with oxfmt. A finding or a',
+        'refusal from a read is the verb working. Only a crash, stdout a --json',
+        'caller cannot parse, or an unformatted write fails the run.',
+        'A snapshot also fails a step whose exit or finding count drifted from',
+        `the ${EXPECTED_FILE} beside it, and fails every step when it has none.`,
+        '--record rewrites those files, refusing named paths and a broken run.',
+        'A named checkout with uncommitted changes is refused, never synced over.',
+        '',
+        'Exit codes: 0 clean or recorded, 1 refused, 2 when any step failed.',
+      ].join('\n'),
+    )
+    .action((paths: string[], options: ReplayOptions) => {
+      runReplay(paths, options)
+    })
 }

package/src/gate/measures.ts

@@ -519,9 +519,12 @@ export const documentCeiling: Measure = async (ctx) => {
  *
  * `canon/context/context-model.md` is exempt, since "context model" is the
  * domain's own name and the entry reads as nothing else without the prefix.
+ * So is a replay snapshot, which copies a consumer's paths verbatim, such as
+ * `canon/config/config.json`, and a renamed copy would sync as another file.
  */
 export function isFolderEchoedName(path: string): boolean {
   if (path === 'canon/context/context-model.md') return false
+  if (path.startsWith('sandbox/fixtures/replay/')) return false
   const segments = path.split('/')
   if (segments.length < 2) return false
   const folder = segments[segments.length - 2] ?? ''

package/src/gate/stages.ts

@@ -304,6 +304,31 @@ export const STAGES: readonly Stage[] = [
     label: 'Unreferenced rules',
     checks: [{ kind: 'measure', measure: unreferencedRules }],
   },
+  {
+    // A defect that only shows after a sync, such as a read crashing on a
+    // rule layout the sync just renamed, passes every unit test and every
+    // stage that reads this repository. Replaying the frozen consumer
+    // snapshots through this checkout's sync is what reaches it before a
+    // consumer does. Scoped to what a sync ships or reads, since a replay
+    // costs seconds a docs-only push should not pay. Governance is whole
+    // but for the ledger, since sync resolves stacks and renames as well as
+    // rules, and a rename is the class the stage was built against.
+    id: 'consumer-replay',
+    label: 'Consumer replay',
+    scope:
+      /^src\/|^governance\/(?!ledger\/)|^tooling\/|^sandbox\/fixtures\/replay\//,
+    skipped:
+      'No synced surface or snapshot changed, so no consumer was replayed',
+    checks: [
+      {
+        kind: 'cli',
+        argv: ['sandbox', 'replay'],
+        failure:
+          'A consumer replay crashed, printed unparsable JSON, left an unformatted write, or drifted from its recorded answer. Run bun src/cli.ts sandbox replay, and when a drift is one the change meant, such as a governance rename moving a sync count, run it with --record and commit the expectations.',
+      },
+    ],
+    success: 'Consumer replays clean',
+  },
   {
     // The facts the audit can answer from the files gate: a cited path that
     // does not resolve, a required section an entry does not declare, an H2