# Strict Oxlint and Oxfmt Engineering Standard

**Version 5.4 · 20 November 2026**

- **Canonical agent-readable Markdown (always the latest version):** `https://fitchhub.com/standards/oxlint-oxfmt.md`
- **Pinned release Markdown (this version only):** `https://fitchhub.com/standards/oxlint-oxfmt/v5.4.md`

This standard defines linting, formatting, typechecking, and verification requirements for JavaScript and TypeScript repositories. It is written primarily for coding agents implementing or updating quality enforcement in a target repository, and for engineers and reviewers governing that work.

**Apply strict checks by default. Relax an applicable rule only when the best reasonable compliant implementation demonstrably harms a supported contract or introduces disproportionate complexity without a meaningful safety or correctness benefit.**

**Treat this standard as a baseline floor, not a ceiling. Do not weaken stricter rules, tighter thresholds, or extra checks that are already working well and delivering real value in the target repository; keep them and raise them to the user driving the work so they can be considered for upstream adoption in this standard.**

**Treat every package version named in this standard as a minimum floor, never a pin or ceiling. Always install the latest published releases available from the registry, inspect the installed schemas, declarations, and documentation, and adjust configuration or flags to match the installed toolchain.**

**If any mandated rule, option, threshold, or requirement in this standard causes regressions in the target repository, raise those concerns directly to the user driving the work with concrete evidence before weakening enforcement or introducing workarounds.**

The objective is software that is correct, maintainable, readable, consistent, appropriately reusable, and efficient. Automated checks support that objective; passing them is necessary for acceptance but does not by itself establish engineering quality.

This document is self-contained. Each adopting repository supplies its own configurations, source mappings, verification commands, and local exception records. No prior releases or external conversations are required to interpret or apply it.

Adoption covers both first-time implementations and upgrades from earlier versions of this standard, including correcting existing nonconformance and harmful compliance patterns within the declared scope.

## Contents

