@erclx/canon 4.0.0

package/governance/rules/lib/340-pydantic.md

@@ -0,0 +1,38 @@
+---
+description: Enforce pydantic v2 patterns for validation and serialization
+paths:
+  - '**/*.py'
+---
+
+# Pydantic standards
+
+## Models
+
+- Use `pydantic.BaseModel` over `dataclass` at I/O and API boundaries.
+- Use `model_config = ConfigDict(...)` over the legacy nested `Config` class.
+- Set `extra="forbid"` on models receiving external input to prevent data pollution.
+- Use `Field(...)` for defaults, descriptions, and constraints over docstring conventions.
+
+## Validation
+
+- Use `Model.model_validate(data)` over `Model(**data)` for untrusted dict input.
+- Use `Model.model_validate_json(s)` over `json.loads` followed by validation.
+- Use `@field_validator` over the legacy `@validator`.
+- Use `@model_validator(mode="after")` for cross-field invariants.
+
+## Types
+
+- Use `AnyUrl`, `EmailStr`, `SecretStr`, and `PositiveInt` over hand-rolled regex constraints.
+- Use `Annotated[T, Field(...)]` over default-value `Field(...)` for reusable constrained types.
+- Do not use `Any` in fields. Reach for `JsonValue` or a `Union` of concrete types.
+
+## Settings
+
+- Use `pydantic_settings.BaseSettings` for env-driven configuration.
+- Load environment through a single `Settings` model. Do not read `os.environ` directly elsewhere.
+
+## Serialization
+
+- Use `model.model_dump(mode="json")` over the legacy `.dict()`.
+- Use `model.model_dump_json()` over `json.dumps(model.dict())`.
+- Use `by_alias=True` when serializing to external schemas with non-Python field names.

package/governance/rules/lib/350-security-web.md

@@ -0,0 +1,32 @@
+---
+description: Enforce web frontend security and XSS prevention
+paths:
+  - '**/*.tsx'
+  - '**/*.jsx'
+  - '**/*.html'
+  - '**/*.astro'
+---
+
+# Web security standards
+
+## Link safety
+
+- Add `rel="noopener noreferrer"` to all external links with `target="_blank"`.
+
+## Content sanitization
+
+- Sanitize all user-generated content rendered via `dangerouslySetInnerHTML` using DOMPurify or equivalent.
+- Never use `dangerouslySetInnerHTML` without sanitization.
+
+## Input validation
+
+- Validate all URL parameters and query strings using schema validation before use.
+
+## Storage and tokens
+
+- Do not store sensitive data (tokens, passwords, PII) in `localStorage` or `sessionStorage`.
+- Store authentication tokens in httpOnly cookies over exposing them to JavaScript.
+
+## Third-party scripts
+
+- Audit and pin versions for all third-party scripts loaded in the browser.

package/governance/rules/lib/360-security-server.md

@@ -0,0 +1,39 @@
+---
+description: Enforce server-side authorization, secret handling, and abuse limits on request handlers
+paths:
+  - '**/*.py'
+  - '**/*.ts'
+  - '**/*.js'
+---
+
+# Server security standards
+
+## Authorization
+
+- Authorize every request on the server, whatever the client already checked.
+- Derive the caller identity from the verified session or token. Never read it from a request body, query string, or header the client sets.
+- Check that the caller owns or may reach the specific record a request names, not only that the caller is signed in.
+- Deny by default. Grant a route access through an explicit allow.
+
+## Credentials
+
+- Hash passwords with a memory-hard algorithm and a per-record salt. Never store a reversible password.
+- Compare tokens, signatures, and password hashes with a constant-time function.
+- Expire and revoke sessions and refresh tokens on the server. Do not rely on client-side deletion.
+
+## Secrets
+
+- Read every secret from the environment or a secret manager at runtime.
+- Never commit a secret, connection string, or private key to the repository.
+- Never return a secret, connection string, or internal hostname in a response body.
+
+## Abuse limits
+
+- Rate-limit authentication, password reset, and any endpoint that sends mail or costs money per call.
+- Set an explicit maximum body size and request timeout on every endpoint.
+- Bound pagination parameters with a server-side maximum.
+
+## Transport
+
+- Serve every route over TLS and reject plaintext requests.
+- Restrict CORS to an explicit origin list. Never reflect the request origin or pair a wildcard with credentials.

