Maintainability rules

Root package.json must define the packageManager field (e.g., "pnpm@9.x") and the repo must not contain other lockfiles or tool config (e.g., yarn.lock, package-lock.json) conflicting with that choice.

Do not violate the project's architecture boundaries. Examples of violations: Controllers/Views directly querying the database; UI importing infrastructure modules; domain modules importing unrelated domains. If the repo defines boundaries (lint rules, Nx tags, dependency-cruiser, ARCHITECTURE.md), enforce them. When in doubt, route all I/O through the intended service/repository layer and keep domain logic isolated.

Ensure that `StringBuilder` instances are converted to strings using `ToString()` before use to prevent memory wastage.

Copy-pasting code can lead to errors where getters or setters access the wrong fields. Always verify that properties interact with the expected fields.

All public classes, interfaces, and methods must include Javadoc with a summary sentence, @param for each parameter, @return when not void, and @throws where applicable.

All exported JS/TS functions, classes, and public members must include JSDoc with a summary and @param/@returns; include @throws when applicable.

Docstrings must match parameter names, optional defaults, return type, and raised exceptions; update the docstring in the same PR as any signature change.

Ensure that variables that never change are marked as `const` to prevent accidental modification and enhance code clarity.

Ensure the PR title/description honestly reflects what the diff actually changes. Flag out-of-scope changes (behavioral changes hidden as refactors, unrelated dependency bumps, config/security changes) and require either: - splitting into separate PRs, or - an explicit 'Additional changes' section with rationale and risk/rollout notes.

Identify function parameters that are declared but never used within the function body. Remove them to improve clarity and maintainability.

If a PR modifies a workspace with "private": false in its package.json, enforce a .changeset/*.md entry describing semver impact for each affected package.

Do not rewrite accepted ADRs. When reversing or replacing a decision, create a new ADR with Status: accepted and add 'Supersedes: NNNN' while marking the old ADR as 'Status: superseded by NNNN'.

All Terraform/Kubernetes resources must include standard tags/labels: owner, env, cost-center (and application if available).

Every ADR must contain the sections: Context, Decision, Consequences, Status. Allowed Status values: proposed, accepted, deprecated, superseded.

Configure a remote backend with state locking (e.g., S3 + DynamoDB table or AzureRM blob with leases). Do not use local backend for shared environments.

For changes affecting public APIs or modules, include 'Versioning & Deprecation' with semantic version impact and deprecation timeline; link to CHANGELOG and deprecation notices.

Ensure that constants are declared with the `final` keyword to prevent modification.

Ensure that immutable instance fields are marked as `readonly`, and compile-time constants are marked as `const`.

Store decision records under docs/adr/ with zero-padded incremental numbering and a kebab-case title: docs/adr/NNNN-title.md (e.g., docs/adr/0001-choose-postgresql.md).

Ensure that Java records are used for immutable data structures instead of manually implementing immutable classes.

Make utility classes non-instantiable by providing a private constructor or marking them as `abstract`.

Provide a decorator/context manager that opens/closes DB sessions and handles commit/rollback automatically.

Ensure that all classes, fields, and methods are documented with JSDoc. JSDoc improves code clarity, provides documentation for developers, and helps with IDE autocompletion.

Add a CI job that validates docs/adr/ files: filename pattern, required sections, valid Status, presence of PR/issue links, and optional schema (YAML front matter).