Maintainability rules

Avoid functions or extensions deprecated in recent PHP versions (e.g., mysql_* or preg_replace without proper delimiters). Use modern supported alternatives like PDO/MySQLi for DB or PCRE functions (preg_match, preg_replace with correct syntax).

When a TS package depends on another workspace package, tsconfig.json must set "composite": true and include a "references" entry to the dependency; root must aggregate paths via tsconfig.base.json if used.

Move magic values (strings, thresholds, paths) to module-level constants with descriptive names.

When the same set of attribute/field names is used in multiple places (strong params, serializers, queries), extract it to a constant and reuse.

Move repeated sequences of operations into named helpers or utilities and reuse them.

Parameterize tool/runtime versions via ARGs (and CI build args) instead of hardcoding them across multiple Dockerfiles.

Replace raw numeric/string literals used for dimensions, durations, and thresholds with named constants.

Define SQL strings as static final constants or in a repository, not inline across methods.

Centralize queue names and reuse across workers and tests.

The first sentence should be a standalone summary used by godoc. For functions returning error, state error conditions succinctly.

Keep public types in files with matching names (one top-level type per file) to improve navigation.

Freeze constant objects (arrays/hashes/strings) to avoid accidental mutation at runtime.

List all included builds/modules in settings.gradle and manage versions via gradle/libs.versions.toml (version catalogs). Forbid hardcoded versions and repo declarations in module build.gradle files.

Use template helpers to set metadata.name and labels (app.kubernetes.io/) consistently across templates; prohibit hardcoded mismatches.

Changes that create new ePHI stores must also include retention configuration and a scheduled purge job aligned to policy (e.g., 6 years). Document tables/collections covered and add tests for TTL behavior.

When a PR implements or changes a decision, include 'ADR: docs/adr/NNNN-title.md' in the PR description and reference it in the merge commit body.

Reference at least one tracking ID (e.g., JIRA/GitHub issue) in the PR description using a consistent format (e.g., 'Refs: ABC-123').

Keep docs/adr/README.md updated with a table of ADRs (number, title, status, date). Update the index in the same PR that adds/changes an ADR.

Expose constant dicts as read-only via MappingProxyType (or frozen dataclasses) to prevent runtime mutation.

Check if properties that are never reassigned are marked as readonly. This improves code clarity and prevents unintended reassignment.

Store long static templates/prompts in files and load them at runtime; avoid embedding huge multi-line strings in code.

Check if type aliases are used instead of interfaces. Interfaces provide better extensibility and readability when defining object shapes.

Avoid re-creating existing UI components or duplicating styles (CSS/Tailwind) when the company design system already provides an official component. If the PR touches UI and a design system entry point is referenced (e.g., `ui/index.ts`, `design-system.md`), use it as the source of truth and suggest the equivalent official component.

Check for functions with unused parameters and ensure they are titled with `_` or `__` to indicate they are intentionally unused.