package/governance/rules/lib/370-database.md

@@ -0,0 +1,35 @@
+---
+description: Enforce persistence boundaries for migrations, query construction, transactions, and rollback
+paths:
+  - '**/*.py'
+  - '**/*.ts'
+  - '**/*.js'
+  - '**/*.sql'
+---
+
+# Persistence standards
+
+## 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.
+- 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.
+
+## 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.
+
+## 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.
+
+## Access patterns
+
+- Load related rows in the query that fetches their parents. Do not resolve a relation lazily inside an iteration.
+- Scope a connection or session to the request that opened it and release it on exit.

package/governance/rules/snippets/505-at-references.md

@@ -0,0 +1,9 @@
+---
+description: Execute an @-referenced snippet's instructions immediately using session context
+---
+
+# Snippet reference standards
+
+## Execution
+
+- When a snippet is referenced with `@`, execute its instructions immediately using available session context

package/governance/rules/ui/400-ui.md

@@ -0,0 +1,36 @@
+---
+description: Enforce UI copy and text standards for rendered strings in components
+paths:
+  - '**/*.tsx'
+  - '**/*.jsx'
+  - '**/*.astro'
+  - '**/*.html'
+---
+
+# UI copy standards
+
+## Casing
+
+- Use sentence case for all rendered UI text: headings, labels, nav items, tab titles, and dialog titles.
+- Retain original casing for proper nouns and product names: `GitHub`, `macOS`, `TypeScript`.
+
+## Punctuation
+
+- Do not use em dashes (`—`). Use a comma or period, or restructure the sentence.
+- Do not add punctuation to button labels or short action strings.
+
+## Button copy
+
+- Use imperative verbs for actions: `Save`, `Delete`, `Connect`, `Cancel`.
+- Avoid padded phrasing: `Save` over `Save changes`, `Delete` over `Click to delete`.
+
+## Error messages
+
+- State what to do, not what went wrong: `Enter a valid email` over `Email is invalid`.
+- Keep messages short and actionable.
+- One sentence maximum.
+
+## Placeholder text
+
+- Show format examples over instructions: `name@example.com` over `Enter your email here`.
+- Reserve instructions for labels or helper text below the input.

package/governance/rules/ui/410-a11y.md

@@ -0,0 +1,48 @@
+---
+description: Keyboard interaction, focus management, and ARIA accessibility for rendered UI
+paths:
+  - '**/*.tsx'
+  - '**/*.jsx'
+  - '**/*.astro'
+  - '**/*.html'
+  - '**/*.css'
+---
+
+# Accessibility and keyboard standards
+
+## Focus styles
+
+- All interactive elements must use the project focus ring. Do not define per-component focus styles.
+- Never apply `outline-none` without a custom focus ring in the same rule.
+- Focus ring must have 3:1 contrast against its background in both light and dark modes.
+
+## Keyboard interaction model
+
+- Tab / Shift+Tab: move focus sequentially through interactive elements in DOM order.
+- Enter: activates buttons and links, submits forms.
+- Space: activates buttons and checkboxes, toggles selection in listboxes.
+- Arrow keys: navigate within composite widgets. Do not let them exit the widget.
+- Escape: closes any overlay, popover, dialog, or dropdown. Cancels in-progress edits.
+- Do not introduce non-standard key bindings for common actions.
+
+## Composite widgets
+
+- Roving tabindex for interactive collections: one item in the tab sequence at a time.
+- Combobox: arrow keys navigate options, Enter selects, Escape closes, typing filters.
+
+## Focus management
+
+- Move focus into any overlay, popover, or dialog on open. Return focus to the trigger on close.
+- Never move focus on hover. Only on keyboard input or explicit pointer activation.
+
+## ARIA semantics
+
+- Use semantic HTML over custom elements: `<button>` over a `<div>` carrying a click handler, `<a>` over a `<span>` carrying one.
+- A `<div>` with a click handler requires a role, a tab index, and keyboard handlers. Use `<button>` instead.
+- Spell an attribute the way the file's syntax spells it: `onclick` and `tabindex` in HTML and Astro markup, `onClick` and `tabIndex` in JSX.
+- Set role on custom controls: `role="combobox"`, `role="listbox"`, `role="menu"`, `role="option"`.
+- Synchronize state attributes with visual state: `aria-expanded`, `aria-selected`, `aria-checked`, `aria-disabled`.
+- Add `aria-label` or `aria-labelledby` to interactive elements with no visible text label.
+- Always provide `alt` on `<img>`. Use `alt=""` for decorative images.
+- Describe the content or function of the image, not its appearance. Do not prefix with "Image of" or "Photo of".
+- Alt text for functional images (icons, buttons) should describe the action, not the graphic.

