@erclx/canon 5.44.0 → 5.45.0

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

@@ -26,10 +26,10 @@ A page a reader cannot sort by that question is a page whose subject has not bee
 
 ## Where the wiki sits
 
-The folder has two spellings and a project carries whichever its scaffold wrote:
+The folder has two spellings and a project carries whichever the project created:
 
-- `.claude/wiki/`, which is where the scaffolding verb creates one
-- A folder named `wiki` at the project root, which is where a project scaffolded before the move keeps its pages
+- `.claude/wiki/`, the folder inside the Claude setup
+- A folder named `wiki` at the project root
 
 Read which one exists rather than composing either. A project carrying both keeps its pages at the root, so propose the root spelling and say the other folder is there.
 
@@ -38,10 +38,10 @@ Read which one exists rather than composing either. A project carrying both keep
 A project carrying neither gets a refusal rather than a scaffold:
 
 ```plaintext
-❌ No wiki folder. Run canon wiki init to create one, then promote again.
+❌ No wiki folder. Create `.claude/wiki/` with an `index.md`, then promote again.
 ```
 
-Creating the folder as a side effect of promoting one page hands the project a surface it never chose, and the refusal is one command from resolved.
+Creating the folder as a side effect of promoting one page hands the project a surface it never chose, and the refusal is one step from resolved.
 
 ## What a promoted page owes its destination
 

package/docs/agents/install-and-sync.md

@@ -9,9 +9,9 @@ What each verb writes, refuses, and leaves alone. `canon --help` lists flags.
 
 ## Bootstrap
 
-`canon init [path]` installs up to five core domains and reports each independently. A failed domain does not abort the run, which finishes the rest and exits 1 naming the failures.
+`canon init [path]` installs up to four core domains and reports each independently. A failed domain does not abort the run, which finishes the rest and exits 1 naming the failures.
 
-Any flag skips the confirmation prompt, but the `base` default of `--stack` does not count, so a bare `canon init` still prompts. `--skip` takes `wiki`, `governance`, and `records`, and warns on any other value.
+Any flag skips the confirmation prompt, but the `base` default of `--stack` does not count, so a bare `canon init` still prompts. `--skip` takes `governance` and `records`, and warns on any other value.
 
 ## Governance install
 

package/docs/agents/output-shape.md

@@ -62,14 +62,13 @@ Discover names at runtime rather than hardcoding them.
 Set `CANON_NON_INTERACTIVE=1` to refuse every prompt.
 
 ```bash
-CANON_NON_INTERACTIVE=1 canon init --stack node --skip wiki /path/to/project
+CANON_NON_INTERACTIVE=1 canon init --stack node --skip records /path/to/project
 CANON_NON_INTERACTIVE=1 canon sync /path/to/project
 CANON_NON_INTERACTIVE=1 canon gov install node --add astro,shadcn /path/to/project
 CANON_NON_INTERACTIVE=1 canon gov sync /path/to/project
 CANON_NON_INTERACTIVE=1 canon gov build /path/to/project
 CANON_NON_INTERACTIVE=1 canon tooling diff astro /path/to/project
 CANON_NON_INTERACTIVE=1 canon tooling sync astro /path/to/project --write
-CANON_NON_INTERACTIVE=1 canon wiki init /path/to/project
 canon tooling inject base /path/to/project --configs --seeds
 canon tooling prune-gitignore base /path/to/project
 canon tooling verify vite-react

package/docs/target/migrations.md

@@ -160,3 +160,21 @@ canon migrate session-defaults --write --json
 ```
 
 The verb only adds a key that is absent. A person who wants auto memory back sets it in their own `.claude/settings.local.json`.
+
+## Move the capture cases out of the harness, once
+
+A web project's `e2e/screenshot.ts` is a config, so sync overwrites it. It now loads `CASES` from a seeded `e2e/capture/cases.ts` that sync copies once and never overwrites. Cases edited in the old harness leave the working tree on the first sync and stay in git history.
+
+- Copy your cases from the old `e2e/screenshot.ts` into `e2e/capture/cases.ts` before the next sync.
+- Evidence now defaults to `e2e/evidence/`. Set `export const EVIDENCE_ROOT = 'evidence'` in `e2e/capture/cases.ts` to keep a committed baseline at the old path.
+- A run from a folder with no `e2e/capture/cases.ts` exits 1 and names the file.
+
+## Add the keyboard rule beside a held a11y rule, once
+
+The `a11y` rule split in two. Focus styles, Escape and shortcuts, composite widgets, focus management, and pointer target size moved to a new `keyboard` rule. `canon gov sync` refreshes only the rules a project holds, so it rewrites `a11y.md` without those bullets and never adds `keyboard.md`.
+
+A project holding `.claude/rules/canon/ui/a11y.md` adds the new rule alone:
+
+```bash
+canon gov install --add keyboard --yes .
+```

