@erclx/canon 5.44.0 → 5.46.0

package/docs/agents/context-audit.md

@@ -22,18 +22,25 @@ canon context audit tooling/base/seeds --gate
 
 ## Output
 
-| Check               | Reports                                                                                                                                          | Reaches                 | Finding                                                     |
-| ------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------ | ----------------------- | ----------------------------------------------------------- |
-| Citations           | A path into an audited folder that resolves nowhere                                                                                              | Every audited folder    | Gates always                                                |
-| Requirements record | Words past the cap the record states as `This record holds at most 600 words.`                                                                   | `canon/REQUIREMENTS.md` | Gates past a stated cap, never under `--citations-only`     |
-| Required sections   | An entry missing `Overview` or `Layout`. A split folder answers by any sibling                                                                   | `canon/context/`        | Gates under `--gate`                                        |
-| Closed set          | An H2 outside `Overview`, `Layout`, and `Gotchas`, under `extraSections`                                                                         | `canon/context/`        | Gates under `--gate`                                        |
-| Shape               | `retired-section`, `gotcha-count`, `gotcha-heading`, `gotcha-paragraph`, `layout-heading`, `layout-bullets`, `layout-paragraphs`, `layout-depth` | `canon/context/`        | Gates under `--gate` in a `SHAPE_GATED_FOLDERS` folder only |
-| Index drift         | An entry its index does not link, or a link resolving to nothing                                                                                 | Every audited folder    | Gates under `--gate`                                        |
-| Reference form      | A backticked bare filename matching a sibling entry, under `bareReferences`                                                                      | Split folders           | Reports                                                     |
-| Length              | An entry past about 150 rendered lines at 80 columns, with its `causes`                                                                          | Every audited folder    | Reports                                                     |
-| Tables              | Six or more body rows whose first column mostly carries a path, command, or link                                                                 | Every audited folder    | Reports                                                     |
-| Provenance          | A date, change number, or release label. A date after measured, verified, driven, passed, or fired is excluded                                   | `canon/context/`        | Reports                                                     |
+| Check               | Reports                                                                                                                                               | Reaches                 | Finding                                                     |
+| ------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------- | ----------------------- | ----------------------------------------------------------- |
+| Citations           | A path into an audited folder that resolves nowhere                                                                                                   | Every audited folder    | Gates always                                                |
+| Requirements record | Words past the cap the record states as `This record holds at most 600 words.`                                                                        | `canon/REQUIREMENTS.md` | Gates past a stated cap, never under `--citations-only`     |
+| Required sections   | An entry missing `Overview` or `Layout`. A split folder answers by any sibling                                                                        | `canon/context/`        | Gates under `--gate`                                        |
+| Closed set          | An H2 outside `Overview`, `Layout`, and `Gotchas`, under `extraSections`                                                                              | `canon/context/`        | Gates under `--gate`                                        |
+| Shape               | `retired-section`, `gotcha-count`, `gotcha-heading`, `gotcha-paragraph`, `layout-heading`, `layout-bullets`, `layout-paragraphs`, `layout-depth`      | `canon/context/`        | Gates under `--gate` in a `SHAPE_GATED_FOLDERS` folder only |
+| Index drift         | An entry its index does not link, or a link resolving to nothing                                                                                      | Every audited folder    | Gates under `--gate`                                        |
+| Coverage            | A folder directly under a code root that no Layout names, one with a Layout H3 in two entries, and a declared root matching nothing, under `coverage` | `canon/context/`        | Gates under `--gate`, never under `--citations-only`        |
+| Reference form      | A backticked bare filename matching a sibling entry, under `bareReferences`                                                                           | Split folders           | Reports                                                     |
+| Length              | An entry past about 150 rendered lines at 80 columns, with its `causes`                                                                               | Every audited folder    | Reports                                                     |
+| Tables              | Six or more body rows whose first column mostly carries a path, command, or link                                                                      | Every audited folder    | Reports                                                     |
+| Provenance          | A date, change number, or release label. A date after measured, verified, driven, passed, or fired is excluded                                        | `canon/context/`        | Reports                                                     |
+
+The coverage roots come from `roots` in `canon/config/context.toml`, a list of folders or globs such as `packages/*/src`.
+
+- Without the file the root defaults to `src` when that folder exists, and `roots = []` opts out
+- A file that is not valid TOML, or holds no list of strings under `roots`, gates under `--gate`
+- With no declaration and no `src/`, the audit reports no code root and never gates
 
 A shape break is any of these:
 

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/markdown-audit.md

