hex-audit 0.7.0 → 0.8.0

package/dist/skills/fuzz/UPSTREAM.md

@@ -0,0 +1,119 @@
+# Upstream
+
+`/fuzz`, `/fuzz-sync` and `/fuzz-convert` are a fork of **pashov's `fizz` skill** (`VERSION` 1):
+
+- Repository: https://github.com/pashov/skills (`fizz/`)
+- Commit: `c577eb7799c349de0acb187ba00ca98e14e436fd` (2026-07-09, "fizz: remove shipped self-test and de-hardcode eval paths (#39)")
+- License: MIT (see `LICENSE` in this directory, copied from the upstream repository root at that commit)
+
+The pipeline, the 5 discovery agents, the Synthesizer, the 2 implementers, the report writer, the references, the Solidity templates and the scripts are upstream's work. Hex keeps them as close to upstream's wording as possible. To merge a future upstream release, re-apply the changes below.
+
+## Layout
+
+| Upstream | Hex |
+|---|---|
+| `fizz/SKILL.md`, `agents/`, `references/`, `scripts/`, `templates/` | `src/skills/fuzz/` |
+| `fizz/skills/fizz-sync/SKILL.md` | `src/skills/fuzz-sync/SKILL.md` (top level: Claude Code only discovers top-level skills) |
+| `fizz/skills/fizz-convert/SKILL.md` | `src/skills/fuzz-convert/SKILL.md` |
+| `fizz/README.md`, `fizz/VERSION`, `fizz/evals/` | not shipped (Hex ships the skill inside `hex-audit`; update with `npx --no-install hex update`) |
+
+Where things land in an audited project:
+
+| Upstream | Hex |
+|---|---|
+| `PROPERTIES.md` (project root) | `.hex/fuzz/PROPERTIES.md` |
+| `fizz_data/` (ABIs, selection, property plan, corpora, logs, `report.md`, `last-run.json`) | `.hex/fuzz/fizz_data/` |
+| `test/fizz/` (the Solidity suite) | unchanged: it must compile with the project |
+| `echidna.yaml`, `medusa.json` (project root) | unchanged |
+
+## Hex changes
+
+### Mechanical
+
+Re-apply with sed after pulling a new upstream version. Apply to the markdown files: the three `SKILL.md` files, `agents/` and `references/`.
+
+| Upstream | Hex |
+|---|---|
+| `{PROJECT_ROOT}/PROPERTIES.md` | `{PROJECT_ROOT}/.hex/fuzz/PROPERTIES.md` |
+| `` `PROPERTIES.md` (project root) `` | `` `.hex/fuzz/PROPERTIES.md` `` |
+| `/fizz-sync`, `fizz-sync` | `/fuzz-sync`, `fuzz-sync` |
+| `/fizz-convert`, `fizz-convert` | `/fuzz-convert`, `fuzz-convert` |
+| `` `fizz` skill ``, `the Fizz skill`, `**Fizz** skill`, `Fizz skill's`, `Fizz harness`, `Fizz pipeline` | `` `fuzz` skill ``, `the fuzz skill`, `**fuzz** skill`, `fuzz skill's`, `fuzz harness`, `fuzz pipeline` |
+| ``run `fizz` first``, ``last `fizz` run``, ``since `fizz` last ran``, ``re-run `fizz` Step 7``, ``main `fizz` skill`` | the same with `` `/fuzz` `` (or `` `fuzz` skill ``) |
+| `{SKILL_PATH}/../../scripts/` (sub-skills) | `{FUZZ_SKILL_PATH}/scripts/` |
+
+In the scripts, the default meta dir changes from `let metaRelDir = 'fizz_data';` to `'.hex/fuzz/fizz_data'`, and the usage comments follow. This applies to `extract_abis.js`, `select_functions.js`, `estimate_cost.js`, `generate_suite.js`, `generate_handlers.js`, `run_medusa.js`, `run_echidna.js` and `fizz_sync.js` (`metaRelDir:` in its options object).
+
+`templates/` is unchanged. `medusa.json`, `echidna.yaml` and `README.md` keep upstream's `fizz_data` placeholder, and `generate_suite.js` rewrites it to the meta dir. The script's `!== 'fizz_data'` checks compare against that placeholder, not the default, so they stay; a comment there says so.
+
+### By hand
+
+- `scripts/fizz_sync.js`: `propertiesMdPath` is `.hex/fuzz/PROPERTIES.md`, and the `--init` hint compares against the new default meta dir.
+- `scripts/estimate_cost.js`: the two strings that mention x-ray name the Hex protocol model instead.
+- `SKILL.md`:
+  - `name: fuzz`, a Hex description, and a "Hex fork" note. A one-line Hex banner replaces the PASHOV SKILLS ASCII art.
+  - Workflow rules: files go under `.hex/fuzz/`, and the CLI is always `npx --no-install hex` (an unrelated npm package named `hex` exists).
+  - Parameters:
+    - `PROJECT_ROOT` is the directory that holds `.hex/`.
+    - `SKILL_PATH` comes from Claude Code's `Base directory for this skill`. The fallback is a Glob of exactly `.claude/skills/fuzz/SKILL.md`, never a broad `**/` Glob that could match an installed upstream fizz.
+    - `META_DIR` is `.hex/fuzz/fizz_data`.
+  - Step 1:
+    - New item 0 stops early when no invariant is accepted.
+    - The missing-tool messages are actionable: exact install commands for Foundry, Medusa and Echidna, the `crytic-compile`/Slither prerequisites, and "re-run `/fuzz`". The skill never installs anything.
+  - Step 3: upstream's **x-ray Acquisition Protocol** is removed. That covers the `Skill('x-ray')` invocation, the `git clone` of pashov/skills into `~/.claude/skills`, and the `/tmp/x-ray-attempts.md` gate. "Hex inputs" replaces it:
+    - Accepted invariants come from `npx --no-install hex invariant list --status accepted --json` and are saved to `{META_DIR}/hex-invariants.json`. If there are none, the skill stops and tells the auditor to accept some.
+    - `.hex/model/protocol.json` is the primary source, with a section-by-section guide.
+    - Exact facts come from `npx --no-install hex facts query …`.
+    - The Protocol Analyzer fallback runs only when `protocol.json` is missing.
+  - Step 4: the preselection comes from `hex facts query entry-points` / `callers` and the model's `actors` / `privileges`, not the x-ray entry-point map.
+  - Step 9a:
+    - `INVARIANT_CONTEXT` opens with an "Accepted invariants (the property list)" block. Discovery agents tag checks with `INV-NNN`, and everything else they find is a candidate.
+    - The model's accounting, state machine and risky flow sections replace x-ray's notes.
+    - Facts `layout` / `writers` help find aggregate variables.
+  - Step 9c:
+    - The Synthesizer also gets `{SKILL_PATH}`.
+    - A "Hex mapping" block checks one tagged entry per accepted invariant, records each with `hex invariant set-test … --tool fizz --property GL-NN --file {SUITE_DIR}/Properties.sol --status not_written`, and runs `hex model validate` after proposals.
+    - The summary counts the proposed invariants, and the guided pause keeps the tags.
+  - Step 10: violations name their `INV-NNN`; the sync runs right after the campaign; Campaign Iteration writes repros and syncs again.
+  - Step 11: `test_repro_<propertyFunction>` must use the property function's exact name, which is how the sync attributes violations.
+  - New **Step 12**: `npx --no-install hex invariant sync-fuzz`, and what to tell the auditor.
+- `agents/invariant-discovery/synthesizer.md`:
+  - Reads `hex-invariants.json` and `references/hex-invariants.md`.
+  - New Step 0: accepted invariants are the property list, one property each, tagged `(INV-NNN)`. An infeasible one is still written, as `[-]`. Every other discovery property is appended to `.hex/model/invariants.json` as `status: "proposed"` and is not fuzzed. Upstream's non-mergeable and `[MANDATORY]` properties become standalone proposals.
+  - The PROPERTIES.md entry description, header note and example lines carry the tag, and the return line reports proposals.
+- `agents/protocol-analyzer.md`: it is spawned when the Hex model is missing, not when x-ray is. It reads the accepted invariants and uses facts queries.
+- `agents/report-writer.md`: takes the project name from `.hex/config.json` / `protocol.json` when `protocol-understanding.md` is absent. A violation names its Spec ID and `INV-NNN`.
+- `agents/implementers/*.md`: one sentence: keep the `(INV-NNN)` tag when flipping a checkbox.
+- `references/template-map.md`: `.hex/fuzz/` paths, rows for `hex-invariants.json` and `PROPERTIES.md`, and the Hex model instead of x-ray.
+- New: `references/hex-invariants.md`, covering:
+  - the inputs
+  - the `(INV-NNN)` tag rule
+  - `set-test`
+  - how to propose an invariant: read, append, write `invariants.json`, next free `INV-NNN`, field rules
+  - what `sync-fuzz` reads and decides
+- `fuzz-sync/SKILL.md`:
+  - A Hex description and fork note.
+  - The `META_DIR` default, and where `PROPERTIES.md` lives.
+  - `FUZZ_SKILL_PATH`: the base directory, then `../fuzz`. The fallback is a Glob of exactly `.claude/skills/fuzz/scripts/<script>.js`.
+  - The `(INV-NNN)` tag stays on `[~]` lines.
+  - Step 8 runs `hex invariant sync-fuzz` after an applied sync.
+- `fuzz-convert/SKILL.md`:
+  - A Hex description and fork note, and the parameters (`META_DIR`, `PROPERTIES.md`, `FUZZ_SKILL_PATH`, `npx --no-install hex`).
+  - New STEP 0 adds entries and `set-test` mappings for invariants accepted after `/fuzz` ran, and proposes hand-written untagged entries as invariants.
+  - The format shows the tag, and the template map is read from `{FUZZ_SKILL_PATH}`.
+  - The summary lists `INV-NNN`s and how to run a campaign and sync.
+
+Untouched: the five discovery agents, `references/` other than `template-map.md`, `templates/`, `scripts/lib/log-viewer.js`, `ensure_foundry.sh`, `setup_fuzz_profile.sh`, and the logic of every script.
+
+## Coupled Hex code
+
+`src/core/fuzz-sync.ts` (`npx --no-install hex invariant sync-fuzz`) parses these upstream formats:
+
+- the PROPERTIES.md line (`- [x] **GL-01** …`) and its checkbox states `[ ]` / `[x]` / `[~]` / `[-]`
+- the `/// @notice GL-NN:` doctag
+- `test_repro_<property>` and the `TODO: manual repro needed` placeholder in `FoundryTester.sol`
+- `suiteDir` in `last-run.json`
+- the log paths written by `run_medusa.js` / `run_echidna.js` and Medusa's `logDirectory`
+- Medusa's `[PASSED]`/`[FAILED] … Test:` lines and Echidna's text output
+
+If a new upstream release changes any of these, update `fuzz-sync.ts` and its fixtures in `fuzz-sync.test.ts` too.

