@erclx/canon 5.44.0 → 5.46.0

package/governance/ledger/lib/e2e-reliability.md

@@ -0,0 +1,57 @@
+---
+title: End-to-end reliability rule ledger
+description: Sources for governance/rules/lib/e2e-reliability.md, one row per bullet
+---
+
+# End-to-end reliability rule ledger
+
+The field is browser test automation. The authorities are the Playwright documentation at playwright.dev, MDN for the `scrollend` event, and the Chrome DevTools Protocol definition for CPU throttling. A guard bullet is a house choice wherever no page takes a side, and each such row names the false pass it prevents. None of the pages read names a Playwright major, so the rows record the read date alone.
+
+## Waiting
+
+| Bullet                         | Source                                                                                                                                                                                                                                                                                                         | Read       |
+| ------------------------------ | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ---------- |
+| Settle, never `waitForTimeout` | [Page API](https://playwright.dev/docs/api/class-page): `waitForTimeout` is "Discouraged", since "Tests that wait for time are inherently flaky", and [assertions](https://playwright.dev/docs/test-assertions): "You can convert any synchronous `expect` to an asynchronous polling one using `expect.poll`" | 2026-10-18 |
+| Fixed window for absence       | House choice: an absence has no signal to settle on, so a web-first assertion of it passes before the thing it rules out has had time to happen                                                                                                                                                                | 2026-10-18 |
+| Bound every settle             | [Assertions](https://playwright.dev/docs/test-assertions): "by default `toPass` has timeout 0 and does not respect custom" expect timeouts                                                                                                                                                                     | 2026-10-18 |
+| No raised timeout under load   | House choice: a longer timeout hides a race that the load exposed, and it returns on a slower runner                                                                                                                                                                                                           | 2026-10-18 |
+| `scrollend`, then stillness    | [MDN scrollend](https://developer.mozilla.org/en-US/docs/Web/API/Element/scrollend_event): "If the scroll position did not change, then no scrollend event fires"                                                                                                                                              | 2026-10-18 |
+| Reduced motion by default      | [Test options](https://playwright.dev/docs/api/class-testoptions): `reducedMotion` "Emulates `'prefers-reduced-motion'` media feature"                                                                                                                                                                         | 2026-10-18 |
+
+## Falsifiable guards
+
+| Bullet                   | Source                                                                                                                                   | Read       |
+| ------------------------ | ---------------------------------------------------------------------------------------------------------------------------------------- | ---------- |
+| Non-empty before every   | House choice: a property asserted over an empty set holds vacuously, so the guard passes on the page that lost every member              | 2026-10-18 |
+| Raise when refused       | House choice: an instrument returning a default on refusal hands the assertion a value it accepts, so the guard passes without measuring | 2026-10-18 |
+| See the guard fail first | House choice: a guard never run against its defect may pass on the defect too, and nothing tells the two apart                           | 2026-10-18 |
+| Never weaken to pass     | House choice: a loosened assertion passes on the defect it was written to catch, where a narrowed wait keeps the check                   | 2026-10-18 |
+
+## Reproducing a failure that only appears in CI
+
+| Bullet                      | Source                                                                                                                                                                                          | Read       |
+| --------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ---------- |
+| CPU throttling to reproduce | [DevTools Protocol, Emulation](https://chromedevtools.github.io/devtools-protocol/tot/Emulation/): `setCPUThrottlingRate` "Enables CPU throttling to emulate slow CPUs", as a "slowdown factor" | 2026-10-18 |
+| Read the trace              | [Best practices](https://playwright.dev/docs/best-practices): "For CI failures, use the Playwright trace viewer instead of videos and screenshots"                                              | 2026-10-18 |
+| Vary one condition          | House choice: two runs that differ in an uncontrolled condition cannot attribute a change in count to the one under suspicion                                                                   | 2026-10-18 |
+
+## Authority
+
+| Bullet                  | Source                                                                                              | Read       |
+| ----------------------- | --------------------------------------------------------------------------------------------------- | ---------- |
+| Pointer to `testing-ts` | House choice: a pointer to the rule that owns placement and naming, claiming no practice of its own | 2026-10-18 |
+
+## Declined
+
+Every bullet the rewrite removed or reshaped, grouped by why.
+
+### Cut from the subject
+
+- Cut "read the check conclusion as its own act, since a green diff review reports nothing about the gate". It governs reading CI after a push, which the ship and review skills own, and an end-to-end file is the wrong trigger for it.
+
+### Merged or reworded
+
+- Merged "do not read a value once after a pause, poll it" into the settle bullet, which now names `page.waitForTimeout` as the call it bans.
+- Reworded "bound every settle with an explicit timeout" to name `toPass`, the one settle the docs leave unbounded.
+- Reworded "run with motion reduced" to name the `reducedMotion` option.
+- Reworded "read the state the assertion does not" to read it from the trace, which the best practices page names for a CI failure.

package/governance/ledger/lib/pydantic.md

@@ -0,0 +1,61 @@
+---
+title: Pydantic rule ledger
+description: Sources for governance/rules/lib/pydantic.md, one row per bullet
+---
+
+# Pydantic rule ledger
+
+The field is Python data validation, and the authority is the Pydantic documentation at pydantic.dev, which moved from docs.pydantic.dev. Every page read is the Pydantic 2 docs, so a version-bound bullet opens with "On Pydantic 2" and a Pydantic 1 target is never told to call an API it lacks.
+
+## Models
+
+| Bullet                       | Source                                                                                                                                                                                       | Read                   |
+| ---------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ---------------------- |
+| `BaseModel` at boundaries    | House choice: a standard library `dataclass` checks no type at runtime, so malformed input passes the boundary unvalidated                                                                   | 2026-10-18, Pydantic 2 |
+| `model_config`, not `Config` | [Migration guide](https://pydantic.dev/docs/validation/latest/get-started/migration/): "to specify config on a model, you should set a class attribute called `model_config`"                | 2026-10-18, Pydantic 2 |
+| `extra="forbid"` on input    | [Models](https://pydantic.dev/docs/validation/latest/concepts/models/): "`'forbid'`: Providing extra data is not permitted", and "`'ignore'`: Providing extra data is ignored (the default)" | 2026-10-18, Pydantic 2 |
+| Constraints in `Field(...)`  | [Fields](https://pydantic.dev/docs/validation/latest/concepts/fields/): "The Field() function can also be used to add constraints to specific types"                                         | 2026-10-18, Pydantic 2 |
+
+## Validation
+
+| Bullet                                     | Source                                                                                                                                                                                     | Read                   |
+| ------------------------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | ---------------------- |
+| `model_validate` and `model_validate_json` | [Models](https://pydantic.dev/docs/validation/latest/concepts/models/): for a JSON payload, `model_validate_json()` "is generally considered faster" than parsing it to a dictionary first | 2026-10-18, Pydantic 2 |
+| v2 validator decorators                    | [Migration guide](https://pydantic.dev/docs/validation/latest/get-started/migration/): "`@validator` has been deprecated", and so has `@root_validator`, each replaced by its v2 decorator | 2026-10-18, Pydantic 2 |
+| Cross-field checks after                   | [Validators](https://pydantic.dev/docs/validation/latest/concepts/validators/): after model validators "run after the whole model has been validated"                                      | 2026-10-18, Pydantic 2 |
+
+## Types
+
+| Bullet                       | Source                                                                                                                                                                                           | Read                   |
+| ---------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | ---------------------- |
+| `SecretStr` for credentials  | [Pydantic Types](https://pydantic.dev/docs/validation/latest/api/pydantic/types/): "A string used for storing sensitive information that you do not want to be visible in logging or tracebacks" | 2026-10-18, Pydantic 2 |
+| Constrained types over regex | [Pydantic Types](https://pydantic.dev/docs/validation/latest/api/pydantic/types/): `PositiveInt` is "An integer that must be greater than zero"                                                  | 2026-10-18, Pydantic 2 |
+| `Annotated` for reuse        | [Fields](https://pydantic.dev/docs/validation/latest/concepts/fields/): Pydantic "supports the Annotated typing construct", and "Types can be made reusable"                                     | 2026-10-18, Pydantic 2 |
+| No `Any` fields              | [Standard Library Types](https://pydantic.dev/docs/validation/latest/api/standard_library_types/): `Any` "Allows any value, including `None`"                                                    | 2026-10-18, Pydantic 2 |
+
+## Settings
+
+| Bullet                   | Source                                                                                                                                                                                                                    | Read                   |
+| ------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ---------------------- |
+| One `BaseSettings` model | [Settings Management](https://pydantic.dev/docs/validation/latest/concepts/pydantic_settings/): the initializer "will attempt to determine the values of any fields not passed as keyword arguments" from the environment | 2026-10-18, Pydantic 2 |
+
+## Serialization
+
+| Bullet                    | Source                                                                                                                                                                                                                                                                                                               | Read                   |
+| ------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ---------------------- |
+| `model_dump(mode="json")` | [Serialization](https://pydantic.dev/docs/validation/latest/concepts/serialization/): "The `mode` argument can be set to `'json'` to ensure JSON-compatible types are used", and the [migration guide](https://pydantic.dev/docs/validation/latest/get-started/migration/) says "The `.json()` method is deprecated" | 2026-10-18, Pydantic 2 |
+| `by_alias=True` outward   | [Fields](https://pydantic.dev/docs/validation/latest/concepts/fields/): "the by_alias keyword argument defaults to False, and must be specified explicitly"                                                                                                                                                          | 2026-10-18, Pydantic 2 |
+
+## Declined
+
+Every bullet the rewrite removed or reshaped, grouped by why.
+
+### Merged or reworded
+
+- Merged "use `@field_validator` over the legacy `@validator`" with the `@root_validator` swap, which the old rule never named.
+- Merged "use `model.model_dump_json()` over `json.dumps(model.dict())`" into the serialization bullet beside `model_dump(mode="json")`.
+- Merged "use `Model.model_validate_json(s)` over `json.loads`" into the `model_validate` bullet. `Model(**data)` validates too, so the old contrast named no bug.
+- Merged "use `pydantic_settings.BaseSettings` for env-driven configuration" into the one-model bullet.
+- Narrowed "use `AnyUrl`, `EmailStr`, `SecretStr`, and `PositiveInt` over hand-rolled regex" into a `SecretStr` bullet for the log leak and a constrained-type bullet.
+- Prefixed every legacy-API swap with "On Pydantic 2", since the rule loads on every Python file and a Pydantic 1 target lacks the v2 names.
+- Reworded "use `Field(...)` over docstring conventions" to name the enforcement a docstring lacks.

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.