mnemosyne/CLAUDE.md

## 🐾 Red Panda Approval™

The standard every change is judged against. Don't satisfy a checklist —
satisfy the red pandas. Ask of each change: *does this earn approval?*

1. **Fresh Migration Test** — migrations apply cleanly from an empty database.
2. **Elegant Simplicity** — no unnecessary complexity; the obvious solution, done well.
3. **Observable & Debuggable** — proper logging; failures say what broke and why.
4. **Consistent Patterns** — follows Django conventions and the patterns already in this repo.
5. **Actually Works** — passes all checks *and* serves a real user need.

Criteria 1 and 5 are **externally verifiable** — migrations apply or they
don't; checks pass or they don't. Verify them, don't assert them. Criteria
2–4 are judgement calls: when in doubt, match what the repo already does
rather than grading your own elegance.

> If a paw print isn't leading the response, the rest of this file probably
> isn't being honoured either. Lead with one. 🐾

---

## Conventions (always-on)

These are the rubric made concrete for the common case — writing models,
views, forms, templates, and queries.

### Models
- Names: singular PascalCase (`User`, `BlogPost`, `OrderItem`).
- Every model defines `__str__` and `get_absolute_url`.
- Every model has `created_at = DateTimeField(auto_now_add=True)` and
  `updated_at = DateTimeField(auto_now=True)`.
- `TextChoices` for status fields.
- `related_name` on every `ForeignKey`; plural snake_case with correct
  English pluralisation.
- Public-facing models: consider `UUIDField` primary key and
  `is_active` for soft deletes.

### Field naming
- Foreign keys: singular, no `_id` suffix (`author`, `category`, `parent`).
- Booleans: prefixed (`is_active`, `has_permission`, `can_edit`).
- Dates: suffixed (`created_at`, `updated_at`, `published_on`).
- No abbreviations (`description`, not `desc`).

### Views
- **Function-based views exclusively.** Explicit logic over implicit
  inheritance. Extract shared logic into utility functions.
- Business logic lives in service functions, not views and not `save()`.

### Forms
- `ModelForm` with an explicit `fields` list — never `__all__`, never `exclude`.
- Validate at the boundary; never trust client-side validation alone.

### Queries
- `select_related()` for FKs; `prefetch_related()` for reverse and M2M.
- No queries inside loops (N+1). No `.all()` when you need a subset.
- `.only()` / `.defer()` for large models. Comment non-obvious querysets.

### URLs & identifiers
- Public URLs use 12-char short UUIDs via `shortuuid`. Never expose
  sequential IDs (enumeration risk). Internal refs may use PKs.
- Resource-based, namespaced URL names per app, trailing slashes, flat
  structure preferred.

### Docstrings
- **Google style.** Document public classes, functions, methods, modules.
- Imperative one-line summary. `Args:`/`Returns:`/`Raises:` only when the
  signature doesn't already convey it. Don't restate type hints in prose.
- Skip obvious one-liners and standard Django overrides.

### Code organisation
- PEP 8 import ordering (stdlib, third-party, local). Type hints on params.
- CSS and JS in external files only — no inline styles, `<style>`,
  inline handlers, or `<script>` blocks.
- File length: split by domain concept past ~500 lines; hard ceiling 1000.

### Testing
- Django `TestCase` (not pytest). Separate files per module:
  `test_models.py`, `test_views.py`, `test_forms.py`.

An app isn't done until it's reachable
django-admin startapp builds an island. A complete-from-its-own-boundary
app — models, views, urls, templates, tests all present and passing — is

# Add to always-on Django CLAUDE.md — Conventions section
 
Insert this block under "Conventions (always-on)", as its own subsection.
It is the universal Django definition-of-done. It fires for *every* app,
not just registered tools.

### An app isn't done until it's reachable
 
`django-admin startapp` builds an **island**. A complete-from-its-own-boundary
app — models, views, urls, templates, tests all present and passing — is
still *unfinished* if nothing in the running site links to it. "It works in
isolation" is not done; **"a user can reach it from the running site" is done.**
 
Before reporting a new app complete, wire it into the site:
 
1. **`INSTALLED_APPS`** — add the app's config.
2. **Root URLconf** — `include()` the app's `urls.py` in `config/urls.py`.
   An app whose URLconf isn't included has unreachable views, full stop.