package/governance/rules/ui/420-forms.md

@@ -0,0 +1,36 @@
+---
+description: Form validation timing, save-blocking, and derived state for rendered forms
+paths:
+  - '**/*.tsx'
+  - '**/*.jsx'
+  - '**/*.astro'
+  - '**/*.html'
+---
+
+# Form standards
+
+## Validation timing
+
+- Validate on blur, not on every keystroke. Exception: realtime feedback that is explicitly part of the feature (e.g. character count, live search).
+- After a field shows its first error (on blur), re-validate on every change so the error clears as soon as the input becomes valid.
+- Apply the same validation timing to all fields in a form. Do not mix blur-only and change-only validation within one form.
+- Do not show an error on a field the user has never touched.
+
+## Save blocking
+
+- Block save when any required field is empty, invalid, or has never been touched.
+- Treat whitespace-only values as empty for required fields.
+
+## Error placement
+
+- Show the error directly under the field that caused it, not under an unrelated field.
+- When a change to field A causes a conflict involving field B, show the error under field A (the field the user edited), not under field B.
+
+## Input sanitization
+
+- Trim leading and trailing whitespace from text inputs on blur or submit, not on every keystroke.
+- If a field is case-sensitive, surface that constraint near the field. Do not silently treat `Foo` and `foo` as different values without warning.
+
+## Derived display state
+
+- Reset status indicators, counts, and derived display values when their source input changes.

package/governance/rules/ui/430-ux-completeness.md

@@ -0,0 +1,65 @@
+---
+description: UX completeness checklist for interactive components and views
+paths:
+  - '**/*.tsx'
+  - '**/*.jsx'
+  - '**/*.astro'
+  - '**/*.html'
+  - '**/*.css'
+---
+
+# UX completeness standards
+
+## Mutation feedback
+
+- Every user-initiated mutation (save, delete, sync, import, export) must show inline feedback on success.
+- Feedback must be transient: auto-dismiss after 2-3 seconds without requiring user action.
+- Show inline error feedback when a mutation fails. Do not fail silently.
+
+## Empty states
+
+- Every list, table, or collection view must handle the empty state explicitly.
+- Empty states must include a next action: a button, link, or instruction that tells the user what to do.
+- Distinguish between "nothing exists yet" (onboarding) and "nothing matches your filter" (recovery). Use different copy for each.
+- Filter-driven empty states must include a way to clear the filter (link or button).
+
+## Loading states
+
+- Every async operation visible to the user must show a loading indicator (spinner, skeleton, or disabled state).
+- Do not show stale content while new content is loading. Either show a loading state or keep the previous content with a progress indicator.
+
+## Destructive actions
+
+- Destructive actions (delete, disconnect, discard) must require confirmation before executing.
+- Confirmation UI must be dismissible via Escape in addition to a cancel button.
+
+## Inline confirmations
+
+- All inline confirmation rows (delete, discard, cancel) must be dismissible via Escape.
+- Confirmation labels and destructive buttons must have sufficient contrast in both light and dark modes.
+
+## Status indicators
+
+- Status indicators (dots, badges, connection status) must reset to a neutral state when their source input changes.
+- Do not show optimistic status (green dot, "connected") while unsaved edits are pending.
+
+## State transitions
+
+- Do not flash intermediate states during transitions (e.g., white flash on theme load, layout jump before data arrives).
+- Use CSS transitions or deferred rendering to prevent visible flicker between states.
+
+## Interactive element states
+
+- All interactive elements must visually respond to hover, active, focus, and disabled states.
+- Disabled elements must use reduced opacity or muted colors and `cursor: not-allowed`.
+- Do not rely on a single state (e.g., focus only) to communicate interactivity.
+
+## Overflow and truncation
+
+- Long text in constrained containers must truncate with ellipsis, not overflow or wrap unexpectedly.
+- Truncated text must be accessible via `title` attribute or expandable interaction.
+
+## Scroll and clipping
+
+- Focus rings and interactive borders must not be clipped by parent `overflow: hidden` or `overflow: auto` containers.
+- Add padding or adjust overflow to prevent clipping on edge items in scrollable lists.

