# CLAUDE.md Read [AGENTS.md](AGENTS.md) first: it holds this repository's rules, current reality, guardrails and the per-change check table. This file only points at the shared workflow. Work loop: **retrieve → inspect → act → verify → persist → report** (YAMS-first; see AGENTS.md "Operating Model"). Validate material claims — code behavior, paths, command syntax, versions, counts, completion status — against current source or tool output before asserting them; a successful edit is not a working feature and a passing test covers only what it exercises. - **Memory and retrieval**: YAMS-first loop in [docs/prompts/PROMPT-eng-codex.md](docs/prompts/PROMPT-eng-codex.md) (claim → checkpoints → handoff; plans, decisions and evidence live in YAMS, hydrated by hash before use). - **Audits**: [docs/prompts/PROMPT-strawberry-audit.md](docs/prompts/PROMPT-strawberry-audit.md): brick (structure), fold (`scripts/fold_changed.sh`, bounded symbolic SAST), pipe (`enum class` state flow). - **Before calling a change done**: the "Per-change checks" table in AGENTS.md (meson tests incl. source invariants and fault injection, clang-tidy on changed files, `make analyze` (clang static analyzer, strict) on changed TUs, `make fuzz`, fold on changed TUs, live Docker tests, `make perf-kpi`). Index the change in YAMS at each checkpoint, before and after. - **Performance & C++**: heavy or hot-path changes carry a constrained-lane KPI (`make perf-kpi`, `scripts/perf_kpi_report.py --compare`, 3 repeats) and Tracy zones (`STRAWBERRY_ZONE`, `-Denable_profiling=true`) recorded in `PerfStats` and surfaced in status `timings`. Code reading is not evidence. - **CLI changes**: follow [docs/cli-ux.md](docs/cli-ux.md) (yams-style `noun verb` table in `src/cli_commands.cpp`, `--json` contract, exit codes, terminal-safe output, "adding a command" checklist). - **Never leave a `catch` empty**: handle it, or record it with `STRAWBERRY_NOTE_SWALLOWED()` (`include/strawberry/swallowed.hpp`). Enforced by source invariant R7 and clang-tidy `bugprone-empty-catch` (`.clang-tidy`). - **This machine**: builds and tools run niced and capped (`nice -n 19`, `-j2`, Docker `--cpus=2`); an uncapped fold build has frozen it before. - **Plans in flight**: YAMS `task=strawberry-data-engine` (staged data engine + online learning), `task=strawberry-settings-ux`, `task=strawberry-encoder`.