2026 02 17 audit

.gitignore

@@ -11,4 +11,3 @@ docs
 
 # This is for our deploy scripts that report the addresses of deployed contracts
 deployments
-audit

AUDIT.md

@@ -1,9 +1,11 @@
 # Audit Review
 
-An audit consists of four separate passes. All four passes are mandatory. Do not combine them into a single pass. Each pass must be run as its own separate conversation to avoid hitting context limits.
+An audit consists of the passes defined below. All passes are mandatory. Do not combine them into a single pass. Each pass must be run as its own separate conversation to avoid hitting context limits.
 
 Each pass will need multiple agents to cover the full codebase. When partitioning files across agents, assign one file per agent. This ensures each agent reads its file thoroughly rather than skimming across many files. For passes that require cross-file context (e.g., Pass 2 needs both source and test files), the agent receives the source file plus its corresponding test file(s) — this is still a single-file-per-agent partition from the source file perspective.
 
+Agents are assigned sequential IDs (A01, A02, ...) based on alphabetical order of their source file paths. Each agent prefixes its findings with its ID (e.g., A03-1, A03-2). This produces a stable global ordering: sort by agent ID, then by finding number within each agent. The ordering is deterministic because it derives from the file list, which is fixed for a given codebase snapshot.
+
 Every pass requires reading every assigned file in full. Do not rely on grepping as a substitute for reading — systematic line-by-line review catches issues that keyword searches miss. Grepping is appropriate for cross-referencing (e.g., checking if an error name appears in test files) but not for understanding code.
 
 After reading each file, the agent must list evidence of thorough reading before reporting findings. For each file, list:
@@ -13,7 +15,23 @@ After reading each file, the agent must list evidence of thorough reading before
 
 This evidence must appear in the agent's output before any findings for that file. If the evidence is missing or incomplete, the audit of that file is invalid and must be re-run.
 
-Findings from all passes should be reported, not fixed. Fixes are a separate step after findings are reviewed.
+Findings from all passes should be reported, not fixed. Fixes are a separate step after findings are reviewed. Each finding must be classified as one of: **CRITICAL** (exploitable now with direct impact), **HIGH** (significant risk requiring specific conditions), **MEDIUM** (real concern with mitigating factors), **LOW** (minor issue or theoretical risk), **INFO** (observation with no direct risk).
+
+Each agent must write its findings to `audit/<YYYY-MM-DD>-<NN>/pass<M>/<FileName>.md` where `<NN>` is a zero-padded incrementing integer starting at 01, `<M>` is the pass number, and `<FileName>` matches the source file name (e.g. `LibEval.md` for `LibEval.sol`). To determine `<NN>`, glob for `audit/<YYYY-MM-DD>-*` and use one higher than the highest existing number, or 01 if none exist. All passes of the same audit share the same `<NN>`. Each audit run uses this namespace so previous runs are preserved as history. Findings that only exist in agent task output are lost when context compacts — the file is the record of truth.
+
+## Triage
+
+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.
+
+## 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`.
+
+Check for:
+- Ambiguous instructions a future session could misinterpret (e.g. reused placeholder names, unclear defaults)
+- Instructions that are fragile under context compression (e.g. relying on subtle distinctions)
+- Missing defaults or undefined terms
+- Inconsistencies between CLAUDE.md and AUDIT.md
 
 ## Pass 1: Security
 

CLAUDE.md

@@ -2,6 +2,8 @@
 
 This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.
 
+**This file takes precedence over session summaries.** When a session is restored from a compressed summary, the summary may contain incorrect interpretations of processes defined here. Always re-read and follow this file as written — do not rely on the summary's framing of what a process means or what the user intended.
+
 ## Build Environment
 
 This project uses **Nix flakes** for development. All commands must be run inside `nix develop` or prefixed with `nix develop -c`. The `.envrc` auto-loads the nix shell via direnv.