package/dist/skills/fuzz/agents/implementers/global-property-implementer.md

@@ -0,0 +1,81 @@
+# Agent 7A: Global Property & Ghost/Snapshot Implementer
+
+**Role**: Implement global properties into Properties.sol, wire ghost variables into Base.sol, and populate Snapshots.sol. These are checked by the fuzzer after every handler call.
+
+**Spawn config**: `general-purpose` agent, `model: "{AGENT_MODEL}"` (see SKILL.md "Subagent Model" section — defaults to `sonnet`, `opus` under `--max`). Spawned in parallel with Agent 7B.
+
+---
+
+## Prompt
+
+You implement the GLOBAL properties and the ghost/snapshot infrastructure from the property plan.
+
+## Your Inputs
+- Read: `{SKILL_PATH}/references/property-generation.md` — common knowledge on ghosts, snapshots, properties, naming, and assertion helpers
+- Read: `{META_DIR}/property-plan.md` — implement ONLY Global Properties section
+- Read: Ghost Variable Plan and Snapshot State Plan sections
+- Read + Edit: `{SUITE_DIR}/Base.sol` (add ghost variables to Ghosts struct)
+- Read + Edit: `{SUITE_DIR}/Snapshots.sol` (add state to State struct and _takeSnapshot)
+- Read + Edit: `{SUITE_DIR}/Properties.sol` (add global property functions)
+- Read + Edit: `{PROJECT_ROOT}/.hex/fuzz/PROPERTIES.md` (flip `[ ]` → `[x]` for each GL-* property you actually implement with a real assertion; flip `[ ]` → `[-]` for any GL-* property you skip or leave as a TODO/commented stub — `[-]` means "do not auto-touch", so `/fuzz-convert` will not retry it later)
+- Read: `{SUITE_DIR}/handlers/` (all handler files — for context on what operations exist)
+- Read: Source contract files (for actual function signatures and state variables)
+
+## Implementation Rules
+
+These rules expand on the general property implementation instructions in `property-generation.md` with specifics for the global properties and wiring.
+
+Global properties are `public` functions starting with `property_` prefix. The fuzzer calls them directly after every handler.
+
+### MANDATORY: Spec ID doctag
+
+Every property function you write MUST have its Spec ID as the first thing in its natspec, on its own line, in this exact form:
+
+```solidity
+/// @notice GL-NN: <one-line description>
+function property_<name>() public { ... }
+```
+
+The `GL-NN:` token (with the colon) is how `/fuzz-convert` and future runs locate the existing implementation of a Spec ID for re-generation or deletion. Without it, automation cannot reconcile the spec with the code. This is a hard requirement, not a style preference.
+
+```solidity
+// ―――――――――――――――――――― Global properties ―――――――――――――――――――――
+// These properties must always hold after any function call
+// They MUST BE PUBLIC so that fuzzers can find and call them
+
+function property_solvency() public {
+    gte(
+        token.balanceOf(address(vault)),
+        vault.totalAssets(),
+        "Solvency: token balance < totalAssets"
+    );
+}
+
+function property_totalSupplyMatchesBalances() public {
+    uint256 sum;
+    for (uint256 i; i < NUMBER_OF_ACTORS; i++) {
+        sum += vault.balanceOf(address(actors[i]));
+    }
+    eq(sum, vault.totalSupply(), "Sum of balances != totalSupply");
+}
+
+function property_ghostAccounting() public {
+    gte(
+        ghosts.totalDeposited,
+        ghosts.totalWithdrawn,
+        "Ghost: more withdrawn than deposited"
+    );
+}
+```
+
+Global properties run after EVERY handler call. Keep them O(n) where n = NUMBER_OF_ACTORS (typically 3-5). Avoid unbounded loops.
+
+## PROPERTIES.md Status Updates
+
+For every `GL-*` property:
+- If you implemented it with a real assertion: change `- [ ] **GL-NN** ...` to `- [x] **GL-NN** ...`
+- If you skipped it or left it as a TODO/commented stub: change `- [ ] **GL-NN** ...` to `- [-] **GL-NN** ...`. This marks it as "do not auto-touch" so `/fuzz-convert` will not retry it later — the user must manually flip it back to `[ ]` or implement it by hand.
+
+Match by exact ID. Do NOT renumber, reorder, or rewrite other lines. (Hex) Keep the `(INV-NNN)` tag after the ID exactly as it is: it maps the property to its Hex invariant.
+
+Return: `DONE: X global properties implemented (Y marked [x], Z marked [-] as skipped/TODO). Ghosts: G fields added to Base.sol. Snapshot: S fields added to Snapshots.sol.`

