coding-rules

Coding Rules

Reference

Read references/typescript.md only for TypeScript used in web frontend work, including React applications. It does not apply to backend or non-web TypeScript. Read references/security-checks.md when the change crosses an input, authorization, secret, persistence, or output boundary.

Source Order

Follow, in order:

1. User-required outcome, explicit constraints, repository rules, and actual consumer contracts
2. Task, acceptance criteria, Design Doc, ADR, and Work Plan as the current implementation plan
3. Representative repository patterns
4. Language/framework defaults

Use a sourced project contract in preference to generic best practice. When a planned mechanism is unnecessary or incorrect, preserve user outcomes and explicit constraints while reducing it: document passage and a generated AC do not make that mechanism mandatory. Keep the affected plan and proof aligned with the selected reduction.

Minimal Design Surface

Deliver the current requirement with the least justified total complexity. Before detailing new state, fields, modes, abstractions, or component splits, establish what required result a direct implementation cannot deliver. Evidence of a possible benefit makes the addition a candidate; retain it only when necessary now and worth its total lifecycle cost over subtraction or reuse.

Private local implementation details and test fixtures are not new design surface. If an element matches both categories, treat it as design surface. If several sufficient options remain, prefer the one with lower lifecycle cost.

Contract and Boundary Safety

• Preserve contracts required by remaining consumers and explicit user constraints; authorized removal includes the retired entry point and its unused implementation. Absence of repository call sites does not establish absence of external consumers. Resolve uncertainty only when it changes the removal or compatibility decision.
• Validate untrusted input at the boundary and encode output for its destination. Untrusted input includes request data, external service responses, model or tool output, and stored data whose writer is untrusted or whose consumer needs a guarantee the store does not make.
• When a change alters a boundary where external content or model output selects a tool's action, target, or destination, verify that those values cannot exceed the operation scope and access rights already granted to the caller.
• Propagate or handle errors with useful context and keep failures observable.
• Keep secrets and sensitive values out of source, client bundles, errors, and logs.
• Use parameterized data access and verify authorization at resource access points when applicable.
• For persistent or shared state, verify when partial, stale, committed, and rollback-only states become observable.