package/docs/target/projects.md

@@ -70,10 +70,9 @@ The default is `base`. Escalate only for a project writing code, and `target-set
 
 ### Core domains and skips
 
-`canon init` installs base tooling, the Claude workflow, and governance, and scaffolds `.claude/wiki/`. Pass `--stack <name>` for a language stack.
+`canon init` installs base tooling, the Claude workflow, and governance. Pass `--stack <name>` for a language stack.
 
 - `--skip governance` leaves `.claude/rules/` empty. The run prints the `canon gov install <stack> <path>` command that restores the rules it dropped.
-- `--skip wiki` skips the `.claude/wiki/` scaffold. A root `wiki/` is kept.
 
 ## Add a domain later
 

package/docs/target/scenarios.md

@@ -42,4 +42,7 @@ canon tooling sync python ./backend --skip base --write
 
 `--skip base` keeps husky, oxfmt, commitlint, and CI at the root. Every subtree still receives `scripts/verify.ts` and `scripts/verify.json`, and its own framework configs.
 
-A sync into a subfolder withholds `.github/`, so run the subtree from the root workflow with `working-directory` set to the path the sync prints. It installs nothing into a subtree without a `package.json` and ends on `run 'bun init' in <path>, then sync again`. Run `bun scripts/verify.ts` in the subtree, since the `check` script lives at the root.
+A sync into a subfolder withholds `.github/`, so run the subtree from the root workflow with `working-directory` set to the path the sync prints. Run `bun scripts/verify.ts` in the subtree, since the `check` script lives at the root.
+
+- A subtree with no `package.json` gets a minimal one holding the folder's name, version `0.0.0`, and `type: module`, then the install runs into it
+- An existing file is never rewritten, and one that is not valid JSON ends the sync on `package.json is not valid JSON: fix it in <path>, then sync again`

package/docs/workflow/skill-map-on-request.md

@@ -40,4 +40,4 @@ These skills serve a request rather than a moment. With the [skill map](skill-ma
 | `canon:markdown-craft`      | Before a substantial markdown edit                    |
 | `canon:write-human`         | Before drafting or revising prose                     |
 
-Ask `canon:teach-workspace` to promote a learning workspace's reference pages and glossaries. It proposes a destination per page and waits. An Anthropic-owned subject goes to the wiki, an internal one to the matching context entry, and the rest to the public docs. A project with no wiki folder gets a refusal naming `canon wiki init`.
+Ask `canon:teach-workspace` to promote a learning workspace's reference pages and glossaries. It proposes a destination per page and waits. An Anthropic-owned subject goes to the wiki, an internal one to the matching context entry, and the rest to the public docs. A project with no wiki folder gets a refusal naming the folder to create.

package/governance/detect.toml

@@ -169,6 +169,10 @@ files = ["index.html", "*/index.html"]
 deps = ["react", "vue", "svelte", "astro", "next", "solid-js", "preact"]
 files = ["index.html", "*/index.html"]
 
+["keyboard"]
+deps = ["react", "vue", "svelte", "astro", "next", "solid-js", "preact"]
+files = ["index.html", "*/index.html"]
+
 ["forms"]
 deps = ["react", "vue", "svelte", "astro", "next", "solid-js", "preact"]
 files = ["index.html", "*/index.html"]

package/governance/ledger/lang/go.md

@@ -0,0 +1,61 @@
+---
+title: Go rule ledger
+description: Sources for governance/rules/lang/go.md, one row per bullet
+---
+
+# Go rule ledger
+
+The field is Go programming, and the authority is the Go project's own documentation at go.dev and pkg.go.dev, with the Code Review Comments wiki as the team's review guide. The package pages read name go1.27.2, and the wiki and layout pages name no release.
+
+## Errors
+
+| Bullet                       | Source                                                                                                                                                        | Read                 |
+| ---------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------- | -------------------- |
+| Wrap with `%w`               | [errors](https://pkg.go.dev/errors): "An easy way to create wrapped errors is to call fmt.Errorf and apply the %w verb to the error argument"                 | 2026-10-18, go1.27.2 |
+| Match with `Is` or `As`      | [errors](https://pkg.go.dev/errors): `Is` "should be used in preference to simple equality checks", since it walks the wrapped chain                          | 2026-10-18, go1.27.2 |
+| Never discard with `_`       | [Code Review Comments](https://go.dev/wiki/CodeReviewComments#handle-errors): "Do not discard errors using `_` variables"                                     | 2026-10-18           |
+| `panic` for broken invariant | [Code Review Comments](https://go.dev/wiki/CodeReviewComments#dont-panic): "Don't use panic for normal error handling. Use error and multiple return values." | 2026-10-18           |
+
+## Context
+
+| Bullet                   | Source                                                                                                                                                             | Read                 |
+| ------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------ | -------------------- |
+| First parameter, `ctx`   | [context](https://pkg.go.dev/context): "The Context should be the first parameter, typically named ctx"                                                            | 2026-10-18, go1.27.2 |
+| Never in a struct        | [context](https://pkg.go.dev/context): "Do not store Contexts inside a struct type", and "pass a Context explicitly to each function that needs it"                | 2026-10-18, go1.27.2 |
+| No `nil`, `context.TODO` | [context](https://pkg.go.dev/context): "Do not pass a nil Context, even if a function permits it. Pass context.TODO if you are unsure about which Context to use." | 2026-10-18, go1.27.2 |
+
+## Interfaces
+
+| Bullet                             | Source                                                                                                                                                                                                                                                                                  | Read       |
+| ---------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ---------- |
+| In the consumer, only its calls    | [Code Review Comments](https://go.dev/wiki/CodeReviewComments#interfaces): "Go interfaces generally belong in the package that uses values of the interface type", and [Effective Go](https://go.dev/doc/effective_go#interfaces): "Interfaces with only one or two methods are common" | 2026-10-18 |
+| Accept interfaces, return concrete | [Code Review Comments](https://go.dev/wiki/CodeReviewComments#interfaces): "The implementing package should return concrete (usually pointer or struct) types"                                                                                                                          | 2026-10-18 |
+
+## Packages
+
+| Bullet                       | Source                                                                                                                                                                                                               | Read       |
+| ---------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ---------- |
+| `internal/` for private code | [Organizing a Go module](https://go.dev/doc/modules/layout): `internal` "prevents other modules from depending on packages we don't necessarily want to expose", and "keep packages in internal as much as possible" | 2026-10-18 |
+| No side effects in `init`    | House choice: `init` runs on every import, tests included, in an order the reader cannot see from the call site, so a dependency it wires is hidden and cannot be swapped                                            | 2026-10-18 |
+| No mutable package state     | House choice: a package-level variable is shared by every caller and every parallel test, so one test's write leaks into another and a data race needs no visible goroutine                                          | 2026-10-18 |
+
+## Declined
+
+Every bullet the rewrite removed or reshaped, grouped by why.
+
+### A convention Claude follows unprompted
+
+The four casing bullets went under the plan's question 1, whose suggestion stood. `gofmt`, [Effective Go](https://go.dev/doc/effective_go#names), and Code Review Comments set each of them, and Claude writes them without the rule. The error-position bullet went on the same test.
+
+- Cut "`MixedCaps` for exported names, never underscores", which Effective Go states as "the convention in Go is to use MixedCaps or mixedCaps rather than underscores".
+- Cut "one short lowercase package name, not `util`, `common`, or `helpers`", which Effective Go and the wiki's "Avoid meaningless package names like util, common, misc" both state.
+- Cut "do not repeat the package name in an exported identifier", which Effective Go shows with `bufio.Reader` over `BufReader`.
+- Cut "keep initialisms in one case". No sampled session was run to test it, so the suggestion's condition for keeping it was never met.
+- Cut "return an error as the last result value", a convention every Go signature Claude writes already follows.
+
+### Merged or reworded
+
+- Merged "keep an interface to the methods its consumer calls" into the consumer-placement bullet, since both state where an interface's method set comes from.
+- Reworded the `errors.Is` bullet to ban `==` as well as string matching, since the package page sets `Is` against "simple equality checks".
+- Gave the discard ban the wiki's own alternative, to handle, return, or panic.
+- Gave the package-state ban an alternative, a struct the caller owns.

package/governance/ledger/lang/php.md

@@ -0,0 +1,50 @@
+---
+title: PHP rule ledger
+description: Sources for governance/rules/lang/php.md, one row per bullet
+---
+
+# PHP rule ledger
+
+The field is PHP programming, and the authority is the PHP manual at php.net, with the PHP Framework Interop Group's standards at php-fig.org for autoloading and file layout. The manual pages read belong to the PHP 8.5 manual.
+
+## Strictness
+
+| Bullet                      | Source                                                                                                                                                                                                                                             | Read                |
+| --------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------- |
+| `strict_types=1`            | [Type declarations](https://www.php.net/manual/en/language.types.declarations.php): "By default, PHP will coerce values of the wrong type into the expected scalar type declaration if possible", and strict mode is enabled "on a per-file basis" | 2026-10-18, PHP 8.5 |
+| Native types over docblocks | [Type declarations](https://www.php.net/manual/en/language.types.declarations.php): native declarations "ensure that the value is of the specified type at call time, otherwise a TypeError is thrown", which no docblock does                     | 2026-10-18, PHP 8.5 |
+| `===` over `==`             | [Comparison operators](https://www.php.net/manual/en/language.operators.comparison.php): `==` is "equal after type juggling", and the page's warning shows `"1" == "01"` and `100 == "1e2"` both true in PHP 8                                     | 2026-10-18, PHP 8.5 |
+
+## Layout
+
+| Bullet              | Source                                                                                                                                                                                                | Read       |
+| ------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ---------- |
+| PSR-4 autoloading   | [PSR-4](https://www.php-fig.org/psr/psr-4/): "This PSR describes a specification for autoloading classes from file paths", and "The terminating class name corresponds to a file name ending in .php" | 2026-10-18 |
+| One symbol per file | [PSR-1](https://www.php-fig.org/psr/psr-1/): "This means each class is in a file by itself, and is in a namespace of at least one level"                                                              | 2026-10-18 |
+
+## Data shapes
+
+| Bullet                         | Source                                                                                                                                                                                                                                                                                                                          | Read                |
+| ------------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------- |
+| `enum` for a closed set        | [Enumerations](https://www.php.net/manual/en/language.enumerations.overview.php): a type "limited to one of a discrete number of possible values", and [backed enums](https://www.php.net/manual/en/language.enumerations.backed.php) exist for a case that "needs to be able to round-trip to a database or similar datastore" | 2026-10-18, PHP 8.5 |
+| `readonly` value objects       | [Properties](https://www.php.net/manual/en/language.oop5.properties.php): `readonly` "prevents modification of the property after initialization", and [a readonly class](https://www.php.net/manual/en/language.oop5.basic.php) adds it "to every declared property"                                                           | 2026-10-18, PHP 8.5 |
+| `final` unless designed for it | House choice: a subclass nobody planned for couples to the parent's internals, so a refactor of the parent breaks code its author never saw                                                                                                                                                                                     | 2026-10-18          |
+| No associative array boundary  | House choice: a misspelled or missing array key reads as `null` with a warning rather than failing, and no native type declares an array's keys, so the shape drifts unchecked                                                                                                                                                  | 2026-10-18          |
+
+## Errors
+
+| Bullet                        | Source                                                                                                                                                                                                                                                                  | Read                |
+| ----------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------- |
+| Domain exception, not `false` | House choice: a caller that forgets to test a `false` or `null` return carries on with a bad value, and `0` and `false` look alike under the loose checks the strictness bullets ban                                                                                    | 2026-10-18          |
+| No `@`                        | House choice: [Error control](https://www.php.net/manual/en/language.operators.errorcontrol.php) says `@` suppresses "any diagnostic error that might be generated by that expression", so the failure leaves no trace for whoever debugs it                            | 2026-10-18, PHP 8.5 |
+| No `extract` or `eval`        | [eval](https://www.php.net/manual/en/function.eval.php): "very dangerous because it allows execution of arbitrary PHP code. Its use thus is discouraged.", and [extract](https://www.php.net/manual/en/function.extract.php) overwrites a colliding variable by default | 2026-10-18, PHP 8.5 |
+
+## Declined
+
+Every bullet stayed, so nothing was cut. Three were reshaped.
+
+### Merged or reworded
+
+- Reworded "a backed `enum` for a closed set" to an `enum`, backed only when stored or serialized. The manual gives a pure enum for a closed set and a backing value for a datastore round trip.
+- Gave the `@` ban an alternative, to check the condition first or catch the exception.
+- Gave the `extract`, variable variables, and `eval` ban an alternative, to name each variable and call each function directly.

package/governance/ledger/lang/python.md

@@ -0,0 +1,68 @@
+---
+title: Python rule ledger
+description: Sources for governance/rules/lang/python.md, one row per bullet
+---
+
+# Python rule ledger
+
+The field is Python programming, and the authority is the Python documentation at docs.python.org with the PEPs at peps.python.org. The library pages read are the Python 3.15 documentation.
+
+## Type hints
+
+| Bullet                                  | Source                                                                                                                                                                                                          | Read                    |
+| --------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ----------------------- |
+| Annotate public functions               | House choice: a gradual type checker treats an unannotated function as dynamically typed and leaves its body unchecked, so a public function with no hints hides its callers' mistakes                          | 2026-10-18              |
+| `X \| None` and built-in generics       | [typing](https://docs.python.org/3/library/typing.html): the `int \| str` shorthand "is recommended", `Optional[X]` "is equivalent to `X \| None`", and `typing.List` is a "Deprecated alias to list" since 3.9 | 2026-10-18, Python 3.15 |
+| No `from __future__ import annotations` | [`__future__`](https://docs.python.org/3/library/__future__.html): "This feature will eventually be deprecated and removed. See PEP 649 and PEP 749."                                                           | 2026-10-18, Python 3.15 |
+| `Protocol` over an ABC                  | [PEP 544](https://peps.python.org/pep-0544/): with an ABC "a class has to be explicitly marked to support them", and protocols provide "structural subtyping (static duck typing)"                              | 2026-10-18              |
+| `object` over `Any`                     | [typing](https://docs.python.org/3/library/typing.html#the-any-type): "Use object to indicate that a value could be any type in a typesafe manner. Use Any to indicate that a value is dynamically typed."      | 2026-10-18, Python 3.15 |
+
+## Errors
+
+| Bullet                   | Source                                                                                                                                                                                     | Read       |
+| ------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | ---------- |
+| Specific exception class | [PEP 8](https://peps.python.org/pep-0008/#programming-recommendations): "Design exception hierarchies based on the distinctions that code catching the exceptions is likely to need"       | 2026-10-18 |
+| Narrowest catch          | [PEP 8](https://peps.python.org/pep-0008/#programming-recommendations): "When catching exceptions, mention specific exceptions whenever possible instead of using a bare `except:` clause" | 2026-10-18 |
+| `raise ... from err`     | [PEP 8](https://peps.python.org/pep-0008/#programming-recommendations): "`raise X from Y` should be used to indicate explicit replacement without losing the original traceback"           | 2026-10-18 |
+
+## Data shapes
+
+| Bullet                    | Source                                                                                                                                                                                                                  | Read                    |
+| ------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ----------------------- |
+| Frozen, slotted dataclass | [dataclasses](https://docs.python.org/3/library/dataclasses.html): with `frozen`, "assigning to fields will generate an exception", and `slots` generates `__slots__`, added in 3.10                                    | 2026-10-18, Python 3.15 |
+| `Enum` for a closed set   | [enum](https://docs.python.org/3/library/enum.html): an enumeration "is a set of symbolic names (members) bound to unique values", and `StrEnum` members "are also strings", added in 3.11                              | 2026-10-18, Python 3.15 |
+| `pathlib` over `os.path`  | [pathlib](https://docs.python.org/3/library/pathlib.html): "`Path` is most likely what you need", and its normalization is "more opinionated and consistent than `os.path`", keeping `..` segments "for greater safety" | 2026-10-18, Python 3.15 |
+
+## Imports and modules
+
+| Bullet                | Source                                                                                                                                                                                                                                | Read                    |
+| --------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ----------------------- |
+| Absolute imports      | [PEP 8](https://peps.python.org/pep-0008/#imports): "Absolute imports are recommended, as they are usually more readable and tend to be better behaved"                                                                               | 2026-10-18              |
+| No shortening aliases | House choice: an internal name aliased at import no longer matches its definition, so a search for the name misses every call site behind the alias                                                                                   | 2026-10-18              |
+| `__main__` guard      | [`__main__`](https://docs.python.org/3/library/__main__.html): imported "to unit test it, the script code would unintentionally execute as well", and "Most often, a function named main encapsulates the program's primary behavior" | 2026-10-18, Python 3.15 |
+
+## Declined
+
+Every bullet the rewrite removed or reshaped, grouped by why.
+
+### Contradicted by the docs
+
+- Reworded the pydantic-only `__future__` caveat to a plain ban, since the docs say the feature "will eventually be deprecated and removed".
+- Reworded the ban on parent-relative imports to a preference for absolute ones. PEP 8 calls explicit relative imports "an acceptable alternative to absolute imports", so a ban overstated it.
+- Cut `typing.cast` as the alternative to `Any`, since the docs say it "returns the value unchanged" and checks nothing. The bullet now names `object`.
+
+### A convention Claude follows unprompted
+
+PEP 8's naming conventions set all four casing bullets, and Claude writes them without the rule.
+
+- Cut "`snake_case` for modules, functions, variables, and methods".
+- Cut "`PascalCase` for classes, type aliases, `TypeVar`, and `ParamSpec`".
+- Cut "`UPPER_SNAKE_CASE` for module-level constants and environment variables", which PEP 8 states as "written in all capital letters with underscores separating words".
+- Cut "`_leading_underscore` for module-private names, `__dunder__` for the protocol".
+
+### Merged or reworded
+
+- Merged the `X | None` bullet and the built-in generics bullet, since both replace a `typing` spelling with the native one.
+- Merged "raise specific built-in exceptions" and "define a project-rooted exception hierarchy" into one bullet naming both kinds a raise may take.
+- Narrowed "annotate all public functions, methods, and class attributes" to functions and methods, and gave it the unchecked-body reason.
+- Gave the `__main__` guard the docs' own shape, a `main` function the guard calls.

package/governance/ledger/lang/typescript.md

@@ -0,0 +1,64 @@
+---
+title: TypeScript rule ledger
+description: Sources for governance/rules/lang/typescript.md, one row per bullet
+---
+
+# TypeScript rule ledger
+
+The field is TypeScript programming, and the authority is the TypeScript documentation at typescriptlang.org, with MDN for the JavaScript runtime the language compiles to. The handbook names no release, so rows read the handbook as TypeScript 5.
+
+## File names
+
+| Bullet                 | Source                                                                                                                                                                         | Read       |
+| ---------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | ---------- |
+| `kebab-case` filenames | House choice: an import differing from its file only in case resolves on a case-insensitive filesystem such as macOS and fails on Linux CI, and one casing leaves no such pair | 2026-10-18 |
+
+## Type declarations
+
+| Bullet                             | Source                                                                                                                                                                                                      | Read                     |
+| ---------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------ |
+| `unknown` over `any`               | [More on Functions](https://www.typescriptlang.org/docs/handbook/2/functions.html): `unknown` "is similar to the `any` type, but is safer because it's not legal to do anything with an `unknown` value"    | 2026-10-18, TypeScript 5 |
+| `interface` until `type` is needed | [Everyday Types](https://www.typescriptlang.org/docs/handbook/2/everyday-types.html): "If you would like a heuristic, use `interface` until you need to use features from `type`."                          | 2026-10-18, TypeScript 5 |
+| `as const` over `enum`             | [Enums](https://www.typescriptlang.org/docs/handbook/enums.html): "you may not need an enum when an object with `as const` could suffice", which "keeps your codebase aligned with the state of JavaScript" | 2026-10-18, TypeScript 5 |
+
+## Type safety
+
+| Bullet                             | Source                                                                                                                                                                                                                                                                         | Read                     |
+| ---------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | ------------------------ |
+| Narrow over assert or `!`          | [Everyday Types](https://www.typescriptlang.org/docs/handbook/2/everyday-types.html): "there is no runtime checking associated with a type assertion", and the non-null `!` likewise "doesn't change the runtime behavior of your code"                                        | 2026-10-18, TypeScript 5 |
+| `Promise.all` for independent work | [Promise.all()](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Promise/all): sequential `await` makes the function "pause until the choice is made, and then again until the prices are fetched", and `Promise.all` runs "them concurrently" | 2026-10-18               |
+
+## Imports and configuration
+
+| Bullet                  | Source                                                                                                                                                                                                                                                                                                                 | Read                     |
+| ----------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------ |
+| `@/` alias where mapped | House choice: a `../../` chain breaks whenever the importing file moves. The condition comes from [Modules reference](https://www.typescriptlang.org/docs/handbook/modules/reference.html), where `paths` "does not change the import path in the code emitted", so an alias the bundler lacks "will crash at runtime" | 2026-10-18, TypeScript 5 |
+| No barrel re-exports    | House choice: importing through a barrel loads every module it re-exports, which slows tests and opens import cycles that surface as `undefined` at load time                                                                                                                                                          | 2026-10-18               |
+| `import type`           | [TypeScript 3.8](https://www.typescriptlang.org/docs/handbook/release-notes/typescript-3-8.html): `import type` "always gets fully erased, so there's no remnant of it at runtime"                                                                                                                                     | 2026-10-18, TypeScript 5 |
+| `strict: true`          | [TSConfig strict](https://www.typescriptlang.org/tsconfig/#strict): "The strict flag enables a wide range of type checking behavior that results in stronger guarantees of program correctness"                                                                                                                        | 2026-10-18, TypeScript 5 |
+
+## Declined
+
+Every bullet the rewrite removed or reshaped, grouped by why.
+
+### Cut without a source or a bug class
+
+- Cut "enforce explicit types or strict inference", which no reviewer can check against a line of code.
+- Cut "discriminated unions for error handling over throwing exceptions". No TypeScript page takes that side, and this repository's own CLI throws, so the bullet loaded against the code it governs.
+- Cut "built-in utility types over manual type manipulation". The utility types page describes them and sets them against nothing.
+- Cut "prefer `readonly` properties for data objects". The object types page describes `readonly` and takes no side on when to use it.
+
+### A convention Claude follows unprompted
+
+- Cut "`camelCase` for variables, functions, and methods".
+- Cut "`PascalCase` for types, interfaces, classes, and components".
+- Cut "`UPPER_SNAKE_CASE` for constants and environment variables".
+- Cut "do not prefix interfaces with `I`", a prefix Claude does not write without being asked.
+
+### Merged or reworded
+
+- Reworded the `interface` bullet to the handbook's heuristic, and merged "`type` for unions, intersections, and utility types" into it as the point where `type` takes over.
+- Merged "do not use non-null assertions" into the narrowing bullet, since the handbook groups `!` with the type assertion it is.
+- Reworded the `@/` bullet to apply only where both tsconfig.json and the bundler map the alias, under the plan's question 2, whose suggestion stood.
+- Moved the `kebab-case` filename bullet under a `File names` heading, since it was the one casing bullet kept, and gave it the case-sensitivity reason.
+- Gave the `unknown` bullet the narrowing step `unknown` requires before use.

package/governance/ledger/lib/database.md

@@ -0,0 +1,65 @@
+---
+title: Persistence rule ledger
+description: Sources for governance/rules/lib/database.md, one row per bullet
+---
+
+# Persistence rule ledger
+
+The field is database engineering, plus application security for query construction. The authorities are the migration and ORM documentation of Rails, Prisma, Django, and SQLAlchemy, the PostgreSQL manual, Martin Fowler's article on evolutionary database design, and the OWASP Cheat Sheet Series. Spike S1 of the rule-standard groundwork drafted this ledger, and its three unopened leads were read for it.
+
+## Schema changes
+
+| Bullet                           | Source                                                                                                                                                                                                                                                                                                                                                                                    | Read       |
+| -------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ---------- |
+| Every change is a migration      | [Evolutionary Database Design](https://martinfowler.com/articles/evodb.html): every change is "a database migration script which is version controlled together with application code changes"                                                                                                                                                                                            | 2026-10-18 |
+| A way back, down or forward      | [Rails migrations](https://guides.rubyonrails.org/active_record_migrations.html): "you can raise `ActiveRecord::IrreversibleMigration` in your `down` block", and [Prisma down migrations](https://www.prisma.io/docs/orm/prisma-migrate/workflows/generating-down-migrations) undoes an applied one with "you will instead need to revert your `schema.prisma` file" and a new migration | 2026-10-18 |
+| No change outside a migration    | [Evolutionary Database Design](https://martinfowler.com/articles/evodb.html): the authors never "run ad hoc DDL or DML", and "all changes are made by migrations"                                                                                                                                                                                                                         | 2026-10-18 |
+| Never edit a run migration       | [Rails migrations](https://guides.rubyonrails.org/active_record_migrations.html): "editing existing migrations that have been already committed to source control is not a good idea"                                                                                                                                                                                                     | 2026-10-18 |
+| Drop after reads and writes stop | [Expand and contract](https://www.prisma.io/dataguide/types/relational/expand-and-contract-pattern): "Once all clients have been updated to stop writing to the original schema, you can safely delete the original data structure"                                                                                                                                                       | 2026-10-18 |
+
+## Query construction
+
+| Bullet                    | Source                                                                                                                                                                                                                                                | Read       |
+| ------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ---------- |
+| Bind every runtime value  | [SQL Injection Prevention](https://cheatsheetseries.owasp.org/cheatsheets/SQL_Injection_Prevention_Cheat_Sheet.html): developers "should be told to use prepared statements with variable binding (aka parameterized queries)"                        | 2026-10-18 |
+| Never interpolate a value | [SQL Injection Prevention](https://cheatsheetseries.owasp.org/cheatsheets/SQL_Injection_Prevention_Cheat_Sheet.html): building the string by hand ranks last, as "STRONGLY DISCOURAGED: Escaping All User Supplied Input"                             | 2026-10-18 |
+| Allow-list identifiers    | [SQL Injection Prevention](https://cheatsheetseries.owasp.org/cheatsheets/SQL_Injection_Prevention_Cheat_Sheet.html): for "table names, column names, or sort order indicators", "input validation or query redesign is the most appropriate defense" | 2026-10-18 |
+
+## Transactions
+
+| Bullet                               | Source                                                                                                                                                                                                                                                                                                                                                       | Read       |
+| ------------------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | ---------- |
+| One owner per transaction            | [SQLAlchemy session basics](https://docs.sqlalchemy.org/en/20/orm/session_basics.html): "Keep the lifecycle of the session (and usually the transaction) separate and external"                                                                                                                                                                              | 2026-10-18 |
+| Savepoint, never commit a handed one | [Django transactions](https://docs.djangoproject.com/en/5.2/topics/db/transactions/): Django "creates a savepoint when entering an inner `atomic` block" and commits "when exiting the outermost block", and [PostgreSQL SAVEPOINT](https://www.postgresql.org/docs/current/sql-savepoint.html) "establishes a new savepoint within the current transaction" | 2026-10-18 |
+| Side effects after commit            | [Django transactions](https://docs.djangoproject.com/en/5.2/topics/db/transactions/): `on_commit()` callbacks run "after the open transaction is successfully committed", for "a background task, an email notification, or a cache invalidation"                                                                                                            | 2026-10-18 |
+
+## Access patterns
+
+| Bullet                      | Source                                                                                                                                                                                                                                                                                                                      | Read       |
+| --------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ---------- |
+| Load relations with parents | [Django optimization](https://docs.djangoproject.com/en/5.2/topics/db/optimization/): "Retrieve everything at once if you know you will need it", naming `select_related()` and `prefetch_related()`, and [Rails querying](https://guides.rubyonrails.org/active_record_querying.html) solves N + 1 queries with `includes` | 2026-10-18 |
+| Session per request         | [SQLAlchemy session basics](https://docs.sqlalchemy.org/en/20/orm/session_basics.html): "create a Session at the start of a web request" and "close the session at the end of web request"                                                                                                                                  | 2026-10-18 |
+
+## Declined
+
+Every bullet the rewrite removed or reshaped, grouped by why.
+
+### Contradicted by the docs
+
+- Cut "name the columns a read needs, never select every column by wildcard". The [Django optimization](https://docs.djangoproject.com/en/5.2/topics/db/optimization/) page says "Don't be too aggressive in deferring fields without profiling", and no page read backs the ban.
+- Narrowed "never open a transaction inside a function that was handed one". Django designs a nested `atomic` as a savepoint, so the bullet now bans committing the caller's transaction.
+- Reworded "ship a tested rollback path with every migration". Prisma has no down step and undoes a migration with a new one, which the old wording read as missing.
+
+### Merged or reworded
+
+- Reworded "separate a destructive migration from the deploy that stops reading the dropped column" to the order expand and contract states, removal after reads and writes stop.
+
+### Gaps filled
+
+- Added the allow-list bullet. OWASP names identifiers as the part of a query no bind reaches, the case a model gets wrong after it binds every value.
+
+### Leads read
+
+- Fowler's article backs the migration bullets but says nothing on editing an applied migration, so Rails carries that row.
+- The PostgreSQL `SAVEPOINT` page backs the savepoint wording beside Django's.
+- The Rails querying guide backs eager loading through `includes`.

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.