package/dist/skills/fuzz/agents/implementers/specific-property-implementer.md

@@ -0,0 +1,121 @@
+# Agent 7B: Specific Property & Handler Wiring Implementer
+
+**Role**: Implement specific (per-handler) properties into Properties.sol and wire ghost updates + snapshot calls + property assertions into handler files.
+
+**Spawn config**: `general-purpose` agent, `model: "{AGENT_MODEL}"` (see SKILL.md "Subagent Model" section — defaults to `sonnet`, `opus` under `--max`). Spawned in parallel with Agent 7A.
+
+---
+
+## Prompt
+
+You implement SPECIFIC properties and wire all ghost/snapshot/property calls into the handler files.
+
+## Your Inputs
+- Read: `{SKILL_PATH}/references/property-generation.md` — common knowledge on ghosts, snapshots, properties, naming, and assertion helpers
+- Read: `{META_DIR}/property-plan.md` — implement Specific Properties + Handler Wiring Plan
+- Read + Edit: `{SUITE_DIR}/Properties.sol` (add specific property functions as internal)
+- Read + Edit: `{PROJECT_ROOT}/.hex/fuzz/PROPERTIES.md` (flip `[ ]` → `[x]` for each SP-* property you actually implement AND wire into a handler; flip `[ ]` → `[-]` for any SP-* property you skip or leave as a TODO/commented stub — `[-]` means "do not auto-touch", so `/fuzz-convert` will not retry it later)
+- Read + Edit: `{SUITE_DIR}/handlers/<Contract>Handler.sol` (wire ghost updates, snapshot calls, property calls)
+- Read: `{SUITE_DIR}/Base.sol` (for ghosts struct and actor array)
+- Read: `{SUITE_DIR}/Snapshots.sol` (for snapshot state and before/after access)
+- Read: Source contract files (for actual function signatures)
+
+## Implementation Rules
+
+These rules expand on the general property implementation instructions in `property-generation.md` with specifics for the per-handler properties and wiring.
+
+Specific properties are `internal` functions called at the end of relevant handlers. They check postconditions for specific operations.
+
+### MANDATORY: Spec ID doctag
+
+Every property function you write MUST have its Spec ID as the first thing in its natspec, on its own line, in this exact form:
+
+```solidity
+/// @notice SP-NN: <one-line description>
+function property_<name>() internal { ... }
+```
+
+The `SP-NN:` token (with the colon) is how `/fuzz-convert` and future runs locate the existing implementation of a Spec ID for re-generation or deletion. Without it, automation cannot reconcile the spec with the code. This is a hard requirement, not a style preference.
+
+```solidity
+// ――――――――――――――――――― Specific properties ――――――――――――――――――――
+// These properties must hold after specific function calls
+// They MUST BE INTERNAL and called at the end of the relevant handlers
+
+function property_depositIncreasesShares() internal {
+    gt(
+        stateAfter.vaultTotalSupply,
+        stateBefore.vaultTotalSupply,
+        "Deposit did not increase total supply"
+    );
+}
+
+function property_withdrawDecreasesAssets() internal {
+    lt(
+        stateAfter.vaultTotalAssets,
+        stateBefore.vaultTotalAssets,
+        "Withdraw did not decrease total assets"
+    );
+}
+
+function property_roundTripNoFreeValue(uint256 balanceBefore, uint256 balanceAfter) internal {
+    lte(
+        balanceAfter,
+        balanceBefore,
+        "Round-trip created free value"
+    );
+}
+```
+
+## Wiring Specific Property Calls into Handlers
+
+Call specific properties at the END of the handler, AFTER ghost updates and snapshotAfter():
+
+```solidity
+function vault_withdraw_clamped(uint256 assets) public {
+    // ... clamping logic ...
+    vault_withdraw(assets);
+}
+
+function vault_withdraw(uint256 assets) public asActor {
+    snapshotBefore();
+
+    vm.prank(address(actor));
+    vault.withdraw(assets);
+
+    snapshotAfter();
+    ghosts.totalWithdrawn += assets;
+
+    property_withdrawDecreasesAssets();
+}
+```
+
+## Round-Trip / Liveness Properties
+
+For round-trip and liveness checks that need to execute a multi-step sequence and then revert (no state pollution), implement them as handler-level functions that test the sequence inline:
+
+```solidity
+/// @notice Liveness: every actor with balance > 0 can withdraw
+function property_allCanWithdraw() public {
+    for (uint256 i; i < NUMBER_OF_ACTORS; i++) {
+        uint256 bal = vault.balanceOf(address(actors[i]));
+        if (bal > 0) {
+            vm.prank(address(actors[i]));
+            try vault.redeem(bal, address(actors[i]), address(actors[i])) {}
+            catch { t(false, "Liveness: user cannot withdraw"); }
+        }
+    }
+}
+```
+
+Note: Stateless properties are properties that must not pollute state, as they are extreme cases that will make subsequent calls revert. For stateless properties, use `try/catch` patterns or implement them as view-approximations where possible. For true round-trip tests, consider using `FoundryTester.sol` for Foundry-based scenario tests.
+
+## PROPERTIES.md Status Updates
+
+For every `SP-*` property:
+- If you implemented it with a real assertion AND wired it into the relevant handler: change `- [ ] **SP-NN** ...` to `- [x] **SP-NN** ...`
+- If you skipped it or left it as a TODO/commented stub: change `- [ ] **SP-NN** ...` to `- [-] **SP-NN** ...`. This marks it as "do not auto-touch" so `/fuzz-convert` will not retry it later.
+
+Match by exact ID. Do NOT renumber, reorder, or rewrite other lines. (Hex) Keep the `(INV-NNN)` tag after the ID exactly as it is: it maps the property to its Hex invariant.
+
+Return: `DONE: X specific properties implemented (Y marked [x], Z marked [-] as skipped/TODO). Handler wiring: A handlers updated with ghost updates, B with snapshot calls, C with property assertions.`

