@erclx/canon 5.43.0 → 5.45.0

package/governance/ledger/lib/security-server.md

@@ -0,0 +1,62 @@
+---
+title: Server security rule ledger
+description: Sources for governance/rules/lib/security-server.md, one row per bullet
+---
+
+# Server security rule ledger
+
+The field is application security, and the authorities are the OWASP Cheat Sheet Series, the OWASP API Security Top 10 2023, and MDN for the CORS protocol. The CORS bullet is worded the way `framework/fastapi.md` states it, so a FastAPI target reads one rule twice rather than two.
+
+## Authorization
+
+| Bullet                           | Source                                                                                                                                                                                                                             | Read       |
+| -------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ---------- |
+| Authorize on the server          | [Authorization](https://cheatsheetseries.owasp.org/cheatsheets/Authorization_Cheat_Sheet.html): "Developers must never rely on client-side access control checks", and "Permission should be validated correctly on every request" | 2026-10-18 |
+| Identity from the verified token | House choice: an identity read from a field the client sets is one the client chooses, which turns every authorization check into a check of the attacker's claim                                                                  | 2026-10-18 |
+| Check the specific record        | [Authorization](https://cheatsheetseries.owasp.org/cheatsheets/Authorization_Cheat_Sheet.html): "Perform access control checks on every request for the specific object or functionality being accessed"                           | 2026-10-18 |
+| Deny by default                  | [Authorization](https://cheatsheetseries.owasp.org/cheatsheets/Authorization_Cheat_Sheet.html): "an application should be configured to deny access by default"                                                                    | 2026-10-18 |
+
+## Credentials
+
+| Bullet                          | Source                                                                                                                                                                                                                                              | Read       |
+| ------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ---------- |
+| Argon2id and a salt             | [Password Storage](https://cheatsheetseries.owasp.org/cheatsheets/Password_Storage_Cheat_Sheet.html): "If Argon2id is not available, use scrypt", a salt is "unique, randomly generated" per password, and "hashing is a one-way function"          | 2026-10-18 |
+| Constant-time comparison        | [Authentication](https://cheatsheetseries.owasp.org/cheatsheets/Authentication_Cheat_Sheet.html): a comparison should return "in constant time, to protect against timing attacks"                                                                  | 2026-10-18 |
+| Expire and revoke on the server | [Session Management](https://cheatsheetseries.owasp.org/cheatsheets/Session_Management_Cheat_Sheet.html): "Session timeout management and expiration must be enforced server-side", and "deleting a cookie alone does not invalidate a stolen copy" | 2026-10-18 |
+
+## Secrets
+
+| Bullet                         | Source                                                                                                                                                                                                                                       | Read       |
+| ------------------------------ | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ---------- |
+| Secrets at runtime             | [Secrets Management](https://cheatsheetseries.owasp.org/cheatsheets/Secrets_Management_Cheat_Sheet.html): "It is even better when the consumer of the secret retrieves the secret", or an orchestrator injects it as an environment variable | 2026-10-18 |
+| Never commit a secret          | [Secrets Management](https://cheatsheetseries.owasp.org/cheatsheets/Secrets_Management_Cheat_Sheet.html) names the failure: secrets "hardcoded within the source code in plaintext"                                                          | 2026-10-18 |
+| Nothing internal in a response | [Error Handling](https://cheatsheetseries.owasp.org/cheatsheets/Error_Handling_Cheat_Sheet.html): a response should "not provide any content as part of the response that would reveal implementation details"                               | 2026-10-18 |
+
+## Abuse limits
+
+| Bullet                      | Source                                                                                                                                                                                                                                                         | Read       |
+| --------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ---------- |
+| Rate-limit costly endpoints | [API4:2023](https://api-security.owasp.org/editions/2023/en/0xa4-unrestricted-resource-consumption): "Implement a limit on how often a client can interact with the API within a defined timeframe", and "Configure spending limits for all service providers" | 2026-10-18 |
+| Body size and timeout       | [API4:2023](https://api-security.owasp.org/editions/2023/en/0xa4-unrestricted-resource-consumption): "Define and enforce a maximum size of data on all incoming parameters and payloads", with missing "Execution timeouts" listed as a weakness               | 2026-10-18 |
+| Bound pagination            | [API4:2023](https://api-security.owasp.org/editions/2023/en/0xa4-unrestricted-resource-consumption): validate the parameter "that controls the number of records to be returned in the response"                                                               | 2026-10-18 |
+
+## Transport
+
+| Bullet                            | Source                                                                                                                                                                                                                                                       | Read       |
+| --------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | ---------- |
+| TLS, and fail plaintext API calls | [Transport Layer Security](https://cheatsheetseries.owasp.org/cheatsheets/Transport_Layer_Security_Cheat_Sheet.html): "API endpoints should fail requests made over unencrypted HTTP connections instead of redirecting them"                                | 2026-10-18 |
+| Explicit CORS origins             | [MDN CORS](https://developer.mozilla.org/en-US/docs/Web/HTTP/Guides/CORS): for a credentialed request the server "must not specify the `*` wildcard", and reflecting the origin is a house choice, since it grants every origin the wildcard was refused for | 2026-10-18 |
+
+## Declined
+
+Every bullet the rewrite removed or reshaped, grouped by why.
+
+### Contradicted by the docs
+
+- Reworded "serve every route over TLS and reject plaintext requests". The TLS cheat sheet allows a public site to redirect port 80 to HTTPS, and requires the refusal for an API endpoint only.
+
+### Merged or reworded
+
+- Narrowed "hash passwords with a memory-hard algorithm" to the order the password storage page gives, since bcrypt is not memory-hard and the page still lists it.
+- Reworded "restrict CORS to an explicit origin list, never pair a wildcard with credentials" to the wording `framework/fastapi.md` uses, keeping the ban on reflecting the origin.
+- Added stack traces to the response bullet, the leak the error handling page shows first.

package/governance/ledger/lib/security-web.md

@@ -0,0 +1,51 @@
+---
+title: Web security rule ledger
+description: Sources for governance/rules/lib/security-web.md, one row per bullet
+---
+
+# Web security rule ledger
+
+The field is web application security in the browser, and the authorities are the OWASP Cheat Sheet Series and MDN. The two disagreed on `target="_blank"`, and MDN was kept, since it states what browsers do and the extra attribute adds nothing a current browser lacks.
+
+## Content sanitization
+
+| Bullet                    | Source                                                                                                                                                                                                                                                                    | Read       |
+| ------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ---------- |
+| DOMPurify before raw HTML | [XSS Prevention](https://cheatsheetseries.owasp.org/cheatsheets/Cross_Site_Scripting_Prevention_Cheat_Sheet.html) lists "React's `dangerouslySetInnerHTML` without sanitizing the HTML" as an unsafe escape hatch, and "OWASP recommends DOMPurify for HTML Sanitization" | 2026-10-18 |
+| Allow-list URL schemes    | [XSS Prevention](https://cheatsheetseries.owasp.org/cheatsheets/Cross_Site_Scripting_Prevention_Cheat_Sheet.html): React blocking `javascript:` URLs "does not replace application-specific URL validation", which allows only http and HTTPS                             | 2026-10-18 |
+
+## Input validation
+
+| Bullet                            | Source                                                                                                                                          | Read       |
+| --------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------- | ---------- |
+| Parse URL params through a schema | House choice: a URL parameter is a string the visitor writes, and one read unparsed reaches rendering or a request in whatever shape it arrived | 2026-10-18 |
+
+## Storage and tokens
+
+| Bullet                           | Source                                                                                                                                                                                               | Read       |
+| -------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ---------- |
+| Nothing sensitive in web storage | [HTML5 Security](https://cheatsheetseries.owasp.org/cheatsheets/HTML5_Security_Cheat_Sheet.html): "Do not store session identifiers in local storage as the data is always accessible by JavaScript" | 2026-10-18 |
+| Tokens in `HttpOnly` cookies     | [Session Management](https://cheatsheetseries.owasp.org/cheatsheets/Session_Management_Cheat_Sheet.html): the `HttpOnly` flag "is mandatory to prevent session ID stealing through XSS attacks"      | 2026-10-18 |
+
+## Third-party scripts
+
+| Bullet                   | Source                                                                                                                                                                                                                            | Read       |
+| ------------------------ | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ---------- |
+| Pinned, with `integrity` | [Subresource Integrity](https://developer.mozilla.org/en-US/docs/Web/Security/Subresource_Integrity): it lets browsers "verify that resources they fetch (for example, from a CDN) are delivered without unexpected manipulation" | 2026-10-18 |
+
+## Declined
+
+Every bullet the rewrite removed or reshaped, grouped by why.
+
+### Contradicted by the docs
+
+- Cut "add `rel="noopener noreferrer"` to all external links with `target="_blank"`". [MDN noopener](https://developer.mozilla.org/en-US/docs/Web/HTML/Reference/Attributes/rel/noopener) says `target="_blank"` "implicitly provides the same `rel` behavior as setting `rel="noopener"`". The [HTML5 Security](https://cheatsheetseries.owasp.org/cheatsheets/HTML5_Security_Cheat_Sheet.html) page still asks for it, and MDN was kept as the newer statement of browser behavior.
+
+### Merged or reworded
+
+- Merged "never use `dangerouslySetInnerHTML` without sanitization" into the DOMPurify bullet, and named `innerHTML` and Astro's `set:html`, since the rule loads on `.html` and `.astro` files too.
+- Reworded "audit and pin versions for all third-party scripts" to the `integrity` attribute, which makes the pin checkable.
+
+### Gaps filled
+
+- Added the URL scheme bullet. The XSS page names `javascript:` URLs as the hole sanitizing markup leaves.

package/governance/ledger/lib/tanstack-query.md

@@ -0,0 +1,57 @@
+---
+title: TanStack Query rule ledger
+description: Sources for governance/rules/lib/tanstack-query.md, one row per bullet
+---
+
+# TanStack Query rule ledger
+
+The field is client-side data fetching in React, and the authority is the TanStack Query documentation at tanstack.com. The pages read are the latest docs, which name no major but deprecate `prefetchQuery`, so the prefetch bullet names the route loader rather than either method. `queryOptions()` needs TanStack Query 5 or later.
+
+## Query conventions
+
+| Bullet                         | Source                                                                                                                                                                                                                                    | Read               |
+| ------------------------------ | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------ |
+| `queryOptions()` at every site | [Query options](https://tanstack.com/query/latest/docs/framework/react/guides/query-options): it lets you "share `queryKey` and `queryFn` between multiple places", with "type inference and type safety for all of them"                 | 2026-10-18, latest |
+| Every variable in the key      | [Query keys](https://tanstack.com/query/latest/docs/framework/react/guides/query-keys): "If your query function depends on a variable, include it in your query key"                                                                      | 2026-10-18, latest |
+| `staleTime` per query          | [Important defaults](https://tanstack.com/query/latest/docs/framework/react/guides/important-defaults): queries "consider cached data as stale" by default, and setting `staleTime` is "the recommended way to avoid excessive refetches" | 2026-10-18, latest |
+| Throw on a non-`ok` response   | [Query functions](https://tanstack.com/query/latest/docs/framework/react/guides/query-functions): a query function "must throw or return a rejected Promise", and `fetch` does not "throw errors by default"                              | 2026-10-18, latest |
+
+## Mutations
+
+| Bullet                          | Source                                                                                                                                                                                                                                   | Read               |
+| ------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------ |
+| Writes through `useMutation`    | House choice: a write outside a mutation has no pending or error state and invalidates nothing, so the cache keeps serving what the write replaced                                                                                       | 2026-10-18, latest |
+| Invalidate in `onSuccess`       | [Invalidations from mutations](https://tanstack.com/query/latest/docs/framework/react/guides/invalidations-from-mutations): "Returning a Promise on `onSuccess` makes sure the data is updated before the mutation is entirely complete" | 2026-10-18, latest |
+| `onError` with visible feedback | House choice: a failed write with no handler leaves the screen showing the edit as if it saved                                                                                                                                           | 2026-10-18, latest |
+
+## Cache management
+
+| Bullet                       | Source                                                                                                                                                                                                | Read               |
+| ---------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------ |
+| Prefetch in the route loader | [Prefetching](https://tanstack.com/query/latest/docs/framework/react/guides/prefetching): a loader starts a route's data ahead of render, with "Fetch comments asap, but don't block or throw errors" | 2026-10-18, latest |
+
+## Separation of concerns
+
+| Bullet                     | Source                                                                                                                                                                                                                        | Read               |
+| -------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------ |
+| Pure query functions       | [Important defaults](https://tanstack.com/query/latest/docs/framework/react/guides/important-defaults): stale queries refetch when "The window is refocused" and "The network is reconnected", so a side effect fires on each | 2026-10-18, latest |
+| `enabled`, not `useEffect` | [Dependent queries](https://tanstack.com/query/latest/docs/framework/react/guides/dependent-queries): "using the `enabled` option to tell a query when it is ready to run"                                                    | 2026-10-18, latest |
+
+## Declined
+
+Every bullet the rewrite removed or reshaped, grouped by why.
+
+### Contradicted by the docs
+
+- Reworded "prefetch predictable navigations with `queryClient.prefetchQuery`". The [prefetching guide](https://tanstack.com/query/latest/docs/framework/react/guides/prefetching) calls `prefetchQuery` "now deprecated", and a target on an older major still has it, so the bullet names the loader alone.
+
+### Merged or reworded
+
+- Merged "define query keys as `readonly` tuple constants", "co-locate query keys with their query functions", and "encapsulate each query in a custom `use*Query` hook" into the `queryOptions()` bullet, the helper the docs name for sharing a key with its function.
+- Merged "never mutate data outside the mutation lifecycle" into the `useMutation` bullet.
+- Merged "use `invalidateQueries` over `setQueryData` unless implementing optimistic updates" into the `onSuccess` bullet.
+
+### Gaps filled
+
+- Added the bullet putting every variable in the key, the stale-data bug the query keys page warns about.
+- Added the bullet throwing on a response that is not `ok`, since a `fetch` query function otherwise caches an error body as data.

package/governance/ledger/lib/test-scope.md

@@ -0,0 +1,43 @@
+---
+title: Test scope rule ledger
+description: Sources for governance/rules/lib/test-scope.md, one row per bullet
+---
+
+# Test scope rule ledger
+
+The field is browser test automation, and the authority is the Playwright documentation, read at playwright.dev and from its source in the microsoft/playwright repository. The rule ships to every Playwright target, so it names the Playwright CLI rather than a package script a target may not carry. None of the pages read names a Playwright major, so the rows record the read date alone.
+
+## Selecting a run
+
+| Bullet                               | Source                                                                                                                                                                                                                 | Read       |
+| ------------------------------------ | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ---------- |
+| Narrow by path or name, never engine | House choice: a run narrowed to one engine passes while another engine fails, and the gap surfaces only in CI                                                                                                          | 2026-10-18 |
+| One test by name                     | [Command line](https://raw.githubusercontent.com/microsoft/playwright/main/docs/src/test-cli-js.md): `-g` will "Only run tests matching this regular expression"                                                       | 2026-10-18 |
+| One surface by path                  | [Command line](https://raw.githubusercontent.com/microsoft/playwright/main/docs/src/test-cli-js.md): "Run a single test file" by passing its path                                                                      | 2026-10-18 |
+| `--only-changed`                     | [Command line](https://raw.githubusercontent.com/microsoft/playwright/main/docs/src/test-cli-js.md): "Only run test files that have been changed between 'HEAD' and 'ref'"                                             | 2026-10-18 |
+| Whole suite before push              | House choice: a narrowed run skips the specs a change broke without touching, which the push would hand to CI                                                                                                          | 2026-10-18 |
+| `--project` only to reproduce        | [Command line](https://raw.githubusercontent.com/microsoft/playwright/main/docs/src/test-cli-js.md): `--project` will "Only run tests from the specified list of projects", where the default is to "run all projects" | 2026-10-18 |
+| No one-engine script                 | House choice: a script pinning one engine becomes the run everyone types, which is the engine narrowing the first bullet bans                                                                                          | 2026-10-18 |
+
+## Instruments
+
+| Bullet                       | Source                                                                                                                                                                                                      | Read       |
+| ---------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ---------- |
+| A script, not the suite      | House choice: a suite run answers a question about the page only through assertions written for another question, and costs the whole run                                                                   | 2026-10-18 |
+| No `fullyParallel`           | [Parallelism](https://playwright.dev/docs/test-parallel): by default "Tests in a single file are run in order, in the same worker process", and parallel tests "cannot share any state or global variables" | 2026-10-18 |
+| Pointer to `surface-capture` | House choice: a pointer to the rule that owns capture scope, claiming no practice of its own                                                                                                                | 2026-10-18 |
+| Pointer to `e2e-reliability` | House choice: a pointer to the rule that owns waits and guards, claiming no practice of its own                                                                                                             | 2026-10-18 |
+
+## Declined
+
+Every bullet the rewrite removed or reshaped, grouped by why.
+
+### A script a target may lack
+
+- Replaced `bun run test:e2e -- -g '<name>'` with `playwright test -g '<name>'`. The `test:e2e` scripts are this toolkit's alone, and the rule ships to every Playwright target.
+- Replaced `bun run test:e2e -- e2e/<area>.spec.ts` with the CLI's path argument.
+- Replaced `bun run test:e2e:changed`, which selected specs from the import graph, with `--only-changed`, the CLI's own selection by git diff.
+
+### Merged or reworded
+
+- Named the Playwright config in the `fullyParallel` bullet rather than the `playwright.config.ts` filename, since a target may write the config in JavaScript.

package/governance/ledger/lib/testing-go.md

@@ -0,0 +1,57 @@
+---
+title: Go testing rule ledger
+description: Sources for governance/rules/lib/testing-go.md, one row per bullet
+---
+
+# Go testing rule ledger
+
+The field is Go testing, and the authorities are the `testing` and `net/http/httptest` package documentation at pkg.go.dev, the Go wiki at go.dev, and the race detector article. None of the pages read names a Go release beyond a 1.22 loop-variable note, so the rows record the read date alone.
+
+## Layer
+
+| Bullet                  | Source                                                                                              | Read       |
+| ----------------------- | --------------------------------------------------------------------------------------------------- | ---------- |
+| Load `test-craft` first | House choice: a pointer to the skill that owns the choice of layer, claiming no practice of its own | 2026-10-18 |
+
+## Framework
+
+| Bullet                                | Source                                                                                                                                                                     | Read       |
+| ------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ---------- |
+| Standard `testing`, no assert library | [Go test comments](https://go.dev/wiki/TestComments): "Avoid the use of 'assert' libraries to help your tests", which "make it too easy to write imprecise tests"          | 2026-10-18 |
+| External `_test` package              | [Package testing](https://pkg.go.dev/testing): a test file in a package with the "_test" suffix is black-box, where "the package being tested must be imported explicitly" | 2026-10-18 |
+
+## Table-driven cases
+
+| Bullet                           | Source                                                                                                                                  | Read       |
+| -------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------- | ---------- |
+| Slice of structs through `t.Run` | [Table driven tests](https://go.dev/wiki/TableDrivenTests): "Each table entry is a complete test case with inputs and expected results" | 2026-10-18 |
+| A `name` per case                | [Package testing](https://pkg.go.dev/testing): "Run runs f as a subtest of t called name", which is how a failure names its case        | 2026-10-18 |
+
+## Helpers and setup
+
+| Bullet                     | Source                                                                                                                                                        | Read       |
+| -------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------- | ---------- |
+| `t.Helper()` first         | [Package testing](https://pkg.go.dev/testing): "Helper marks the calling function as a test helper function", skipped when printing file and line             | 2026-10-18 |
+| `t.Cleanup` over `defer`   | [Package testing](https://pkg.go.dev/testing): Cleanup runs "when the test (or subtest) and all its subtests complete"                                        | 2026-10-18 |
+| `t.TempDir` and `t.Setenv` | [Package testing](https://pkg.go.dev/testing): the directory is removed when the test finishes, and Setenv "uses Cleanup to restore the environment variable" | 2026-10-18 |
+| `httptest` over a listener | [Package httptest](https://pkg.go.dev/net/http/httptest): "NewServer starts and returns a new Server listening on a local network loopback interface"         | 2026-10-18 |
+
+## Concurrency
+
+| Bullet                              | Source                                                                                                                                  | Read       |
+| ----------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------- | ---------- |
+| No `time.Sleep` sync                | House choice: a sleep long enough on one machine is too short on a loaded runner, so the test fails with no defect in the code          | 2026-10-18 |
+| `-race`                             | [Data race detector](https://go.dev/doc/articles/race_detector): "add the `-race` flag to the go command", as in `go test -race mypkg`  | 2026-10-18 |
+| `t.Parallel()` without shared state | [Table driven tests](https://go.dev/wiki/TableDrivenTests): "Parallelizing table tests is simple, but requires precision to avoid bugs" | 2026-10-18 |
+
+## Declined
+
+Every bullet the rewrite removed or reshaped, grouped by why.
+
+### A default the toolchain already applies
+
+- Cut "place a test beside the code it tests, in a `_test.go` file of the same package". The `go` tool finds tests only in `_test.go` files, and Claude writes them that way unprompted.
+
+### Merged or reworded
+
+- Gave the `t.Cleanup` bullet its reason, a `defer` in a helper firing as the helper returns.

package/governance/ledger/lib/testing-php.md

@@ -0,0 +1,51 @@
+---
+title: PHP testing rule ledger
+description: Sources for governance/rules/lib/testing-php.md, one row per bullet
+---
+
+# PHP testing rule ledger
+
+The field is PHP testing, and the authority is the PHPUnit documentation at docs.phpunit.de with its release announcements at phpunit.de. The manual pages read are the PHPUnit 12.4 edition. Attributes arrived in PHPUnit 10, so the attribute bullet names that floor and a PHPUnit 9 target is never told to use them.
+
+## Layer
+
+| Bullet                  | Source                                                                                              | Read       |
+| ----------------------- | --------------------------------------------------------------------------------------------------- | ---------- |
+| Load `test-craft` first | House choice: a pointer to the skill that owns the choice of layer, claiming no practice of its own | 2026-10-18 |
+
+## Framework
+
+| Bullet                        | Source                                                                                                                                                                                   | Read                     |
+| ----------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------ |
+| PHPUnit as the runner         | House choice: the toolkit's PHP stack configures PHPUnit, so a test written for a second runner never runs in the gate                                                                   | 2026-10-18, PHPUnit 12.4 |
+| `final`, extending `TestCase` | [Writing tests](https://docs.phpunit.de/en/12.4/writing-tests-for-phpunit.html): "`GreeterTest` inherits from `PHPUnit\Framework\TestCase`", and every example class is declared `final` | 2026-10-18, PHPUnit 12.4 |
+
+## Attributes
+
+| Bullet                        | Source                                                                                                                                                                                                                                                                       | Read                     |
+| ----------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------ |
+| Attributes over annotations   | [PHPUnit 12 announcement](https://phpunit.de/announcements/phpunit-12.html): "Support for using annotations has now been removed", and the [PHPUnit 10 announcement](https://phpunit.de/announcements/phpunit-10.html): "PHPUnit 10 introduces support for PHP 8 attributes" | 2026-10-18, PHPUnit 12   |
+| `public static` data provider | [Writing tests](https://docs.phpunit.de/en/12.4/writing-tests-for-phpunit.html): "A data provider method must be `public` and `static` and its name must not start with `test`"                                                                                              | 2026-10-18, PHPUnit 12.4 |
+
+## Assertions and doubles
+
+| Bullet                           | Source                                                                                                                                                                                                              | Read                     |
+| -------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------ |
+| `assertSame` over `assertEquals` | [Assertions](https://docs.phpunit.de/en/12.4/assertions.html): `assertSame()` fails when the values "do not have the same type and value", while `assertEquals()` compares with `==`                                | 2026-10-18, PHPUnit 12.4 |
+| `expectException` first          | [Writing tests](https://docs.phpunit.de/en/12.4/writing-tests-for-phpunit.html): "The `expectException()` method has to be used **before** the exception you expect to be thrown is thrown"                         | 2026-10-18, PHPUnit 12.4 |
+| Stub unless asserting a call     | [Test doubles](https://docs.phpunit.de/en/12.4/test-doubles.html): a stub "(optionally) returns configured return values", and a mock "verifies expectations, for instance asserting that a method has been called" | 2026-10-18, PHPUnit 12.4 |
+| No real network calls            | House choice: a test reaching the network fails on an outage or a rate limit with no defect in the code under test                                                                                                  | 2026-10-18               |
+
+## Declined
+
+Every bullet the rewrite removed or reshaped, grouped by why.
+
+### Cut without a source or a bug class
+
+- Cut "place tests under `tests/`, mirroring the `src/` namespace layout, in files named `*Test.php`" as a layout call, which the `codebase-layout` skill owns. The PHPUnit manual shows the layout in examples and states no rule.
+
+### Merged or reworded
+
+- Prefixed the attribute bullet with "On PHPUnit 10 or later", since attributes do not exist before it.
+- Named `public static` in the data provider bullet, the signature the manual requires.
+- Reworded the `expectException` bullet to the ordering the manual stresses.

package/governance/ledger/lib/testing-py.md

@@ -0,0 +1,67 @@
+---
+title: Python testing rule ledger
+description: Sources for governance/rules/lib/testing-py.md, one row per bullet
+---
+
+# Python testing rule ledger
+
+The field is Python testing, and the authorities are the pytest documentation at docs.pytest.org and the pytest-asyncio documentation. The pytest pages name no major beyond a feature added in 9.0, and the pytest-asyncio page names none, so the rows record the read date alone.
+
+## Framework
+
+| Bullet                         | Source                                                                                                                                                                                   | Read       |
+| ------------------------------ | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ---------- |
+| Plain functions, no `TestCase` | [unittest.TestCase support](https://docs.pytest.org/en/stable/how-to/unittest.html): in a `TestCase` subclass, regular fixtures and parametrization do not work, "and likely never will" | 2026-10-18 |
+
+## Fixtures
+
+| Bullet                               | Source                                                                                                                                                                                                                                                                                                      | Read       |
+| ------------------------------------ | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ---------- |
+| Yield fixtures for teardown          | [Fixtures](https://docs.pytest.org/en/stable/how-to/fixtures.html): "yield fixtures are considered to be the cleaner and more straightforward option"                                                                                                                                                       | 2026-10-18 |
+| Narrowest `conftest.py`              | [Fixtures](https://docs.pytest.org/en/stable/how-to/fixtures.html): in a `conftest.py`, "tests from multiple test modules in the directory can access the fixture function"                                                                                                                                 | 2026-10-18 |
+| Widen scope only for unmutated state | [Fixtures](https://docs.pytest.org/en/stable/how-to/fixtures.html): "`function`: the default scope, the fixture is destroyed at the end of the test", so a wider scope hands one object to every test in it                                                                                                 | 2026-10-18 |
+| `tmp_path` and `monkeypatch`         | [tmp_path](https://docs.pytest.org/en/stable/how-to/tmp_path.html) is "a temporary directory unique to each test function", and with [monkeypatch](https://docs.pytest.org/en/stable/how-to/monkeypatch.html) "All modifications will be undone after the requesting test function or fixture has finished" | 2026-10-18 |
+
+## Parametrize
+
+| Bullet                   | Source                                                                                                                                          | Read       |
+| ------------------------ | ----------------------------------------------------------------------------------------------------------------------------------------------- | ---------- |
+| `parametrize` for tables | [Parametrizing tests](https://docs.pytest.org/en/stable/how-to/parametrize.html): it "enables parametrization of arguments for a test function" | 2026-10-18 |
+
+## Async
+
+| Bullet                      | Source                                                                                                                                                                                                         | Read       |
+| --------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ---------- |
+| Mark async tests or go auto | [pytest-asyncio concepts](https://pytest-asyncio.readthedocs.io/en/latest/concepts.html): "In strict mode pytest-asyncio will only run tests that have the _asyncio_ marker", and strict "is the default mode" | 2026-10-18 |
+| The plugin's event loop     | [pytest-asyncio concepts](https://pytest-asyncio.readthedocs.io/en/latest/concepts.html): "Pytest-asyncio provides one asyncio event loop for each pytest collector"                                           | 2026-10-18 |
+
+## Assertions and mocks
+
+| Bullet                  | Source                                                                                                                                                                                            | Read       |
+| ----------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ---------- |
+| Plain `assert`          | [Assertions](https://docs.pytest.org/en/stable/how-to/assert.html): failure details come from "rewriting assert statements before they are run"                                                   | 2026-10-18 |
+| `pytest.raises`         | [Assertions](https://docs.pytest.org/en/stable/how-to/assert.html): you "can use pytest.raises() as a context manager" for an expected exception                                                  | 2026-10-18 |
+| Patch through a fixture | [monkeypatch](https://docs.pytest.org/en/stable/how-to/monkeypatch.html): it "helps you to safely set/delete an attribute", undone after the test, where a hand assignment leaks into later tests | 2026-10-18 |
+| No real network calls   | House choice: a test reaching the network fails on an outage or a rate limit with no defect in the code under test                                                                                | 2026-10-18 |
+
+## Declined
+
+Every bullet the rewrite removed or reshaped, grouped by why.
+
+### A default pytest already applies
+
+- Cut "name files `test_*.py` and test functions `test_*`". [Good practices](https://docs.pytest.org/en/stable/explanation/goodpractices.html) states it as pytest's default discovery, and Claude names tests that way unprompted.
+- Narrowed "set `scope=` explicitly when reuse matters" to the one case a wider scope breaks, since `function` is already the default.
+
+### Cut without a source or a bug class
+
+- Cut "place tests under `tests/`, mirroring the `src/` package layout" as a layout call, which the `codebase-layout` skill owns. Good practices says only that a separate directory "might be useful".
+- Cut "use `ids=` to label parametrized cases when their repr is unclear" as readability naming no failure.
+- Cut "arrange, act, assert per test, with one logical assertion group" as test structure, which the `test-craft` skill owns.
+- Cut "use descriptive `test_*` names that read as the assertion, never `should_`" as naming style naming no failure.
+
+### Merged or reworded
+
+- Merged "use `pytest` for all tests, never `unittest.TestCase`" with the reason the unittest page gives.
+- Reworded "do not start a fresh event loop inside tests" to name the loop the plugin provides and the calls that bypass it.
+- Replaced `httpx_mock`, a fixture name, with `pytest-httpx`, the package that provides it.

package/governance/ledger/lib/testing-ts.md

@@ -0,0 +1,63 @@
+---
+title: TypeScript testing rule ledger
+description: Sources for governance/rules/lib/testing-ts.md, one row per bullet
+---
+
+# TypeScript testing rule ledger
+
+The field is JavaScript and TypeScript testing. The authorities are the Vitest documentation at vitest.dev, the Testing Library documentation at testing-library.com, and the Playwright documentation at playwright.dev. None of the pages read names a major, so the rows record the read date alone.
+
+## Unit and integration
+
+| Bullet                           | Source                                                                                                                                                                                                                                | Read       |
+| -------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ---------- |
+| Vitest as the runner             | House choice: the toolkit's web stacks install and configure Vitest, so a test written for a second runner never runs in the gate                                                                                                     | 2026-10-18 |
+| `userEvent` over `fireEvent`     | [user-event](https://testing-library.com/docs/user-event/intro): it "factors in that the browser e.g. wouldn't let a user click a hidden element or type in a disabled text box"                                                      | 2026-10-18 |
+| MSW, no hand mocks or real calls | [Vitest, mocking requests](https://vitest.dev/guide/mocking/requests): "We recommend Mock Service Worker to accomplish this", since it mocks "http, WebSocket and GraphQL network requests"                                           | 2026-10-18 |
+| Role or label first              | [Testing Library queries](https://testing-library.com/docs/queries/about): `getByRole` "should be your top preference for just about everything", and a test ID "is only recommended for cases where you can't match by role or text" | 2026-10-18 |
+
+## End-to-end
+
+| Bullet                        | Source                                                                                                                                                                            | Read       |
+| ----------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ---------- |
+| Playwright for end-to-end     | House choice: the toolkit's web stack configures Playwright, so a second browser runner's tests never run in the gate                                                             | 2026-10-18 |
+| Playwright tests under `e2e/` | [Vitest include](https://vitest.dev/config/include) defaults to `**/*.{test,spec}.?(c\|m)[jt]s?(x)`, so a Playwright spec under `src/` is collected by Vitest too, where it fails | 2026-10-18 |
+
+## Timers and async
+
+| Bullet                           | Source                                                                                                                                                                                                               | Read       |
+| -------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ---------- |
+| `advanceTimers` with fake timers | [user-event options](https://testing-library.com/docs/user-event/options): "When using fake timers it is necessary to set this option to your test runner's time advancement function"                               | 2026-10-18 |
+| Restore after pending timers     | [Using fake timers](https://testing-library.com/docs/using-fake-timers): "you usually call `useRealTimers` in `afterEach`", and "It's important to also call `runOnlyPendingTimers` before switching to real timers" | 2026-10-18 |
+
+## Conventions
+
+| Bullet                              | Source                                                                                                                                                                                                                   | Read       |
+| ----------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | ---------- |
+| `.test` for unit, `.spec` otherwise | House choice: [Playwright](https://playwright.dev/docs/test-configuration) runs "`**/*.@(spec\|test).?(c\|m)[jt]s?(x)` files" and Vitest matches the same pair, so the suffix is what a config separates the two runs on | 2026-10-18 |
+
+## Declined
+
+Every bullet the rewrite removed or reshaped, grouped by why.
+
+### Contradicted by the docs
+
+- Cut "never use `vi.useFakeTimers()` in `beforeEach` when tests use `waitFor`, `act`, or `userEvent`". [Using fake timers](https://testing-library.com/docs/using-fake-timers) shows `beforeEach` as the usual setup, and names `advanceTimers` as the fix for the `userEvent` timeout, which the kept bullet carries.
+- Cut "scope fake timers to the individual test that needs them" with it, since no page read scopes them below the file.
+
+### Cut without a source or a bug class
+
+- Cut "`it()` descriptions use "should" + sentence case". The rule-standard audit flagged it as contested style naming no bug class.
+- Cut "`describe()` labels use the exact identifier of the subject" as naming style naming no failure.
+
+### Owned elsewhere
+
+- Cut "co-locate unit tests with their respective components". The `codebase-layout` skill's test reference places a unit test beside its module.
+- Cut "keep specs apart from their fixtures, page objects, and helpers inside `e2e/`", which the same reference owns.
+
+### Merged or reworded
+
+- Folded "place all Playwright tests within `e2e/`", "never place Playwright tests inside `src/`", and the scope bullet for a Vitest test driving a browser into one placement bullet.
+- Merged "do not make real network calls in unit tests" into the MSW bullet.
+- Merged the two suffix bullets into one.
+- Reworded "use `userEvent` over synthetic events" and the accessible-query bullet to name what each source says the choice prevents.

package/governance/ledger/lib/zod.md

@@ -0,0 +1,47 @@
+---
+title: Zod rule ledger
+description: Sources for governance/rules/lib/zod.md, one row per bullet
+---
+
+# Zod rule ledger
+
+The field is TypeScript runtime validation, and the authority is the Zod documentation at zod.dev with its changelog in the colinhacks/zod repository. The rule assumes Zod 4, since the methods it replaces stay available as legacy and a Zod 3 target keeps `z.strictObject()`.
+
+## Type inference
+
+| Bullet                       | Source                                                                                                                                                 | Read              |
+| ---------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------ | ----------------- |
+| `z.infer`, no twin interface | [Basic usage](https://zod.dev/basics): "Zod infers a static type from your schema definitions. You can extract this type with the `z.infer<>` utility" | 2026-10-18, Zod 4 |
+
+## Boundary validation
+
+| Bullet                                | Source                                                                                                                                                                                                                                       | Read              |
+| ------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ----------------- |
+| `z.strictObject()` on untrusted input | [Zod 4 changelog](https://raw.githubusercontent.com/colinhacks/zod/main/packages/docs/content/v4/changelog.mdx): "Instead use the top-level `z.strictObject()` and `z.looseObject()` functions", and the old methods "are considered legacy" | 2026-10-18, Zod 4 |
+| `.pick()` or `.omit()`, not loose     | [Defining schemas](https://zod.dev/api): "Zod provides dedicated APIs for picking and omitting certain keys from an object schema", and a loose schema "allows unknown keys to pass through"                                                 | 2026-10-18, Zod 4 |
+| `.parse()` or `.safeParse()`          | [Basic usage](https://zod.dev/basics): `.parse()` "will throw a `ZodError`", and `.safeParse()` returns "a plain result object containing either the successfully parsed data or a `ZodError`"                                               | 2026-10-18, Zod 4 |
+| `z.coerce` at string boundaries       | [Defining schemas](https://zod.dev/api): "The coerced variant of these schemas attempts to convert the input value to the appropriate type", applying `String(input)` for `z.coerce.string()`                                                | 2026-10-18, Zod 4 |
+
+## Schema safety
+
+| Bullet                       | Source                                                                                              | Read              |
+| ---------------------------- | --------------------------------------------------------------------------------------------------- | ----------------- |
+| `z.unknown()`, not `z.any()` | [Defining schemas](https://zod.dev/api): `z.any()` infers `any`, and `z.unknown()` infers `unknown` | 2026-10-18, Zod 4 |
+
+## Declined
+
+Every bullet the rewrite removed or reshaped, grouped by why.
+
+### Contradicted by the docs
+
+- Replaced "use `.strict()` for untrusted external API boundaries". The [Zod 4 changelog](https://raw.githubusercontent.com/colinhacks/zod/main/packages/docs/content/v4/changelog.mdx) marks `.strict()` legacy and names `z.strictObject()`.
+- Replaced "prefer `.strict()` at boundaries or explicit `.pick()`/`.omit()` over `.passthrough()`", which recommended the legacy method and read as a preference. The kept bullet names `z.looseObject()` beside it.
+
+### Cut without a source or a bug class
+
+- Cut "do not export the runtime Schema if only the inferred Type is required by consumers" as an export taste naming no failure.
+
+### Merged or reworded
+
+- Merged "do not manually declare interfaces that duplicate Zod schemas" into the `z.infer` bullet.
+- Narrowed "restrict `z.coerce` to I/O boundaries" to string input and named the conversion, which is why `z.coerce.boolean()` reads `"false"` as `true`.

package/governance/ledger/tooling/ci-workflow.md

@@ -0,0 +1,33 @@
+---
+title: CI workflow rule ledger
+description: Sources for governance/rules/tooling/ci-workflow.md, one row per bullet
+---
+
+# CI workflow rule ledger
+
+The field is continuous integration on GitHub Actions, and the authority is GitHub's own Actions documentation at docs.github.com. The rule is the second half of a pair with the `ci-workflow` skill, which owns triggers, pinning, job shape, and the top-level read-only default, so this ledger covers only what the rule itself states.
+
+## Authority
+
+| Bullet                  | Source                                                                                                                                         | Read       |
+| ----------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------- | ---------- |
+| Load the skill, routing | Routing only: it sends workflow authoring to the `canon:ci-workflow` skill, which carries the sourced directives, and claims no outside source | 2026-10-18 |
+
+## Commit-back
+
+| Bullet                                 | Source                                                                                                                                                                                                                                                                                                                                                                                              | Read       |
+| -------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ---------- |
+| Commit back only what the branch moved | House choice: a refresh an outside input moved, such as a font or a build-time count, lands a diff on a pull request whose change did not cause it, so the reviewer reads churn the author cannot explain                                                                                                                                                                                           | 2026-10-18 |
+| Deterministic output, diff check first | House choice: a step that regenerates differently on each run commits noise on every push, and a commit step with no diff check ahead of it pushes a capture that did not change                                                                                                                                                                                                                    | 2026-10-18 |
+| Skip a fork's pull request             | [Workflow syntax, permissions](https://docs.github.com/en/actions/reference/workflows-and-actions/workflow-syntax): "if the workflow was triggered by a pull request event other than `pull_request_target` from a forked repository, and the Send write tokens to workflows from pull requests setting is not selected, the permissions are adjusted to change any write permissions to read only" | 2026-10-18 |
+| Never commit back to the trunk         | House choice: a workflow pushing onto the trunk lands a change no pull request carried and no reviewer read                                                                                                                                                                                                                                                                                         | 2026-10-18 |
+
+## Token scopes
+
+| Bullet                      | Source                                                                                                                                                                                                                                                                                                                                       | Read       |
+| --------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ---------- |
+| Write scope on the job only | [Workflow syntax, permissions](https://docs.github.com/en/actions/reference/workflows-and-actions/workflow-syntax): "For a specific job, you can use `jobs.<job_id>.permissions` to modify the default permissions granted to the `GITHUB_TOKEN`, adding or removing access as required, so that you only allow the minimum required access" | 2026-10-18 |
+
+## Declined
+
+Nothing was cut. Every bullet already sat inside the shape limits, and the rule keeps its split with the skill, a pointer plus at most five directives.