1. [Quality, current-date grounding, and authority](#1-quality-current-date-grounding-and-authority)
2. [Quality exceptions](#2-quality-exceptions)
3. [Code design and behavioral contracts](#3-code-design-and-behavioral-contracts)
4. [Source coverage and compiler requirements](#4-source-coverage-and-compiler-requirements)
5. [Toolchain and lint requirements](#5-toolchain-and-lint-requirements)
6. [Frameworks and test runners](#6-frameworks-and-test-runners)
7. [Formatting and generated artifacts](#7-formatting-and-generated-artifacts)
8. [Verification and enforcement integrity](#8-verification-and-enforcement-integrity)
9. [Adoption, upgrades, and escalation](#9-adoption-upgrades-and-escalation)
10. [Acceptance and maintenance](#10-acceptance-and-maintenance)

- [Appendix A: Base Oxlint configuration](#appendix-a-base-oxlint-configuration)
- [Appendix B: Repository records](#appendix-b-repository-records)
- [Appendix C: Changelog](#appendix-c-changelog)
- [References](#references)

## 1. Quality, current-date grounding, and authority

### 1.1 Quality criteria

Evaluate resulting code against all six criteria:

| Criterion       | Required outcome                                                                                       |
| --------------- | ------------------------------------------------------------------------------------------------------ |
| Correctness     | Supported behavior, public contracts, security boundaries, and failure semantics remain sound.         |
| Maintainability | Responsibilities and state ownership are clear; changes have understandable, bounded effects.          |
| Readability     | Names, control flow, and interfaces support local reasoning without unnecessary indirection.           |
| Consistency     | Equivalent operations follow established project conventions and use the same authoritative contracts. |
| Reuse           | Shared domain knowledge, types, schemas, validation, and utilities have appropriate common ownership.  |
| Efficiency      | Resource use, execution order, concurrency, and runtime cost fit the actual workload and contracts.    |

A reduction in line count or diagnostic count is not by itself evidence of improvement. A gain in one criterion cannot justify incorrect behavior or unsafe data flow.

### 1.2 Current-date, native-first engineering

Agents and engineers often operate on incomplete or outdated assumptions about what a language, runtime, compiler, linter, formatter, or package provides. Treat memory as a lead, never as proof:

- **Install the latest releases.** Version numbers cited in this standard are minimum floors verified at publication time, not pins or upper bounds. Install the latest published versions of `oxlint`, `tsrs`, `oxfmt`, compilers, and project quality packages through the repository's package manager, and adapt configs or CLI flags whenever newer releases change schemas, defaults, or native capabilities.
- **Inspect installed code and current documentation.** Before designing a workaround, custom wrapper, rule override, exception, or test, inspect the actual installed package source, type declarations (`node_modules/**/*.d.ts`), tool schemas (`configuration_schema.json`), CLI help, and current-date official documentation for the exact versions in use.
- **Lean on native capabilities.** Prefer built-in language syntax, runtime APIs, compiler guarantees, native linter rules and options, formatter capabilities, and first-class package primitives over custom shims, hand-rolled wrappers, or bespoke enforcement code.
- **Verify against the real toolchain.** Check rule behavior, declaration origins, and config composition directly against the installed binaries instead of inferring behavior from older tools such as ESLint or Prettier.

### 1.3 Requirements, discretion, and escalation

**Must** identifies a requirement. **Should** identifies a recommendation whose applicability depends on the stated context. **May** identifies a permitted choice. Configuration blocks and limits are normative where their stated profile applies.

Implementers must apply the baseline and defined profiles. An **implementation mapping** selects actual repository files, runtimes, framework settings, test-runner profiles, or commands without reducing required enforcement. Applying a defined profile (such as the test profile or `node:test` runner mapping) to genuine matching files is a mapping, not an exception.

A **relaxation** disables an applicable rule, weakens an option, raises a limit, broadens an allowance, or reduces the source operations a required check examines. It remains a relaxation whether expressed through an override, directive, nested config, CLI flag, plugin list, wrapper, or custom rule. Every repository-specific relaxation beyond the defined profiles requires a quality exception under Section 2.

An instruction to adopt or update this standard authorizes implementation work and evidence-backed Section 2 quality exceptions. Existing review requirements, branch protections, ownership constraints, and repository permissions remain in force. Adoption alone does not authorize merging, deploying, altering product contracts, or overwriting unrelated work.

**Mandatory regression escalation:** If you determine that a mandated rule, option, threshold, or requirement in this standard causes regressions in the target repository — breaking supported behavior, degrading runtime or type safety, conflicting with current upstream tool or runtime contracts, or forcing harmful workarounds — you must raise those concerns directly to the user driving the work with concrete evidence (see Section 9.4).

**Baseline floor, not a ceiling:** This standard defines minimum required quality enforcement, not a strictness cap. If the target repository already enforces stricter lint rules, tighter structural thresholds, additional compiler checks, or stronger domain guardrails that work cleanly without inducing over-engineered workarounds, keep them intact and surface them to the user driving the work for potential upstream adoption in this standard (see Section 9.5).

Additional architectural rules must come from repository instructions or a demonstrated engineering need. This standard does not impose universal bans on barrels, mutable resource types, single-consumer helpers, or checked JavaScript.

## 2. Quality exceptions

### 2.1 Eligibility

Use a straightforward compliant implementation whenever one is reasonably available. A quality exception is permitted only when a concrete comparison demonstrates that the best reasonable compliant implementation would:

1. Harm supported functionality, sound typing, correctness, or safety, including an established ownership, lifecycle, accessibility, compatibility, or performance contract; or
2. Introduce disproportionate verbosity, indirection, or complexity without a meaningful safety or correctness benefit.

The resulting implementation must still satisfy Section 1.1 and every boundary in Section 2.5. Exceptions may address lint rules, structural thresholds, or formatting requirements. A checker limitation must be demonstrated on the installed toolchain; calling a finding a false positive does not establish eligibility.

Modest explicit typing, boundary validation, or meaningful decomposition is normal compliance work. Fewer lines, stylistic preference, migration effort, deadlines, historical practice, and the desire for green checks are not grounds for an exception. Compare realistic alternatives; do not fabricate awkward rewrites to justify an exemption.

### 2.2 Decision process

Each exception must establish:

1. **The finding.** Identify the installed tool versions, rule and options, affected operation, and reproducible diagnostic. Inspect project membership, `.d.ts` declarations, and effective configuration (`oxlint --print-config`) before attributing the problem to the rule.
2. **The contract.** Explain the behavior, type relationship, ownership, or design responsibility that must remain correct. Cite the relevant code, consumers, or API contract.
3. **The comparison.** Present the best reasonable compliant alternative and demonstrate one of the two grounds in Section 2.1. For complexity claims, show the concrete code and explain why its extra machinery adds no meaningful safety or correctness benefit.
4. **The adjustment.** Select the narrowest scope and least reduction in checking that resolves the demonstrated problem: a native rule option, declaration-qualified allowance, operation-bound directive, or file-scoped override. Preserve all unaffected protections. A global change requires evidence of a mismatch across the rule's entire relevant scope that a narrower adjustment cannot address.
5. **The remaining protection.** Verify that the intended code passes and state clearly what detection is lost and what other checks protect the affected contract.
6. **The review record.** Record the decision in Appendix B and include the code, configuration, and verification in the same reviewable change.

If an exception cannot resolve a mandated requirement cleanly because the requirement itself induces regressions across the repository, escalate to the user under Section 9.4 instead of normalizing a workaround.

### 2.3 Structural and unsafe-type evidence

For a structural exception, compare the proposed implementation with the best compliant alternative, including any helpers or signature changes it introduces. Record the metric before and after and explain the concrete effect on responsibilities, contracts, or readability.

For `no-explicit-any` or any `no-unsafe-*` exception, brevity or stylistic preference is never sufficient. Trace the exact value and type flow, explain why the operation is sound despite the diagnostic, show how untrusted data is validated or constrained before trusted use, and record every safety assumption that remains unverified by the type system.

### 2.4 Scope, directives, and automated directive enforcement

Use native configuration when it expresses the intended scope cleanly. When a single site is more precise, use a next-line directive for one rule with a stable exception identifier and concise reason:

```ts
// oxlint-disable-next-line unicorn/prefer-add-event-listener -- QX-001: SDK exposes only an onMessage callback property.
```

Blanket, file-wide, and range lint disables, ESLint disable directives (`eslint-disable*`), and undocumented inline disables are prohibited. If one operation legitimately requires more than one exception, identify each rule explicitly and verify attachment against the installed Oxlint version.

Keep site directives tied to specific authorized operations rather than vague prose. Remove unused directives immediately (enforced by `reportUnusedDisableDirectives: "error"`) and prune stale exception records when dependencies, rules, or contracts change. No arbitrary exception quota or expiration date is required.

**Automated enforcement of directive format:** ESLint-ecosystem comment plugins such as `@eslint-community/eslint-plugin-eslint-comments` inspect only `eslint-disable*` comments and silently ignore `oxlint-disable-*`. When a repository wants mechanical enforcement of `QX-*` exception identifiers and single-line directive boundaries across CLI runs, `--fix`, and editor LSP, register a small native Oxlint JS plugin using `context.sourceCode.getDisableDirectives()` instead of building a custom parser or AST engine:

```js
// tools/oxlint-suppressions-plugin.mjs
const EXCEPTION_ID = /^QX-[A-Z0-9-]+:\s+\S/u;
const POLICY_RULE = "repo-policy/documented-disables";

export default {
  meta: { name: "repo-policy" },
  rules: {
    "documented-disables": {
      create(context) {
        return {
          Program() {
            const { directives } = context.sourceCode.getDisableDirectives();
            for (const directive of directives) {
              const rules = directive.value
                .split(",")
                .map((rule) => rule.trim())
                .filter(Boolean);
              if (rules.length === 0 || rules.includes(POLICY_RULE)) {
                throw new Error(
                  `Blanket or self-targeted disable directive is prohibited in ${context.filename}.`,
                );
              }
              if (
                !/^\s*oxlint-disable-next-line\b/u.test(directive.node.value)
              ) {
                context.report({
                  node: directive.node,
                  message:
                    "Only oxlint-disable-next-line directives are permitted.",
                });
                continue;
              }
              if (!EXCEPTION_ID.test(directive.justification.trim())) {
                context.report({
                  node: directive.node,
                  message:
                    "Disable directives must cite a recorded exception (for example, -- QX-001: reason).",
                });
              }
            }
          },
        };
      },
    },
  },
};
```

Register the plugin and enable its rule in the root Oxlint config. Oxlint resolves `jsPlugins` paths relative to the config file:

```json
{
  "jsPlugins": ["./tools/oxlint-suppressions-plugin.mjs"],
  "rules": {
    "repo-policy/documented-disables": "error"
  }
}
```

Throwing on blanket disables and on attempts to disable `repo-policy/documented-disables` prevents an inline directive from silencing the policy rule itself, while ordinary formatting mistakes still emit normal file-and-line diagnostics.

Oxlint's JS plugin support is in alpha and requires the Node-based `oxlint` npm package. Cover the plugin with a focused test (Section 8.1) and rerun that test after every Oxlint upgrade.

### 2.5 Non-negotiable boundaries

An exception must not:

- Conceal diagnostics through output filtering, finding-count budgets, skipped checks, or swallowed exit statuses.
- Remove maintained source from required lint, compiler, or formatter coverage.
- Disable compiler strictness, checked-JavaScript coverage, or required declaration checking.
- Replace sound types or validation with unjustified `any`, unsound predicates, misleading generics, or unsafe assertion chains.
- Hide the same operation behind aliases, reflection, wrappers, proxies, or removed annotations while claiming the original check still protects it.
- Reclassify production code as tests, static data, generated output, or fixtures to gain an exemption.
- Weaken test assertions or silently alter supported behavior.

## 3. Code design and behavioral contracts

### 3.1 Shared contracts and reuse

Before adding a type, schema, validator, decoder, or utility, locate the repository's existing authoritative definition and consumers. Reuse it when semantic contract, ownership, dependency direction, and distribution requirements match. Equivalent domain concepts must not gain competing definitions solely to clear local lint or compiler errors.

When a runtime schema owns a contract, derive its static types using the schema library's native facilities where appropriate. When an external API or independently owned type is authoritative, use explicit adapters or checked mappings rather than maintaining parallel declarations that drift.

Consolidate shared knowledge at the appropriate boundary without merging genuinely distinct domain models, transport formats, persistence records, or independently versioned APIs. Respect package layering and standalone distribution boundaries.

### 3.2 Types, validation, and ownership

Use accurate types, `unknown` at untrusted boundaries, explicit validation, and type narrowing. Validate external data where it enters the trusted model and avoid repeating redundant guards for invariants already established at that boundary.

Carry established contracts through accurate shared types instead of propagating `unknown` into trusted code and reconstructing ordinary property access or calls via reflection helpers.

Apply these idiomatic native boundary patterns rather than suppressions:

- **JSON parsing:** `const value: unknown = JSON.parse(text);` preserves native `SyntaxError` behavior and satisfies `typescript/no-unsafe-assignment` cleanly before validation. Use schema decoders when their error and fallback contract matches.
- **Dynamic `import(specifier)`:** TypeScript types non-literal dynamic `import(url)` as `Promise<any>`. Annotate the binding explicitly as `const mod: unknown = await import(specifier);` and narrow or validate `mod` before accessing exports. This passes `typescript/no-unsafe-assignment` cleanly on Oxlint with `tsrs` with zero directives.
- **Test doubles:** Build typed fakes and stubs using accurate interfaces, `satisfies`, or focused typed test helpers. Do not weaken production `no-unsafe-*` rules for test convenience. When mocking a genuinely untyped external boundary in tests, keep any required type boundary minimal and local to the test helper.
- **Parameter mutation (`no-param-reassign`):** Keep `{ "props": true }` by default. For files that legitimately mutate named parameters in place — such as Immer `draft` callbacks, reducer accumulators (`acc`), HTTP/RPC middleware (`ctx`, `req`, `res`), DOM builders, or SDK hooks whose contract observes mutation on a shared options object — use a file-scoped `ignorePropertyModificationsFor` override targeting the exact parameter names (keeping `props: true` everywhere else) rather than disabling `no-param-reassign` globally or adding lint-only copies or wrappers.

Use `readonly` views for borrowed data when they accurately express the contract, while preserving accurate mutable ownership and lifecycle types where mutation belongs.

### 3.3 Behavioral preservation and banned compliance shims

Typing, formatting, lint compliance, and decomposition must preserve supported behavior. Treat intentional behavioral improvements as separate behavioral work with appropriate tests.

| Area            | Contracts to preserve or explicitly change                                                                                      |
| --------------- | ------------------------------------------------------------------------------------------------------------------------------- |
| Errors          | Identity, subclass, code, `cause`, redaction, messages, thrown vs returned failures, and operator-visible output                |
| Data            | Accepted inputs, defaults, validation location, serialization, absent vs explicit `undefined`, ordering, and reference identity |
| Objects         | Object vs collection APIs, property access, getters, prototypes, and consumer expectations                                      |
| Async execution | Ordering, concurrency, registration and hook timing, cancellation, retries, cleanup, and rejection ownership                    |
| Resources       | Public signatures, receiver identity, lifecycle ownership, framework-required exports, and generated bindings                   |
| Distribution    | Package entrypoints, standalone execution, emitted artifacts, and deployment contracts                                          |

**Harmful compliance shims are prohibited.** Never distort runtime behavior or add artificial machinery solely to satisfy a lint or compiler diagnostic. Specifically, do not introduce:

- **Synthetic runtime guards on typed parameters** (such as throwing a fabricated `TypeError` on values already constrained by the TypeScript signature) when the contract does not call for runtime validation.
- **Artificial async yields** (such as `await Promise.resolve()` or dummy microtasks) added solely to satisfy async rules.
- **Reflection, descriptor, or double-cast dodges** (`Reflect.get`, `Object.getOwnPropertyDescriptor`, `as unknown as`, proxy indirection, or unused aliases) added to hide an operation from type or mutation rules.
- **Lint-only forwarding wrappers, dummy state, no-op assignments, or empty error handlers** whose only purpose is clearing a finding.
- **Custom shims reimplementing native language, runtime, or dependency features** that already exist in the installed toolchain.

Own asynchronous work through the appropriate `await`, `return`, or lifecycle/error handler. Preserve required sequential loops and resource limits. Use concise explanatory comments for intentional no-ops instead of dummy state or fake returns.

If satisfying a mandated rule appears to require any of the shims above or risks regressing supported behavior, inspect the installed API and rule documentation first; if a conflict remains, use a narrow Section 2 exception or escalate to the user under Section 9.4.

### 3.4 Decomposition

Extract meaningful responsibilities and clear interfaces. Keep control flow and assertions easy to follow locally. Evaluate cohesion and clarity, not raw file or helper count.

Avoid numbered-stage functions (`step1`, `step2`), compressed statements, dummy closures, or moving production logic into exempt profiles to beat a threshold. Use options objects when they express a coherent API, not as a mechanical workaround for every multi-parameter signature. Public APIs, constructors, and SDK callbacks retain their supported contracts.

### 3.5 Practices to correct

Review existing code as well as new changes within the declared adoption scope. Correct the following patterns wherever found; prior passing checks do not justify keeping them:

| Practice                                                                                                                                                  | Required correction                                                                                                    |
| --------------------------------------------------------------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------- |
| Duplicate types, schemas, validators, or guards restating an established contract                                                                         | Reuse the authoritative contract at the right boundary while preserving real ownership and distribution boundaries.    |
| Harmful compliance shims (synthetic `TypeError`s, fake `await Promise.resolve()`, reflection/cast dodges, lint-only wrappers/copies/aliases)              | Remove the shim and express the actual API and ownership directly using native idioms or a narrow Section 2 exception. |
| Misleading generics, unjustified casts or predicates, or annotation removal evading safety checks                                                         | Restore accurate types and checked value flow; document a narrow exception only if Section 2 is met.                   |
| Fragmentation or helper extraction done solely to satisfy a metric that does not apply                                                                    | Restore cohesive responsibilities and readable scenarios while keeping genuinely useful abstractions.                  |
| Accidental changes to errors, accepted inputs, serialization, scheduling, cleanup, or assertions during compliance edits                                  | Restore the supported contract, or handle the change as explicitly authorized and verified behavioral work.            |
| Obsolete stock-rule proof tests, legacy `oxlint-tsgolint` plumbing, finding-count baselines, or hand-rolled policy engines duplicating native tool checks | Remove obsolete scaffolding and rely on the native published toolchain and focused repo-owned checks.                  |

Verify consumers and responsibilities before deleting existing helpers or safeguards. Retain independently necessary launcher, resource, compatibility, and custom domain checks.

## 4. Source coverage and compiler requirements

### 4.1 Source profiles

Every maintained handwritten JavaScript and TypeScript file — implementation, tests, scripts, tooling, and executable templates — receives its applicable checks across `.js`, `.jsx`, `.mjs`, `.cjs`, `.ts`, `.tsx`, `.mts`, and `.cts` where used.

Classify files by actual contents and consumers:

| Profile                                                      | Required treatment                                                                                                        |
| ------------------------------------------------------------ | ------------------------------------------------------------------------------------------------------------------------- |
| Production, libraries, adapters, build/admin/quality tooling | Applicable lint, compiler, and formatter checks; production structural limits                                             |
| Tests and exclusively test-only support                      | Full applicable safety checks, assertion checks, and test structural limits                                               |
| Handwritten declarations and augmentations                   | Applicable lint, real declaration checking, and relevant public-consumer checks; no implementation-size metrics           |
| Static literal data                                          | Parsing, formatting, applicable typing/schema checks; no implementation-size metrics                                      |
| Dedicated negative type tests                                | Compiler-verified expected errors and passing counterparts; test structural limits                                        |
| Generated or vendored output                                 | Identifiable generator or upstream source, freshness/provenance check, and build/compatibility verification as applicable |

Helpers imported by both production and tests are production. A data module containing executable factories, calls, or orchestration is implementation. Maintained generators and executable templates carry full implementation requirements.

Verify that every maintained file is covered by the actual acceptance commands — not merely matched by an unused `tsconfig` or ignored by a stale ignore pattern. Missing ownership is a coverage bug, not a reason to add an exemption.

### 4.2 Compiler settings

Apply these options effectively to every maintained implementation project, including tests and scripts, while preserving appropriate runtime targets, module resolution, JSX mode, libraries, references, and asset handling:

```json
{
  "compilerOptions": {
    "strict": true,
    "noImplicitReturns": true,
    "noFallthroughCasesInSwitch": true,
    "noImplicitOverride": true,
    "noUncheckedIndexedAccess": true,
    "exactOptionalPropertyTypes": true,
    "noUncheckedSideEffectImports": true,
    "forceConsistentCasingInFileNames": true,
    "noCheck": false
  }
}
```

Projects that execute `.ts` or `.mts` directly in Node (via native type stripping) should also enable `"erasableSyntaxOnly": true` and `"verbatimModuleSyntax": true` so non-erasable syntax and value-vs-type import mismatches fail at compile time.

Apply these scoping rules cleanly across compiler projects:

- **Checked JavaScript (`allowJs` and `checkJs`):** Enable `"allowJs": true` and `"checkJs": true` only on compiler projects that actually own maintained JavaScript files (`.js`, `.mjs`, `.cjs`, `.jsx`). Do **not** enable `checkJs: true` on a TypeScript-only framework root config (such as a Next.js root `tsconfig.json` that keeps `allowJs: true` for framework integration) if doing so pulls generated build bundles (such as `.open-next/worker.js`) into typechecking. Keep maintained repository scripts in a dedicated `scripts/tsconfig.json` (with `allowJs: true` and `checkJs: true`) when the main app config is TypeScript-only.
- **Declaration checking and `skipLibCheck`:** Keep `"skipLibCheck": true` on normal application and mixed-runtime projects (for example, repositories combining Cloudflare Workers, Node, and DOM typings) to avoid unrelated third-party `.d.ts` collisions and to keep `tsrs --fast` lazy declaration parsing eligible. Check every handwritten `.d.ts`, `.d.mts`, and `.d.cts` file and module augmentation with `"skipLibCheck": false` — either directly or through a dedicated declarations `tsconfig` covering the handwritten declarations and their real dependency closure, without permissive stubs.
- **Idiomatic `noUncheckedIndexedAccess` patterns:** Prefer destructuring, `for...of`, `.find()`, or explicit narrowing in production code. In tests (where non-null assertions `!` are prohibited), use a small typed helper (such as `at(items, index)` that throws a descriptive error when an element is missing) rather than repeating defensive `if (!item) throw` boilerplate at every assertion site.
- **Idiomatic `exactOptionalPropertyTypes` patterns:** On internal React props and option interfaces that legitimately forward optional values, declare `prop?: T | undefined` explicitly. On external payload contracts, strict schema decoders, or object spreads where an explicit `undefined` key alters serialization or validation semantics, keep `prop?: T` and omit absent keys conditionally (`...(value !== undefined ? { prop: value } : {})`).

Every declared maintained project must actually execute through the canonical compiler or framework checker in acceptance. Individual strict-family options must not be disabled. `@ts-check` on selected files does not replace project-wide `checkJs: true` on maintained JavaScript projects. Ordinary implementation must not use `@ts-ignore`, `@ts-nocheck`, or `@ts-expect-error` to hide errors.

Dedicated negative type tests (`*.test-d.ts`) may use `@ts-expect-error` with a description of at least ten characters explaining the expected contract failure; the compiler must reject unused `@ts-expect-error` directives.

### 4.3 JavaScript and TypeScript

Both checked JavaScript and TypeScript are supported. Choose the form that produces the clearest maintainable implementation within the repository's runtime and distribution constraints. Native runtime type stripping (for example, Node running `.ts` directly) executes code without typechecking; always keep the full compiler gate active. Do not switch languages or abuse JSDoc inference gaps to bypass safety checks.

## 5. Toolchain and lint requirements

### 5.1 Published tools, version floors, and `tsrs`

**Minimum version floors (never pins or ceilings):**

| Tool         | Minimum floor verified by this standard | Install policy                                                |
| ------------ | --------------------------------------- | ------------------------------------------------------------- |
| `oxlint`     | `>= 1.94.0`                             | Always install latest published release (`oxlint@latest`)     |
| `tsrs`       | `>= 7.1.0-beta.tsrs3`                   | Always install latest published release (`tsrs@latest`)       |
| `oxfmt`      | `>= 0.79.0`                             | Always install latest published release (`oxfmt@latest`)      |
| `typescript` | `>= 7.0.2` (on TypeScript 7 projects)   | Keep on the latest release compatible with repository tooling |

Always install the latest available releases rather than pinning down to the floor versions above, and inspect the installed `configuration_schema.json`, CLI `--help`, and official docs to adjust configs or flags whenever newer releases evolve.

**Use `tsrs` as Oxlint's type-aware linting backend.** Do not install or retain `oxlint-tsgolint`. When `tsrs` is installed as a devDependency alongside `oxlint`, Oxlint automatically discovers `tsrs-lint` and uses it for `--type-aware` (and `--type-check` when enabled) with no extra configuration:

```bash
pnpm add -D oxlint@latest tsrs@latest oxfmt@latest
```

Use the repository's own package manager (`npm`, `pnpm`, `yarn`, or `bun`) and commit updated manifests and lockfiles so local development, coding agents, CI, and editors share one resolved dependency tree.

Keep the canonical compiler or framework typechecker (`tsc --noEmit`, `tsrs --noEmit`, framework `typegen && tsc --noEmit`, etc.) as a required gate with Oxlint `options.typeCheck: false` by default. `oxlint --type-check` only reports type diagnostics for files Oxlint lints, so ignored files and whole `tsconfig` graphs still require a dedicated compiler check. A repository may opt into `options.typeCheck: true` only after verifying compatibility with its TypeScript version, `tsconfig` graph, and ignored-file coverage.

**`tsrs` performance and CI memory controls:**

- Direct `tsrs --noEmit` defaults to pinned TypeScript's four checkers. Opt into `tsrs`'s fast preset with `--fast` or `TSRS_FAST=1`. The preset scales the checker count with the machine's cores (up to 32), and enables lazy type members, lazy `.d.ts` parsing when `skipLibCheck` or `noCheck` is set, and freeing of finished leaf files on eligible `--noEmit` runs.
- `tsrs-lint` (the backend that `oxlint --type-aware` runs) enables the fast preset **by default**. Set `TSRS_FAST=0` to disable it and return to four checkers.
- More checkers use more memory. On memory-constrained CI runners, lower the checker count instead of weakening checks:
  - **Direct `tsrs --noEmit` runs:** use `--checkers N`, `--singleThreaded`, or `--fast --maxMemory <size>` (for example, `8G`). `--maxMemory` applies to `--noEmit` checks only; `TSRS_MAX_MEMORY` is its environment equivalent.
  - **Type-aware lint runs:** set `TSRS_FAST=0`, or set a positive `RAYON_NUM_THREADS`, which sets both the parse thread count and the lint checker count.
- **Prefer those flags and environment variables over `compilerOptions.checkers`.** TypeScript 7 and `tsrs` accept `checkers` in `tsconfig.json`, and it also sets the `tsrs-lint` checker count, but TypeScript 6 rejects it as an unknown compiler option (`TS5025`). Add it to a `tsconfig.json` only when every tool that reads that file runs TypeScript 7 or `tsrs`.
- `tsrs` does not implement `--init` or `--showConfig`. `tsrs -b` accepts `--fast`, `--checkers`, and `--singleThreaded`, and rejects the other `tsrs`-only flags, including `--maxMemory` and `--lazyMembers`.

Lean on Oxlint's native diagnostic and inspection flags instead of building wrapper scripts:

- `oxlint --format=agent` — compact, single-line diagnostics designed for coding agents.
- `oxlint --format=default --debug=timings` — per-rule timing profile to diagnose slow lint runs. The `agent` format, which Oxlint selects automatically when it detects a coding-agent environment, omits the timing table.
- `oxlint --debug=files` — exact file list linted under current ignore patterns.
- `oxlint --print-config` — inspect effective resolved configuration and overrides.

Do not maintain a forked linter or hand-patched `node_modules` installation. If a latest release introduces a real regression or breaks required checks, retain the last passing toolchain, inspect upstream release notes and issues, and escalate if a mandated requirement is affected.

### 5.2 Base configuration, composition, and editor setup

Use the complete [Appendix A configuration](#appendix-a-base-oxlint-configuration). Adapt `$schema` paths and profile globs to the repository layout without weakening enforcement. Add applicable framework and test-runner mappings from Section 6. Keep local Section 2 exceptions clearly distinguishable from the baseline.

Configuration format:

- **Default:** `.oxlintrc.json` or `.oxlintrc.jsonc`. Both load without a JavaScript runtime and accept comments. Any custom repository script that reads `.oxlintrc.json` must use a JSONC parser rather than strict `JSON.parse`.
- **TypeScript config:** `oxlint.config.ts` or `oxlint.config.mts` using `defineConfig` from `"oxlint"` is useful when extending a config object imported from a shared package (`extends` in a JSON config accepts file paths only, not package names). Oxlint marks JavaScript and TypeScript configs experimental, and they require the Node-based `oxlint` npm package.
- **Auto-discovered names:** Oxlint finds only `.oxlintrc.json`, `.oxlintrc.jsonc`, `oxlint.config.ts`, and `oxlint.config.mts` on its own. A config with any other name or extension (for example, `oxlint.config.mjs` or `oxlint.config.js`) loads only when passed through `--config`; without that flag Oxlint ignores the file and lints with its default rules, with no warning. One directory can hold only one config file: Oxlint fails when a JSON config and a TypeScript config sit side by side.

**Editor and LSP configuration (VS Code / Cursor Oxc extension):**

- Leave `oxc.configPath` and `oxc.fmt.configPath` unset (`null`) whenever standard auto-discovery finds the config.
- When a custom path is required, use a **workspace-relative path** such as `"config/oxlint.json"`. Never use `${workspaceFolder}/...`: the extension expands only `${userHome}` and `${env:NAME}`, so the config fails to load and the language server lints with Oxlint's default rules instead of the repository's. Setting either path also disables nested config lookup in the editor.
- The language server reloads when a config file or a file listed in its `extends` changes. It does not watch other files that a TypeScript config reads at load time; restart the language server after editing those.

Active categories (`correctness`, `suspicious`, `perf`) enable rules beyond the explicit `rules` map; preserve their effective coverage. Applicable required rules run at `"error"`; `"off"` is limited to defined profiles or documented Section 2 exceptions. Keep `denyWarnings: true`, `typeAware: true`, `reportUnusedDisableDirectives: "error"`, and `respectEslintDisableDirectives: false`.

An explicit root `plugins` array replaces Oxlint's default plugin set. Preserve all six base entries (`eslint`, `typescript`, `unicorn`, `oxc`, `import`, `promise`) when adding framework plugins.

When using `extends`, nested configs, or overlapping `overrides`, verify effective composition using `oxlint --print-config` and actual lint runs across affected scopes rather than assuming array order alone. Passing `--config` / `-c` explicitly disables nested config lookup.

### 5.3 Structural profiles

| Metric                                                                   | Production | Tests and test-only support |
| ------------------------------------------------------------------------ | ---------: | --------------------------: |
| Modified cyclomatic complexity                                           |         10 |                          15 |
| Nesting depth                                                            |          3 |                           4 |
| Parameters (`max-params`)                                                |          5 |                           6 |
| Statements per function (`max-statements`)                               |         40 |                         Off |
| Effective lines per function, including IIFEs (`max-lines-per-function`) |         80 |                         Off |
| Effective lines per file (`max-lines`)                                   |        800 |                         Off |

Effective line limits exclude blank lines and comments (`skipBlankLines: true`, `skipComments: true`). Handwritten declarations and static literal data do not carry implementation-size limits; all other applicable checks remain active. Map test-only support files by actual role rather than relying solely on filename conventions.

Tighter structural tiers (such as `max-lines: 500` and `max-params: 4`) are valid and should be preserved under Section 9.5 on repositories that already pass cleanly at zero debt.

### 5.4 Deliberate baseline choices

| Setting                                                                                      | Engineering rationale and remaining protection                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                           |
| -------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| `array-callback-return: error`                                                               | Catches real missing-`return` bugs in `.map()`, `.filter()`, `.reduce()`, `.every()`, `.some()`, `.find()`, and `.sort()` callbacks with near-zero false positives.                                                                                                                                                                                                                                                                                                                                                                                                      |
| `max-lines: 800` and `max-params: 5` (production)                                            | Accommodates cohesive modules and real 5-argument SDK/framework callbacks without forcing artificial splitting or parameter-bag wrappers, while flagging genuinely bloated files and 6+ argument signatures that warrant options objects. Repositories already clean at tighter limits keep them (Section 9.5).                                                                                                                                                                                                                                                          |
| `unicorn/no-useless-undefined` with `checkArguments: false`, `checkArrowFunctionBody: false` | Prevents breakage on required `T \| undefined` positional arguments (`fn(undefined)`) and typed `() => T \| undefined` callbacks, while retaining checks on useless `let x = undefined` initializers and `= undefined` parameter defaults. Oxlint permits `return undefined` in any function whose return-type annotation is something other than exactly `void` or `undefined` (for example, `string \| undefined`, `unknown`, or `Promise<void>`); it flags it in functions annotated exactly `void` or `undefined` and in functions without a return-type annotation. |
| `import/no-cycle` with `ignoreTypes: false`, `ignoreExternal: true`                          | Enforces cycle-free static imports across repository-owned modules, including type-only imports (`ignoreTypes: false`). Oxlint always skips modules under `node_modules` and does not follow dynamic `import()` edges. On the verified floor version, `ignoreExternal` and `allowUnsafeDynamicCyclicDependency` are accepted but have no effect; Appendix A sets them so the intended scope holds if Oxlint implements them.                                                                                                                                             |
| `typescript/prefer-readonly-parameter-types: off`                                            | Accurate domain and resource types take priority over universal deep-readonly annotations. Direct parameter-mutation checks (`no-param-reassign`), readonly views, and `prefer-readonly` remain active.                                                                                                                                                                                                                                                                                                                                                                  |
| `typescript/strict-void-return: off`                                                         | Ordinary synchronous callbacks may legitimately ignore return values. Floating Promises and async-callback misuse remain checked.                                                                                                                                                                                                                                                                                                                                                                                                                                        |
| `typescript/no-base-to-string` with `checkUnknown: false`                                    | Unknown diagnostic values may legitimately be formatted; known base-object stringification and unsafe `any` propagation remain checked.                                                                                                                                                                                                                                                                                                                                                                                                                                  |
| `typescript/prefer-promise-reject-errors` with `allowThrowingUnknown: true`                  | Preserves existing error identity when forwarding caught `unknown` rejections while still rejecting `any`, known non-Errors, and empty `reject()`.                                                                                                                                                                                                                                                                                                                                                                                                                       |
| `no-await-in-loop: off`                                                                      | Sequential `await` in loops is frequently required for pagination, rate limits, ordered side effects, and resource lifetimes.                                                                                                                                                                                                                                                                                                                                                                                                                                            |
| `no-control-regex: off`                                                                      | Control-character validation and sanitization are legitimate; use legible escape sequences and tests.                                                                                                                                                                                                                                                                                                                                                                                                                                                                    |
| Test statement/function/file-size limits off                                                 | Clear, linear test scenarios and thorough assertions should not be fragmented purely for line count; complexity, nesting, and parameter limits remain active.                                                                                                                                                                                                                                                                                                                                                                                                            |

### 5.5 Common native-rule traps and idiomatic resolutions

Before writing a suppression or workaround for these recurring native rules, apply the idiomatic native pattern:

| Rule                                                                                                | Common trap                                                                                                                                                                                        | Idiomatic resolution                                                                                                                                                                                    |
| --------------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `preserve-caught-error`                                                                             | Wrapping a caught error in a new `Error` drops the original cause.                                                                                                                                 | Use ES2022 `new Error("...", { cause: error })`. Use a narrow Section 2 directive only when security/redaction contracts prohibit attaching raw underlying errors.                                      |
| `unicorn/prefer-add-event-listener`                                                                 | Assigning `target.onmessage = ...` or `window.onresize = ...`.                                                                                                                                     | Use `addEventListener` with `{ once: true }` or `{ signal }` (`AbortController`). Document a narrow Section 2 directive only when an SDK exposes an `on*` callback property without `addEventListener`. |
| `react-perf/jsx-no-new-object-as-prop` / `jsx-no-new-function-as-prop` / `jsx-no-new-array-as-prop` | On non-React-Compiler apps that opt into `react-perf`, flagging inline `style={{ ... }}` or `onClick={() => ...}` on native HTML elements triggers pointless `useMemo`/`useCallback` churn.        | Omit `react-perf` entirely when using React Compiler (Section 6.1). Without React Compiler, configure `["error", { "nativeAllowList": "all" }]` so intrinsic DOM elements stay ergonomic.               |
| `typescript/no-unnecessary-condition`                                                               | TypeScript control-flow narrowing assumes values do not mutate externally, flagging real checks on live getters (`AbortSignal.aborted`, reactive refs, or shared state mutated across an `await`). | Never delete a real post-`await` or live-getter guard to satisfy the rule. Read through a clean helper/method or record a targeted Section 2 exception citing the live mutation boundary.               |
| Upstream checker bugs (for example, narrowed-control-flow false positives)                          | A specific tool version emits a demonstrable false diagnostic on valid code.                                                                                                                       | Confirm the minimal repro on the installed `oxlint`/`tsrs` version, record a targeted Section 2 exception linking the upstream issue and revisit trigger, and remove it once fixed upstream.            |

## 6. Frameworks and test runners

Enable native framework plugins in their applicable scope while keeping base protections active. Inspect the actual installed plugin rules, runtime globals, and test-runner `.d.ts` declarations rather than assuming plugin defaults cover every helper or convention.

### 6.1 React, React Compiler, and DOM accessibility

For React code, add `"react"` to `plugins` and enable these explicit rules alongside category coverage:

```json
{
  "react/rules-of-hooks": "error",
  "react/exhaustive-deps": "error",
  "react/jsx-key": "error",
  "react/jsx-no-duplicate-props": "error",
  "react/jsx-no-undef": "error"
}
```

With the base categories (`correctness`, `suspicious`, `perf`) active, adding `"react"` to `plugins` also enables Oxlint's native React Compiler rules (`react/immutability`, `react/purity`, `react/refs`, `react/set-state-in-effect`, `react/set-state-in-render`, `react/preserve-manual-memoization`, `react/static-components`, `react/error-boundaries`, `react/incompatible-library`, `react/use-memo`, and related checks).

The `suspicious` category also enables `react/react-in-jsx-scope`, which applies only to the classic JSX transform. Projects that use the automatic JSX runtime (`"jsx": "react-jsx"` or `"react-jsxdev"` in `tsconfig.json`, or the equivalent bundler setting) set `"react/react-in-jsx-scope": "off"`. This is an implementation mapping, not a Section 2 exception.

**React Compiler vs. `react-perf`:**

- **Applications using React Compiler:** Rely on Oxlint's native `"react"` rules and **omit `"react-perf"`**. The `react-perf` allocation rules force manual `useMemo` and `useCallback` wrappers that duplicate and fight automatic compiler memoization.
- **Applications not using React Compiler:** May opt into `"react-perf"` with `{ "nativeAllowList": "all" }` on its JSX allocation rules (`react-perf/jsx-no-jsx-as-prop`, `react-perf/jsx-no-new-array-as-prop`, `react-perf/jsx-no-new-function-as-prop`, `react-perf/jsx-no-new-object-as-prop`) so custom components stay checked while native HTML elements remain ergonomic.

For JSX targeting DOM interfaces, add `"jsx-a11y"`, keep category coverage, and explicitly enable:

```json
{
  "jsx-a11y/no-noninteractive-element-interactions": "error",
  "jsx-a11y/no-noninteractive-tabindex": "error",
  "jsx-a11y/prefer-tag-over-role": "error"
}
```

Prefer native HTML controls where they fit the contract; interactive widget changes still require keyboard, focus, and accessible-name/role verification beyond static linting.

### 6.2 Vitest

Add `"vitest"` for Vitest test scopes and enable:

```json
{
  "vitest/no-focused-tests": "error",
  "vitest/valid-expect": [
    "error",
    {
      "minArgs": 1,
      "maxArgs": 2
    }
  ],
  "vitest/expect-expect": [
    "error",
    {
      "assertFunctionNames": ["expect", "expectTypeOf", "assert", "assertType"]
    }
  ],
  "vitest/no-conditional-expect": "error"
}
```

`vitest/expect-expect` checks only the test blocks it recognizes: the global Vitest test functions, `test` and `it` imported from `"vitest"` or `"@effect/vitest"`, and functions derived in the same file with `.extend(...)` from a `test` or `it` imported from `"vitest"`. Register custom members of a recognized test function (such as Effect's `it.effect` or `it.scoped`) in its `additionalTestBlockFunctions` option; without the entry the rule skips those calls without warning, so assertion-free tests inside them pass.

The rule does not check tests declared any other way, even when the name is listed in that option. Three common harness shapes stay unchecked: a standalone harness function (for example, `withFixtures(...)`); a function derived with `.extend(...)` from the global `test` in Vitest globals mode; and a `test` or `it` imported from another module, including an `.extend(...)` fixture exported from a shared fixtures file. Do not rely on this rule for tests declared through such a harness. Confirm what the installed Oxlint version checks by running the rule against an assertion-free test declared through each harness the repository uses.

`vitest/no-standalone-expect`, which the `correctness` category enables, fails in the opposite direction on the same code: it reports every `expect` inside a test block it does not recognize, including custom members such as `it.effect` and all three harness shapes above. Register each of those names in that rule's own `additionalTestBlockFunctions` option, which takes effect for every shape. Entries are literal dotted names without wildcards, and each member needs its own entry (for example, `"mcpTest"` and `"mcpTest.each"`). Do not disable the rule or restructure valid tests to silence it.

Each `assertFunctionNames` entry matches a call whose dotted name equals the entry or continues it: `"assert"` matches `assert(...)`, `assert.ok(...)`, and every other `assert.<member>(...)` call. `*` matches within one name segment and `**` matches across segments, so `"*"` and `"**"` match every call and let assertion-free tests pass; never use them. Add only verified repository assertion helpers. If a repository keeps non-asserting helpers under an assertion namespace, replace the namespace entry with `$`-anchored exact names (for example, `"assert$"` and `"assert.ok$"`), and confirm on the installed Oxlint version that a test calling only the non-asserting helper fails.

### 6.3 Jest

Add `"jest"` for Jest test scopes and enable:

```json
{
  "jest/no-focused-tests": "error",
  "jest/valid-expect": "error",
  "jest/valid-expect-in-promise": "error",
  "jest/expect-expect": [
    "error",
    {
      "assertFunctionNames": ["expect"]
    }
  ],
  "jest/no-conditional-expect": "error"
}
```

Add only verified repository assertion helpers to `assertFunctionNames`; never use broad wildcards that allow assertion-free tests to pass.

### 6.4 Node test runner (`node:test`)

In `@types/node/test.d.ts`:

- Lifecycle hooks (`before`, `after`, `beforeEach`, `afterEach`) return `void` and do not trigger `typescript/no-floating-promises`.
- Test and suite registrations (`test`, `it`, `describe`, `suite`) return `Promise<void>`. Nested subtests (`t.test(...)` on `TestContext`) also return `Promise<void>` and **must** be awaited or returned inside async tests.

Choose one of these defined runner mappings in your `node:test` file override (no separate Section 2 exception is required for these defined profiles):

1. **Top-level `await` (preferred when ESM top-level `await` fits the suite):** Write `await test(...)` and `await describe(...)` with **no** `allowForKnownSafeCalls` entry. Every unawaited top-level registration and every unawaited nested `t.test(...)` fails `typescript/no-floating-promises` mechanically. Never mass-rewrite existing unawaited registrations into top-level `await` if doing so changes module-evaluation or hook-ordering semantics.
2. **Aliased top-level imports (preferred when keeping unawaited top-level registrations without blinding nested `t.test(...)`):** Import top-level registrations under distinct aliases (`import { describe as nodeDescribe, it as nodeIt, suite as nodeSuite, test as nodeTest } from "node:test"`) and allowlist **only** those aliased names in the `node:test` test override:

```json
{
  "typescript/no-floating-promises": [
    "error",
    {
      "checkThenables": true,
      "ignoreIIFE": false,
      "ignoreVoid": false,
      "allowForKnownSafeCalls": [
        {
          "from": "package",
          "package": "node:test",
          "name": ["nodeTest", "nodeIt", "nodeDescribe", "nodeSuite"]
        }
      ],
      "allowForKnownSafePromises": []
    }
  ]
}
```

Because `TestContext.test` is named `test` rather than `nodeTest`, top-level `nodeTest(...)` passes while unawaited nested `t.test(...)` still fails `typescript/no-floating-promises` mechanically. The allowlist does not cover member calls such as `nodeTest.skip(...)`, `nodeTest.todo(...)`, or `nodeTest.only(...)`, which still fail when unawaited; use the options form instead (`nodeTest("name", { skip: true }, fn)`).

3. **Unaliased registrations on existing suites:** Existing `node:test` suites may allowlist `["test", "it", "describe", "suite"]` from `"node:test"` (including `"suite"` because `@types/node` re-exports `describe` as `export { suite as describe }`). **Caveat:** matching bare `"test"` from `"node:test"` also matches `TestContext.test`, which disables automated `no-floating-promises` detection on unawaited nested `t.test(...)` subtests. Always `await` or return `t.test(...)`, and prefer Option 1 or Option 2 for new suites.

Never allowlist `test.only` or `describe.only`, and never disable `typescript/no-floating-promises` in tests; real floating promises inside test bodies must still fail lint.

## 7. Formatting and generated artifacts

### 7.1 Formatter ownership

Oxfmt owns formatting for supported maintained files. Preserve intentional, established repository style conventions; otherwise use this baseline `.oxfmtrc.json` (or `.oxfmtrc.jsonc`, or `oxfmt.config.ts` using `defineConfig` from `"oxfmt"`):

```json
{
  "$schema": "./node_modules/oxfmt/configuration_schema.json",
  "printWidth": 100,
  "tabWidth": 2,
  "useTabs": false,
  "semi": true,
  "singleQuote": false,
  "trailingComma": "all",
  "endOfLine": "lf",
  "insertFinalNewline": true,
  "sortImports": false,
  "sortPackageJson": false,
  "sortTailwindcss": false,
  "jsdoc": false
}
```

Oxfmt natively supports `sortImports`, `sortPackageJson`, `sortTailwindcss`, `jsdoc`, `ignorePatterns`, `overrides`, `associations`, and `.editorconfig`. Keep automatic sorting disabled unless the repository deliberately opts into it and verifies that import reordering does not alter side effects or runtime initialization order.

**Ignore configuration:** Oxfmt applies three ignore sources: `ignorePatterns` in its config file; Git's ignore rules (every `.gitignore` in the directory tree and in parent directories up to the repository root, plus `.git/info/exclude`); and `.prettierignore` in the current directory. `--ignore-path` replaces `.prettierignore` only; the Git ignore rules still apply. Oxfmt does **not** automatically load `.oxfmtignore`. Keep ignore globs tight to generated, vendored, or non-code files (for example, `patches/*.patch` rather than `patches/**`) so handwritten source inside mixed directories is never silently excluded from formatting checks.

Assign each file type one clear formatting owner and avoid overlapping formatters. Generated, vendored, and byte-sensitive fixtures may designate an explicit generator or separate owner; handwritten maintained source remains formatted and checked by `oxfmt --check .`.

### 7.2 Generated freshness

Verify committed generated artifacts (such as Cloudflare Worker types, schema outputs, or generated content indexes) in acceptance using each generator's native non-writing check where available (for example, Wrangler `types --check` when supported), or by regenerating into an isolated temporary directory and diffing without mutating tracked files. A successful generator run alone does not prove committed output is current.

## 8. Verification and enforcement integrity

### 8.1 Focused gate integrity — no stock-rule proof tests

Verification must prove that **this repository's own configuration, coverage, acceptance commands, and custom code work** — not that upstream tools still implement their built-in rules.

**Do not write or retain tests whose only purpose is re-verifying stock Oxlint, Oxfmt, or TypeScript compiler rules** (such as synthetic fixtures asserting that Oxlint still reports `typescript/no-floating-promises`, `eqeqeq`, or `max-lines`, or that `tsc` still rejects a type error). Upstream projects own and test their native rules; duplicating those checks in adopting repositories adds maintenance drag without improving code quality.

Focus verification strictly on what the repository owns:

1. **Real acceptance gates pass on the actual repository tree:**
   - Formatting check (`oxfmt --check .`)
   - Full type-aware lint with zero warnings and zero unused disables (`oxlint --deny-warnings .`, backed by `tsrs`)
   - Every declared compiler, framework-typegen, and handwritten-declaration check (`tsc --noEmit`, `tsrs --noEmit`, etc.)
   - Generated-artifact freshness checks where applicable
   - Real unit, integration, and end-to-end tests covering repository behavior
2. **Effective configuration and source coverage are verified natively:**
   - Inspect effective config (`oxlint --print-config`) and matched files (`oxlint --debug=files`) during adoption and config changes to confirm that all maintained source files, overrides, and plugins are active and that no maintained source is silently ignored.
   - Verify compiler project membership and formatter `ignorePatterns` so every maintained TS and checked-JS file is actually compiled, linted, and formatted by the acceptance workflow. Multi-package repositories should keep a lightweight repo-owned scope-coverage check comparing tracked maintained files against `oxlint --debug=files`, compiler/declaration `tsconfig` membership, and formatter ignores to prevent silent drift as new packages or scripts are added.
   - Ensure aggregate scripts and CI workflows propagate failures accurately without diagnostic filtering, finding budgets, or `continue-on-error`.
3. **Custom repository-owned quality code is tested directly:**
   - Write and retain targeted tests **only** for quality tooling this repository itself owns — such as custom JS lint plugins (including a Section 2.4 directive-policy plugin), scope-coverage checks, custom architecture/boundary scripts, config generators, or generated-artifact freshness scripts.

### 8.2 Evidence quality

Record exact revisions, installed tool versions, commands run, selection scope, and exit statuses when reporting verification. Report each check plainly as passed, failed, blocked, or unrun. Selected suites are not full suites; a script existing in `package.json` does not prove it ran; local verification does not prove hosted CI passed. Investigate flaky checks rather than rerunning until a single pass hides the issue.

## 9. Adoption, upgrades, and escalation

### 9.1 Inspect the target repository first

Before editing files:

1. Record the starting Git revision and preserve any unrelated uncommitted work.
2. Inventory runtimes, package manager, installed toolchain versions, `tsconfig` projects, test runners, frameworks, generators, existing lint/format configs, custom quality checks, and CI workflows.
3. Inspect the actual installed `node_modules` declarations, tool schemas, and current docs where any framework or API contract is in doubt.
4. Check whether the repository is a **first-time adoption** or an **upgrade from an earlier version** of this standard.

### 9.2 First-time adoption

When a repository has never implemented this standard:

1. Install the latest published `oxlint`, `tsrs`, and `oxfmt` (and required framework plugins) using the repository's package manager.
2. Create the root Oxlint config from Appendix A, add applicable Section 6 framework/runner mappings, configure Oxfmt from Section 7, and align compiler settings with Section 4.2.
3. Group findings by underlying contract and fix them cleanly using idiomatic native code (no harmful compliance shims). Separate intentional behavioral improvements from mechanical compliance edits.
4. Record any genuinely eligible relaxations under Section 2 in Appendix B.
5. Wire the required scripts and CI acceptance workflow (Section 10.1), verify coverage natively (`--print-config` / `--debug=files`), and run the full acceptance suite.

### 9.3 Upgrading from an earlier version (delta workflow)

When a repository already adopted an earlier version of this standard:

1. **Compute the delta** between the repository's existing configs, scripts, exception records, and quality tests against this standard.
2. **Inventory repo-owned safeguards before deleting old policy suites:** Separate repository-owned checks (generated-artifact freshness, CI script wiring, custom lint plugins, directive-policy checks, scope-coverage checks) from stock-rule proof tests before removing obsolete test files so real guardrails are never deleted accidentally.
3. **Retire stale standard copies and ceiling generators:** Remove vendored copies of earlier standards, SHA-256 locks pinned to old guide text, and config generators that treat Appendix A as a maximum ceiling (which silently erase stricter local rules).
4. **Upgrade the toolchain and backend:** Install the latest published `oxlint`, `tsrs`, and `oxfmt`, remove legacy `oxlint-tsgolint` packages and plumbing, and drop temporary backend-swap exceptions no longer needed.
5. **Reconcile baseline settings and preserve stricter value:** Align configs with Appendix A and Sections 4–7 while preserving high-value stricter local rules under Section 9.5 and auditing them for rule-vs-rule contradictions. Remove obsolete site directives made unnecessary by the reconciled baseline.
6. **Clean up obsolete machinery and shims:** Remove stock-rule proof tests (Section 8.1), lint-only wrappers/scaffolding, and harmful compliance shims (Sections 3.3 and 3.5).
7. **Re-verify the integrated repository** through its canonical acceptance workflow (Section 10.1) and update Appendix B records.

Do not leave behind mixed old/new standard copies, dead config keys, or obsolete verifier scripts that contradict this standard.

### 9.4 Raising regressions to the driving user

If while tailoring or implementing this standard you identify that a **mandated rule, option, threshold, or guidance in this standard causes regressions** in the target repository — for example, breaking supported runtime behavior, forcing broken types, triggering incompatibilities with the current runtime/framework/compiler, or pushing code toward harmful shims — **stop and raise the concern directly to the user driving the work**.

Include:

1. **The exact requirement:** Section, rule/option/threshold, and installed tool versions (`oxlint`, `tsrs`, `oxfmt`, `typescript`, runtime).
2. **Concrete evidence:** Reproducible diagnostic, failing test, or exact behavioral/type contract harmed.
3. **Options and recommendation:** Whether a narrow Section 2 quality exception resolves the repository issue cleanly, or whether the standard's mandated rule itself should be reconsidered.

Never hide a regression behind a silent disable, a compliance shim, or weakened test assertions.

### 9.5 Preserving and surfacing stronger repository conventions

This standard is a floor, not a ceiling. Target repositories often carry stricter rules, tighter thresholds, additional compiler flags, or custom domain checks tailored to their workload.

When you encounter existing enforcement that is stricter than this standard:

1. **Evaluate real value vs. compliance friction:** Confirm whether the stricter check is genuinely paying for itself — catching real defects, enforcing meaningful invariants, and passing cleanly without forcing synthetic splits, wrapper boilerplate, or harmful compliance shims.
2. **Audit retained extra rules for contradictions and self-inflicted noise:** Check every retained non-baseline rule against Appendix A and the repository's actual libraries. Remove or scope any extra rule that directly contradicts a baseline rule (for example, `typescript/non-nullable-type-assertion-style` conflicts directly with `typescript/no-non-null-assertion`) or causes systematic false-positive suppressions on legitimate library APIs (for example, `unicorn/prefer-dom-node-text-content` flagging Playwright `Locator.innerText()` in browser tests).
3. **Preserve what works well:** Do not weaken, relax, or delete a clean, high-value stricter rule or threshold merely to normalize the repository down to this standard's baseline.
4. **Surface it for upstream consideration:** Highlight each high-value stricter rule or convention directly to the user driving the work — naming the exact rule, option, or check, why it fits cleanly without slop, and the class of bugs or maintainability issues it prevents — so it can be considered for adoption in a future revision of this standard.
5. **Reconcile only what actively harms quality:** If an existing stricter rule is demonstrably inducing compliance slop or harmful shims, present the concrete evidence to the user before relaxing it.

## 10. Acceptance and maintenance

### 10.1 Required commands and CI

Preserve established repository script names and package managers where appropriate. Standard script shape:

```json
{
  "scripts": {
    "lint": "oxlint --deny-warnings .",
    "lint:agent": "oxlint --deny-warnings --format=agent .",
    "lint:fix": "oxlint --fix .",
    "format": "oxfmt --write .",
    "format:check": "oxfmt --check ."
  }
}
```

The canonical acceptance workflow must require:

- Formatting check (`format:check`) and full type-aware lint (`lint`) backed by `tsrs` with zero warnings and zero unused disable directives.
- Every applicable compiler, framework typegen, and handwritten declaration check.
- Generated-artifact freshness and relevant build/package checks.
- The repository's real unit, integration, and behavioral tests (plus tests for any custom repo-owned lint plugins, scope-coverage checks, or policy scripts).

`lint:agent` is a compact diagnostic output format for coding agents, not a second full lint run in CI. Run independent gates so one failure does not mask others, and ensure the aggregate acceptance command exits non-zero whenever any required gate fails.

In `pnpm` workspaces, pass `--stream` to recursive scripts that run in parallel (for example, `pnpm -r --stream run typecheck`). In an interactive terminal, pnpm's default reporter cuts each line of parallel script output to the terminal width, which hides compiler and lint messages; `--stream` prints every line in full. Piped output, such as CI logs, is not affected.

### 10.2 Completion criteria

Adoption or upgrade is complete when:

1. Every maintained source file is covered by active lint, compiler, and formatter checks.
2. Effective configuration meets or exceeds the baseline, applicable defined profiles, and justified Appendix B exceptions (preserving high-value stricter local rules under Section 9.5).
3. Migration finding budgets, diagnostic filtering, legacy `oxlint-tsgolint` dependencies, and incomplete-source exemptions are removed.
4. All required acceptance checks pass on the exact integrated revision.
5. Intentional behavioral changes, Section 2 exceptions, escalated regression concerns (Section 9.4), and high-value stricter local rules worth considering upstream (Section 9.5) have been reviewed with the driving user.
6. Required hosted CI passes on the relevant revision (or local-only acceptance is explicitly recorded if the repo has no hosted CI).

### 10.3 Ongoing maintenance

Keep `oxlint`, `tsrs`, `oxfmt`, and compiler dependencies on current published releases. Reassess exceptions whenever their underlying dependency, rule, or API contract changes.

In repository `AGENTS.md` / `CLAUDE.md` instructions, point coding agents to the canonical agent-readable Markdown URL (`https://fitchhub.com/standards/oxlint-oxfmt.md`), which always serves the latest version of this standard. Also name the repository's canonical acceptance command, and note where local Appendix B records live. Keep those pointers short so this standard remains the single authoritative specification.

Use a pinned release URL (such as `https://fitchhub.com/standards/oxlint-oxfmt/v5.4.md`) only to identify the version a repository adopted, for example in its Appendix B adoption record. Agent instructions that point at a pinned URL keep serving that version after a newer one is published.

## Appendix A: Base Oxlint configuration

This is the normative starting `.oxlintrc.json` (or `.oxlintrc.jsonc`, or equivalent `oxlint.config.ts` via `defineConfig`). Adapt `$schema` paths and profile globs per Sections 4 and 5, and add applicable Section 6 framework/runner mappings. Every weakening of an applicable requirement follows Section 2.

```json
{
  "$schema": "./node_modules/oxlint/configuration_schema.json",
  "plugins": ["eslint", "typescript", "unicorn", "oxc", "import", "promise"],
  "categories": {
    "correctness": "error",
    "suspicious": "error",
    "perf": "error",
    "pedantic": "off",
    "style": "off",
    "restriction": "off",
    "nursery": "off"
  },
  "options": {
    "typeAware": true,
    "typeCheck": false,
    "denyWarnings": true,
    "reportUnusedDisableDirectives": "error",
    "respectEslintDisableDirectives": false
  },
  "rules": {
    "array-callback-return": "error",
    "typescript/no-explicit-any": [
      "error",
      {
        "fixToUnknown": false,
        "ignoreRestArgs": false
      }
    ],
    "typescript/no-non-null-assertion": "error",
    "typescript/no-unsafe-type-assertion": "error",
    "typescript/no-unnecessary-type-assertion": [
      "error",
      {
        "checkLiteralConstAssertions": true
      }
    ],
    "typescript/consistent-type-assertions": [
      "error",
      {
        "assertionStyle": "as",
        "objectLiteralTypeAssertions": "never",
        "arrayLiteralTypeAssertions": "never"
      }
    ],
    "typescript/no-unsafe-argument": "error",
    "typescript/no-unsafe-assignment": "error",
    "typescript/no-unsafe-call": "error",
    "typescript/no-unsafe-member-access": "error",
    "typescript/no-unsafe-return": "error",
    "typescript/no-empty-object-type": "error",
    "typescript/no-unsafe-function-type": "error",
    "typescript/no-wrapper-object-types": "error",
    "typescript/no-invalid-void-type": [
      "error",
      {
        "allowAsThisParameter": true,
        "allowInGenericTypeArguments": true
      }
    ],
    "typescript/no-unnecessary-type-parameters": "error",
    "typescript/no-deprecated": "error",
    "typescript/no-duplicate-type-constituents": "error",
    "typescript/no-redundant-type-constituents": "error",
    "typescript/unbound-method": "error",
    "typescript/no-misused-spread": "error",
    "typescript/no-for-in-array": "error",
    "typescript/require-array-sort-compare": "error",
    "typescript/ban-ts-comment": [
      "error",
      {
        "ts-check": false,
        "ts-expect-error": true,
        "ts-ignore": true,
        "ts-nocheck": true
      }
    ],
    "typescript/strict-boolean-expressions": [
      "error",
      {
        "allowAny": false,
        "allowNullableBoolean": false,
        "allowNullableEnum": false,
        "allowNullableNumber": false,
        "allowNullableObject": true,
        "allowNullableString": false,
        "allowNumber": false,
        "allowString": false
      }
    ],
    "typescript/no-unnecessary-condition": [
      "error",
      {
        "checkTypePredicates": false,
        "allowConstantLoopConditions": "only-allowed-literals"
      }
    ],
    "typescript/switch-exhaustiveness-check": [
      "error",
      {
        "considerDefaultExhaustiveForUnions": false
      }
    ],
    "eqeqeq": ["error", "always"],
    "no-implicit-coercion": "error",
    "typescript/restrict-plus-operands": [
      "error",
      {
        "allowAny": false,
        "allowBoolean": false,
        "allowNullish": false,
        "allowNumberAndString": false,
        "allowRegExp": false,
        "skipCompoundAssignments": false
      }
    ],
    "typescript/restrict-template-expressions": [
      "error",
      {
        "allowAny": false,
        "allowArray": false,
        "allowBoolean": true,
        "allowNever": false,
        "allowNullish": false,
        "allowNumber": true,
        "allowRegExp": false
      }
    ],
    "typescript/no-base-to-string": [
      "error",
      {
        "checkUnknown": false
      }
    ],
    "typescript/no-floating-promises": [
      "error",
      {
        "checkThenables": true,
        "ignoreIIFE": false,
        "ignoreVoid": false,
        "allowForKnownSafeCalls": [],
        "allowForKnownSafePromises": []
      }
    ],
    "typescript/no-misused-promises": "error",
    "typescript/await-thenable": "error",
    "typescript/return-await": ["error", "error-handling-correctness-only"],
    "typescript/strict-void-return": "off",
    "typescript/no-confusing-void-expression": [
      "error",
      {
        "ignoreArrowShorthand": true,
        "ignoreVoidOperator": false,
        "ignoreVoidReturningFunctions": false
      }
    ],
    "typescript/no-meaningless-void-operator": "error",
    "promise/always-return": [
      "error",
      {
        "ignoreLastCallback": true,
        "ignoreAssignmentVariable": []
      }
    ],
    "promise/catch-or-return": "error",
    "no-async-promise-executor": "error",
    "no-promise-executor-return": "error",
    "typescript/only-throw-error": [
      "error",
      {
        "allowThrowingAny": false,
        "allowThrowingUnknown": false,
        "allowRethrowing": true
      }
    ],
    "typescript/use-unknown-in-catch-callback-variable": "error",
    "typescript/prefer-promise-reject-errors": [
      "error",
      {
        "allowEmptyReject": false,
        "allowThrowingAny": false,
        "allowThrowingUnknown": true
      }
    ],
    "no-useless-catch": "error",
    "no-param-reassign": [
      "error",
      {
        "props": true,
        "ignorePropertyModificationsFor": [],
        "ignorePropertyModificationsForRegex": []
      }
    ],
    "typescript/prefer-readonly": "error",
    "typescript/explicit-module-boundary-types": "error",
    "typescript/method-signature-style": ["error", "property"],
    "typescript/consistent-type-imports": [
      "error",
      {
        "prefer": "type-imports",
        "fixStyle": "inline-type-imports",
        "disallowTypeAnnotations": true
      }
    ],
    "typescript/consistent-type-exports": "error",
    "typescript/no-import-type-side-effects": "error",
    "import/no-cycle": [
      "error",
      {
        "ignoreTypes": false,
        "ignoreExternal": true,
        "allowUnsafeDynamicCyclicDependency": false
      }
    ],
    "import/no-self-import": "error",
    "import/no-duplicates": [
      "error",
      {
        "preferInline": true
      }
    ],
    "import/no-mutable-exports": "error",
    "complexity": [
      "error",
      {
        "max": 10,
        "variant": "modified"
      }
    ],
    "max-depth": [
      "error",
      {
        "max": 3
      }
    ],
    "max-params": [
      "error",
      {
        "max": 5
      }
    ],
    "max-statements": [
      "error",
      {
        "max": 40
      }
    ],
    "max-lines-per-function": [
      "error",
      {
        "max": 80,
        "skipBlankLines": true,
        "skipComments": true,
        "IIFEs": true
      }
    ],
    "max-lines": [
      "error",
      {
        "max": 800,
        "skipBlankLines": true,
        "skipComments": true
      }
    ],
    "curly": ["error", "all"],
    "no-var": "error",
    "prefer-const": "error",
    "no-nested-ternary": "error",
    "no-return-assign": ["error", "always"],
    "no-sequences": "error",
    "no-multi-assign": "error",
    "no-else-return": "error",
    "no-eval": "error",
    "no-implied-eval": "error",
    "no-new-func": "error",
    "no-with": "error",
    "no-debugger": "error",
    "no-control-regex": "off",
    "no-empty": [
      "error",
      {
        "allowEmptyCatch": false
      }
    ],
    "no-empty-function": "error",
    "unicorn/no-useless-undefined": [
      "error",
      {
        "checkArguments": false,
        "checkArrowFunctionBody": false
      }
    ],
    "unicorn/no-abusive-eslint-disable": "error",
    "typescript/prefer-readonly-parameter-types": "off",
    "no-await-in-loop": "off",
    "require-await": "off",
    "typescript/require-await": "off",
    "typescript/consistent-return": "off",
    "no-underscore-dangle": "off",
    "unicorn/consistent-function-scoping": "off",
    "unicorn/no-array-sort": "off",
    "unicorn/no-array-reverse": "off"
  },
  "overrides": [
    {
      "files": [
        "**/*.test.{js,jsx,ts,tsx,mjs,cjs,mts,cts}",
        "**/*.spec.{js,jsx,ts,tsx,mjs,cjs,mts,cts}",
        "**/__tests__/**/*.{js,jsx,ts,tsx,mjs,cjs,mts,cts}"
      ],
      "rules": {
        "complexity": [
          "error",
          {
            "max": 15,
            "variant": "modified"
          }
        ],
        "max-depth": [
          "error",
          {
            "max": 4
          }
        ],
        "max-params": [
          "error",
          {
            "max": 6
          }
        ],
        "max-statements": "off",
        "max-lines-per-function": "off",
        "max-lines": "off"
      }
    },
    {
      "files": ["**/*.d.ts", "**/*.d.mts", "**/*.d.cts"],
      "rules": {
        "complexity": "off",
        "max-depth": "off",
        "max-params": "off",
        "max-statements": "off",
        "max-lines-per-function": "off",
        "max-lines": "off"
      }
    },
    {
      "files": ["**/*.test-d.{ts,mts,cts}"],
      "rules": {
        "typescript/ban-ts-comment": [
          "error",
          {
            "ts-check": false,
            "ts-expect-error": "allow-with-description",
            "ts-ignore": true,
            "ts-nocheck": true,
            "minimumDescriptionLength": 10
          }
        ],
        "complexity": [
          "error",
          {
            "max": 15,
            "variant": "modified"
          }
        ],
        "max-depth": [
          "error",
          {
            "max": 4
          }
        ],
        "max-params": [
          "error",
          {
            "max": 6
          }
        ],
        "max-statements": "off",
        "max-lines-per-function": "off",
        "max-lines": "off"
      }
    }
  ]
}
```

## Appendix B: Repository records

Maintain these records in each adopting repository (for example, in `docs/code-quality.md` or alongside the repository's quality config). Supporting tests and review artifacts live in their normal locations, and the record must explain each decision without relying on an external conversation.

### Adoption record

Record:

- Repository name and adopted standard version (`v5.4`), with its pinned release URL
- Supported runtimes and package manager
- Installed toolchain versions (`oxlint`, `tsrs`, `oxfmt`, compiler/framework checker)
- Configuration files, compiler projects, source profiles, and acceptance commands
- Formatter and generator ownership
- Verification evidence: exact verified commit SHA or the linked pull request / tracking issue recording the integrated revision, commands run, and hosted CI outcomes

### Quality-exception record

Use stable identifiers such as `QX-001`. One rationale may cover a bounded repeated pattern. Record concrete evidence rather than restating eligibility criteria.

```text
ID and title:
Rule, option, or threshold; installed tool versions:
Scope: files, authorized operations, origins, or bounded pattern:
Diagnostic and required contract:
Best reasonable compliant alternative and demonstrated quality cost:
Eligibility ground: supported-contract harm or disproportionate complexity without meaningful safety/correctness benefit:
Chosen adjustment and why its scope is appropriate:
Structural comparison or unsafe-type evidence (where applicable):
Verification commands, relevant tests, and results:
Retained protection, lost detection, and remaining assumptions:
Review and revisit trigger:
```

## Appendix C: Changelog

### v5.4 (20 November 2026)

- **Minimum version floors:** Explicitly established that all cited package versions (`oxlint >= 1.94.0`, `tsrs >= 7.1.0-beta.tsrs3`, `oxfmt >= 0.79.0`, `typescript >= 7.0.2`) are minimum floors, never pins or ceilings; agents must always install the latest published releases and adapt to current schemas and documentation.
- **`tsrs` fast mode and CI memory controls:** Documented `tsrs-lint`'s default-on fast preset (`TSRS_FAST=0` to disable), the controls that lower checker count and memory use (`--checkers N`, `--singleThreaded`, `--fast --maxMemory <size>`, `TSRS_MAX_MEMORY`, `RAYON_NUM_THREADS`), and why to prefer them over `compilerOptions.checkers`, which TypeScript 6 rejects.
- **Base lint baseline:** Added `"array-callback-return": "error"` to Appendix A.
- **Native directive enforcement:** Added a concise native Oxlint JS plugin recipe using `context.sourceCode.getDisableDirectives()`, with its `jsPlugins` registration, that enforces `oxlint-disable-next-line` and `QX-*` identifiers across CLI, `--fix`, and editor LSP while blocking blanket and self-targeted disables.
- **Compiler scoping and strict-TS idioms:** Clarified `checkJs: true` scoping (avoiding generated build outputs in TypeScript-only framework configs), `skipLibCheck: true` on app/mixed-runtime projects paired with `skipLibCheck: false` on handwritten declarations, `erasableSyntaxOnly` + `verbatimModuleSyntax` for Node-executed `.ts` scripts, and idiomatic patterns for `noUncheckedIndexedAccess` and `exactOptionalPropertyTypes`.
- **Config discovery, editor/LSP, and JSONC hygiene:** Listed the four config file names Oxlint auto-discovers and the default-rules fallback for any other name, documented JSONC parsing for `.oxlintrc.json` readers, and warned against `${workspaceFolder}` in VS Code's `oxc.configPath` (use workspace-relative paths or leave unset).
- **React profile:** Clarified that Oxlint's `"react"` plugin with base categories already enables native React Compiler rules, that React Compiler apps should omit `"react-perf"`, and that non-Compiler apps opting into `"react-perf"` should use `{ "nativeAllowList": "all" }`. Defined `"react/react-in-jsx-scope": "off"` as the mapping for projects on the automatic JSX runtime.
- **Vitest and `node:test` profiles:** Documented `vitest/expect-expect`'s `additionalTestBlockFunctions` option, how `assertFunctionNames` entries match, the ban on match-everything wildcards (`"*"`, `"**"`), and registering custom test blocks with `vitest/no-standalone-expect`; prioritized top-level `await` and aliased `node:test` imports (`nodeTest` / `nodeIt` / `nodeDescribe` / `nodeSuite`) so unawaited nested `t.test(...)` subtests still fail `typescript/no-floating-promises` mechanically.
- **Formatter ignores, scope-coverage checks, and upgrade hygiene:** Clarified that Oxfmt uses `ignorePatterns`, Git's ignore rules, and `.prettierignore` (not `.oxfmtignore`); added lightweight scope-coverage verification guidance; added pre-cleanup safeguard inventory, retiring vendored standard copies/ceiling generators, `--stream` for parallel `pnpm` script output, stricter-rule contradiction auditing, and PR/issue linking in Appendix B to avoid self-referential commit SHA loops.
- **Latest and pinned URLs:** Agent instructions point at the canonical URL, which always serves the latest version; a pinned release URL only identifies the version a repository adopted.

### v5.3 (19 November 2026)

- Switched Oxlint's type-aware backend from `oxlint-tsgolint` to `tsrs`.
- Formalized current-date native-first engineering, mandatory regression escalation, and baseline-floor preservation for stronger repository conventions.
- Removed stock-rule proof tests in favor of repo-owned verification and native `--print-config` / `--debug=files` checks.
- Calibrated baseline defaults (`max-lines: 800`, `max-params: 5`, `unicorn/no-useless-undefined` options, `import/no-cycle` `ignoreExternal: true`, `node:test` profile) and published canonical agent-readable Markdown.

## References

Primary upstream references for current tool behavior (this standard defines repository enforcement and exception authority):

- [Oxlint configuration](https://oxc.rs/docs/guide/usage/linter/config), [configuration reference](https://oxc.rs/docs/guide/usage/linter/config-file-reference.html), [type-aware linting](https://oxc.rs/docs/guide/usage/linter/type-aware), and [JS plugins](https://oxc.rs/docs/guide/usage/linter/js-plugins).
- [`tsrs` CLI usage and performance options](https://github.com/oxc-project/tsrs/blob/main/docs/USAGE.md), [differences from pinned TypeScript](https://github.com/oxc-project/tsrs/blob/main/docs/DEFAULTS.md), and [faster type-aware linting with `tsrs`](https://oxc.rs/blog/2026-11-17-faster-type-aware-linting-with-tsrs).
- [Oxlint ignore comments](https://oxc.rs/docs/guide/usage/linter/ignore-comments.html) and [Oxc VS Code extension](https://github.com/oxc-project/oxc-vscode).
- [Floating-Promise checks](https://oxc.rs/docs/guide/usage/linter/rules/typescript/no-floating-promises), [array callback return](https://oxc.rs/docs/guide/usage/linter/rules/eslint/array-callback-return), [readonly parameter types](https://oxc.rs/docs/guide/usage/linter/rules/typescript/prefer-readonly-parameter-types), [strict void returns](https://oxc.rs/docs/guide/usage/linter/rules/typescript/strict-void-return), and [`unicorn/no-useless-undefined`](https://oxc.rs/docs/guide/usage/linter/rules/unicorn/no-useless-undefined).
- [Promise rejection options](https://oxc.rs/docs/guide/usage/linter/rules/typescript/prefer-promise-reject-errors).
- [Node test runner (`node:test`)](https://nodejs.org/api/test.html).
- [Oxfmt configuration](https://oxc.rs/docs/guide/usage/formatter/config), [configuration reference](https://oxc.rs/docs/guide/usage/formatter/config-file-reference.html), [CLI](https://oxc.rs/docs/guide/usage/formatter/cli.html), and [language support](https://oxc.rs/docs/guide/usage/formatter/language-support).