package/dist/skills/fuzz/agents/invariant-discovery/adversarial-profit-maximizer.md

@@ -0,0 +1,123 @@
+# Agent 4: Adversarial Profit Maximizer
+
+**Discovery approach**: Think like an attacker. What would maximize extracted value? What sequence breaks liveness? What edge conditions create exploitable state?
+
+**Spawn config**: `general-purpose` agent, `model: "{AGENT_MODEL}"` (see SKILL.md "Subagent Model" section — defaults to `sonnet`, `opus` under `--max`).
+
+---
+
+## Prompt
+
+You are the Adversarial Profit Maximizer — you think like an attacker, not a tester.
+
+## Your Discovery Method
+
+Instead of asking 'what should hold?', ask:
+1. 'How would I extract value from this protocol?'
+2. 'How would I brick this protocol so users can't withdraw?'
+3. 'What edge states would break core assumptions?'
+
+Then write properties that DETECT these attacks. If the fuzzer can violate the property, the attack is real.
+
+
+## INVARIANT_CONTEXT
+{INVARIANT_CONTEXT}
+
+## Read the source code of these target contracts:
+{FILE_PATHS}
+
+## Step 1: Liveness / DoS Properties
+
+### Pattern A — Universal Withdrawal Liveness
+`For every actor with balance > 0: withdrawal of their full balance must not revert`
+
+### Pattern B — Liquidation Liveness
+`For every actor whose position is unhealthy: liquidation must not revert`
+
+### Pattern C — Critical Function Liveness
+`For each critical function: if valid preconditions are met, the call must succeed`
+
+## Step 2: Value Extraction Properties
+
+### Pattern D — No Free Profit
+`attacker_balance_after <= attacker_balance_before + epsilon`
+
+### Pattern E — First-Depositor / Share Inflation
+`After any sequence of operations: shares_minted_for_deposit(1e18) > 0`
+
+### Pattern F — Flash Loan Profit
+`Within a single transaction context: user cannot end with more value than they started`
+
+## Step 3: Edge State Properties
+
+### Pattern G — Zero State Safety
+`After all users withdraw everything: totalSupply == 0 AND totalAssets == 0`
+`Empty protocol is re-enterable: deposit after full withdrawal works correctly`
+
+### Pattern H — Dust State Safety
+`Positions with dust amounts (1 wei) can still be closed/liquidated/exited`
+
+### Pattern I — Boundary-Value Exploits
+
+Test four boundary directions — bugs cluster where clamped handlers don't reach:
+
+**I-a: Near-zero / sub-unit truncation**
+`When a code path divides or scales, values below the divisor truncate to zero — user pays nothing`
+Grep for division, `mulDiv`, decimal scaling (`10**`, `1eN`), conversion functions. For each, write a property: `if user receives X tokens, user must have paid > 0`. Generate a handler that inputs values near and below the divisor.
+
+**I-b: Type-narrowing overflow**
+`When uint256 arithmetic is stored in a narrower type, large accumulations truncate silently`
+Grep for storage declared as `uint80`, `uint96`, `uint128`, `uint160`, or packed struct fields. For each, identify the accumulation path and write a property that the uint256 computation fits in the storage type. Generate a handler that pushes values toward the type boundary.
+
+**I-c: Full-amount operations**
+`Performing an operation on the ENTIRE balance/debt/supply in one call must not break invariants`
+For each core operation, write a handler that uses the maximum available amount from current state (full balance, full debt, full supply). Write a property that invariants hold after full-amount operations.
+
+**I-d: Cumulative bypass**
+`Per-call validation passes but the aggregate violates an invariant after repeated calls`
+When a function checks limits per-call but doesn't track cumulative totals, repeated calls bypass the cap. Write a property tracking cumulative amounts against the intended limit. Generate a handler designed for high-frequency repeated calls.
+
+## Step 4: Access Control Attack Properties
+
+### Pattern J — Privilege Escalation
+`Non-admin calling admin functions always reverts`
+`User A cannot operate on User B's position without approval`
+
+### Pattern K — Self-Destructive Operations
+`A user cannot intentionally make their own position unliquidatable`
+
+## Step 5: Protocol-Specific Adversarial Thinking
+
+For each external dependency: 'What if this returns an unexpected value?'
+For each economic flow: 'What if someone front-runs this?'
+
+## Tag Each Property: SHOULD-HOLD vs EXPLORATORY
+
+Every property you emit MUST carry a `GUARANTEE` tag recording *why you believe it holds*. This is what lets a downstream campaign separate confirmed bugs from leads needing human review.
+
+- **SHOULD-HOLD** — the property is explicitly guaranteed by the protocol's docs/spec/whitepaper (read from INVARIANT_CONTEXT), by a standard the contract claims to implement (e.g. an ERC MUST-clause), or by a closed-form mathematical/accounting identity. A violation of a SHOULD-HOLD property is, by construction, a confirmed bug.
+- **EXPLORATORY** — the property is inferred from the code, naming, or general DeFi patterns but is NOT explicitly promised anywhere. It is a reasonable hypothesis worth fuzzing, but a violation needs human review before it can be called a bug.
+
+Rules:
+- **Default to EXPLORATORY.** Only tag SHOULD-HOLD when you can cite specific evidence. When in doubt, it is EXPLORATORY.
+- When you tag SHOULD-HOLD you MUST fill `EVIDENCE` with the concrete basis: a short quote or section reference from the docs/INVARIANT_CONTEXT, the named standard clause, or the exact identity. No citable evidence ⇒ EXPLORATORY.
+- Provenance is independent of `PRIORITY` and of any `[MANDATORY]` marker — a HIGH-priority guess is still EXPLORATORY.
+
+Most attack hypotheses you generate are **EXPLORATORY by nature** — they probe assumptions the protocol never explicitly promised. Tag SHOULD-HOLD only for guarantees the docs state outright (e.g. "users can always withdraw their full balance", "only the admin may call X", "no fee on withdrawal") or that follow from an exact identity. An attack idea you reasoned your way to, without a doc/code promise behind it, is EXPLORATORY even when it is HIGH priority.
+
+## Output Format
+Write each property as:
+```
+PROPERTY_ID: [ADV-XX]
+TYPE: GLOBAL or SPECIFIC
+ENGLISH: [plain English — frame as 'an attacker cannot...']
+SOLIDITY_SKETCH: [pseudocode]
+GHOST_NEEDS: [ghost variables needed in Base.sol Ghosts struct]
+SNAPSHOT_NEEDS: [state needed in Snapshots.sol]
+PRIORITY: HIGH / MEDIUM / LOW (liveness is always HIGH)
+GUARANTEE: SHOULD-HOLD or EXPLORATORY
+EVIDENCE: [if SHOULD-HOLD: the doc quote / standard clause / math identity that guarantees it; otherwise "none — inferred"]
+RATIONALE: [what attack this detects]
+```
+
+SCOPE: Write ONLY adversarial/attack properties. Do NOT write conservation, rounding, or state transition properties.

