2026 02 18 audit

.coderabbit.yaml

@@ -0,0 +1,7 @@
+reviews:
+  path_filters:
+    - "!audit/**"
+    - "!CLAUDE.md"
+    - "!AUDIT.md"
+    - "!TESTING.md"
+    - "!.claude/**"

AUDIT.md

@@ -23,6 +23,8 @@ Each agent must write its findings to `audit/<YYYY-MM-DD>-<NN>/pass<M>/<FileName
 
 During triage, maintain `audit/<YYYY-MM-DD>-<NN>/triage.md` recording the disposition of every LOW+ finding, keyed by finding ID (e.g., A03-1). Each entry has a status: **FIXED** (code changed), **DOCUMENTED** (NatSpec/comments added), **DISMISSED** (no action needed), or **PENDING** (not yet triaged). This file is the durable record of triage progress — conversation context is lost on compaction, but the file persists. Before presenting the next finding, check the triage file for the first PENDING ID in sort order. Present findings neutrally and let the user decide the disposition.
 
+When triaging a finding as already FIXED (test already exists), apply the same rigor as writing a new fix: read the actual test code, verify it covers the finding, check for missing edge cases and boundary conditions, and add tests if gaps exist. "Test exists" is not the same as "properly tested." One finding at a time — no batch-marking.
+
 ## Pass 0: Process Review
 
 Review CLAUDE.md and AUDIT.md for issues that would cause future sessions to misinterpret instructions. This pass reviews process documents, not source code. No subagents needed — the documents are small enough to review in the main conversation. Record findings to `audit/<YYYY-MM-DD>-<NN>/pass0/process.md`.
@@ -67,6 +69,7 @@ Review all documentation for completeness and accuracy, including but not limite
 - Systematically enumerate every function in every contract and library, and verify each has NatSpec documentation
 - Explicitly list undocumented functions as findings
 - All NatSpec must include `@param` and `@return` tags as relevant for functions, structs, errors, etc.
+- When a doc block contains any explicit tag (e.g. `@title`), all entries must be explicitly tagged. Untagged lines after a tag are parsed as continuation of the previous tag, not as implicit `@notice`. Every contract/library-level doc block with `@title` must also have an explicit `@notice`.
 - After ensuring documentation exists, review it against the implementation for accuracy
 
 ## Pass 4: Code Quality

CLAUDE.md

@@ -101,17 +101,29 @@ External contracts can extend the interpreter with additional opcodes. `src/conc
 - Custom bytecode serialization is used instead of ABI encoding for gas efficiency
 - Function pointer dispatch (no switch/if chains) for opcode routing
 - Assembly blocks are used extensively and marked `memory-safe` where applicable
+- NatSpec: when a doc block contains any explicit tag (e.g. `@title`), all entries must be explicitly tagged — untagged lines continue the previous tag, not implicit `@notice`
 
 ## Test Conventions
 
+Testing patterns and conventions are in `TESTING.md`. Read that file before writing tests.
+
 - Test files are in `test/` mirroring `src/` structure, suffixed `.t.sol`
-- Base test contracts in `test/abstract/` — `OpTest` for opcodes, `ParseTest` for parser tests
-- Use `opReferenceCheck` to test opcode runtime behavior against a reference implementation
 - Rust test fixtures (`crates/test_fixtures/`) deploy all four contracts on a local Anvil instance
 
 ## Process (Jidoka)
 
-Each fix is a complete cycle: understand → fix → build → test → verify. Do not move to the next item with incomplete work. The "test" step means both: write tests for any new code paths introduced by the fix, then run the full test suite to confirm nothing is broken. New code must meet the same audit requirements defined in `AUDIT.md` — a fix that introduces untested error paths, missing NatSpec, or other audit findings is not complete. When a process defect is found, stop and fix the process before resuming. When the user asks "why" about a defect, they are asking for root cause analysis of the process failure — not requesting that you go do the thing. Answer the "why" first, agree on the process fix, then resume.
+Jidoka is a priority: process correctness (correct future) over ad hoc progress (present state). Quality at the source enables throughput; skipping quality steps creates rework and slows overall flow. Process introspection takes precedence over following the process.
+
+Each fix is a complete cycle: understand → fix → build → test → verify. Do not move to the next item with incomplete work. The "test" step means both: write tests for any new code paths introduced by the fix, then run the full test suite to confirm nothing is broken. New code must meet the same audit requirements defined in `AUDIT.md` — a fix that introduces untested error paths, missing NatSpec, or other audit findings is not complete.
+
+When the user says "jidoka," they are signaling a process defect. The response is:
+1. Identify the process defect.
+2. Propose a durable fix (document edit, rule change).
+3. **Stop and wait for agreement.** Do not resume task work, run commands, or do anything else. The process fix is the deliverable of that moment.
+
+When the user asks "why" about a defect, they are asking for root cause analysis of the process failure — not requesting that you go do the thing. Answer the "why" first, agree on the process fix, then resume.
+
+Do not claim motivations or internal states. Describe what you actually did, not a story about why. Say "I skipped the test suite run" not "I was optimizing for throughput." Say "the rule is in CLAUDE.md" not "I've internalized it." You have no metrics, no persistence, and no self-observation — narratives about your own reasoning are fabrications.
 
 ## Audit Review
 

TESTING.md

@@ -0,0 +1,41 @@
+# Testing Conventions
+
+## Base Contracts
+
+Test base contracts in `test/abstract/`:
+
+- **`RainterpreterExpressionDeployerDeploymentTest`** — Full stack deployment. Exposes `I_PARSER`, `I_INTERPRETER`, `I_STORE`, `I_DEPLOYER`.
+- **`OpTest`** — Opcode tests. Provides `opReferenceCheck()`, `checkHappy()`, `checkUnhappy()`.
+- **`ParseTest`** — Parser tests. Provides `parseExternal()`.
+- **`OperandTest`** — Operand handler tests. Provides `checkOperandParse()`.
+- **`ParseLiteralTest`** — Literal parsing tests. Provides `checkLiteralBounds()`.
+
+## Fuzz Testing
+
+- Use `bound()` to constrain fuzz inputs, not `vm.assume()`. `vm.assume()` wastes runs by discarding inputs. `vm.assume()` is acceptable when the rejection rate is low or `bound()` cannot express the constraint.
+- When fuzzing over a non-contiguous set (e.g., non-hex bytes), `bound()` to the count of valid values, then map with arithmetic to skip excluded ranges.
+- When a fuzz parameter affects expression structure, build rainlang dynamically. The fuzz variable must match what the rainlang produces.
+
+## Library Internals
+
+Internal library functions need an external wrapper in the test contract. Construct `ParseState` inside the wrapper so memory pointers are valid. Call via `this.externalFoo()`.
+
+## Revert Paths
+
+Use `vm.expectRevert` with `abi.encodeWithSelector` and the custom error type. Call through `this.externalFoo()` for library functions or directly on `I_PARSER`/`I_INTERPRETER` for integration tests.
+
+## Bytecode Construction
+
+Use the parse library to generate bytecode from rainlang when the test needs valid bytecode. Only hand-encode bytecode when the test intentionally needs invalid or malformed bytecode that the parser cannot produce.
+
+## Bytecode Inspection
+
+Use `LibBytecode` from `rain.interpreter.interface/lib/bytecode/LibBytecode.sol`. Do not manually index into bytecode bytes.
+
+## Opcode Testing
+
+Use `opReferenceCheck` to validate that `run` output matches a pure reference implementation and that `integrity` correctly declares inputs/outputs.
+
+## Boundary Tests
+
+Always test both sides: the max valid value (should succeed) and one past it (should revert).