package/governance/rules/ui/440-surface-capture.md

@@ -0,0 +1,34 @@
+---
+description: Require a capture against a running preview after a rendered surface changes
+paths:
+  - '**/routes/**/*.{tsx,jsx,vue,svelte,astro}'
+  - '**/pages/**/*.{tsx,jsx,vue,svelte,astro}'
+  - '**/app/**/page.{tsx,jsx}'
+  - '**/*.html'
+---
+
+# Surface capture standards
+
+## What a surface is
+
+- A surface is anything the project renders for a person to look at. A framework route is one. A page the project generates is another, whoever generates it.
+- Judge a generated page by the same rule as a route. Reading its markup reports nothing about how it composes.
+
+## When to capture
+
+- Run the project's capture command after changing what a surface renders. Report it rather than proceeding silently when the project has none.
+- Capture against a running preview server. Do not capture against a dev server.
+- Capture every theme the surface ships. Do not capture the default theme alone.
+- Capture again after fixing a defect a capture found. A repair inside a shared stylesheet can cancel a rule written earlier in the same file.
+
+## What a capture covers
+
+- Capture the full page at the viewport its case declares. Do not capture a component in isolation.
+- Drive a state a screenshot cannot reach. An initial render reports nothing about a menu that opens, an answer that is chosen, or a rail that tracks scrolling.
+- Add a case to the capture record when adding a surface.
+- Remove a surface's case in the change that removes the surface.
+
+## Sharing a capture
+
+- Attach a capture to the pull request by hand when a reviewer needs to see it.
+- Do not commit a capture. Do not remove the capture folder from `.gitignore`.

package/governance/rules/ui/450-link-behavior.md

@@ -0,0 +1,19 @@
+---
+description: Enforce the same-tab default for an outbound link and for a mail link
+paths:
+  - '**/*.tsx'
+  - '**/*.jsx'
+  - '**/*.astro'
+  - '**/*.html'
+---
+
+# Link behavior standards
+
+## Default target
+
+- Open a link in the same tab. Reserve `target="_blank"` for a destination that would discard in-progress work if it replaced the current page, such as a document a user is midway through elsewhere.
+- Do not add `target="_blank"` as a default for every external link.
+
+## mailto: links
+
+- Open a `mailto:` link in the same tab. It hands off to the mail client rather than replacing page content, so a new tab leaves an empty tab behind.

package/governance/stacks/astro.toml

@@ -0,0 +1,2 @@
+extends = "node"
+rules = ["210-astro", "350-security-web", "400-ui", "410-a11y", "430-ux-completeness", "440-surface-capture", "450-link-behavior"]

package/governance/stacks/base.toml

@@ -0,0 +1,8 @@
+extends = ""
+# All four folders whole. Every rule authored under them ships to a base
+# consumer, so adding one is a single edit rather than a file and a name here.
+# `snippets` carries the `@`-reference convention rule, which lost its only
+# other delivery path when `canon snippets install` retired. `ci` carries the
+# workflow rule, whose glob is the only inbound route to the `ci-workflow`
+# skill.
+rules = ["core", "claude", "snippets", "ci", "120-bash"]

package/governance/stacks/node-server.toml

@@ -0,0 +1,2 @@
+extends = "node"
+rules = ["360-security-server", "370-database"]

package/governance/stacks/node.toml

@@ -0,0 +1,2 @@
+extends = "base"
+rules = ["100-typescript"]

package/governance/stacks/python-fastapi.toml

@@ -0,0 +1,2 @@
+extends = "python"
+rules = ["220-fastapi"]

package/governance/stacks/python.toml

@@ -0,0 +1,2 @@
+extends = "base"
+rules = ["110-python", "340-pydantic", "330-testing-py", "360-security-server", "370-database"]

package/governance/stacks/react.toml

@@ -0,0 +1,2 @@
+extends = "node"
+rules = ["200-react", "230-nextjs", "250-tailwind", "300-testing-ts", "305-e2e-reliability", "306-test-scope", "310-zod", "350-security-web", "400-ui", "410-a11y", "420-forms", "430-ux-completeness", "440-surface-capture", "450-link-behavior"]

