@brighterly/lib-fe-codestyle 1.0.0 → 1.0.2

package/README.md

@@ -1,31 +1,214 @@
 # `@brighterly/lib-fe-codestyle`
 
-Shared, deterministic code-review machinery for the Brighterly Nuxt apps — land-app,
-cs-app, app-tutor, app-admin.
+Shared, deterministic code review for the Brighterly Nuxt apps: a rule engine with a
+binary (`codestyle`), eleven package rules, and a shared ESLint flat config. A consumer
+declares one file, `codestyle.config.ts`; its own domain rules live next to it.
 
-It holds the **mechanisms**. Domain rules stay in each app.
+**New here?** [docs/how-it-works.md](docs/how-it-works.md) explains what one run does,
+the proof forms, overrides and tags. Moving a repo from 0.5.x:
+[docs/migration-1.0.md](docs/migration-1.0.md).
 
-**New here?** [docs/how-it-works.md](docs/how-it-works.md) — how a check reads real
-code, what the gate can and cannot cover, what is already enforced, how to extend it,
-and how to run it.
+## Quick start
 
-## Subpaths
+```bash
+pnpm add -D @brighterly/lib-fe-codestyle
+```
 
-| Import | What it is |
+`typescript` and `@vue/compiler-sfc` are **peers**: the engine parses your files with the
+same compiler instances your build uses. Every Brighterly app already has both.
+
+```ts
+// codestyle.config.ts — the only required file
+import { defineConfig } from '@brighterly/lib-fe-codestyle'
+import repo from './codestyle/index.ts'          // { custom: [...] } — this repo's own rules
+
+export default defineConfig({
+  settings: {                                    // app landmarks the package rules read
+    scssTokensFile: 'app/assets/scss/_colors.scss',
+    typographySource: 'the font() mixin',
+    scriptAttrOrder: 'setup-first',
+  },
+  rules: {                                       // one level map for package AND custom rules
+    'script-attr-order': 'error',
+    'vueuse-first': 'off',
+  },
+  ...repo,                                       // contributes `custom` only — levels stay in `rules`
+  overrides: [                                   // never "the rule is off" — always "this place, this reason"
+    { files: ['app/components/UI/Buttons/BtnAuth*.vue'], rules: { 'inline-scss': 'off' },
+      reason: 'UI-kit exception, decided 2026-08-18' },
+    { files: ['app/components/Views/ViewQuizExp132.vue'], rules: { 'journey-coverage': 'warn' },
+      reason: 'funnel still being built; until 2026-10-31' },
+  ],
+})
+```
+
+A rule not named in `rules` runs at its own `level`. Keep the spread object to `{ custom }`:
+object spread replaces a same-named key, so a `rules` map inside it and the one above would
+silently overwrite each other.
+
+Two loading facts, because Node runs this file with its own type stripping:
+
+- **Relative imports spell `.ts`** (`./codestyle/index.ts`, and inside `codestyle/` too) —
+  Node does not rewrite `.js` to `.ts`. The tsconfig that covers these files needs
+  `allowImportingTsExtensions`.
+- **Erasable syntax only** — no `enum`, `namespace` or parameter properties. `codestyle`
+  names the file and the reason if one slips in. Node 22.18+ is required for a `.ts`
+  config; `codestyle.config.mjs` works on older Node — unless it imports `.ts` rule files,
+  which still need 22.18+.
+
+### Config keys
+
+| Key | Default | What it is |
+|---|---|---|
+| `settings` | `{}` | app landmarks for the package rules (`SharedRuleSettings` — see below) |
+| `rules` | `{}` | `name → 'off' \| 'warn' \| 'error'` for package and custom rules. An unknown name, an engine rule (`IG0`–`IG2`) or an ESLint/test-owned declaration here is a config error |
+| `custom` | `[]` | this repo's rules (each carries a proof) and check-less declarations owned by ESLint or a test. Shape-checked: a rule has no `owner` and needs `level` (`off`/`warn`/`error`), a non-empty `scope`, a `check` function and `title`/`why`/`fix`; a declaration has `owner: 'eslint' \| 'test'` and `ref`/`title`/`why`. Errors name the field (`custom[2].level`) |
+| `overrides` | `[]` | `{ files, rules, reason }` — a level for some rules on some files, reason mandatory |
+| `files` | `['app', 'config', 'tests', 'codestyle']` | scan roots: directories, files or globs |
+| `ignores` | `['node_modules', '.nuxt', '.output', 'dist', 'coverage']` | pruned from the walk: names, paths or globs |
+| `ruleSources` | `['codestyle/']` | where this repo's rules live: a staged change there triggers the self-test; their files are exempt from ignore-comment parsing (fixture strings carry ignore comments on purpose) |
+| `docs` | `[]` | `{ template, output, tags? }` rendered by `codestyle docs` |
+| `validate` | `[]` | `{ name, run }` steps for `codestyle validate` |
+| `precommit` | `[]` | `{ name, run }` steps `codestyle precommit` runs after the staged check |
+
+An unknown top-level key is a config error, so a typo never silently does nothing.
+
+## Package rules
+
+| Rule | Default | Catches |
+|---|---|---|
+| `no-bare-storage` | warn* | bare `localStorage` / `sessionStorage` — the accessor itself throws on Safari ITP and in in-app webviews |
+| `inline-scss` | error | SCSS rules inside a Vue `<style>` block instead of a referenced `.scss` file |
+| `guarded-json-parse` | warn* | `JSON.parse` with no enclosing `try`/`catch` — a corrupt stored value breaks that path permanently |
+| `font-face-single-family` | error | `@font-face` declaring a font *stack* — an invalid descriptor, so the browser drops the face silently |
+| `vueuse-first` | warn | a hand-rolled browser API with a VueUse equivalent |
+| `ui-kit-unique-names` | warn | a component whose name duplicates a UI-kit component |
+| `scss-tokens` | warn | a literal colour in SCSS instead of a design token |
+| `date-format-enum` | warn | a hand-rolled date format string, or the date part cut out of `toISOString()` |
+| `types-layout` | warn | a type file outside `types/<entity>/{enums,interfaces,types}.ts` |
+| `typography-source` | warn | a raw `font-family` / `font-size` / `font-weight` instead of the app's typography source |
+| `script-attr-order` | warn | `<script>` attribute order differing from the app's canonical |
+
+`error` is reserved for crash-class rules; conventions ship at `warn` so each app measures
+its backlog before anything blocks. `no-bare-storage` and `guarded-json-parse` (marked *)
+ship at `warn` as an interim state while the fleet backlog exists; their target is
+`error`. Underscore-prefixed SCSS partials are declaration files and exempt from
+`scss-tokens` and `typography-source`. Hover a `packageRuleNames` member for the rule's
+contract.
+
+### `settings`
+
+```ts
+settings: {
+  safeStorageModule: 'safeLocalStorage from @helpers/safe-local-storage', // no-bare-storage / guarded-json-parse messages
+  safeStorageFile:   'app/utils/helpers/safe-local-storage.ts',           // no-bare-storage exempts the wrapper itself
+  safeJsonParse:     'parseStoredJson() from @helpers/safe-local-storage',
+  scssTokensFile:    'app/assets/scss/_colors.scss',
+  uiKitRoot:         'app/components/UI',                                 // ui-kit-unique-names (default shown)
+  dateFormatModule:  'DateFormat from @ts-types/date/enums',
+  typesRoot:         'app/types',                                         // types-layout (default shown)
+  typographySource:  'the font() mixin from @scss/_mixins.scss',
+  scriptAttrOrder:   'setup-first',                                       // or 'lang-first' (default 'setup-first')
+}
+```
+
+A missing key degrades the rule's *message* or falls back to the documented default —
+never silences the rule.
+
+## Commands
+
+| Command | What it does |
 |---|---|