package/dist/skills/fuzz/agents/invariant-discovery/conservation-auditor.md

@@ -0,0 +1,92 @@
+# Agent 1: Conservation Auditor
+
+**Discovery approach**: For every aggregate/total variable, write a "sum of individual parts = tracked whole" property. This is the #1 bug-finding pattern in DeFi history.
+
+**Spawn config**: `general-purpose` agent, `model: "{AGENT_MODEL}"` (see SKILL.md "Subagent Model" section — defaults to `sonnet`, `opus` under `--max`).
+
+---
+
+## Prompt
+
+You are the Conservation Auditor — a specialist in accounting identity invariants.
+
+## Your Discovery Method
+
+For every aggregate variable in the protocol, determine what individual components should sum to it, and write an invariant asserting equality. 
+
+## INVARIANT_CONTEXT
+{INVARIANT_CONTEXT}
+
+## Read the source code of these target contracts:
+{FILE_PATHS}
+
+## Step 1: Identify ALL Aggregate Variables
+
+For each contract, find every variable that represents an aggregate/total:
+- Variables named total*, sum*, accumulated*, aggregate*
+- Variables incremented/decremented by multiple functions
+- Mappings whose individual entries should sum to a standalone variable
+- Internal accounting that should match external token balances
+
+## Step 2: For Each Aggregate Variable, Write Conservation Invariants
+
+### Pattern A — Sum of Parts = Tracked Whole
+`SUM(individual_entries) == aggregate_variable`
+Example: sum of all user balances == totalSupply
+
+### Pattern B — Internal Accounting = External Reality
+`contract.trackedBalance == token.balanceOf(address(contract))`
+Example: vault's internal asset tracking == actual ERC-20 balance held
+
+### Pattern C — Cross-Variable Consistency
+`variableA == variableB + variableC` (when the protocol documents this relationship)
+Example: totalDebt == totalBorrowShares * borrowIndex (after interest accrual)
+
+### Pattern D — Per-Entity Aggregation
+`SUM(mapping[entity].field) for all entities == global.field`
+Example: sum of all position collateral == pool's totalCollateral
+
+## Step 3: For Each Invariant, Assess
+
+- Can the fuzzer compute both sides? (does it have access to all individual entries via the actors array in Base.sol?)
+- Does it need ghost variables in Base.sol's Ghosts struct?
+- Does it need snapshot state in Snapshots.sol's State struct?
+- Priority: HIGH if it checks a core economic guarantee, MEDIUM if secondary accounting, LOW if cosmetic
+
+## Bug Patterns This Catches
+- Phantom minting/burning (supply changes without balance changes)
+- Fee leakage (fees recorded but not collected, or collected but not recorded)
+- Rounding drift (tiny errors accumulating over many operations)
+- Missing updates (state variable changed in function A but not function B)
+- Double-counting (same value counted in two aggregates)
+
+## Tag Each Property: SHOULD-HOLD vs EXPLORATORY
+
+Every property you emit MUST carry a `GUARANTEE` tag recording *why you believe it holds*. This is what lets a downstream campaign separate confirmed bugs from leads needing human review.
+
+- **SHOULD-HOLD** — the property is explicitly guaranteed by the protocol's docs/spec/whitepaper (read from INVARIANT_CONTEXT), by a standard the contract claims to implement (e.g. an ERC MUST-clause), or by a closed-form mathematical/accounting identity. A violation of a SHOULD-HOLD property is, by construction, a confirmed bug.
+- **EXPLORATORY** — the property is inferred from the code, naming, or general DeFi patterns but is NOT explicitly promised anywhere. It is a reasonable hypothesis worth fuzzing, but a violation needs human review before it can be called a bug.
+
+Rules:
+- **Default to EXPLORATORY.** Only tag SHOULD-HOLD when you can cite specific evidence. When in doubt, it is EXPLORATORY.
+- When you tag SHOULD-HOLD you MUST fill `EVIDENCE` with the concrete basis: a short quote or section reference from the docs/INVARIANT_CONTEXT, the named standard clause, or the exact identity. No citable evidence ⇒ EXPLORATORY.
+- Provenance is independent of `PRIORITY` and of any `[MANDATORY]` marker — a HIGH-priority guess is still EXPLORATORY.
+
+Conservation/accounting identities (Patterns A, B, D) are usually SHOULD-HOLD *only when* the protocol's accounting is documented or the identity is exact and total (e.g. "totalSupply == Σ balances" with no untracked mint path). Pattern C is SHOULD-HOLD when, and only when, the docs state the relationship (as Step 2 Pattern C already requires).
+
+## Output Format
+Write each property as:
+```
+PROPERTY_ID: [CON-XX]
+TYPE: GLOBAL or SPECIFIC
+ENGLISH: [plain English description]
+SOLIDITY_SKETCH: [pseudocode showing the check]
+GHOST_NEEDS: [any ghost variables needed in Base.sol Ghosts struct]
+SNAPSHOT_NEEDS: [any state needed in Snapshots.sol State struct]
+PRIORITY: HIGH / MEDIUM / LOW
+GUARANTEE: SHOULD-HOLD or EXPLORATORY
+EVIDENCE: [if SHOULD-HOLD: the doc quote / standard clause / math identity that guarantees it; otherwise "none — inferred"]
+RATIONALE: [why this specific invariant matters for this protocol]
+```
+
+SCOPE: Write ONLY conservation/accounting properties. Do NOT write state transition, rounding, or attack scenario properties — other agents handle those.