# {{ cookiecutter.project_name }} — Claude Reference

Auto-loaded by Claude Code at session start. Keeps the engineering
standards from `mgf-common` at hand without manual prompting.

> **Always run the four gates before committing:**
> ```
> uv run ruff check
> uv run mypy --strict src/
> uv run pytest
> uv run lint-imports
> ```

---

## Project shape

- **Package:** `{{ cookiecutter.package_name }}`
- **Python:** {{ cookiecutter.python_version }}+
- **License:** {{ cookiecutter.license }}
- **Depends on:** `mgf-common{{ cookiecutter.mgf_common_pin }}` —
  the cornerstone library + standards source-of-truth.

---

## Engineering standards (top 30, most-violated)

The full standards live in `mgf-common`. Read any topic via:

```bash
mgf-fed standards <topic>
```

Available topics: `DESIGN_PRINCIPLES`, `ERROR_HANDLING`, `LOGGING`,
`CONFIGURATION`, `SECURITY`, `TESTING`, `API_DESIGN`, `SCOPE`,
`COMMON_COMPONENTS`.

The rules below are inlined for in-session use:

### Public API (AP-*)

- **AP-01** — Every public package + module declares `__all__`.
- **AP-08** — Every public module starts with
  `from __future__ import annotations`.
- **AP-09** — Every typed package ships a `py.typed` marker.
- **AP-13** — `__version__` MUST match
  `pyproject.toml::project.version`.
- **AP-14** — Underscore-prefixed module names are private.
  Consumers MUST NOT import from them.

### Error handling (EH-*)

- **EH-01** — Subclass `mgf.common.exceptions.AppError` for the
  project's exception hierarchy. Don't define a parallel root.
- **EH-02** — Translate every third-party exception at the
  boundary that owns the call.
- **EH-08** — Concrete exceptions carry machine-readable fields
  (e.g. `CommandError.argv` / `.returncode`).

### Logging (LG-*)

- **LG-02** — Use `logging.getLogger(__name__)` for hierarchical
  naming. NEVER pass a string literal name.
- **LG-04** — Sensitive fields are redacted by default. Never log
  passwords, tokens, API keys, or session cookies.

### Configuration (CF-*)

- **CF-04** — Path resolution is LAZY — never resolve paths at
  module-import time.

### Testing (TS-*)

- **TS-04** — `pyproject.toml` sets `filterwarnings = ["error",
  ...]` so warnings escalate to test failures.

### Design principles (DP-*)

- **DP-12** — UTC time only. NEVER `datetime.utcnow()` or
  `datetime.now()` without a `tzinfo`.

### Security (SC-*)

- **SC-03** — `yaml.safe_load` only. Never `yaml.load(...)`.
- **SC-05** — PBKDF2 with ≥600 000 iterations for any
  password-derived key (OWASP 2023 baseline).

---

## Running standards-conformance audits

```bash
# Project setup audit (pin staleness, four-gate config, etc.)
mgf-fed catch-up

# Code-level conformance audit
mgf-fed app-doctor --standards
```

Both are read-only. `catch-up --apply` performs mechanical
fixes; `doctor --standards` has no auto-fix path (every finding
is a human refactoring decision).
