Seriously Crash? You can not even have agents record work? Clone Toastie by accident? Senpai is mad at you.HEADmaster

1 files changed, 59 insertions, 40 deletions

diff --git a/AGENTS.md b/AGENTS.md
index c3c0acd..7b5cf40 100644
--- a/AGENTS.md
+++ b/AGENTS.md
@@ -2,7 +2,7 @@
 
 ## Documentation
 
-User-facing documentation is in `README.asciidoc`. Agent notes go in `./llm/` (note: this folder is now gitignored for security).
+User-facing documentation in `README.asciidoc`. Agent notes in `./llm/` (gitignore'd for security).
 
 ## Contact
 
@@ -12,52 +12,71 @@ Community XMPP MUC: xmpp:nixtamal@chat.toastal.in.th?join
 
 ## Build/Lint/Test Commands
 
-### Traditional Nix Commands
+### Traditional Nix
 - Build: `nix-build release.nix` or `nix build`
 - Test all: `nix-build release.nix -A check` or `dune runtest`
-- Run single test: `dune runtest --filter <test_name>` (use with alcotest test names)
+- Single test: `dune runtest --filter <test_name>` (alcotest names)
 - Format: `dune build @fmt` (ocamlformat)
 - Clean: `dune clean`
 
-### Nix Flake Commands
-- Build: `nix flake build` or `nix build .#nixtamal`
-- Dev shell: `nix develop` or `nix shell .#devShell`
+### Nix Flake
+- Build: `nix build .#nixtamal`
+- Dev shell: `nix develop`
+- Coverage: `BISECT_ENABLE=YES dune runtest --instrument-with bisect_ppx --force`
+- Coverage report: `bisect-ppx-report summary --coverage-path _build/default/test`
+
+### CI Coverage
+`.github/workflows/coverage.yml` runs tests with bisect_ppx, uploads reports.
 
 ## Code Style Guidelines
-- **Formatting**: Use ocamlformat (auto-formatted via dune @fmt)
-- **Indentation**: Tabs for OCaml, spaces for Nix/dune files (per .editorconfig)
-- **Naming**: Modules CamelCase, functions/values snake_case, types lowercase
-- **Imports**: `open` for common modules (e.g., Name), qualified otherwise
-- **Types**: Use records with `[@@deriving show, eq, make, qcheck]` for testability
-- **Error Handling**: Prefer `Result` over exceptions; use `Error` module for custom errors
-- **Comments**: SPDX headers required; TODOs for future work
-- **Line Length**: No strict limit, but aim for readability
-- **Pattern Matching**: Exhaustive, use `|` for clarity
+- Formatting: ocamlformat (`dune @fmt`)
+- Indentation: Tabs for OCaml, spaces for Nix/dune (.editorconfig)
+- Naming: Modules CamelCase, functions snake_case, types lowercase
+- Imports: `open` common modules, qualified otherwise
+- Types: Records with `[@@deriving show, eq, make, qcheck]`
+- Error Handling: `Result` over exceptions; custom `Error` module
+- Comments: SPDX headers; TODOs for future work
+- Pattern Matching: Exhaustive with `|`
+
+## Nix Engineering Principles
+- **READ** `/speed-storage/opencode/llm/shared/` Nix files before Nix ops
+- **No Home-Manager**: Pure Nix configs only
+- **Declarative**: Never imperative `nix-env`, `nix-channel`
+- **Tooling**: `nix-shell -p <pkg> --run <cmd>` - never install to env
+- Dev shell includes checkInputs for bisect_ppx, alcotest, qcheck
 
 ## Ongoing Integrations
 
-### Nilla Framework (In Progress)
-
-Adding first-class support for https://github.com/nilla-nix/nilla[Nilla], a Nix framework with loaders and module system.
-
-**Status**: Types, codecs, and manifest serialization implemented. Prefetch not yet implemented.
-
-**Files modified**:
-- `lib/input.ml` - Nilla module with Reference type, Kind variant
-- `lib/manifest.ml` - KDL codec for Nilla input type
-- `lib/error.ml` - Added Nilla to prefetch_method, Not_implemented error
-- `lib/prefetch.ml` - Stub returning "not yet implemented"
-- `lib/input_foreman.ml` - Display and needs_prefetch logic
-- `lib/lock_loader.ml` - Feature constant
-- `lib/lockfile.ml` - Lockfile serialization
-- `lib/nixtamal.ml` - meld_input_with_lock support
-
-### Future Integrations
-- Additional VCS support as needed
-- Migration utilities (flakes, npins, niv)
-
-## Agent Notes
-- After each major change, create comprehensive notes in `./llm/` folder
-- Use the template in `./llm/README.md` (if present)
-- Document learnings, challenges, solutions, and insights for future reference
-- **Flake integration changes** should be specifically documented with strategic reasoning
+### Nilla Framework (Phase 2.5)
+Types, codecs, manifest serialization complete. Prefetch stubbed ("not yet implemented").
+
+**Files**:
+- `lib/input.ml`: Nilla Reference/Kind
+- `lib/manifest.ml`: KDL codec
+- `lib/error.ml`: Nilla prefetch_method
+- `lib/prefetch.ml`: Stub
+- `lib/input_foreman.ml`: Display/prefetch logic
+- `lib/lock_loader.ml`: Feature flag
+- `lib/lockfile.ml`: Serialization
+- `lib/nixtamal.ml`: meld support
+
+### Fossil VCS (Complete)
+Full support: input type, manifest/lockfile codecs, prefetch (`nix-prefetch-fossil`), lock_loader Nix gen.
+
+### Tests/Coverage (Recent)
+- `test_upgrade.ml`: Schema upgrade (backup, dry-run, validation)
+- `test_fossil.ml`: Fossil codec/roundtrip
+- `test_lockfile.ml`: Auto-creation, serialization
+- bisect_ppx instrumentation + CI workflow
+
+## Agent Workflow
+- **Drone Selection**: @Bellana-Drone (cheap) for small changes, @TPol for adversarial verification after each task
+- **Verification**: Always build (`nix build .#nixtamal`) + test (`dune runtest`) + coverage after changes
+- **Phased Remediation Plan**: Phase 1 (security) complete. Phase 2: Replace failwith → Result in nixtamal.ml/input_foreman.ml
+- **Commits**: Use CrashOverBurn identity. No force-push to main.
+
+## Development State (Apr 15 2026)
+- Working tree clean, master ahead origin/master by 3 commits
+- Features: Fossil VCS, schema upgrade, lockfile auto-creation, bisect_ppx coverage (17 tests passing)
+- Roadmap: Phase 2 (correctness), Phase 3 (Fossil/Nilla lock_loader), Phase 4 (80% coverage), Phase 5 (refactor)
+- Agent notes gitignored in `./llm/`
\ No newline at end of file