@noctcore/lint-meta-rules 0.6.0 → 0.6.2

package/docs/rules/security-scanner-version-parity.md

@@ -3,6 +3,10 @@
 > CI and the local pre-push hook pin the same secret-scanner version, and the hook checks it at run
 > time.
 
+<!-- begin generated rule header -->
+Runs under `@noctcore/harness`, not ESLint · Factory `createSecurityScannerVersionParityRule` from `@noctcore/lint-meta-rules` · Category `ci` · Fails CI by default: yes
+<!-- end generated rule header -->
+
 ## Why
 
 Different scanner versions ship different rulesets, so a push can pass the local hook and fail CI (or
@@ -20,8 +24,6 @@ With the defaults (gitleaks):
 - a hook `GITLEAKS_IMAGE="...gitleaks:vX.Y.Z"` tag that differs from CI,
 - a hook that never runs `gitleaks version`.
 
-Dormant when neither the workflows nor the hook mention the scanner.
-
 ```yaml
 # .github/workflows/security.yml
 env:
@@ -39,7 +41,15 @@ GITLEAKS_VERSION="8.29.0"
 gitleaks git .
 ```
 
-## Factory
+## What it does not flag
+
+- A repo where neither the workflows nor the hook mention the scanner: the rule is dormant.
+- Whether the hook's version comparison is correct: it checks only that the hook's text runs
+  `<scanner> version`.
+- Versions not written as `x.y.z`, and any hook other than `hookFile`. A repo with several hooks needs
+  one rule instance per hook.
+
+## Options
 
 ```ts
 createSecurityScannerVersionParityRule(options?: SecurityScannerVersionParityOptions): IMetaRule
@@ -54,8 +64,7 @@ createSecurityScannerVersionParityRule(options?: SecurityScannerVersionParityOpt
 | `workflowGlobs` | `string[]` | `['.github/workflows/*.yml', '.github/workflows/*.yaml']` | Workflow files to scan. |
 | `ciCritical` | `boolean` | `true` | Whether a violation fails CI. |
 
-## Limits
+## When not to use it
 
-It checks that the hook's text runs `<scanner> version`, not that the comparison is correct, and it
-reads only `x.y.z` versions. One hook file is checked; a repo with several hooks needs one rule
-instance per hook.
+If you run the secret scanner in only one place (CI or a local hook, not both), there is no second pin
+to keep in step.

package/docs/rules/service-image-digest-pin.md

@@ -2,6 +2,10 @@
 
 > Workflow service/container images and docker-compose images are pinned by `@sha256:` digest.
 
+<!-- begin generated rule header -->
+Runs under `@noctcore/harness`, not ESLint · Factory `createServiceImageDigestPinRule` from `@noctcore/lint-meta-rules` · Category `ci` · Fails CI by default: yes
+<!-- end generated rule header -->
+
 ## Why
 
 A tag (`postgres:17-alpine`) or `latest` names whatever the registry serves today, so a green build
@@ -11,9 +15,9 @@ can change under an unchanged commit, and a local run cannot promise the bytes C
 ## What it flags
 
 - In workflow files: `image:` under a job's `services:`, and a job's `container:` in scalar or mapping
-  form. An action step's `with: image:` input is not an image pull and is ignored.
-- In compose files: every service's `image:`, except a service that also has `build:` (there `image:`
-  tags an image built locally, which has no upstream digest).
+  form.
+- In compose files: every service's `image:`, including one behind an env default
+  (`${REDIS_IMAGE:-redis:7}`), which is reported as written since the text does not show a digest.
 
 Each violation carries the 1-indexed line.
 
@@ -32,7 +36,17 @@ services:
     image: app-api:local
 ```
 
-## Factory
+## What it does not flag
+
+- An image pinned as `tag@sha256:<digest>`.
+- An action step's `with: image:` input: it is not an image pull.
+- A compose service that also has `build:`: there `image:` tags an image built locally, which has no
+  upstream digest.
+- An exact ref listed in `allowUnpinned`, and compose files under a `skipDirs` segment.
+
+The check is line-based text, not a YAML parse.
+
+## Options
 
 ```ts
 createServiceImageDigestPinRule(options?: ServiceImageDigestPinOptions): IMetaRule
@@ -46,7 +60,7 @@ createServiceImageDigestPinRule(options?: ServiceImageDigestPinOptions): IMetaRu
 | `allowUnpinned` | `string[]` | `[]` | Exact image refs allowed unpinned, for a ref the registry cannot serve a digest for. Only that exact ref passes; a bumped tag is checked again. |
 | `ciCritical` | `boolean` | `true` | Whether a violation fails CI. |
 
-## Limits
+## When not to use it
 
-Line-based text, not a YAML parse. An image behind an env default (`${REDIS_IMAGE:-redis:7}`) is
-reported as written, since the text does not show a digest.
+If your workflows and compose files only run throwaway local services where you accept whatever a tag
+serves today, skip it.

package/docs/rules/session-epoch-captured.md

@@ -3,6 +3,10 @@
 > Every call into the sign-in seam passes the session epoch it captured before reading the
 > credential.
 
+<!-- begin generated rule header -->
+Runs under `@noctcore/harness`, not ESLint · Factory `createSessionEpochCapturedRule` from `@noctcore/lint-meta-rules/session` · Category `source-text` · Fails CI by default: yes
+<!-- end generated rule header -->
+
 Import it from the `session` entry point:
 
 ```ts
@@ -25,9 +29,11 @@ never mention the epoch.
 ## What it flags
 
 Each `.<call>(...)` call in a file matched by `sourceGlobs` whose argument text (found by balancing
-parentheses) does not mention `field` as a whole word.
+parentheses) does not mention `field` as a whole word. The parenthesis scanner reads each call on its
+own, so a call written on one line is checked too, and an unstamped call cannot borrow the epoch of
+the next one.
 