3. **Navigation / discovery** — register the app so it surfaces wherever
   this project expects apps to appear. This project uses an **app
   registry** (see Project Setup): the app registers itself in its own
   `apps.py.ready()` and the navigation template tag picks it up. Do **not**
   hand-edit nav templates or central list views — they read from the
   registry.
4. **Verify reachability** — confirm the app's main page actually loads
   from the running site (not just that its tests pass). Per Red Panda
   criterion 5, this is externally verifiable: load the page, don't assert
   it works.
Why this rule exists: an LLM reasons locally and closes the visible task at
the app's own boundary. The wiring that makes an app reachable lives in
*other* files (`config/urls.py`, `INSTALLED_APPS`, the registry) with no
signal inside the new app pointing to them. Without this rule, the
near-certain result is a fully-built, completely inaccessible app. The
registry exists precisely so that "surface it" happens *inside* the app's
own boundary (a `register()` call in `ready()`) — collapsing the wiring
into the one place local reasoning will actually look.
 
> The same principle generalises beyond Django: a new route that isn't
> mounted, a CLI subcommand not added to the dispatcher, a handler not
> registered — all the same failure. Done means *connected*, not *written*.

---

## Always-on anti-patterns

The cross-cutting tripwires worth carrying everywhere. File-specific
landmines (nginx, compose, broker) are in path-scoped rules.

- **Models:** no `.get()` without handling `DoesNotExist`; no `null=True`
  on `CharField`/`TextField` (use `blank=True, default=""`); always specify
  `on_delete`; don't override `save()` for business logic; no
  `Meta.ordering` on large tables.
- **Security:** secrets via env vars, never in `settings.py`; never commit
  `.env`; never `DEBUG=True` in production; never `mark_safe()` on
  user-supplied content; never disable CSRF.
- **Templates:** `{% url %}` not `{{ variable }}` for URLs; no logic in
  templates; `{% csrf_token %}` in every form.
- **Imports/style:** no `import *`; no mutable default args; no bare
  `except:`; don't silence linter warnings without a documented reason.

---

## Environment

- Virtual environment: `~/env/PROJECT/bin/activate` (replace PROJECT).
- `pyproject.toml` for config — no `setup.py`, no `requirements.txt`.
- Dependencies floor-pinned with ceiling (`Django>=5.2,<6.0`). Exact `==`
  pins only in application lock files, never in reusable packages.
- Dev DB: SQLite. Production DB: PostgreSQL.

---

## Path-scoped rules to create (`.claude/rules/`)

These hold the landmines extracted from the standards doc. Each loads only
when its `paths` match, keeping this file lean. Frontmatter shown.

- **`nginx.md`** — `paths: ["nginx/**", "**/*.conf"]` — reverse-proxy
  reference config: Docker DNS resolver + variable `proxy_pass`,
  `$proxy_x_forwarded_proto` map, access-log filtering, RFC1918 allowlists
  (all four ranges), `always` security headers.
- **`docker-compose.md`** — `paths: ["docker-compose*.y*ml", ".env*"]` —
  per-service `environment:` scoping (no shared `env_file:`), `${VAR}`
  interpolation, `.env.example` annotation convention, the `repr()` parse
  diagnostic.
- **`celery-tasks.md`** — `paths: ["**/tasks.py"]` — idempotency, retry
  logic, pass IDs not instances, synchronous-by-default, broker URL
  percent-encoding, progress pattern `{app}:task:{task_id}:progress`.
- **`migrations.md`** — `paths: ["**/migrations/**"]` — never edit deployed
  migrations; `RunPython` needs a reverse; no non-nullable field without a
  default; meaningful `--name`; test forward and backward.
- **`memcached.md`** — `paths: ["**/settings.py", ".env*"]` — bind
  `0.0.0.0` not localhost; container can't reach `127.0.0.1`; LAN hostname
  in `KVDB_LOCATION`; key pattern `{app}:{model}:{identifier}:{field}`.
- **`frontend.md`** — `paths: ["**/templates/**", "**/static/**"]` — DaisyUI+
  Tailwind for new projects / Bootstrap 5 for existing; extend
  `themis/base.html`; no inline styles or scripts.

## Reference docs (consult on demand, don't inline)

- `docs/` gotcha writeups: broker-URL/Kombu parsing, env-file parsing
  differences, nginx IP-caching. State the rule in the rule file; link the
  *why* here.
- Preferred-packages list and per-app architecture: keep in `docs/`, not in
  this always-on file.