@@ -109,7 +111,7 @@ External contracts can extend the interpreter with additional opcodes. `src/conc
 
 ## Process (Jidoka)
 
-Each fix is a complete cycle: understand → fix → test → build → verify. Do not move to the next item with incomplete work. 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.
+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.
 
 ## Audit Review
 

audit/2026-02-17-02/pass0/process.md

@@ -0,0 +1,76 @@
+# Pass 0 (Process Review) -- CLAUDE.md and AUDIT.md
+
+## Evidence of Thorough Reading
+
+### CLAUDE.md
+- Precedence statement (line 5)
+- Build Environment: prerequisites (lines 11-17), common commands (lines 23-41), build pipeline (lines 45-52)
+- Architecture: four core components (lines 56-66), opcode system (lines 68-76), extern system (lines 78-80), rust crates (lines 82-89), deployment (lines 91-93)
+- Solidity Conventions (lines 95-103)
+- Test Conventions (lines 105-110)
+- Process (Jidoka) (lines 112-114)
+- Audit Review (lines 116-118)
+
+### AUDIT.md
+- General instructions (lines 1-16): pass count, agent partitioning, evidence requirements, file naming
+- Pass 0: Process Review (lines 18-26)
+- Pass 1: Security (lines 28-44)
+- Pass 2: Test Coverage (lines 46-53)
+- Pass 3: Documentation (lines 55-62)
+- Pass 4: Code Quality (lines 64-72)
+
+---
+
+## Findings
+
+### [P0-1] AUDIT.md says "four separate passes" but there are now five
+
+- **File**: AUDIT.md line 3
+- **Description**: Opening sentence says "An audit consists of four separate passes." With Pass 0 added, there are five (0-4).
+- **Impact**: A future session may skip Pass 0 because the opening line says four.
+
+### [P0-2] "Each pass in its own conversation" conflicts with Pass 0
+
+- **File**: AUDIT.md line 3 vs line 20
+- **Description**: Line 3 says "Each pass must be run as its own separate conversation." Line 20 says Pass 0 should "Run in the main conversation before launching code audit agents." These contradict.
+- **Impact**: A future session may either skip Pass 0 (following line 3's rule) or waste a conversation on it.
+
+### [P0-3] General instructions assume all passes use agents
+
+- **File**: AUDIT.md lines 5-14
+- **Description**: Lines 5-6 describe agent partitioning ("one file per agent"). Lines 9-14 require evidence of thorough reading per file. Pass 0 doesn't use agents and doesn't audit source files. A future session trying to apply these general rules to Pass 0 will be confused.
+- **Impact**: Ambiguity about which general rules apply to Pass 0.
+
+### [P0-4] `<FileName>` convention doesn't apply to Pass 0
+
+- **File**: AUDIT.md line 16 vs line 20
+- **Description**: Line 16 says `<FileName>` matches the source file name. Line 20 says Pass 0 output is `pass0/process.md`. These are inconsistent — Pass 0 doesn't audit source files.
+- **Impact**: Minor inconsistency. Pass 0 has its own explicit path so this is unlikely to cause confusion in practice.
+
+### [P0-5] Jidoka cycle order "test -> build" doesn't match bytecode change workflow
+
+- **File**: CLAUDE.md line 114
+- **Description**: The jidoka cycle is "understand -> fix -> test -> build -> verify." For changes affecting bytecode, you must build (pointer regeneration) before running tests, because the build generates constants that tests depend on. Following the cycle literally would fail.
+- **Impact**: A future session may attempt to run tests before building and encounter compilation errors, then waste time debugging a process issue.
+
+### [P0-6] Pointer regeneration and jidoka cycle are two overlapping sequences with no cross-reference
+
+- **File**: CLAUDE.md line 52 vs line 114
+- **Description**: Line 52 describes the build pipeline sequence (i9r-prelude -> BuildPointers -> forge fmt -> LibInterpreterDeployTest -> update constants -> repeat). Line 114 describes the jidoka fix cycle (understand -> fix -> test -> build -> verify). These describe overlapping activities with different step orders and no reference to each other.
+- **Impact**: A future session may follow one sequence and miss steps from the other.
+
+### [P0-7] Deprecated audit directory doesn't match new naming convention
+
+- **File**: Filesystem: `audit/2026-02-17/` and `audit/pass1/`
+- **Description**: These directories predate the `<YYYY-MM-DD>-<NN>` convention. A glob for `audit/2026-02-17-*` won't match them. Their presence may confuse a future session.
+- **Impact**: Low. Could cause incorrect `<NN>` calculation if a future session checks for existing directories by a different method than globbing.
+
+### [P0-8] No severity classification defined for findings
+
+- **File**: AUDIT.md (all pass sections)
+- **Description**: No pass defines how to classify finding severity. The previous audit used CRITICAL/HIGH/MEDIUM/LOW/INFO but this isn't documented. Without a defined scale, different agents may use inconsistent schemes.
+- **Impact**: Makes triage harder when consolidating findings across agents.
+
+## Summary
+
+9 findings total. Key themes: Pass 0 doesn't fit the general instructions written for code audit passes (P0-1 through P0-4), and the jidoka cycle order conflicts with the bytecode change build pipeline (P0-5, P0-6).

audit/2026-02-17-03/pass0/process.md

@@ -0,0 +1,30 @@
+# Pass 0 (Process Review) -- CLAUDE.md and AUDIT.md
+
+## Evidence of Thorough Reading
+
+### CLAUDE.md
+- Precedence statement (line 5)
+- Build Environment: prerequisites (lines 11-17), common commands (lines 23-41), build pipeline (lines 45-52)
+- Architecture: four core components (lines 56-66), opcode system (lines 68-76), extern system (lines 78-80), rust crates (lines 82-89), deployment (lines 91-93)
+- Solidity Conventions (lines 95-103)
+- Test Conventions (lines 105-110)
+- Process / Jidoka (lines 112-114)
+- Audit Review (lines 116-118)
+
+### AUDIT.md
+- General instructions (lines 1-18): pass structure, agent partitioning, evidence requirements, severity classification, file naming
+- Pass 0: Process Review (lines 20-28)
+- Pass 1: Security (lines 30-46)
+- Pass 2: Test Coverage (lines 48-55)
+- Pass 3: Documentation (lines 57-64)
+- Pass 4: Code Quality (lines 66-74)
+
+---
+
+## Findings
+
+No findings. Both documents are internally consistent, unambiguous, and robust to context compression.
+
+## Summary
+
+Clean pass. No CRITICAL, HIGH, MEDIUM, LOW, or INFO findings.