package/package.json

@@ -0,0 +1,69 @@
+{
+  "name": "@erclx/canon",
+  "type": "module",
+  "version": "4.0.0",
+  "description": "Infrastructure and quality tooling for developer workflows",
+  "license": "MIT",
+  "bin": {
+    "canon": "./src/cli.ts"
+  },
+  "files": [
+    "src",
+    "scripts",
+    "standards",
+    "snippets",
+    "governance",
+    "tooling",
+    "claude",
+    "docs",
+    "tsconfig.json",
+    "!scripts/sandbox",
+    "!scripts/eval",
+    "!src/capture",
+    "!**/*.test.ts"
+  ],
+  "publishConfig": {
+    "access": "public"
+  },
+  "scripts": {
+    "check:spell": "cspell '**' '.*/**' '.*' --no-progress --color --show-context",
+    "format": "prettier --write --log-level warn --ignore-path .gitignore --ignore-path .prettierignore . && shfmt --write --indent 2 scripts/ tooling/ claude/",
+    "check:format": "prettier --check --log-level warn --ignore-path .gitignore --ignore-path .prettierignore . && shfmt --diff --indent 2 scripts/ tooling/ claude/",
+    "check:shell": "find scripts tooling claude .claude/hooks -name '*.sh' -exec shellcheck --severity=warning {} +",
+    "check:types": "tsc --noEmit",
+    "check:install": "./scripts/core/install-check.sh",
+    "test": "bun --bun vitest run",
+    "prepare": "husky",
+    "check": "bun src/cli.ts gate run",
+    "check:ci": "bun src/cli.ts gate run --all --no-write",
+    "update": "./scripts/core/update.sh",
+    "clean": "./scripts/core/clean.sh",
+    "snapshot": "./scripts/core/snapshot.sh",
+    "bootstrap": "./scripts/core/bootstrap.sh",
+    "canon:sandbox": "canon sandbox",
+    "canon:sandbox:reset": "canon sandbox reset"
+  },
+  "dependencies": {
+    "commander": "^13.1.0",
+    "execa": "^9.5.2",
+    "playwright-core": "1.59.1",
+    "pptxgenjs": "^4.0.1"
+  },
+  "devDependencies": {
+    "@astrojs/check": "^0.9.8",
+    "@astrojs/react": "^5.0.4",
+    "@commitlint/cli": "^20.4.1",
+    "@commitlint/config-conventional": "^20.4.1",
+    "@playwright/test": "1.59.1",
+    "@tailwindcss/vite": "^4.2.4",
+    "@testing-library/jest-dom": "^6.9.1",
+    "@types/bun": "^1.2.10",
+    "astro": "^6.1.9",
+    "cspell": "^8.17.1",
+    "husky": "^9.1.7",
+    "prettier": "^3.8.1",
+    "prettier-plugin-tailwindcss": "^0.7.2",
+    "typescript": "^5.9.3",
+    "vitest": "^4.1.5"
+  }
+}

package/scripts/config.sh

@@ -0,0 +1,11 @@
+#!/usr/bin/env bash
+
+if [ -z "${GITHUB_ORG:-}" ]; then
+  _origin_url="$(git config --get remote.origin.url 2>/dev/null || true)"
+  if [ -n "$_origin_url" ]; then
+    GITHUB_ORG="$(echo "$_origin_url" | sed -nE 's#^(git@github\.com:|https://github\.com/)([^/]+)/.+#\2#p')"
+  fi
+  unset _origin_url
+fi
+
+export GITHUB_ORG="${GITHUB_ORG:-}"

package/scripts/core/bootstrap.sh

