git:20260716.aea9523 to git:20260719.3848a77

2 added, 2 removed. Audit A to A.

---

name: coding-rules

description: "Language-agnostic coding standards for maintainability, readability, and quality. Use when: implementing features, refactoring code, reviewing code quality, or writing functions."

---

# Coding Rules

## Language-Specific References

For language-specific rules, also read:

- **TypeScript/React**: [references/typescript.md](references/typescript.md)

## Core Philosophy [MANDATORY]

1. **Maintainability over Speed**: Prioritize long-term code health

2. **Simplicity First**: YAGNI principle — simplest solution that meets requirements

- 3. **Design Convergence**: Deliver the current required outcome with the least new design surface. Use "Design Surface Terms" below for classification and implementation-approach for design selection.

+ 3. **Design Convergence**: Deliver the current required outcome with the least new design surface. Add surface only to satisfy a current requirement, verified constraint, observed problem, or evidence-backed material risk; among sufficient options, choose the lowest-lifecycle-cost option.

4. **Explicit over Implicit**: Clear intentions through code structure and naming

5. **Delete over Comment**: Remove unused code instead of commenting it out

**ENFORCEMENT**: Every code change MUST align with these principles

## Design Surface Terms [MANDATORY]

Use these definitions when classifying Design Convergence additions or code-review escalation.

- **Maintenance-surface-bearing elements**: persistent state; public-contract or cross-boundary fields/props; behavioral modes, flags, or variants; reusable abstractions; extracted services; shared utilities; component splits.

- **Non-surface elements**: private local variables, internal helper functions with no external observers, test fixtures or mocks, temporary migration scaffolding removed before completion, and private implementation details confined to one function or file.

- **Classification precedence**: When an element matches both surface-bearing and non-surface conditions, classify it as surface-bearing.

- - **Selection rule**: Follow implementation-approach Design Convergence for design selection. These terms classify design surface; they do not define a second selection process.

+ - **Selection rule**: Add a surface-bearing element only when it is required by a current requirement, verified constraint, observed problem, or evidence-backed material risk. Prefer fewer new elements only when the remaining candidates are otherwise sufficient and equivalent.

- **Relation to YAGNI**: YAGNI decides present vs. future need over time; Design Convergence minimizes surface area for the current accepted scope.

## Code Quality [MANDATORY]

- Resolve technical debt within confirmed scope or dependencies required for its outcome; report other debt separately

- Use meaningful, descriptive names from the problem domain

- Extract magic numbers and strings into named constants

- Keep code self-documenting

## Function Design [MANDATORY]

- **0-2 parameters** per function (use objects for 3+)

- Single responsibility — each function MUST do one thing well

- Keep functions < 50 lines

- Use pure functions where possible — separate data transformation from side effects

- Use early returns to keep nesting ≤ 3 levels

- **Inject external dependencies explicitly** — pass as parameters for testability

## Error Handling [MANDATORY]

- **Always handle errors**: Log with context or propagate explicitly — error suppression is PROHIBITED

- **Fail fast**: Detect and report errors early

- **Protect sensitive data**: Mask passwords, tokens, PII from logs

- Use language-appropriate error handling mechanisms

- Include error context when re-throwing

**ENFORCEMENT**: Zero silent error suppression — every error MUST have log output and appropriate handling

## Dependency Management

- **Inject external dependencies explicitly** — pass as parameters for testability

- Depend on abstractions, not concrete implementations

- Minimize inter-module dependencies

## Reference Representativeness

### Verifying References Before Adoption

When adopting patterns, APIs, or dependencies from existing code:

- If referencing only nearby files, verify the pattern is representative across the repository before adopting it

- If multiple approaches coexist, identify the majority pattern and make a deliberate choice

- If adopting an external dependency, verify repository-wide usage distribution for that dependency and its version

- If repository evidence is insufficient to choose an appropriate dependency version, escalate instead of guessing

- If following an existing pattern when alternatives exist, state the reason for following it

### Principle

Nearby code is a starting point for investigation, not a sufficient basis for adoption. Confirm that the reference is representative of repository conventions before using it as the model.

## Performance

- **Measure first**: Profile before optimizing — no premature optimization

- Focus on algorithms over micro-optimizations

- Choose data structures based on access patterns

## Code Organization

- One primary responsibility per file

- Group related functionality together

- Separate concerns: domain logic, data access, presentation

- Keep files ≤ 500 lines

## Commenting Principles

- Prefer names, types, and structure over comments

- Add comments only for why, limitations, edge cases, or public API contracts

- No historical information — use version control

- Remove commented-out code

- Keep comments concise and timeless

## Refactoring [SAFE CHANGE PROTOCOL]

**STEP 1**: Understand current state

**STEP 2**: Make one small change

**STEP 3**: Run tests — confirm all pass

**STEP 4**: Repeat from STEP 2

**Triggers**: duplication, functions > 50 lines, complex conditionals

**ENFORCEMENT**: Each step MUST maintain working state

## Security

### Secure Defaults

- Store credentials and secrets through environment variables or dedicated secret managers

- Use parameterized queries (prepared statements) for all database access

- Use established cryptographic libraries provided by the language or framework

- Generate security-critical values (tokens, IDs, nonces) with cryptographically secure random generators

- Encrypt sensitive data at rest and in transit using standard protocols

### Input and Output Boundaries

- Validate all external input at system entry points for expected format, type, and length

- Encode output appropriately for its rendering context (HTML, SQL, shell, URL)

- Return only information necessary for the caller in error responses; log detailed diagnostics server-side

### Access Control

- Apply authentication to all entry points that handle user data or trigger state changes

- Verify authorization for each resource access, not only at the entry point

- Grant only the permissions required for the operation (files, database connections, API scopes)

### Knowledge Cutoff Supplement (2026-03)

- OWASP Top 10:2025 shifted from symptoms to root causes; added "Software Supply Chain Failures" (A03) and "Mishandling of Exceptional Conditions" (A10)

- Recent research indicates AI-generated code shows elevated rates of access control gaps — treat authentication and authorization as high-priority review targets

- OpenSSF published "Security-Focused Guide for AI Code Assistant Instructions" — recommends language-specific, actionable constraints over generic advice

- For detailed detection patterns, see `references/security-checks.md`

## Version Control [MANDATORY]

- Atomic, focused commits with clear messages

- Commit working code that passes all tests

- Never commit debug code or secrets

**ENFORCEMENT**: Code MUST pass all quality checks before commit