-| `@brighterly/lib-fe-codestyle/invariants` | the invariants engine — `run(options)`, the rule contract, AST helpers, util |
-| `@brighterly/lib-fe-codestyle/invariants/rules` | the common rule pack, portable across all apps |
-| `@brighterly/lib-fe-codestyle/eslint` | the shared flat config, its seven local rules, and the maps behind them |
-| `@brighterly/lib-fe-codestyle/validate` | the aggregating runner behind `pnpm validate` |
+| `codestyle check` | runs the rules. Flags: `--staged` (this commit), `--stdin --file=<path>` (check piped content as that file), `--json`, `--only=<a,b>` (by name; `--rule=<a,b>` is an alias, merged with `--only`), `--tags=<a,b>` (by tag — a tag no rule carries is exit 2), `--no-self-test`, `--no-color` |
+| `codestyle list` | every rule: `name · level · owner · tags` |
+| `codestyle self-test [--package]` | proves this repo's custom rules (`self-test: 0 rule(s) proven`, exit 0, when there are none); `--package` proves the package's own rules |
+| `codestyle docs [--check]` | renders every `docs` entry; `--check` writes nothing and fails on a stale or missing output. No `docs` entries is exit 2 |
+| `codestyle validate` | runs the `validate` steps — every step, one exit code. No steps is exit 2 |
+| `codestyle precommit` | `check --staged` first; if it fails, the steps are skipped. Then the `precommit` steps run as one group — every step, one exit code. Any other argument is passed to `check` |
+| `codestyle migrate [--write]` | moves a 0.5.x repo: suppression spelling, renamed ids, a config skeleton |
+
+Every command takes `--root=<path>` (default: the working directory). Exit codes:
+**0** clean or warnings only · **1** an error-level finding, a failed self-test, a stale doc
+or a failed step · **2** the tool itself failed (bad flags, no or bad config — a malformed
+`until` such as `until 2026-1-5` included — or a crash).
+
+## Suppressions and overrides
+
+One line, reviewed: `// codestyle-ignore: <name> — <reason>` suppresses that line and the
+next. The reason is mandatory. Three engine rules police the escape hatch:
+
+- **IG0** — an ignore without a reason;
+- **IG1** — a name that is not a live rule (a renamed package rule says what it became), or
+  an override that no longer applies (a glob that matches no file, an `until` that has passed);
+- **IG2** — an ignore naming a rule declared `noIgnore`; the comment suppresses nothing.
+
+`// invariant-ignore:` is still accepted through 1.x with a one-line deprecation warning per
+file; `codestyle migrate --write` rewrites it.
+
+A place-wide exemption is an **override**: `{ files, rules, reason }`. An override can only
+lower a level, never raise it. A `rules` entry is the base level of its rule and a ceiling
+over a finding's own level; without one, a finding's own level wins. A reason may carry `until YYYY-MM-DD`: from `until − 7` days
+through `until` itself (inclusive) the exemption reports at `warn`; after the date it stops
+applying and is reported. A malformed date is a config error. A rule
+may require that date on every override of it (`exemptionsRequireUntil`).
 