-## What it leaves alone
+## What it does not flag
 
 - `epochless: true`, or any identifier that merely contains the field: whole words only.
 - Files in `exempt` (the seam's own home, which defines the method and its default).
@@ -35,11 +41,7 @@ parentheses) does not mention `field` as a whole word.
 
 With no `call` the rule is inert.
 
-Ported from Settly, whose rule matched calls with a regex that stopped at the first `\n );` after the
-call. That missed a call written on one line, and let an unstamped one-line call borrow the epoch of
-the next multi-line call. The parenthesis scanner here reads each call on its own.
-
-## Factory
+## Options
 
 ```ts
 createSessionEpochCapturedRule(options?: SessionEpochCapturedOptions): IMetaRule
@@ -58,7 +60,11 @@ createSessionEpochCapturedRule(options?: SessionEpochCapturedOptions): IMetaRule
 | `hint` | `string` | none | Appended to every message. |
 | `ciCritical` | `boolean` | `true` | Whether a violation fails CI. |
 
-## Worked example: Settly
+### Worked example: an app with a post-credential sign-in seam
+
+Every sign-in entry point (password, OAuth, second factor) ends by calling one seam,
+`beginOrEstablish`, which a two-factor challenge service defines. Each entry point reads the epoch with
+`sessionService.readEpoch(userId)` before it checks the credential, and passes it in:
 
 ```ts
 createSessionEpochCapturedRule({
@@ -74,7 +80,7 @@ createSessionEpochCapturedRule({
 });
 ```
 
-Two Settly flows mint without a captured epoch and are outside the rule by construction, because they
+Two flows in such an app mint without a captured epoch and are outside the rule by construction, because they
 never call the seam: signup (the account did not exist when the request began) and password change (it
 revokes first and then re-issues, so the current counter is the right one).
 

package/docs/rules/session-kind-stamped.md

@@ -3,6 +3,10 @@
 > Every call that mints a session stamps the principal's kind onto it, or sits in an allowlisted,
 > provably single-kind flow.
 
+<!-- begin generated rule header -->
+Runs under `@noctcore/harness`, not ESLint · Factory `createSessionKindStampedRule` from `@noctcore/lint-meta-rules/session` · Category `source-text` · Fails CI by default: yes
+<!-- end generated rule header -->
+
 Import it from the `session` entry point:
 
 ```ts
@@ -17,7 +21,7 @@ mint that wrote it. A session minted without the field reads as whatever the rea
 fence between the two kinds that is a silent promotion: a portal account whose session lost its stamp
 is a staff caller inside its own tenant, and the tenant boundary waves it through as legitimate.
 
-This is not hypothetical. In the project this rule was extracted from, two re-issue paths (a password
+This is not hypothetical. In one production codebase, two re-issue paths (a password
 change and a revoke-other-sessions action, both reachable by a portal account) shipped without the
 stamp while every gate was green, because nothing mechanical looked.
 
@@ -32,10 +36,7 @@ parentheses, so a multi-line options object with nested calls is read whole):
    somewhere. Coarser, but no silent hole.
 3. Otherwise the file must be in `allowUnstamped`.
 
-Residual gap, stated rather than hidden: a file that stamps the field on one delegated mint and forgets
-it on a second delegated mint passes clause 2.
-
-## What it leaves alone
+## What it does not flag
 
 - `.<mintCall>Something(`, and the method's definition.
 - `kindless` or `kinds`: the field must appear as a whole word.
@@ -43,7 +44,10 @@ it on a second delegated mint passes clause 2.
 
 With no `mintCall` the rule is inert.
 
-## Factory
+Residual gap, stated rather than hidden: a file that stamps the field on one delegated mint and forgets
+it on a second delegated mint passes clause 2.
+
+## Options
 
 ```ts
 createSessionKindStampedRule(options?: SessionKindStampedOptions): IMetaRule
@@ -62,7 +66,11 @@ createSessionKindStampedRule(options?: SessionKindStampedOptions): IMetaRule
 | `hint` | `string` | none | Appended to every message. |
 | `ciCritical` | `boolean` | `true` | Whether a violation fails CI. |
 
-## Worked example: Settly
+### Worked example: an app with staff and portal accounts
+
+One sign-in serves staff accounts and invite-only portal accounts, and every session mint goes
+through `establishSession`. Self-signup only ever creates staff accounts, so its file is allowed to
+mint without a stamp:
 
 ```ts
 createSessionKindStampedRule({

package/docs/rules/session-landing-declared.md

@@ -3,6 +3,10 @@
 > Every file that opens a door into a session declares where it leaves the caller, and a door whose
 > landing demands a return shape has it.
 
+<!-- begin generated rule header -->
+Runs under `@noctcore/harness`, not ESLint · Factory `createSessionLandingDeclaredRule` from `@noctcore/lint-meta-rules/session` · Category `source-text` · Fails CI by default: yes
+<!-- end generated rule header -->
+
 Import it from the `session` entry point:
 
 ```ts
@@ -15,8 +19,8 @@ With two shells behind one sign-in (staff and a customer portal, say), the clien
 account to the right one if the response that ends the sign-in says which kind it is. The first door
 (the password sign-in) usually does. A second door that finishes a sign-in from a different service (a
 second-factor challenge) can return the same union and still have its landing unwired, and nothing
-fails: the account signs in, lands in the wrong shell, and bounces off its guard. In the project this
-rule was extracted from, every portal account with 2FA enabled did exactly that.
+fails: the account signs in, lands in the wrong shell, and bounces off its guard. In one production
+codebase, every portal account with 2FA enabled did exactly that.
 
 Two sibling rules fence the same seam, [`session-mint-callers`](./session-mint-callers.md) (who may
 mint) and [`session-kind-stamped`](./session-kind-stamped.md) (the session carries the kind). Neither
@@ -34,7 +38,7 @@ can see this, because both are about the session and this is about the RESPONSE.
 3. **The declarations.** A door whose `landing` is not a key of `landings`, or whose `because` is empty.
 4. **Staleness.** A door whose file no longer exists, or that `sourceGlobs` do not reach.
 
-## What it leaves alone
+## What it does not flag
 
 - A file that only defines a door method (the leading dot is required).
 - A door whose landing maps to `null`: a re-issue that replaces the cookie of a caller already inside a
@@ -43,7 +47,7 @@ can see this, because both are about the session and this is about the RESPONSE.
 
 With no `doorCalls` the rule is inert.
 
-## Factory
+## Options
 
 ```ts
 createSessionLandingDeclaredRule(options?: SessionLandingDeclaredOptions): IMetaRule
@@ -61,7 +65,11 @@ createSessionLandingDeclaredRule(options?: SessionLandingDeclaredOptions): IMeta
 | `hint` | `string` | none | Appended to every message. |
 | `ciCritical` | `boolean` | `true` | Whether a violation fails CI. |
 
-## Worked example: Settly
+### Worked example: an app with two sign-in shells
+
+Staff and portal accounts share one sign-in and land in different shells. Sessions open through
+`establishSession` or the second-factor gate `beginOrEstablish`. The two doors either kind can reach
+must return `Promise<ILoginResult>`; the rest are staff-only or re-issues:
 
 ```ts
 const AUTH = 'apps/api/src/modules/auth';

package/docs/rules/session-mint-callers.md

@@ -3,6 +3,10 @@
 > The method that mints a session is callable only from an allowlist of files, so a new sign-in
 > entry point cannot skip the gate in front of it.
 
+<!-- begin generated rule header -->
+Runs under `@noctcore/harness`, not ESLint · Factory `createSessionMintCallersRule` from `@noctcore/lint-meta-rules/session` · Category `source-text` · Fails CI by default: yes
+<!-- end generated rule header -->
+
 Import it from the `session` entry point:
 
 ```ts
@@ -23,7 +27,7 @@ session, so this rule fences the door by caller.
 A file matched by `sourceGlobs` that calls `.<mintCall>(` (whitespace before the paren allowed) and is
 not in `allowedCallers`.
 
-## What it leaves alone
+## What it does not flag
 
 - The method's definition (`async establishSession(`): the leading dot is required.
 - `.<mintCall>Something(`: only whitespace may sit between the name and the paren.
@@ -33,7 +37,7 @@ not in `allowedCallers`.
 
 With no `mintCall` the rule is inert.
 
-## Factory
+## Options
 
 ```ts
 createSessionMintCallersRule(options?: SessionMintCallersOptions): IMetaRule
@@ -51,7 +55,11 @@ createSessionMintCallersRule(options?: SessionMintCallersOptions): IMetaRule
 | `hint` | `string` | none | Appended to every message, e.g. a pointer to your auth docs. |
 | `ciCritical` | `boolean` | `true` | Whether a violation fails CI. |
 
-## Worked example: Settly
+### Worked example: an app with a gated session mint
+
+`establishSession` mints the session and `beginOrEstablish` is the second-factor gate every sign-in
+must pass through. Only the mint's home, the gate, signup and the two re-issue flows may call the mint
+directly:
 
 ```ts
 const AUTH = 'apps/api/src/modules/auth/services';

package/docs/rules/tenant-model-registry-parity.md

@@ -3,6 +3,10 @@
 > Every tenant-bearing Prisma model is scoped by the runtime tenant extension or exempt with a
 > reason, and the tenant lint rules resolve with exactly that registry.
 
+<!-- begin generated rule header -->
+Runs under `@noctcore/harness`, not ESLint · Factory `createTenantModelRegistryParityRule` from `@noctcore/lint-meta-rules/prisma` · Category `config` · Fails CI by default: yes
+<!-- end generated rule header -->
+
 Import it from the `prisma` entry point:
 
 ```ts
@@ -45,7 +49,17 @@ cannot be resolved.
 
 Async: it implements the harness's `runAsync` (`@noctcore/harness` 0.3.0 or newer).
 
-## Factory
+## What it does not flag
+
+- A schema model that carries only some of the `tenantFields` columns: a model must carry ALL of them
+  to be tenant-bearing.
+- A tenant-bearing model listed in `unscopedByDesign`, once it names its hand-scope columns in
+  `handScopedModels` or records why it cannot in `handScopePending`.
+- Hand-scope gaps when `requireHandScope` is `false`.
+- The resolved ESLint config when `eslint` is `false`; the hand-scope option when `handScopedRule` is
+  `null` or the registry has no hand-scoped models.
+
+## Options
 
 ```ts
 createTenantModelRegistryParityRule(options?: TenantModelRegistryParityOptions): IMetaRule
@@ -77,10 +91,10 @@ createTenantModelRegistryParityRule(options?: TenantModelRegistryParityOptions):
 
 Keys are Prisma delegate accessors (`invoice` for `model Invoice`).
 
-## Worked example: Settly
+### Worked example: a multi-tenant monorepo
 
-Settly scopes on `tenantId`, splits its schema per domain, keeps the runtime map in its API's tenant
-extension and the exemption maps in a registry module its ESLint config also reads:
+A project that scopes on `tenantId`, splits its schema per domain, keeps the runtime map in its API's
+tenant extension and the exemption maps in a registry module its ESLint config also reads:
 
 ```ts
 import { createTenantModelRegistryParityRule } from '@noctcore/lint-meta-rules/prisma';

package/docs/rules/test-runner-segregation.md

@@ -2,6 +2,10 @@
 
 > Bun-side and foreign-side test runners are never mixed within a package.
 
+<!-- begin generated rule header -->
+Runs under `@noctcore/harness`, not ESLint · Factory `createTestRunnerSegregationRule` from `@noctcore/lint-meta-rules` · Category `testing` · Fails CI by default: yes
+<!-- end generated rule header -->
+
 ## Why
 
 A package that mixes two test runners (e.g. `bun:test` and Vitest) has tests that run under one
@@ -15,10 +19,18 @@ and the **foreign set** (`vitestDirs`). For every `*.test.ts(x)` file:
 
 - **bun-side** — must import the bun runner (`bunRunnerImport`) and must NOT import the foreign runner
   (`foreignRunnerImport`);
-- **foreign-side** — must NOT import the bun runner. (A direct foreign-runner import is not required —
-  it may arrive transitively via shared test-utils.)
+- **foreign-side** — must NOT import the bun runner.
+
+## What it does not flag
 
-## Factory
+- A foreign-side test with no direct foreign-runner import: the runner may arrive transitively via
+  shared test-utils.
+- A bun-side test that imports `bunRunnerImport` and not the foreign runner.
+- Anything in a `vitestDirs` directory for a missing bun import (those dirs leave the bun set).
+- Files that are not `*.test.ts` / `*.test.tsx` (setup files, helpers), and `require()` or dynamic
+  imports: only a `from '<runner>'` import is read.
+
+## Options
 
 ```ts
 createTestRunnerSegregationRule(options?: TestRunnerSegregationOptions): IMetaRule
@@ -33,8 +45,6 @@ createTestRunnerSegregationRule(options?: TestRunnerSegregationOptions): IMetaRu
 | `foreignRunnerImport` | `string` | `'vitest'` | The foreign runner import specifier. |
 | `ciCritical` | `boolean` | `true` | Whether a violation fails CI. |
 
-De-projected from nightcore, which hardcoded `bun:test` vs `vitest` and the two dir sets.
-
 ## When not to use it
 
 If your repo uses a single test runner everywhere, this rule has nothing to segregate.

package/docs/rules/test-sibling-enforcement.md

@@ -2,10 +2,14 @@
 
 > Every source file matched by `include` must have a colocated sibling test.
 
+<!-- begin generated rule header -->
+Runs under `@noctcore/harness`, not ESLint · Factory `createTestSiblingEnforcementRule` from `@noctcore/lint-meta-rules` · Category `source-text` · Fails CI by default: yes
+<!-- end generated rule header -->
+
 ## Why
 
 A pure helper with no test is a silent liability — the kind of code that drifts because nothing pins
-its behavior. Requiring a colocated test for a chosen class of files (nightcore's `.utils.ts` sidecars)
+its behavior. Requiring a colocated test for a chosen class of files (`.utils.ts` helper files, say)
 makes "did you test this?" a mechanical check rather than a review-time hope.
 
 ## What it flags
@@ -14,7 +18,13 @@ For each file matched by an `include` glob, the sibling test is the same path wi
 extension replaced by each configured test extension. If none of those siblings exists, the source
 file is flagged. Strict — there is no baseline; the pattern is opt-in via which files `include` selects.
 
-## Factory
+## What it does not flag
+
+- A matched file with a sibling for any one of `testExtensions` (`foo.utils.test.ts` or
+  `foo.utils.test.tsx` for `foo.utils.ts`).
+- Files outside `include` (only `apps/web/src/**/*.utils.ts` by default).
+
+## Options
 
 ```ts
 createTestSiblingEnforcementRule(options?: TestSiblingEnforcementOptions): IMetaRule
@@ -26,9 +36,6 @@ createTestSiblingEnforcementRule(options?: TestSiblingEnforcementOptions): IMeta
 | `testExtensions` | `string[]` | `['.test.ts', '.test.tsx']` | Accepted colocated-test extensions (replace the source extension). |
 | `ciCritical` | `boolean` | `true` | Whether a violation fails CI. |
 
-De-projected from nightcore, which hardcoded `apps/web/src/**/*.utils.ts` and the `.utils.test.ts(x)`
-sibling shape.
-
 ## When not to use it
 
 If you colocate tests loosely or centralize them in a `__tests__` tree, retune `include`/`testExtensions`

package/docs/rules/test-workspace-enrollment.md

@@ -2,6 +2,10 @@
 
 > Every tested package must be enumerated in the aggregate test script.
 
+<!-- begin generated rule header -->
+Runs under `@noctcore/harness`, not ESLint · Factory `createTestWorkspaceEnrollmentRule` from `@noctcore/lint-meta-rules` · Category `testing` · Fails CI by default: yes
+<!-- end generated rule header -->
+
 ## Why
 
 When the CI test command is a hardcoded list of workspace paths, a package added without editing that
@@ -13,10 +17,17 @@ cannot silently escape CI.
 
 Reads the root manifest's `scriptName` command. For each candidate directory (from `packageGlobs`
 plus `extraDirs`, minus `excludeDirs`) that contains at least one file matching `testGlobSuffix`, if
-the directory string does not appear in the script command, it is flagged. A missing or invalid
-manifest is a no-op.
+the directory string does not appear in the script command, it is flagged.
+
+## What it does not flag
 
-## Factory
+- A candidate package with no file matching `testGlobSuffix`.
+- Directories in `excludeDirs` (tested by a different runner or script).
+- Anything when the root manifest is missing or is not valid JSON: the rule is a no-op.
+- A directory whose path appears anywhere in the script text: the check is a substring match, not a
+  parse of the command.
+
+## Options
 
 ```ts
 createTestWorkspaceEnrollmentRule(options?: TestWorkspaceEnrollmentOptions): IMetaRule
@@ -32,9 +43,6 @@ createTestWorkspaceEnrollmentRule(options?: TestWorkspaceEnrollmentOptions): IMe
 | `testGlobSuffix` | `string` | `'**/*.test.ts'` | Glob suffix (per dir) that detects the presence of tests. |
 | `ciCritical` | `boolean` | `true` | Whether a violation fails CI. |
 
-De-projected from nightcore, which hardcoded the `test:node` script, a `packages/*` + `apps/sidecar`
-dir list, and a vitest exclusion set.
-
 ## When not to use it
 
 If your test runner discovers packages automatically (no hardcoded path list), this rule is

package/docs/rules/translation-dead-keys.md

@@ -3,6 +3,10 @@
 > Every translation catalog key is reachable from the source: named by a translation call, or spelled
 > by some string in the code.
 
+<!-- begin generated rule header -->
+Runs under `@noctcore/harness`, not ESLint · Factory `createTranslationDeadKeysRule` from `@noctcore/lint-meta-rules/i18n` · Category `source-text` · Fails CI by default: yes
+<!-- end generated rule header -->
+
 Import it from the `i18n` entry point, which (unlike the main one) loads ESLint:
 
 ```ts
@@ -21,7 +25,27 @@ This rule resolves call sites with the same visitor and catalog loader as
 two checks never disagree on which key a call means. It then adds the data routes a per-file rule
 cannot see.
 
-## What counts as reached
+## What it flags
+
+Every key in `catalogs` that no scanned source reaches (the routes are listed under
+[What it does not flag](#what-it-does-not-flag)). What is left was named by no call and spelled by no
+string. On a production app with 1,824 keys this reported 55, and every one of them had zero
+references outside the catalogs.
+
+### Blind spots
+
+It is conservative, not complete. It reports a reached key as dead when the key arrives by a route it
+cannot see:
+
+- **Keys that never appear in the scanned source**: server-sent codes, a CMS, another app, JSON
+  config. List them in `allow`, or add the files that spell them to `sourceGlobs`.
+- **A variable key under a `keyPrefix` binding**: `useTranslation('ns', { keyPrefix: 'form' })` then
+  `t(field)` with `field = 'name'` reaches `form.name`, but no string spells `form.name`. (A static key
+  under a `keyPrefix` is resolved correctly.)
+- **Keys built by anything other than `+` or a template literal**: `[a, b].join('.')`,
+  `` `${a}` `` split across variables, `String.prototype.concat`.
+
+## What it does not flag
 
 A key is reached, and never reported, when ANY of these holds:
 
@@ -36,29 +60,13 @@ A key is reached, and never reported, when ANY of these holds:
   `` `nav.${id}.label` `` and `'errors.' + code` are patterns, not just call arguments;
 - it matches an `allow` pattern.
 
-And it reports **no dead key at all** when a scanned file cannot be analysed (a parse error), or when
+It reports **no dead key at all** when a scanned file cannot be analysed (a parse error), or when
 `sourceGlobs` match nothing: in both cases the rule would otherwise call reached keys dead.
 
-What is left was named by no call and spelled by no string. On a production app with 1,824 keys this
-reported 55, and every one of them had zero references outside the catalogs.
-
-## Blind spots
-
-It is conservative, not complete. It reports a reached key as dead when the key arrives by a route it
-cannot see:
-
-- **Keys that never appear in the scanned source**: server-sent codes, a CMS, another app, JSON
-  config. List them in `allow`, or add the files that spell them to `sourceGlobs`.
-- **A variable key under a `keyPrefix` binding**: `useTranslation('ns', { keyPrefix: 'form' })` then
-  `t(field)` with `field = 'name'` reaches `form.name`, but no string spells `form.name`. (A static key
-  under a `keyPrefix` is resolved correctly.)
-- **Keys built by anything other than `+` or a template literal**: `[a, b].join('.')`,
-  `` `${a}` `` split across variables, `String.prototype.concat`.
-
 It also misses some dead keys, by design: any string that happens to equal a key (in any namespace)
 keeps it alive, and a broad pattern such as `` `${x}.title` `` keeps every `*.title` alive.
 
-## Factory
+## Options
 
 ```ts
 createTranslationDeadKeysRule(options?: TranslationDeadKeysOptions): IMetaRule
@@ -92,7 +100,12 @@ createTranslationDeadKeysRule({
 });
 ```
 
-## Requirements
+### Requirements
 
 The `i18n` entry needs the optional peers `eslint` (>= 9) and `@typescript-eslint/parser`. Scanned
 files are parsed as TypeScript with JSX enabled, without type information.
+
+## When not to use it
+
+If most keys reach the app from outside the scanned source (server-sent codes, a CMS, another app),
+`allow` would have to list most of the catalog and the rule proves little, so skip it.

package/docs/rules/ui-primitive-shape.md

@@ -2,6 +2,10 @@
 
 > A folder primitive must ship its proof siblings; a flat primitive must carry none at the ui root.
 
+<!-- begin generated rule header -->
+Runs under `@noctcore/harness`, not ESLint · Factory `createUiPrimitiveShapeRule` from `@noctcore/lint-meta-rules` · Category `source-text` · Fails CI by default: yes
+<!-- end generated rule header -->
+
 ## Why
 
 The primitives root is the one place exempt from folder-per-component: flat single files are fine for
@@ -18,7 +22,15 @@ tested + storied.
   `<Name>.<role><extension>` at the ui root is flagged: those proof files belong inside a `<Name>/`
   folder.
 
-## Factory
+## What it does not flag
+
+- A bare flat primitive (`<uiRoot>/Button.tsx`) with no proof sibling at the ui root.
+- A folder primitive that ships every configured role (`Dialog/Dialog.test.tsx`,
+  `Dialog/Dialog.stories.tsx`).
+- A folder without the `barrelFile`, and flat files whose name does not start with a capital letter.
+- Anything outside `uiRoot`.
+
+## Options
 
 ```ts
 createUiPrimitiveShapeRule(options?: UiPrimitiveShapeOptions): IMetaRule
@@ -32,9 +44,6 @@ createUiPrimitiveShapeRule(options?: UiPrimitiveShapeOptions): IMetaRule
 | `extension` | `string` | `'.tsx'` | Extension of primitive and proof files. |
 | `ciCritical` | `boolean` | `true` | Whether a violation fails CI. |
 
-De-projected from nightcore, which hardcoded `apps/web/src/components/ui`, the `test`/`stories` roles,
-and the `.tsx` extension.
-
 ## When not to use it
 
 If you do not maintain a flat-vs-folder primitive convention or do not colocate stories/tests, skip

package/docs/rules/workspace-graph-parity.md

@@ -3,6 +3,10 @@
 > Imported `<scope>/*` specifiers must be declared `workspace:*` deps, and tsconfig `references` must
 > mirror those deps.
 
+<!-- begin generated rule header -->
+Runs under `@noctcore/harness`, not ESLint · Factory `createWorkspaceGraphParityRule` from `@noctcore/lint-meta-rules` · Category `config` · Fails CI by default: yes
+<!-- end generated rule header -->
+
 ## Why
 
 A cross-package edge is real in three places at once: the import in source, the `workspace:*` entry in
@@ -14,13 +18,21 @@ so an edge can never be half-wired.
 
 For each workspace `package.json`:
 
-- **(a) imported ⊆ declared** — every `<scope>/<pkg>` imported under the source dir (test files
-  excluded, self-imports ignored) must appear as a `"<scope>/<pkg>": "workspace:*"` dependency.
+- **(a) imported ⊆ declared** — every `<scope>/<pkg>` imported under the source dir must appear as a
+  `"<scope>/<pkg>": "workspace:*"` dependency.
 - **(b) references mirror deps** — the tsconfig `references` must reference exactly the declared
   workspace deps: a declared dep missing from references, or a referenced package that is not a
   declared dep, is a violation.
 
-## Factory
+## What it does not flag
+
+- A package importing itself by its own `<scope>/<dir>` name.
+- Imports in test files (`.test.ts`, `.test.tsx`) and files outside `srcDir`.
+- Imports without a `from` clause (`import()`, `require()`, a side-effect `import`): only
+  `from '<scope>/<pkg>'` is read.
+- Check (b) for a package with no `tsconfig.json`.
+
+## Options
 
 ```ts
 createWorkspaceGraphParityRule(options?: WorkspaceGraphParityOptions): IMetaRule
@@ -33,8 +45,6 @@ createWorkspaceGraphParityRule(options?: WorkspaceGraphParityOptions): IMetaRule
 | `srcDir` | `string` | `'src'` | Source directory (per package) scanned for imports. |
 | `ciCritical` | `boolean` | `true` | Whether a violation fails CI. |
 
-De-projected from nightcore, which hardcoded the `@nightcore` scope and a `src` source directory.
-
 ## When not to use it
 
 If your project does not use the `workspace:*` protocol, or does not use TypeScript project