solpbc.org
personal memory agent
1# Coding Standards
2
3## Language & Tools
4
5- **Ruff** (`make format`) - Formatting, linting, and import sorting
6- Configuration in `pyproject.toml`
7
8## Naming Conventions
9
10- **Modules/Functions/Variables**: `snake_case`
11- **Classes**: `PascalCase`
12- **Constants**: `UPPER_SNAKE_CASE`
13- **Private Members**: `_leading_underscore`
14
15## Code Organization
16
17- **Imports**: Prefer absolute imports, grouped (stdlib, third-party, local), one per line
18- **Docstrings**: Google or NumPy style with parameter/return descriptions
19- **Type Hints**: Should be included on function signatures (legacy helpers may still need updates)
20- **File Structure**: Constants → helpers → classes → main/CLI
21
22## File Headers
23
24All source code files (but not text or markdown files or prompts) must begin with a license and copyright header:
25
26```
27# SPDX-License-Identifier: AGPL-3.0-only
28# Copyright (c) 2026 sol pbc
29```
30
31Use `//` comments for JavaScript files.
32
33## Development Principles
34
35- **DRY, KISS, YAGNI**: Extract common logic, prefer simple solutions, don't over-engineer
36- **Single Responsibility**: Functions/classes do one thing well
37- **Conciseness & Maintainability**: Clear code over clever code
38- **Robustness**: Minimize assumptions that must be kept in sync across the codebase, avoid fragility and increasing maintenance burden.
39- **Self-Contained Codebase**: All code that depends on this project lives within this repository—never add backwards-compatibility shims, fallback aliases, re-exports for moved symbols, deprecated parameter handling, or legacy support code. When renaming or removing something, update all usages directly. For journal data format changes, write a migration script (see [docs/APPS.md](docs/APPS.md) for `maint` commands) instead of adding compatibility layers.
40- **Trust system path resolution**: Never set `SOLSTONE_JOURNAL` or bypass `get_journal()` from application code, agent prompts, subprocess environments, or service files. Source-checkout installs inherit it from the managed bash wrapper at `~/.local/bin/sol`; packaged installs (`uv tool install` / `pipx install`) rely on `get_journal()` for default resolution; tests use the autouse fixture; Makefile sandboxes set it explicitly. See `environment.md`.
41- **Security**: Never expose secrets, validate/sanitize all inputs
42- **Performance**: Profile before optimizing
43- **Git**: Small focused commits, descriptive branch names. Run git commands directly (not `git -C`) since you're already in the repo.
44
45## Dependencies
46
47- **Minimize Dependencies**: Use standard library when possible
48- **All Dependencies**: Add to `dependencies` in `pyproject.toml`
49- **Package Manager**: [uv](https://docs.astral.sh/uv/) — lock file (`uv.lock`) is committed, `make install` syncs from it
50- **Installation**: `make install` (creates isolated `.venv/` and syncs deps from the lock file for repo-local development)
51- **Updating**: `make update` upgrades all deps to latest and regenerates the lock file
52
53## Layer Hygiene
54
55The L1–L9 layer-hygiene invariants (read/write separation, domain write ownership, naming contracts, CLI verb polarity, indexer/importer/hook/event-handler rules) are inlined in `AGENTS.md` §7. They're promoted to the coder guide because a codebase-wide audit in April 2026 found 14 violations across `solstone/think/` and `solstone/apps/`, and a one-click-away invariant is a routinely-skipped invariant.
56
57Enforcement: `scripts/check_layer_hygiene.py`, wired into `make ci`. Known audit-flagged files are allowlisted with audit-reference TODOs; the allowlist shrinks as remediation bundles ship.
58
59**Go to `AGENTS.md` §7 for the full rules and the domain ownership table.**