-`exports` **is** the public surface. Anything not listed is private — a linked package
-resolves deep paths that break the moment it is published.
+## `--json`
 
-## The one design rule: export data, never factories
+```ts
+{ schemaVersion: 1, ok, scanned, errors, warnings,
+  rules: [{ name, level, title, tags, owner: 'package' | 'custom' | 'eslint' | 'test' }],
+  findings: [{ rule, level, file, line, message }],
+  skipped?: { file, reason },                      // --stdin: outside `files`, under `ignores`, or no rule scopes it
+  selfTest?: { ok, failures } }                    // present whenever the self-test ran
+
+// a tool failure (exit 2) under --json:
+{ schemaVersion: 1, ok: false, error }
+```
+
+`owner` is `package` (this package's rules), `custom` (the repo's own), `eslint` or `test`
+(declarations: never run, here so their names stay live). `schemaVersion` changes only with
+a breaking shape change. ESLint- and test-owned declarations appear in `rules` with no
+findings. Output always drains before the process exits — a large report through a pipe
+arrives whole.
+
+## What checks what
 
-Consumers compose. There is no `defineBrighterlyEslint({...})`, and there never will be —
-the four apps' configs are ~95% identical and the variance is mostly drift, so a factory
-would parameterise accidental difference.
+| Tool | Answers | Runs |
+|---|---|---|
+| ESLint (+ this package's flat config and local rules) | "is this file well-formed by our style?" — one file's AST, IDE feedback, autofix | editor, pre-commit, CI |
+| **This package** | "does the repo still satisfy its contracts?" — anything needing a second file, a registry, the test tree, SCSS/assets/config surfaces, project semantics, or an audited exemption | pre-commit (`--staged`), CI (whole repo), the AI write-time hook (`--stdin`) |
+| Auditor | "what in the repo's state needs a human decision?" — dead code, dependency health, churn, LLM change review, and the trend of this package's warnings | explicit, human-triggered |
+
+If one file's AST decides it and a plugin or a small shared rule can say it, it is ESLint —
+declared in `custom` with `owner: 'eslint'` so there is one catalogue. If the author can fix
+it before the commit lands, gate it here; if it needs history, external signals or judgment,
+it belongs to the auditor, which reads `codestyle check --json` rather than grepping.
+
+## Wiring a consumer
+
+```jsonc
+// package.json
+"scripts": {
+  "codestyle": "codestyle check",
+  "codestyle:e2e": "codestyle check --tags=e2e",
+  "validate": "codestyle validate"
+}
+```
+
+- **Pre-commit**: the hook file is one line, `pnpm exec codestyle precommit`. Keep it in a
+  tracked directory and arm it from `postinstall` with `git config core.hooksPath <dir> || true`
+  (the `|| true` keeps installs without `.git`, such as Docker builds, green).
+- **CI**: one step, `pnpm exec codestyle validate`, with the full chain declared in
+  `validate` (the codestyle check, lint, tests, typecheck).
+- **AI write-time hook**: `codestyle check --stdin --file=<repo-relative path> [--tags=<x>]`
+  checks content before it reaches the disk; a path outside `files`, under `ignores`, or scoped
+  by no selected rule comes back as `skipped`.
+- **Agent rules file**: declare `docs: [{ template, output, tags }]` and run `codestyle docs`;
+  the generated file says so in its first line and is never edited by hand. Put
+  `codestyle docs --check` in `validate` so drift fails the gate.
+- **CLAUDE.md**: paste [docs/consumer-claude-md.md](docs/consumer-claude-md.md).
+
+## The ESLint config — export data, never factories
 
 ```js
 // an app that needs nothing extra
@@ -46,194 +229,67 @@ export default [
 ]
 ```
 
-ESLint **replaces** rule options rather than merging them, so appending an override without
-spreading the shared map silently discards every shared entry. That is why the maps are
-exported as data.
-
-
-## What the rule pack ships
-
-### Invariants — `@brighterly/lib-fe-codestyle/invariants/rules`
-
-| Rule | Level | Checks |
-|---|---|---|
-| `core/R1` | warn* | bare `localStorage` / `sessionStorage` — the accessor itself throws on Safari ITP and in-app webviews |
-| `core/R2` | error | SCSS rules inline in a Vue `<style>` block instead of a referenced `.scss` file |
-| `core/R3` | warn* | `JSON.parse` with no enclosing `try`/`catch` — a corrupt entry breaks that path permanently |
-| `core/R4` | error | `@font-face` declaring a font *stack* — an invalid descriptor, so the browser drops the face silently |
-| `core/C1` | warn | hand-rolled browser API with a VueUse equivalent |
-| `core/C2` | warn | a component duplicating an existing UI-kit component name |
-| `core/C3` | warn | a literal colour in SCSS instead of a design token |
-| `core/C4` | warn | a hand-rolled date format string, or `toISOString()` |
-| `core/C5` | warn | a type file outside the `types/<entity>/{enums,interfaces,types}.ts` structure |
-| `core/C6` | warn | a raw `font-family` / `font-size` / `font-weight` declaration instead of the app's typography source |
-| `core/C7` | warn | `<script>` attribute order differing from the app's canonical (`setup lang` vs `lang setup`) |
-
-Level discipline: `error` is for crash-class rules (`core/R*`); `warn` is for
-conventions (`core/C*`). `core/R1`/`core/R3` (marked *) ship at `warn` **as an interim
-state** (2026-09-25): their fleet backlog is real code nobody has bandwidth to migrate
-and re-verify right now. Their target level is `error` — promote once the backlog
-clears (a breaking-style bump). `core/R2`/`core/R4` stay `error`. A consumer's `levels`
-ceiling is still never the tool for a backlog on an `error` rule — fix or allowlist.
-Underscore-prefixed SCSS partials (`_extends.scss`, `_colors-*.scss`, …) are declaration
-files by convention in every Brighterly app and are exempt from `core/C3`/`core/C6` wholesale.
-
-`core/R*` were ported from land-app, where each was a production scar (as `R1`, `R7`, `R18`,
-`R28` — renumbered sequentially when the prefix landed, pre-publish, while no released
-version pinned the old tokens). `core/C*` are conventions with
-no incident behind them *yet* — they ship at `warn` so a consuming app can measure what they
-find before anyone decides to block on them. Promoting one to `error` is a **major** bump.
-
-Fixtures ship with the rules (`commonFixtures`), so `--self-test` works in any consumer
-without it having to write fixtures for rules it did not author.
-
-### ESLint — `@brighterly/lib-fe-codestyle/eslint`
-
-Seven local rules: `padding-after-macros`, `async-components-after-macros`,
+ESLint **replaces** rule options rather than merging them, so an override that does not
+spread the shared map silently discards every shared entry — that is why the maps are
+exported as data. Seven local rules: `padding-after-macros`, `async-components-after-macros`,
 `no-import-group-labels`, `ref-prefix-prop-mirrors`, `require-component-name`,
-`on-prefixed-callbacks`, and `optional-callback-chaining` (new — an optional callback
-invoked without `?.` throws for the first caller that omits it).
-
-Plus the shared flat config: restricted syntax, restricted imports, the types-organization
-blocks, and the `check-file` naming maps — all exported as data so a consumer can spread
-and extend them.
-
-## App-specific paths: `settings`, not parameters
+`on-prefixed-callbacks`, `optional-callback-chaining`.
 
-A shared rule must not hardcode a consuming app's paths. Each app declares them once:
-
-```ts
-// invariants/config.mts
-export const settings = {
-  safeStorageModule: 'safeLocalStorage from @helpers/safe-local-storage',
-  safeStorageFile:   'app/utils/helpers/safe-local-storage.ts', // core/R1 auto-exempts the wrapper itself
-  safeJsonParse:     'parseStoredJson() from @helpers/safe-local-storage',
-  scssTokensFile:    'app/assets/scss/_colors.scss',
-  uiKitRoot:         'app/components/UI',
-  dateFormatModule:  'DateFormat from @ts-types/date/enums',
-  typesRoot:         'app/types',                              // core/C5 (default shown)
-  typographySource:  'the font() mixin from @scss/_mixins.scss', // core/C6 — cs-app points this at its AppText component instead
-  scriptAttrOrder:   'setup-first',                            // core/C7 — or 'lang-first' (default 'setup-first')
-  selfTestFile:      'invariants/self-test.mts',               // its ignore-strings are fixture DATA — skipped by IG0/IG1
-}
-```
+## Imports
 
-A missing key degrades the rule's *message*, never its firing. A rule that went quiet
-because a path was unset would be the exact silent failure this package exists to prevent.
-Two keys shape behaviour rather than the message — `typesRoot` (where `core/C5` looks) and
-`scriptAttrOrder` (which direction `core/C7` flags) — and both fall back to the documented
-default above, so leaving them unset still never silences the rule.
-
-## What consumers see in the IDE
-
-Three hover surfaces, so "what rules do we have and what do they look for" never
-requires opening this repo:
-
-- **`sharedRuleIds`** (from `…/invariants/rules`) — the catalog: one constant per rule,
-  each JSDoc'd with level, what it checks, and the fix. Use them as `allowlists` /
-  `levels` keys (`[sharedRuleIds.core/C6]: 'off'`) and hover for the contract. A test pins
-  the catalog to the shipped rules, so it cannot drift.
-- **`SharedRuleSettings`** (from `…/invariants`) — annotate the app's `settings` const
-  with it to get completion plus the per-key contract, and a type error on an invalid
-  `scriptAttrOrder` value.
-- **ESLint squiggles** — every local rule ships `meta.docs.description`, which is what
-  the editor shows on hover over a violation.
-
-PhpStorm / WebStorm notes: the IDE runs the **project's own ESLint binary** against the
-flat `eslint.config.mjs`, so rules defined inside this package just work — nothing to
-install or configure beyond the default "Automatic ESLint configuration". Two real
-behaviours to know: the ESLint daemon caches the resolved config, so after upgrading
-this package run *ESLint: Restart Service* (or reopen the project) to pick up new
-rules; and the invariants engine is **not** an IDE inspection — its findings appear in
-the terminal (`pnpm validate:invariants`) and the pre-commit hook only.
+| Import | What it is |
+|---|---|
+| `@brighterly/lib-fe-codestyle` | `defineConfig`; the rule contract types (`Rule`, `RuleContext`, the proofs, …); the helpers custom rules share (`eachLine`, `setting`, `stripCodeComments`, `matchesAny`, the AST helpers, …); `packageRuleNames` |
+| `@brighterly/lib-fe-codestyle/eslint` | the shared flat config, its local rules and the maps behind them |
 
-## Wiring a consumer
+Everything else is reached through the `codestyle` binary. `src/` ships compiled as `dist/`
+(Node does not strip types inside `node_modules`); `eslint/` ships as plain `.mjs`.
 
-1. `pnpm add -D @brighterly/lib-fe-codestyle` — plus, if not already direct devDeps,
-   `@vue/compiler-sfc` and `typescript`. Both are **peers, not dependencies**, on
-   purpose: the validator must parse your files with the *same* compiler instance your
-   build uses, so the package dedupes onto the app's copy instead of carrying its own.
-   Every Brighterly Nuxt app already has both in the store — the devDep line adds a
-   symlink, not a download.
-2. An `invariants/` directory with `cli.mts` (a ~20-line composition root — copy
-   land-app's), `config.mts` (allowlists, levels, retired, unmaintained, `settings` —
-   see above), your app-local rules, and `specs/` for checks needing real module
-   resolution.
-3. A missing peer is loud, never silent: pnpm warns at install (and auto-installs by
-   default), and the engine's lazy `import()` throws on the first AST rule otherwise.
-4. Arm the pre-commit hook from install, not by hand: keep the hook script in a tracked
-   directory and add `git config core.hooksPath <that-dir> || true` to `postinstall`
-   (the `|| true` keeps .git-less installs — Docker builds — green). Setup stays
-   `pnpm i && pnpm dev`; a hand-made `.git/hooks` symlink dies with every fresh clone.
-
-An app with a pre-extraction fork of the engine (app-funnels) deletes its copied
-`ast/util/run/self-test` plumbing and keeps only domain rules + config; its existing
-compiler-sfc devDep already satisfies the peer.
-
-## Why `src/` is compiled but `eslint/` is not
-
-Node refuses to strip types inside `node_modules`
-(`ERR_UNSUPPORTED_NODE_MODULES_TYPE_STRIPPING`), so the TypeScript half ships as `dist/`.
-The ESLint config and its seven rules are already plain `.mjs` and ship as-is.
-
-## Rule IDs
-
-Shared rules carry the **`core/` prefix**: `core/R1`, `core/C3`. App-local rules stay bare:
-`R1`, `B2`. The prefix marks provenance — a `core/`-id is shipped by this package, never
-defined, renumbered or recycled in a consumer — and it keeps the two number lines
-independent: every app allocates its own `R1, R2, …` naturally, with no risk of
-colliding with a rule the package ships later. `run()` still exits 2 on a duplicate,
-so a collision is loud, not silent.
-
-Within the package each family is numbered sequentially with no gaps (`core/R1`–`core/R4`,
-`core/C1`–`core/C7`) — enforced by `test/invariants/rule-ids.test.ts`. The family letter keeps
-meaning provenance — `R` regression scar, `B` business, `C` convention, `L`
-linter-owned — not topic. `core/` in a report means exactly one thing: this finding
-comes from the library, and its numbering is the library's to own.
+In the IDE: `defineConfig` types the whole config, a `packageRuleNames` member's hover is
+that rule's contract, and ESLint squiggles carry each local rule's description. The rule
+engine is not an IDE inspection: its findings appear in the terminal and the pre-commit
+hook. After upgrading this package, run *ESLint: Restart Service*.
 
 ## Versioning is about blocking power
 
 One question decides the bump: **can this change turn a green consumer red, or break
-something a consumer wrote against a rule id?** Yes → major. Adds signal without
+something a consumer wrote against a rule name?** Yes → major. Adds signal without
 blocking → minor. Everything else → patch.
 
 | Change | Bump | Why |
 |---|---|---|
-| New invariant rule at `error` | **major** | can turn a green repo red on install |
+| New package rule at `error` | **major** | can turn a green repo red on install |
 | Promoting a rule `warn` → `error` | **major** | same — new blocking power |
 | Widening a rule's `scope`, narrowing its `exclude`, or making its match stricter | **major** | existing code that passed now fails |
-| Renaming, renumbering or removing a rule id | **major** | breaks every `invariant-ignore:` comment, `allowlists`/`levels` key and doc that names the token — `IG1` starts firing in every consumer |
+| Renaming or removing a rule name | **major** | breaks every `codestyle-ignore:` comment, `rules`/`overrides` key and doc that names it — `IG1` starts firing in every consumer |
 | New ESLint rule at `error`, or adding a selector to `restrictedSyntax` / `restrictedImports` / the `check-file` maps | **major** | the shared config is spread into every app's lint gate |
-| Engine behavior change (`run()` exit codes, finding shape, config contract) | **major** | consumers' composition roots are written against it |
-| New invariant rule at `warn` | minor | new signal, blocks nothing |
+| Engine behaviour change (exit codes, the `--json` shape, the config or rule contract) | **major** | consumers' configs, hooks and CI are written against it |
+| New package rule at `warn` | minor | new signal, blocks nothing |
 | New ESLint rule at `warn` | minor | same |
 | New export (a map, a helper, a settings key a rule *optionally* reads) | minor | additive surface |
 | Demoting a rule `error` → `warn`, or narrowing its scope | patch | strictly relaxing |
-| Bug fix that removes false positives, message/`why`/`fix` wording, fixture improvements | patch | nothing new fires |
+| Bug fix that removes false positives, message/`why`/`fix` wording, proof improvements | patch | nothing new fires |
 
-Two edges worth naming: a bug fix that removes **false negatives** (the rule now
-catches what it always claimed to) is still **major** — correctness of intent does not
-change what happens in a consumer's CI. And a new `settings` key a rule *requires* is
-major; one it merely reads for a better message is minor (a missing key degrades the
-message, never the firing — see above).
+Two edges worth naming: a bug fix that removes **false negatives** (the rule now catches what
+it always claimed to) is still **major** — correctness of intent does not change what happens
+in a consumer's CI. And a new `settings` key a rule *requires* is major; one it merely reads
+for a better message is minor.
 
 ## Publishing
 
-The package is published **publicly** to npmjs.org under the `@brighterly` org — the
-same channel as `@brighterly/lib-lumee-ui`, so consumers need no registry config or
-token. `publishConfig.access: "public"` in `package.json` makes the scoped publish
-work without a paid org plan.
+Published **publicly** to npmjs.org under the `@brighterly` org — the same channel as
+`@brighterly/lib-lumee-ui`, so consumers need no registry config or token.
 
 ```bash
-npm login                 # must be a member of the @brighterly org
-npm version <patch|minor|major>   # per the blocking-power table above
-npm publish               # prepublishOnly rebuilds dist and runs the tests first
+npm login                          # must be a member of the @brighterly org
+npm version <patch|minor|major>    # per the blocking-power table above
+npm publish                        # prepublishOnly rebuilds dist and runs the tests first
 git push && git push --tags
 ```
 
-`dist/` is gitignored; `prepublishOnly` (`clean → build → test`) guarantees the
-tarball is built from the current sources, never a stale artifact.
+`dist/` is gitignored; `prepublishOnly` (`clean → build → test`) guarantees the tarball is
+built from the current sources.
 
 ## Design
 
-`land-app/docs/superpowers/specs/2026-09-22-fe-codestyle-design.md`
+[docs/superpowers/specs/2026-10-16-consumer-architecture-v1-design.md](docs/superpowers/specs/2026-10-16-consumer-architecture-v1-design.md)

package/dist/cli.d.ts

@@ -0,0 +1,8 @@
+#!/usr/bin/env node
+/**
+ * `codestyle` — a thin argv switch over the engine. No engine logic lives here.
+ *
+ * Exit codes: 0 clean · 1 a finding at error, a failed proof, a stale doc or a failed step ·
+ * 2 the tool itself failed (usage, config).
+ */
+export {};