@@ -22,14 +22,14 @@ An argument is a file, a directory, or a glob, taken against the corpus git list
 
 The ban set and checkpoints ship in `src/markdown/bans.ts` and `src/markdown/structure.ts`. `markdown.md` states each rule and the `write-human` skill states the cadence numbers, so move a number in both places in one change.
 
-| Finding         | Reports                                                                              | Gates                     |
-| --------------- | ------------------------------------------------------------------------------------ | ------------------------- |
-| Bans            | The two characters `markdown.md` bans, outside frontmatter, fences, spans, and links | Always                    |
-| Links           | A relative link resolving to nothing on disk                                         | Always                    |
-| Density         | The six limits below, under `density`                                                | On a `GATED_PATHS` prefix |
-| Reference shape | A `kind: reference` page breaking its shape, under `referenceShape`                  | On a `GATED_PATHS` prefix |
-| Colons          | A colon followed by more text in a prose line, under `colons`                        | Never                     |
-| Heading case    | A capital after the first word of a heading or `title`, under `headingCase`          | Never                     |
+| Finding         | Reports                                                                              | Gates             |
+| --------------- | ------------------------------------------------------------------------------------ | ----------------- |
+| Bans            | The two characters `markdown.md` bans, outside frontmatter, fences, spans, and links | Always            |
+| Links           | A relative link resolving to nothing on disk                                         | Always            |
+| Density         | The six limits below, under `density`                                                | On a gated prefix |
+| Reference shape | A `kind: reference` page breaking its shape, under `referenceShape`                  | On a gated prefix |
+| Colons          | A colon followed by more text in a prose line, under `colons`                        | Never             |
+| Heading case    | A capital after the first word of a heading or `title`, under `headingCase`          | Never             |
 
 A page marked `kind: reference` holds its opening, then `Output`, `Refusals`, and `See also` as H2s, each at most once and in that order. It takes no H3 and no table headed `Flag` or `Option`. An unmarked page is never measured.
 
@@ -46,9 +46,14 @@ A page marked `kind: reference` holds its opening, then `Output`, `Refusals`, an
 - A table, fence, list, heading, or bold section marker ends a run of paragraphs
 - A run whose every item opens with a bold label or a link is exempt, and numbered items never count
 - Only context entries, docs, skill bodies, references, and requirements, tooling seeds and stack references, the wiki, `README.md`, and `CONTRIBUTING.md` take a finding
-- A bullet run gates on those paths, and the rest gates under `GATED_PATHS` in `src/markdown/scope.ts`. Outside a canon checkout nothing gates.
+- A requirement gates only once the gated list below names its own file, never through its skill's prefix and never on a bullet run alone
 
-A requirement is the one exception to both. It gates only once `GATED_PATHS` names its own file, never through its skill's prefix and never on a bullet run alone.
+| Root              | A density or reference shape finding gates                                                                 |
+| ----------------- | ---------------------------------------------------------------------------------------------------------- |
+| Canon's checkout  | Under a `GATED_PATHS` prefix in `src/markdown/scope.ts`, and a bullet run on every density path above      |
+| Any other project | Under a prefix `canon/config/markdown.toml` lists, a bullet run included. With no such file nothing gates. |
+
+A project's list grows through `canon markdown gated add <prefix>`, which appends a folder only once it carries no finding, and `canon init` starts a new project with every root that passes already listed. A config that does not parse refuses the audit with its path named.
 
 Five measures report and never set the exit code on their own.
 

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,11 @@ 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.
+
+Init then lists each markdown root that already passes the density limits in `canon/config/markdown.toml`, so those folders fail a push from the start. A root carrying a finding is named and left out, and `canon:document-repair` brings it to zero later. An existing config is kept as it is.
 
 - `--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/docs/workflow/skill-map.md

@@ -99,8 +99,9 @@ Groups run in the order a project meets them. Every name `canon claude skills li
 
 ## Keep the project current with the toolkit
 
-| Skill                         | When to use                                          |
-| ----------------------------- | ---------------------------------------------------- |
-| `canon:target-check`          | In a target, to compare each domain with the toolkit |
-| `canon:canon-feedback`        | The toolkit is broken, missing, or off               |
-| `canon:canon-feedback-triage` | In the toolkit repo, to file feedback issues         |
+| Skill                         | When to use                                             |
+| ----------------------------- | ------------------------------------------------------- |
+| `canon:target-check`          | In a target, to compare each domain with the toolkit    |
+| `canon:document-repair`       | Rewrite a failing docs folder to the limits and gate it |
+| `canon:canon-feedback`        | The toolkit is broken, missing, or off                  |
+| `canon:canon-feedback-triage` | In the toolkit repo, to file feedback issues            |

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`.