@erclx/canon 5.44.0 → 5.46.0

package/governance/ledger/ui/keyboard.md

@@ -0,0 +1,68 @@
+---
+title: Keyboard rule ledger
+description: Sources for governance/rules/ui/keyboard.md, one row per bullet
+---
+
+# Keyboard rule ledger
+
+The field is web accessibility, and the authorities are the W3C, through WCAG 2.2 and the ARIA Authoring Practices Guide, MDN for CSS behavior, and the platform guidelines from Apple and Android for native targets. Every bullet here was split from `a11y.md`.
+
+## Focus styles
+
+| Bullet                                   | Source                                                                                                                                                                                                                                    | Read                 |
+| ---------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -------------------- |
+| One project focus ring                   | House choice: per-component focus styles drift apart, and `canon inventory` reports the ring by computed style, so a one-off treatment shows as its own row                                                                               | 2026-10-18           |
+| No outline removal without a replacement | [outline](https://developer.mozilla.org/en-US/docs/Web/CSS/outline): "Assigning outline a value of 0 or none will remove the browser's default focus style. If an element can be interacted with it must have a visible focus indicator." | 2026-10-18           |
+| 3:1 ring in every theme                  | [Understanding Non-text Contrast](https://www.w3.org/WAI/WCAG22/Understanding/non-text-contrast.html): visual information needed to identify a state needs "a contrast ratio of at least 3:1 against adjacent color(s)"                   | 2026-10-18, WCAG 2.2 |
+
+## Keyboard operation
+
+| Bullet                         | Source                                                                                                                                                                                                                               | Read                 |
+| ------------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | -------------------- |
+| Escape closes                  | [Dialog (modal) pattern](https://www.w3.org/WAI/ARIA/apg/patterns/dialog-modal/): "Escape : Closes the dialog", and the [combobox pattern](https://www.w3.org/WAI/ARIA/apg/patterns/combobox/) gives Escape the same job for a popup | 2026-10-18, APG      |
+| No bare character shortcut     | [Understanding Character Key Shortcuts](https://www.w3.org/WAI/WCAG22/Understanding/character-key-shortcuts.html): a character-only shortcut needs a way to "Turn off", to "Remap", or to be "Active only on focus"                  | 2026-10-18, WCAG 2.2 |
+| Drag has a single-pointer path | [Understanding Dragging Movements](https://www.w3.org/WAI/WCAG22/Understanding/dragging-movements.html): "For any action that involves dragging, provide a simple pointer alternative"                                               | 2026-10-18, WCAG 2.2 |
+
+## Composite widgets
+
+| Bullet                       | Source                                                                                                                                                                                                                                                             | Read            |
+| ---------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | --------------- |
+| One item in the tab sequence | [Developing a keyboard interface](https://www.w3.org/WAI/ARIA/apg/practices/keyboard-interface/): "the tab sequence should include only one focusable element of a composite UI component", managed by "a roving tabindex" or "the aria-activedescendant property" | 2026-10-18, APG |
+| Combobox keys                | [Combobox pattern](https://www.w3.org/WAI/ARIA/apg/patterns/combobox/): "Down Arrow : If the popup is available, moves focus into the popup", Enter accepts the focused option, and "Escape : Dismisses the popup if it is visible"                                | 2026-10-18, APG |
+
+## Focus management
+
+| Bullet                       | Source                                                                                                                                                                                                                                 | Read                 |
+| ---------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -------------------- |
+| Focus into a dialog and back | [Dialog (modal) pattern](https://www.w3.org/WAI/ARIA/apg/patterns/dialog-modal/): "When a dialog opens, focus moves to an element inside the dialog", and "When a dialog closes, focus returns to the element that invoked the dialog" | 2026-10-18, APG      |
+| Focus never covered          | [Understanding Focus Not Obscured (Minimum)](https://www.w3.org/WAI/WCAG22/Understanding/focus-not-obscured-minimum.html): "the component is not entirely hidden due to author-created content"                                        | 2026-10-18, WCAG 2.2 |
+
+## Pointer targets
+
+| Bullet              | Source                                                                                                                                                                                                                                                                                                                              | Read                 |
+| ------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -------------------- |
+| 24 by 24 on the web | [Understanding Target Size (Minimum)](https://www.w3.org/WAI/WCAG22/Understanding/target-size-minimum.html): "at least 24 by 24 CSS pixels", except where "a 24 CSS pixel diameter circle is centered on the bounding box of each" and "the circles do not intersect"                                                               | 2026-10-18, WCAG 2.2 |
+| Native figures      | [Apple accessibility guidelines](https://developer.apple.com/design/human-interface-guidelines/accessibility): a default "44x44 pt" control size on iOS and iPadOS, and [Android accessibility](https://developer.android.com/guide/topics/ui/accessibility/apps): "a focusable area, or touch target size , of at least 48dpx48dp" | 2026-10-18           |
+
+## Declined
+
+Every bullet the split removed or reshaped, grouped by why.
+
+### Browser defaults
+
+- Cut the Tab, Enter, and Space bullets of the old keyboard model. A native element does each by default, and `a11y.md` already sends a session to the native element.
+
+### Rewritten to what the source says
+
+- Replaced "do not introduce non-standard key bindings" with the character key bullet. No reviewer can check "non-standard", and the criterion names the binding that breaks.
+- Narrowed "move focus into any overlay, popover, or dialog on open" to a dialog. The APG moves focus into a modal dialog, and a non-modal popover such as a tooltip leaves focus on its trigger.
+
+### Cut without a source or a bug class
+
+- Cut "never move focus on hover", a convention Claude already follows that no cited page takes a side on.
+
+### Merged or reworded
+
+- Merged "arrow keys navigate within composite widgets" into the roving `tabindex` bullet, which names the arrow keys.
+- Merged "Escape cancels in-progress edits" into the Escape bullet, and took in the inline confirmation case from the `ux-completeness.md` rewrite so the Escape behavior has one copy.
+- Reworded the combobox bullet to the pattern's own keys, dropping "typing filters", which the APG leaves to each autocomplete behavior.

package/governance/ledger/ui/link-behavior.md

@@ -0,0 +1,29 @@
+---
+title: Link behavior rule ledger
+description: Sources for governance/rules/ui/link-behavior.md, one row per bullet
+---
+
+# Link behavior rule ledger
+
+The field is interaction design, and the authority is the Nielsen Norman Group's research on new windows and tabs.
+
+## Default target
+
+| Bullet                      | Source                                                                                                                                                                                                                                                                                           | Read       |
+| --------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | ---------- |
+| Same tab, new tab by task   | [Opening links in new browser windows and tabs](https://www.nngroup.com/articles/new-browser-windows-and-tabs/): "There is generally one good reason to open a page in a new window, and that is that the user will need to refer to that content in order to complete a task in another window" | 2026-10-18 |
+| No blanket external new tab | [Opening links in new browser windows and tabs](https://www.nngroup.com/articles/new-browser-windows-and-tabs/): "New windows or tabs prevent the use of the Back button" and "can cause disorientation"                                                                                         | 2026-10-18 |
+
+## mailto: links
+
+| Bullet             | Source                                                                                                                                       | Read       |
+| ------------------ | -------------------------------------------------------------------------------------------------------------------------------------------- | ---------- |
+| `mailto:` same tab | House choice: the link opens the mail client and leaves the page in place, so `target="_blank"` only adds an empty tab the person must close | 2026-10-18 |
+
+## Declined
+
+Every bullet the rewrite removed or reshaped, grouped by why.
+
+### Rewritten to what the source says
+
+- Reworded the new tab exception from "a destination that would discard in-progress work" to a page the person must consult while finishing a task, the one reason NN/g names.

package/governance/ledger/ui/motion.md

@@ -0,0 +1,33 @@
+---
+title: Motion rule ledger
+description: Sources for governance/rules/ui/motion.md, one row per bullet
+---
+
+# Motion rule ledger
+
+The field is web accessibility, and the authorities are the W3C, through WCAG 2.2 and the ARIA Authoring Practices Guide, and MDN for the media feature.
+
+## Moving content
+
+| Bullet                          | Source                                                                                                                                                                                                                                                                          | Read                 |
+| ------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -------------------- |
+| Pause past five seconds         | [Understanding Pause, Stop, Hide](https://www.w3.org/WAI/WCAG22/Understanding/pause-stop-hide.html): moving information that "starts automatically", "lasts more than five seconds", and sits beside other content needs "a mechanism for the user to pause , stop, or hide it" | 2026-10-18, WCAG 2.2 |
+| Halt rotation on focus or hover | [Carousel pattern](https://www.w3.org/WAI/ARIA/apg/patterns/carousel/): a rotating carousel "Stops rotating when keyboard focus enters the carousel" and "whenever the mouse is hovering over the carousel"                                                                     | 2026-10-18, APG      |
+| Three flashes                   | [Understanding Three Flashes or Below Threshold](https://www.w3.org/WAI/WCAG22/Understanding/three-flashes-or-below-threshold.html): pages "do not contain anything that flashes more than three times in any one second period"                                                | 2026-10-18, WCAG 2.2 |
+
+## Reduced motion
+
+| Bullet                           | Source                                                                                                                                                                                                                                                         | Read                 |
+| -------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -------------------- |
+| Honor the preference             | [prefers-reduced-motion](https://developer.mozilla.org/en-US/docs/Web/CSS/@media/prefers-reduced-motion): it detects a setting "to minimize the amount of non-essential motion", for an interface "that removes, reduces, or replaces motion-based animations" | 2026-10-18           |
+| Essential changes stay visible   | [Understanding Animation from Interactions](https://www.w3.org/WAI/WCAG22/Understanding/animation-from-interactions.html): motion can be disabled "unless the animation is essential to the functionality or the information being conveyed"                   | 2026-10-18, WCAG 2.2 |
+| No autoplay under the preference | [prefers-reduced-motion](https://developer.mozilla.org/en-US/docs/Web/CSS/@media/prefers-reduced-motion): the setting asks the browser for an interface that "removes, reduces, or replaces motion-based animations", and a self-starting video is one         | 2026-10-18           |
+
+## Declined
+
+Every bullet the rewrite removed or reshaped, grouped by why.
+
+### Merged or reworded
+
+- Added the criterion number to the three flashes bullet, so every WCAG bullet in the rule names the criterion it rests on.
+- Reworded "do not" bans to "never" and "start no" forms, with no change of meaning.

package/governance/ledger/ui/surface-capture.md

@@ -0,0 +1,69 @@
+---
+title: Surface capture rule ledger
+description: Sources for governance/rules/ui/surface-capture.md, one row per bullet
+---
+
+# Surface capture rule ledger
+
+The rule states canon's own evidence procedure for a rendered change, so most rows are house choices naming the bug the bullet prevents. The 320 floor rests on WCAG 2.2, and each explanation the old rule carried moved into a row here.
+
+## What a surface is
+
+| Bullet                         | Source                                                                                                                                    | Read       |
+| ------------------------------ | ----------------------------------------------------------------------------------------------------------------------------------------- | ---------- |
+| Generated pages are surfaces   | House choice: reading a generated page's markup reports nothing about how it composes, so a page nobody captured ships its layout unseen  | 2026-10-18 |
+| Skip build-stripped components | House choice: the production build removes a dev-only switcher before anything renders, so a capture of it compares nothing a person sees | 2026-10-18 |
+
+## When to capture
+
+| Bullet                  | Source                                                                                                                                                           | Read       |
+| ----------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------- | ---------- |
+| Preview, not dev server | House choice: a dev server injects overlays and skips the production build's transforms, so its frame differs from what ships                                    | 2026-10-18 |
+| Every theme, and again  | House choice: a defect in the dark theme passes a light-only capture, and a repair inside a shared stylesheet can cancel a rule written earlier in the same file | 2026-10-18 |
+
+## What a capture covers
+
+| Bullet                      | Source                                                                                                                                                                                                                                        | Read                 |
+| --------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -------------------- |
+| Full page                   | House choice: a component captured alone shows none of the spacing, overflow, or stacking its page imposes on it                                                                                                                              | 2026-10-18           |
+| 320 plus breakpoints        | [Understanding Reflow](https://www.w3.org/WAI/WCAG22/Understanding/reflow.html): the criterion tests "a width equivalent to 320 CSS pixels". A 320 frame proves a frame was taken there, never that the page reflows, which `a11y.md` states. | 2026-10-18, WCAG 2.2 |
+| Chrome at both clamps       | House choice: a sidebar widened to its clamp leaves the content under the floor at a window width the criterion passes, and a frame where the chrome turned into an overlay shows none of the width it takes                                  | 2026-10-18           |
+| State case at one width     | House choice: a case driving a menu open tests the state, and repeating it at every layout width multiplies the evidence with no layout to compare                                                                                            | 2026-10-18           |
+| Drive unreachable states    | House choice: an initial render reports nothing about a menu that opens, an answer that is chosen, or a rail that tracks scrolling                                                                                                            | 2026-10-18           |
+| Case lives with the surface | House choice: a surface with no case ships uncaptured, and a case left after its surface goes fails every later capture run                                                                                                                   | 2026-10-18           |
+
+## Sharing a capture
+
+| Bullet                    | Source                                                                                                                                                                                                        | Read       |
+| ------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ---------- |
+| An `evidence` folder      | House choice: the pull request comment collects an image only when a path segment is literally `evidence`, so any other name drops the capture. Several such folders, one per surface, is the ordinary shape. | 2026-10-18 |
+| Commit flagged cases only | House choice: recommitting an unbounded sweep on every run reaches a gigabyte of history inside a hundred merges, while a small committed set lets GitHub draw its own before and after comparison            | 2026-10-18 |
+| Byte-identical twice      | House choice: a case whose output varies between runs shows a diff on every pull request, so the comparison stops meaning a change                                                                            | 2026-10-18 |
+| Mask the moving value     | House choice: an elapsed-time counter or a relative date differs on every run, and masking the smallest element keeps the check running on the rest of the frame                                              | 2026-10-18 |
+| Name the variance         | House choice: a value whose width reflows its neighbors survives the mask, and re-running until two frames match hides the variance rather than removing it                                                   | 2026-10-18 |
+
+## Declined
+
+Every bullet the rewrite removed or reshaped, grouped by why.
+
+### Moved into a row as the reason
+
+- Moved "judge a generated page by the same rule as a route, since reading its markup reports nothing" into the generated pages row.
+- Moved "read a capture at 320 as proof that a frame was taken there, not that the page reflows" into the 320 row.
+- Moved "several `evidence/` folders in one project is the ordinary shape" into the folder row.
+- Moved "recommitting an unbounded sweep reaches a gigabyte of repository history" into the commit row.
+- Moved "do not commit the state as evidence when the masked outputs still differ" into the variance bullet and its row.
+
+### Cut as stated elsewhere
+
+- Cut "`git-pr` and `git-followup` maintain a comparison comment automatically", which those skills own and which directs nothing at the edit.
+- Cut "fall back to the 320 floor alone when the project has no `DESIGN.md`", merged into the 320 bullet's "or at 320 alone".
+- Cut "read those bounds from the code that clamps the chrome", merged into the chrome bullet's "clamp".
+- Cut "do not impose another project's breakpoints", which the bullet reading `## Layout` already prevents.
+
+### Merged or reworded
+
+- Merged "run the capture command", "against a running preview", "every theme", and "capture again" into two bullets.
+- Merged "do not commit the sweep" with "commit a flagged case's evidence" and the established convention exception.
+- Merged "add a case" and "remove a surface's case" into one bullet.
+- Shortened every bullet past 200 characters, cutting the rule from 27 bullets and 840 words to 15 and under 300.

package/governance/ledger/ui/ux-completeness.md

@@ -0,0 +1,79 @@
+---
+title: UX completeness rule ledger
+description: Sources for governance/rules/ui/ux-completeness.md, one row per bullet
+---
+
+# UX completeness rule ledger
+
+The field is interaction design, and the authorities are the Nielsen Norman Group's research articles, WCAG 2.2 for timing, MDN for the `title` attribute and CSS truncation, and web.dev for layout shift.
+
+## Feedback
+
+| Bullet                                | Source                                                                                                                                                                                                                                                                     | Read                 |
+| ------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -------------------- |
+| Confirm success and failure           | [Visibility of system status](https://www.nngroup.com/articles/visibility-system-status/): "Whenever users interact with a system, they need to know whether the interaction was successful"                                                                               | 2026-10-18           |
+| Auto-dismiss only a redundant message | [Understanding Timing Adjustable](https://www.w3.org/WAI/WCAG22/Understanding/timing-adjustable.html): "If the user has no other means of discovering the same information (or performing the same function), then each message would need to meet this success criterion" | 2026-10-18, WCAG 2.2 |
+| No optimistic status                  | House choice: a "connected" dot shown over unsaved edits reports a state the system has not reached, and the person leaves believing their change took                                                                                                                     | 2026-10-18           |
+
+## Empty states
+
+| Bullet                         | Source                                                                                                                                                                                                                                               | Read       |
+| ------------------------------ | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ---------- |
+| Empty state with a next action | [Designing empty states](https://www.nngroup.com/articles/empty-state-interface-design/): designed empty states "Provide direct pathways for getting started with key tasks"                                                                         | 2026-10-18 |
+| Distinguish new from filtered  | [Designing empty states](https://www.nngroup.com/articles/empty-state-interface-design/): after a filter returns nothing, people wonder "Did an error occur? Did I set the wrong filters or parameters?", and "Totally empty states cause confusion" | 2026-10-18 |
+
+## Loading states
+
+| Bullet                         | Source                                                                                                                                                                                                  | Read       |
+| ------------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ---------- |
+| Indicator past one second      | [Progress indicators](https://www.nngroup.com/articles/progress-indicators/): "Use a progress indicator for any action that takes longer than about 1.0 second"                                         | 2026-10-18 |
+| Mark stale content as updating | [Progress indicators](https://www.nngroup.com/articles/progress-indicators/): "Without any visual change from the system, most users will assume the action was not registered and they will try again" | 2026-10-18 |
+
+## Destructive actions
+
+| Bullet                  | Source                                                                                                                                                                                     | Read       |
+| ----------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | ---------- |
+| Confirm unless undoable | [Confirmation dialogs](https://www.nngroup.com/articles/confirmation-dialog/): "consider a confirmation dialog before actions that cannot be undone", and "do try your best to offer undo" | 2026-10-18 |
+
+## Element states
+
+| Bullet                      | Source                                                                                                                                                                                                                          | Read       |
+| --------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ---------- |
+| Distinct interaction states | [Visibility of system status](https://www.nngroup.com/articles/visibility-system-status/): "Did the system actually catch that button press", and an element with no pressed or hover response leaves the person unable to tell | 2026-10-18 |
+| No intermediate flash       | [Cumulative Layout Shift](https://web.dev/articles/cls): "Unexpected layout shifts can disrupt the user experience", caused by content "dynamically added to the page before existing content"                                  | 2026-10-18 |
+
+## Overflow
+
+| Bullet                        | Source                                                                                                                                                                                                                                  | Read       |
+| ----------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ---------- |
+| Ellipsis over overflow        | [text-overflow](https://developer.mozilla.org/en-US/docs/Web/CSS/text-overflow): `text-overflow: ellipsis` with `overflow: hidden` and `white-space: nowrap` clips text at the box with a visible marker                                | 2026-10-18 |
+| Never `title` alone           | [The title attribute](https://developer.mozilla.org/en-US/docs/Web/HTML/Reference/Global_attributes/title): "Use of the title attribute is highly problematic for" people using touch-only devices, keyboards, and assistive technology | 2026-10-18 |
+| Focus rings clear of clipping | House choice: a ring cut off by a parent's `overflow` shows on the middle items of a list and vanishes on the first and last, so the focus indicator fails exactly where the list ends                                                  | 2026-10-18 |
+
+## Declined
+
+Every bullet the rewrite removed or reshaped, grouped by why.
+
+### Contradicted by the source
+
+- Replaced the `title`-or-expand truncation bullet with the never-`title`-alone bullet, since MDN calls the attribute "highly problematic" for touch and keyboard users.
+- Qualified "feedback must auto-dismiss after 2 to 3 seconds" against WCAG 2.2.1, since a message carrying the only copy of its information sets a time limit on reading it.
+- Rewrote "do not show stale content while new content is loading", which offered keeping the previous content as its own alternative, to the marking bullet.
+
+### Moved to a sibling rule
+
+- Moved "confirmation UI must be dismissible via Escape" and "inline confirmation rows must be dismissible via Escape" to the Escape bullet in `keyboard.md`.
+- Moved "status indicators must reset to a neutral state when their source input changes" to `forms.md`, which held the same bullet for derived values.
+- Cut "confirmation labels and destructive buttons must have sufficient contrast", which `a11y.md` holds for every control.
+
+### Cut without a source or a bug class
+
+- Cut "disabled elements must use muted colors and `cursor: not-allowed`", a convention Claude already follows that no source sets.
+- Cut "use CSS transitions or deferred rendering to prevent visible flicker", merged into the intermediate flash bullet as its remedy.
+
+### Merged or reworded
+
+- Merged the `## Inline confirmations`, `## Status indicators`, `## State transitions`, `## Interactive element states`, and `## Scroll and clipping` H2s into six, the merge the plan suggested.
+- Merged "every list must handle the empty state" with "empty states must include a next action", and the two filter bullets into one.
+- Merged "do not rely on a single state to communicate interactivity" into the distinct states bullet.
+- Reworded "every async operation must show a loading indicator" to NN/g's one second threshold, since a shorter spinner distracts.

package/governance/renames.toml

@@ -15,7 +15,6 @@
 # file.
 [renamed]
 "015-output" = "566-output"
-"035-tasks" = "602-tasks"
 "055-scratch" = "604-scratch"
 "085-worktrees" = "605-worktrees"
 "087-git" = "606-git"
@@ -32,7 +31,6 @@
 "655-tasks" = "tasks"
 "570-skill" = "skill"
 "801-markdown" = "markdown"
-"602-tasks" = "task-scope"
 "604-scratch" = "scratch"
 "605-worktrees" = "worktrees"
 "606-git" = "git"

package/governance/rules/claude/output.md

@@ -1,5 +1,5 @@
 ---
-description: Report file paths correctly for the reading surface and group them when the response covers many
+description: Report file paths correctly for the reading surface, group them when the response covers many, and name sessions to a person
 ---
 
 # Output standards
@@ -17,3 +17,7 @@ description: Report file paths correctly for the reading surface and group them
 
 - Group paths under `**Created:**`, `**Modified:**`, and `**Deleted:**` headers when the response covers multiple files, with every path under them in that form.
 - Put a single-file change's path on its own line, with no header.
+
+## Naming sessions
+
+- Name a session to a person by its roster name from `canon sessions list`, and give its id only beside the name, never alone.

package/governance/rules/code/routing.md

@@ -1,5 +1,5 @@
 ---
-description: Routes code placement and shape decisions to the skills that carry them
+description: Routes code placement and shape decisions to the skills that carry them, and library calls to the official docs
 ---
 
 # Code standards
@@ -11,3 +11,7 @@ description: Routes code placement and shape decisions to the skills that carry
 ## Shape
 
 - Load the `canon:code-craft` skill before deciding the shape of a new function, class, or module, and report it rather than proceeding silently when it does not resolve.
+
+## Libraries
+
+- Before calling a library API the codebase does not already use, fetch the official docs for the installed version and match the call to them, since recall of an API goes stale.

package/governance/rules/lang/go.md

@@ -1,40 +1,31 @@
 ---
-description: Enforce Go naming, error wrapping, context passing, and package boundaries
+description: Enforce Go error wrapping, context passing, interface placement, and package boundaries
 paths:
   - '**/*.go'
 ---
 
 # Go standards
 
-## Casing conventions
-
-- Use `MixedCaps` for exported names and `mixedCaps` for unexported ones. Never use underscores in a Go identifier.
-- Name packages with one short lowercase word. Do not use `util`, `common`, or `helpers` as a package name.
-- Do not repeat the package name in an exported identifier (`user.New`, not `user.NewUser`).
-- Keep initialisms in one case (`userID`, `HTTPClient`), never `userId` or `HttpClient`.
-
 ## Errors
 
-- Return an error as the last result value.
 - Wrap an error with `fmt.Errorf("...: %w", err)` when adding context.
-- Match an error with `errors.Is` or `errors.As`. Never compare `err.Error()` strings.
-- Never discard an error with `_`.
-- Do not `panic` for a failure a caller can expect. Reserve it for a broken invariant.
+- Match an error with `errors.Is` or `errors.As`. Never compare with `==` or on `err.Error()` strings, which miss a wrapped error.
+- Never discard an error with `_`. Handle it, return it, or panic on a broken invariant.
+- Return an `error` for a failure a caller can expect. Reserve `panic` for a broken invariant.
 
 ## Context
 
 - Pass `context.Context` as the first parameter, named `ctx`.
-- Never store a `context.Context` in a struct field.
+- Never store a `context.Context` in a struct field. Pass it to each function that needs it.
 - Do not pass a `nil` context. Use `context.TODO()` where none is available yet.
 
 ## Interfaces
 
-- Declare an interface in the package that consumes it, not the one that implements it.
-- Keep an interface to the methods its consumer calls.
+- Declare an interface in the package that consumes it, holding only the methods that consumer calls.
 - Accept interfaces and return concrete types.
 
 ## Packages
 
 - Place code no other module may import under `internal/`.
 - Do not perform side effects in `init`. Wire dependencies explicitly from `main`.
-- Do not hold mutable state in a package-level variable.
+- Do not hold mutable state in a package-level variable. Pass it through a struct the caller owns.

package/governance/rules/lang/php.md

@@ -19,7 +19,7 @@ paths:
 
 ## Data shapes
 
-- Use a backed `enum` for a closed set over class constants.
+- Use an `enum` for a closed set over class constants, backed by a string or int when the value is stored or serialized.
 - Use `readonly` properties or a `readonly` class for value objects.
 - Declare classes `final` unless they are designed for extension.
 - Do not pass an associative array across a public boundary where a typed object fits.
@@ -27,5 +27,5 @@ paths:
 ## Errors
 
 - Throw a domain exception for a failure. Do not return `false` or `null` to signal one.
-- Never suppress an error with the `@` operator.
-- Do not use `extract`, variable variables, or `eval`.
+- Never suppress an error with the `@` operator. Check the condition first or catch the exception.
+- Do not use `extract`, variable variables, or `eval`. Name each variable and call each function directly.

package/governance/rules/lang/python.md

@@ -1,31 +1,22 @@
 ---
-description: Enforce strict Python type hints, casing, and import patterns
+description: Enforce strict Python type hints, exception handling, data shapes, and import patterns
 paths:
   - '**/*.py'
 ---
 
 # Python standards
 
-## Casing conventions
-
-- Use `snake_case` for modules, functions, variables, and methods.
-- Use `PascalCase` for classes, type aliases, `TypeVar`, and `ParamSpec`.
-- Use `UPPER_SNAKE_CASE` for module-level constants and environment variables.
-- Use `_leading_underscore` for module-private names. Reserve `__dunder__` for the standard protocol.
-
 ## Type hints
 
-- Annotate all public functions, methods, and class attributes.
-- Use `X | None` over `Optional[X]` and `X | Y` over `Union[X, Y]`.
-- Use built-in generics (`list[str]`, `dict[str, int]`) over `typing.List` and `typing.Dict`.
-- Avoid `from __future__ import annotations` in modules that pydantic, FastAPI, or other libraries introspect at runtime.
-- Use `typing.Protocol` for structural typing over abstract base classes for interfaces.
-- Do not use `Any`. Reach for `object` or `typing.cast` at boundaries instead.
+- Annotate every public function and method, since a type checker skips the body of an unannotated function.
+- Use `X | None`, `X | Y`, and built-in generics such as `list[str]` over `Optional`, `Union`, and `typing.List`.
+- Do not add `from __future__ import annotations`. Python plans to deprecate and remove it.
+- Use `typing.Protocol` for an interface a class satisfies by shape, over an abstract base class it must subclass.
+- Type a value that can be anything as `object` and narrow it. Never use `Any`, which turns checking off.
 
 ## Errors
 
-- Raise specific built-in exceptions over bare `Exception`.
-- Define a project-rooted exception hierarchy for domain errors.
+- Raise a specific built-in exception or one from a project-rooted hierarchy, never bare `Exception`.
 - Catch the narrowest exception class. Never use bare `except:`.
 - Re-raise with `raise ... from err` to preserve the cause chain.
 
@@ -37,6 +28,6 @@ paths:
 
 ## Imports and modules
 
-- Use absolute imports rooted at the package. Do not use parent-relative (`from ..pkg`) imports.
+- Use absolute imports rooted at the package over relative ones.
 - Do not alias imports to shorten internal names. Ecosystem conventions (`numpy as np`, `pandas as pd`) are exceptions.
-- Do not place executable code at module scope. Guard with `if __name__ == "__main__":`.
+- Do not place executable code at module scope. Guard it with `if __name__ == "__main__":` and call a `main` function.

package/governance/rules/lang/typescript.md

@@ -1,5 +1,5 @@
 ---
-description: Enforce strict TypeScript type safety and patterns
+description: Enforce strict TypeScript type safety, declarations, and import patterns
 paths:
   - '**/*.ts'
   - '**/*.tsx'
@@ -7,34 +7,24 @@ paths:
 
 # TypeScript standards
 
-## Casing conventions
+## File names
 
-- Use `kebab-case` for filenames and directories.
-- Use `camelCase` for variables, functions, and methods.
-- Use `PascalCase` for types, interfaces, classes, and components.
-- Use `UPPER_SNAKE_CASE` for constants and environment variables.
+- Use `kebab-case` for filenames and directories, since a case-only difference resolves on macOS and fails on Linux.
 
 ## Type declarations
 
-- Enforce explicit types or strict inference.
-- Use `unknown` over `any`.
-- Use `interface` for object shapes and component props.
-- Use `type` for unions, intersections, and utility types.
-- Do not prefix interfaces with `I`.
-- Use constant objects or union types instead of `enum`.
+- Use `unknown` over `any`, and narrow it before use.
+- Use `interface` for an object shape until it needs a feature only `type` has, such as a union or a mapped type.
+- Use a constant object with `as const` or a union of literals instead of `enum`.
 
 ## Type safety
 
-- Use type guards and narrowing over type assertions.
-- Use discriminated unions for error handling over throwing exceptions.
-- Use built-in utility types (`Partial`, `Pick`, `Omit`) over manual type manipulation.
-- Prefer `readonly` properties for data objects.
-- Do not use non-null assertions.
-- Use `Promise.all()` for independent async operations.
+- Narrow with a type guard or a runtime check over a type assertion or a non-null `!`, neither of which checks at runtime.
+- Run independent async operations through `Promise.all()` rather than awaiting each in turn.
 
 ## Imports and configuration
 
-- Use absolute imports mapping `@/` to `src/`.
+- Import through the `@/` alias where tsconfig.json and the bundler both map it to `src/`, over a `../../` chain.
 - Import from the module's source file directly over barrel `index` re-exports.
 - Use `import type` for type-only imports.
 - Enable `strict: true` in tsconfig.json with no exceptions.

package/governance/rules/lib/database.md

@@ -14,22 +14,22 @@ paths:
 ## Schema changes
 
 - Express every schema change as a migration file committed to version control.
-- Ship a tested rollback path with every migration that changes a schema.
+- Ship a way back with every schema migration, as a down step or a forward migration that reverses it.
 - Never alter a deployed schema outside a migration.
 - Never edit a migration that has run in a shared environment. Add a new one.
-- Separate a destructive migration from the deploy that stops reading the dropped column.
+- Drop a column or table only after a deploy that stops reading and writing it.
 
 ## Query construction
 
 - Pass every runtime value as a bound parameter.
 - Never interpolate, concatenate, or format a value into a statement string.
-- Name the columns a read needs. Do not select every column by wildcard.
+- Map a table name, column, or sort direction through an allow-list, since none of them can be bound.
 
 ## Transactions
 
 - Give each transaction one owner that opens it, commits it, and rolls it back.
-- Never open a transaction inside a function that was handed one.
-- Keep network calls, queue publishes, and filesystem writes outside an open transaction.
+- Never commit a transaction a function was handed. Take a savepoint, such as a nested `atomic`, for a partial rollback.
+- Keep network calls, queue publishes, and filesystem writes outside an open transaction, running them after commit.
 
 ## Access patterns
 

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

@@ -8,13 +8,12 @@ paths:
 
 ## Waiting
 
-- Settle on the condition a step waits for. Use `expect.poll` or a web-first assertion ahead of any read.
+- Settle on the condition a step waits for with a web-first assertion or `expect.poll`, never `page.waitForTimeout`.
 - Reserve a fixed duration for an assertion that nothing happened across a window.
-- Bound every settle with an explicit timeout.
+- Bound every settle with an explicit timeout. `toPass` defaults to none and ignores the expect timeout.
 - Do not raise a timeout to clear a failure that reproduces under load. Replace the wait with a settle.
-- Do not read a value once after a pause. Poll it.
 - Settle a smooth scroll on the `scrollend` event. Fall back to a stillness window only when the target was already in view.
-- Run with motion reduced unless the test asserts motion, and opt back in per test.
+- Run with `reducedMotion: 'reduce'` unless the test asserts motion, and opt back in per test.
 
 ## Falsifiable guards
 
@@ -26,9 +25,8 @@ paths:
 ## Reproducing a failure that only appears in CI
 
 - Reproduce under `Emulation.setCPUThrottlingRate` rather than by rerunning the gate.
-- Read the state the assertion does not: which markers were set, which listeners fired, how far a transition ran.
+- Read the failure's trace for the state the assertion does not read, such as which markers were set and which listeners fired.
 - Vary the condition under suspicion deliberately. Do not compare counts across runs that differed in something uncontrolled.
-- Read the check conclusion as its own act. A green diff review reports nothing about the gate.
 
 ## Authority