Acorn's code-conventions.md

gistfile1.txt

## Code conventions (Foony)

# Coding pattern preferences
- Always prefer simple solutions
- Avoid duplication of code whenever possible, which means checking for other areas of the codebase that might already have similar code and functionality
- You are careful to only make changes that are requested or you are confident are well understood and related to the change being requested

### Defaults
- **Private-by-default**: make members/functions `private` unless external callers require otherwise.
- **`const`-by-default**: use `const` unless reassignment is required.
- **Export sparingly**: do **not** `export` unless used outside the module.
- **Class / method order**: Public / exported classes / methods should be at the top of files, and private / internal classes / methods should be at the bottom.
- **Descriptive names**: variable names should be descriptive.
  - Exception: `for (let i = ...)` where `i` clearly denotes an index.

### Formatting
- **Rectangle rule**: format code in consistent “rectangles” (predictable indentation, aligned blocks, minimal jagged structure).

### Simplicity (avoid over-engineering)
- **YAGNI by default**: don’t add “just in case” features (flags, modes, abstractions, plugin systems).
- **Start minimal**: implement the smallest working version; iterate only when there’s a concrete need.
- **Prefer direct code over frameworks**: a few lines in one place beats a new abstraction with multiple files.
- **No speculative safety rails**: don’t add extra guards/validators unless there’s a real failure mode observed.
- **Minimize surface area**:
  - Avoid adding new options/parameters unless they’re actively used.
  - Prefer one clear path over multiple interchangeable paths.
- **Optimize for the next reader**: reduce indirection; keep logic close to where it’s used.

### Accessing PGSQL Database
- You have read-only access to the Foony PGSQL database. Example query:
```bash
bash scripts/llm/pg_query.sh "SELECT now();"
```
- DDL for Postgres lives in `server/schema.sql`. **Index-tuning diagnostics** (`pg_stat_*` queries, read proxy usage for those) are documented in `.claude/rules/postgres-index-prioritization.md` (scoped: that file or when the user asks for index optimization).
- **Changing the schema (declarative — psqldef)**: `server/schema.sql` is the single source of truth describing the **desired end state**, not a migration log. To change the schema, **edit `server/schema.sql` directly** so the table/column/index reads as it should finally look — do **not** write imperative migration steps (`ALTER TABLE`, `CREATE INDEX CONCURRENTLY`, `DROP TABLE`) or a separate "production migration" note. The user then runs `server/update_schema.sh` (dry-run by default; `--apply` to apply, add `--drop` when the change removes/renames a table/column/index); psqldef diffs schema.sql against the live DB and emits the needed DDL. **You don't run it** — leave schema.sql in the target state and tell the user whether `--drop` is required.

## Git Workflow

- Do **not** commit or push automatically — wait for the user to ask before running `git commit` or `git push`.
- When the user asks you to commit, break changes up into logical, reviewable commits, each focused on one concern.
- Commit only the changes you made. Leave unrelated working-tree changes untouched.
- Do not **push** unless you've been asked to by the user.