@@ -0,0 +1,81 @@
+#!/usr/bin/env bash
+set -e
+set -o pipefail
+
+SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
+PROJECT_ROOT="${PROJECT_ROOT:-$(cd "$SCRIPT_DIR/../.." && pwd)}"
+
+source "$PROJECT_ROOT/scripts/lib/ui.sh"
+
+ZSHRC="${ZDOTDIR:-$HOME}/.zshrc"
+MARKER_OPEN="# >>> canon aliases >>>"
+MARKER_CLOSE="# <<< canon aliases <<<"
+
+check_dependencies() {
+  command -v bun >/dev/null 2>&1 || log_error "bun is not installed. See https://bun.sh, then re-run."
+}
+
+install_cli() {
+  log_step "Installing the canon CLI"
+  bun install --cwd "$PROJECT_ROOT" >/dev/null
+  bun link --cwd "$PROJECT_ROOT" >/dev/null
+  log_info "Dependencies installed and canon linked"
+}
+
+alias_block() {
+  cat <<EOF
+$MARKER_OPEN
+TOOLKIT="$PROJECT_ROOT"
+
+alias cl='claude'
+alias clr='cl -r'
+alias clc='cl -c'
+alias clw='cl -w'
+alias cls='cl --model sonnet'
+
+alias clp='claude --plugin-dir \$TOOLKIT/claude'
+alias clpc='clp -c'
+alias clps='clp --model sonnet'
+$MARKER_CLOSE
+EOF
+}
+
+install_aliases() {
+  log_step "Installing Claude Code shell aliases"
+
+  if [ -f "$ZSHRC" ] && grep -qF "$MARKER_OPEN" "$ZSHRC"; then
+    log_info "Aliases already present in $ZSHRC, skipping"
+    return
+  fi
+
+  if [ -f "$ZSHRC" ] && grep -qE "^alias clp=" "$ZSHRC"; then
+    log_warn "An unmanaged clp alias is already in $ZSHRC. Leaving it untouched."
+    log_warn "Remove it and re-run to switch to the managed block."
+    return
+  fi
+
+  printf '\n%s\n' "$(alias_block)" >>"$ZSHRC"
+  log_add "Appended canon alias block to $ZSHRC"
+  log_info "Run 'source $ZSHRC' or open a new shell to load them"
+}
+
+verify_cli() {
+  log_step "Verifying the install"
+  if canon --help >/dev/null 2>&1; then
+    log_info "canon resolves on PATH"
+  else
+    log_warn "canon not on PATH yet. Ensure \$BUN_INSTALL/bin is exported, then re-open your shell."
+  fi
+}
+
+main() {
+  open_timeline "canon bootstrap"
+  trap close_timeline EXIT
+
+  check_dependencies
+  install_cli
+  install_aliases
+  verify_cli
+}
+
+main "$@"

package/scripts/core/check-color-source.sh

@@ -0,0 +1,41 @@
+#!/usr/bin/env bash
+set -e
+set -o pipefail
+
+SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
+PROJECT_ROOT="${PROJECT_ROOT:-$(cd "$SCRIPT_DIR/../.." && pwd)}"
+
+SCRIPTS_ROOT="$PROJECT_ROOT/scripts"
+PALETTE_SOURCE="$SCRIPTS_ROOT/lib/ui.sh"
+
+# `find` writes to stderr and returns non-zero for a missing root, inside a
+# process substitution whose status nothing reads. Without this the walk covers
+# nothing and the check reports the tree clean having never measured it.
+if [ ! -f "$PALETTE_SOURCE" ]; then
+  echo "No palette source at ${PALETTE_SOURCE#"$PROJECT_ROOT/"}, color sourcing unverifiable." >&2
+  exit 1
+fi
+
+# Any SGR sequence in either spelling. The cursor and erase sequences an
+# interactive prompt writes end in a letter instead, and they run only where a
+# terminal already exists, so they are not what this measures.
+SGR='\\(033|e|x1b)\[[0-9;]*m'
+
+# Sixteen copies of one decision is what made color impossible to turn off on
+# the TypeScript side. A rule nothing enforces rebuilds them the next time a
+# script wants grey, so the escape lives in the shared library and every other
+# script reads the palette that library derives for its stream.
+offenders=""
+while IFS= read -r file; do
+  [ "$file" = "$PALETTE_SOURCE" ] && continue
+  if grep -qE "$SGR" "$file"; then
+    offenders="$offenders  ${file#"$PROJECT_ROOT/"}"$'\n'
+  fi
+done < <(find "$SCRIPTS_ROOT" -type f -name '*.sh')
+
+if [ -n "$offenders" ]; then
+  echo "A color escape is defined outside the shared library:" >&2
+  printf '%s' "$offenders" >&2
+  echo "Source scripts/lib/ui.sh and read its palette, so one answer covers every writer." >&2
+  exit 1
+fi