# Coding Standards And Engineering Goals

## Scope
This document defines coding standards and engineering goals for the project.

## How To Use This File
1. Use this file during implementation and code review.
2. Apply these rules to PHP, JavaScript, CSS, and project documentation.
3. Treat Must items as required and document any Should exceptions.

## Engineering Goals
1. Keep implementation simple, readable, and maintainable.
2. Preserve safe default behavior for routing, rendering, and user-facing errors.
3. Minimize regressions by keeping UI behavior and navigation stable.
4. Keep docs synchronized with code behavior.

## Must (Coding Gate)
- [ ] Escape dynamic PHP output in HTML context.
- [ ] Keep route keys sanitized and allow-listed.
- [ ] Avoid introducing user-controlled dynamic include paths.
- [ ] Keep shared logic in shared files instead of duplicating behavior.
- [ ] Keep naming consistent across route key, label, and title.
- [ ] Update related docs when behavior or policy changes.

## Should (Expected Practices)
- [ ] Prefer small, scoped changes over large mixed refactors.
- [ ] Prefer reusable CSS classes over repeated inline styles.
- [ ] Keep page-level scripts minimal and move reusable logic to assets/app.js.
- [ ] Add brief rationale notes for non-obvious decisions.

## Could (Optional Maturity)
- [ ] Add static lint checks for PHP, JS, and CSS.
- [ ] Add lightweight architecture decision log for major changes.
- [ ] Add style tokens checklist for consistent UI semantics.

## Sign-Off Record
- [ ] Must items complete.
- [ ] Any Should exceptions documented and approved.
- [ ] Reviewer confirms standards conformance.