strawberry/CLAUDE.md
trvon 50254dc8cc
All checks were successful
release / draft (push) Has been skipped
release / build (debian:trixie, trixie) (push) Successful in 31m52s
release / build (ubuntu:24.04, noble) (push) Successful in 29m30s
release / publish (push) Has been skipped
Docs: codify the system + lean AGENTS/CLAUDE for open-source navigation
- README: front door states the full system (core + experimental shadow-only
  inspection model + distributed fleet learning); new "Fleet learning" usage
  section; learn/ + fleet_export/merge + governor in Architecture; a proper
  "Documentation" map; license corrected MIT -> GPLv3 (matches LICENSE).
- AGENTS.md: crisp YAMS work-loop (retrieve/inspect/persist/report), replaced
  the stale ~64-line dated "Current Project Reality" with an accurate concise
  state + pointers (PLAN/DEVELOPER/git/YAMS), trimmed stale work-order/milestone,
  added "Keep This File Lean".
- CLAUDE.md: work-loop + evidence rule up top.
- gitignore the local validation/attack-range harness (deploy/validation/{docker,vm}).

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
2026-11-08 10:41:05 -07:00

2.4 KiB

CLAUDE.md

Read 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 (claim → checkpoints → handoff; plans, decisions and evidence live in YAMS, hydrated by hash before use).
  • Audits: 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 (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.