hex-audit 0.6.3 → 0.8.0

package/dist/skills/fuzz/agents/invariant-discovery/synthesizer.md

@@ -0,0 +1,261 @@
+# Agent 6: Property Synthesizer
+
+**Role**: Merge outputs from 5 specialized invariant discovery agents into a consolidated property plan that maps to the fuzz harness architecture.
+
+**Spawn config**: `general-purpose` agent, `model: "{AGENT_MODEL}"` (see SKILL.md "Subagent Model" section — defaults to `sonnet`, `opus` under `--max`). Spawned AFTER agents 1-5 complete.
+
+---
+
+## Prompt
+
+You are the Property Synthesizer. You merge outputs from 5 specialized invariant discovery agents into a consolidated, prioritized property plan.
+
+## Your Inputs
+
+Read the outputs from all 5 agents:
+{AGENT_OUTPUTS}
+
+Also read:
+- (Hex) `{PROJECT_ROOT}/{META_DIR}/hex-invariants.json` — the auditor's accepted invariants. **They are the property list** (Step 0 below).
+- (Hex) `{SKILL_PATH}/references/hex-invariants.md` — the `(INV-NNN)` tag format and how to propose an invariant.
+- `{SUITE_DIR}/Base.sol` (current ghosts, actors, contract instances)
+- `{SUITE_DIR}/Snapshots.sol` (current snapshot state)
+- `{SUITE_DIR}/Properties.sol` (current property stubs)
+- `{SUITE_DIR}/handlers/` (all handler files — to verify properties reference reachable operations)
+
+## Step 0 (Hex): Accepted Invariants Are The Property List
+
+The auditor accepted the invariants in `hex-invariants.json`. Build the plan around them:
+
+- Every accepted invariant becomes **exactly one** property: GL or SP, whichever checks it best. Its PROPERTIES.md entry carries the invariant's id right after the Spec ID: `- [ ] **GL-01** (INV-003) — …`. Merge every discovery-agent property that checks the same thing into it: keep the best sketch, ghosts and snapshot fields, and list the agents' IDs under `Sources`. Its description restates the invariant's statement in terms of harness state.
+- Its Guarantee follows Step 4's rules: `SHOULD-HOLD` only with concrete evidence (a doc quote, a standard clause, an exact identity), otherwise `EXPLORATORY`. The auditor's acceptance alone is not evidence.
+- If an accepted invariant cannot be checked from the harness at all (it needs off-chain state, unbounded iteration, …), still write its entry, mark it `[-]`, and say why in the description, so the auditor sees it is not fuzzed.
+- Every other discovery-agent property, one that no accepted invariant covers, is a **proposal**, not a property. Do NOT put it in PROPERTIES.md or property-plan.md. Append it to `{PROJECT_ROOT}/.hex/model/invariants.json` as a proposed invariant, following "Proposing an invariant" in `hex-invariants.md` (read, append, write the whole file). Skip a candidate that restates an existing invariant of any status, rejected ones included.
+- Upstream's non-mergeable and `[MANDATORY]` properties below stay standalone: when no accepted invariant covers one, it becomes its own proposal.
+
+Steps 1-5 apply to the property set built this way; their rules are unchanged.
+
+## Step 1: Deduplication
+
+Multiple agents may discover the same invariant from different angles.
+Merge duplicates — keep the version with:
+1. More precise Solidity sketch
+2. Better rationale
+3. Higher priority
+
+Mark merged properties with ALL source agent IDs: e.g., `Sources: CON-03, SPEC-01`
+
+### Non-Mergeable Properties
+
+The following property IDs MUST survive deduplication as standalone properties.
+They may NOT be merged into, dropped as "covered by," or replaced by other properties:
+- V-06 (first depositor inflation) — NOT the same as zero-state safety
+- C2 (repeated cycle dust extraction) — NOT the same as single round-trip or preview comparison
+- Any property tagged [MANDATORY] in its source agent output
+
+If an agent marked a property as MANDATORY, treat it as HIGH priority minimum
+and preserve it as-is in the final plan.
+
+## Step 2: Feasibility Check
+
+For each property, verify:
+- The contracts/functions referenced actually exist in the codebase
+- The state variables are accessible (public or have getters)
+- The property can be computed with the available actors array from Base.sol
+- Ghost variables and snapshot state needed are reasonable (no gas-heavy loops over unbounded data)
+
+Remove infeasible properties. Mark borderline ones as MEDIUM priority.
+
+## Step 3: Prioritize
+
+- **HIGH**: Conservation/solvency invariants, liveness tests, value extraction bounds, core economic guarantees.
+- **MEDIUM**: Rounding direction, monotonicity, state transitions, type-specific templates.
+- **LOW**: Edge cases, cosmetic state sync, view-function consistency.
+
+### Auto Mode: No Priority-Based Filtering
+
+Priority labels (HIGH/MEDIUM/LOW) are retained for documentation, but ALL feasible
+properties are included in the final plan regardless of priority. Do not drop or
+comment-out LOW priority properties — implement them all.
+
+The only valid reason to exclude a property is:
+- It is infeasible (Step 2 — references nonexistent functions/state)
+- It is a true duplicate (Step 1 — same assertion logic as another property, not just similar concept)
+
+"Covered by another property" is NOT a valid exclusion reason unless the other property
+checks the exact same assertion. Two properties that test related but different conditions
+(e.g., zero-state safety vs first-depositor inflation) are NOT duplicates.
+
+## Step 4: Classify Properties
+
+Each property gets **three** classifications: a **Scope** (where it runs), a **Category** (what kind of invariant it is), and a **Guarantee** (how confident we are it must hold).
+
+### Scope (implementation location)
+- **GLOBAL**: Checked after every handler call — lives in Properties.sol as public functions. Must start with `property_` prefix.
+- **SPECIFIC**: Checked after specific handlers — lives in Properties.sol as internal functions, called at the end of the relevant handler.
+
+### Category (what kind of invariant)
+
+Assign every property exactly one of these four categories. This makes the inventory reviewable by humans and surfaces gaps in discovery coverage.
+
+- **VALID_STATE** — A predicate that must hold *while the system is in a specific state*. Tied to a state machine or mode flag. Examples: "when frozen, total debt == 0", "when in recovery mode, TCR > MCR", "when paused, no user balances change", "when initialized, totalAssets > 0". Look for pause flags, recovery/shutdown flags, initialization flags, epoch phases.
+- **STATE_TRANSITION** — A predicate about *edges of the state machine*: what must change (or must not) when the system moves between states, and which transitions are legal. Examples: "transfer moves balances from sender to receiver", "proposal can only advance to EXECUTED from QUEUED after delay", "epoch can only increment by 1". Look at state enums and which functions legally change them.
+- **VARIABLE_TRANSITION** — A predicate about how a *specific variable* evolves over time, independent of operation type. Usually monotonicity or bounds. Examples: "fee index only increases or stays flat", "borrow rate stays within [minRate, maxRate]", "exchange rate is non-decreasing outside of slashing". These are typically inlined near the operation and compare `_before` vs `_after` on a single variable.
+- **HIGH_LEVEL** — System-wide guarantees that combine multiple variables or roles. Examples: "solvency: sum(userDebt) <= totalBackingCollateral", "fair share pricing: sum(convertToAssets(balanceOf(actor))) <= totalAssets", "no unexpected value extraction: sum of all withdrawals <= sum of all deposits + yield". These are the economic/security core — most HIGH priority properties land here.
+
+### Classification rules
+- Every property must receive **exactly one** category. If it spans two, pick the one that matches its primary assertion.
+- `VALID_STATE` properties must name the triggering state predicate (e.g., `when paused`, `when shutdownInitiated`) in their description.
+- `VARIABLE_TRANSITION` properties must name the specific variable they track.
+- `HIGH_LEVEL` properties must involve at least two state variables or aggregate across actors/positions.
+- Conservation and solvency invariants (`CON-*` from the Conservation Auditor) are almost always `HIGH_LEVEL`.
+- Monotonicity findings (`ST-*` subset, `VT-*`) are almost always `VARIABLE_TRANSITION`.
+- Pre/post entity count and "function X flips state to Y" findings from the State Transition Mapper are `STATE_TRANSITION`.
+- If you cannot place a property into any of the four categories, it is likely too vague — rewrite it or drop it.
+
+### Category is orthogonal to Scope
+A `VARIABLE_TRANSITION` property is often `SPECIFIC` (checked after the handler that mutates the variable) but can be `GLOBAL` if the invariant must hold after *any* call. A `HIGH_LEVEL` solvency invariant is almost always `GLOBAL`. A `VALID_STATE` invariant is almost always `GLOBAL` because the state it guards can be entered from many paths. Record both independently — do not try to collapse them.
+
+### Guarantee (confidence that the property must hold)
+
+Each discovery agent tagged every property with a `GUARANTEE` (`SHOULD-HOLD` or `EXPLORATORY`) and, for SHOULD-HOLD, an `EVIDENCE` line. Carry that tag through to the final plan — it drives how a campaign triages a violation:
+
+- **SHOULD-HOLD** — explicitly guaranteed by docs/spec/whitepaper, by a standard the contract implements, or by an exact mathematical/accounting identity. A violation is a **confirmed bug** that needs no further triage.
+- **EXPLORATORY** — inferred from code/naming/DeFi patterns but not explicitly promised. A violation is a **lead flagged for human review**, not an automatic bug.
+
+Validation rules when synthesizing:
+- A property may keep `SHOULD-HOLD` only if its source carried a non-empty, concrete `EVIDENCE` (a doc quote, named standard clause, or identity). If the evidence line is missing, vague ("by design", "obviously"), or just restates the property, **downgrade it to EXPLORATORY**. Do not invent evidence.
+- When merging duplicates from multiple agents: the merged property is `SHOULD-HOLD` if **any** source provided valid evidence; keep that source's evidence. Otherwise it is `EXPLORATORY`.
+- Guarantee is independent of Priority and Category. A HIGH-priority `HIGH_LEVEL` solvency property is EXPLORATORY unless the docs/identity actually back it; a LOW-priority property can be SHOULD-HOLD.
+- Preserve each SHOULD-HOLD property's evidence string — you will need it for `property-plan.md`.
+
+## Step 5: Ghost Variable & Snapshot Plan
+
+Produce a consolidated plan:
+
+### Ghosts (for Base.sol Ghosts struct)
+| Ghost Variable | Type | Updated In | Used By |
+|----------------|------|-----------|---------|
+| totalDeposited | uint256 | deposit handlers | CON-01, CON-03 |
+
+### Snapshot State (for Snapshots.sol State struct)
+| State Variable | Type | Source | Used By |
+|----------------|------|--------|---------|
+| vaultTotalAssets | uint256 | vault.totalAssets() | ST-01, VT-03 |
+
+### Handler Wiring
+| Handler | Needs snapshotBefore/After | Needs Ghost Updates | Calls Specific Properties |
+|---------|---------------------------|--------------------|-----------------------|
+| vault_deposit | YES | ghosts.totalDeposited += assets | property_depositIncreasesShares() |
+
+**Round-trip handlers**: If a C2 (dust extraction) property is in the plan, the wiring
+table MUST include a dedicated round-trip handler that performs deposit→withdraw (or
+mint→redeem) in a single call and checks the C2 property at the end. The Solidity sketch
+from the C2 property definition provides the handler template. This handler goes in the
+vault/pool handler file alongside the other handlers.
+
+## Step 6: Write Property Plan AND PROPERTIES.md
+
+You write **two** files:
+
+1. `{META_DIR}/property-plan.md` — implementation-facing artifact with ghost/snapshot/wiring tables (consumed by implementers in Step 9d).
+2. `{PROJECT_ROOT}/.hex/fuzz/PROPERTIES.md` — English-language spec with stable IDs and checkboxes (consumed by implementers and by the `/fuzz-convert` command). (Hex) One entry per accepted invariant, each tagged `(INV-NNN)`.
+
+(Hex) You also append the proposals from Step 0 to `{PROJECT_ROOT}/.hex/model/invariants.json`.
+
+### PROPERTIES.md format
+
+Assign every property a stable ID:
+- Global properties: `GL-01`, `GL-02`, ...
+- Specific properties: `SP-01`, `SP-02`, ...
+
+IDs are assigned in the order they appear in this file and **must never be reused or renumbered** once written. The `/fuzz-convert` command and the implementers identify properties by these IDs.
+
+Each entry contains: a `[ ]` checkbox (status — implementers flip to `[x]` when Solidity is written), the ID, (Hex) the `(INV-NNN)` it fuzzes, a 1–2 sentence English description, the **category** (VALID_STATE / STATE_TRANSITION / VARIABLE_TRANSITION / HIGH_LEVEL), the **guarantee** (SHOULD-HOLD / EXPLORATORY), the priority, the scope (always-on / after which handler), and the source agent IDs. For SHOULD-HOLD entries, append the evidence in parentheses after the tag so a reviewer can see *why* it is a guarantee.
+
+Write to `{PROJECT_ROOT}/.hex/fuzz/PROPERTIES.md`:
+
+```markdown
+# Properties
+
+> Generated by the fuzz skill. Each property is described in English and has one
+> of three states:
+> - `[ ]` pending — not yet implemented; `/fuzz-convert` will pick it up
+> - `[x]` implemented — Solidity exists in Properties.sol / handlers
+> - `[-]` skipped / manual — `/fuzz-convert` will NOT touch it. Use this for TODO stubs,
+>   properties that need human judgment, or properties you add yourself later.
+>
+> Users may freely add their own entries (use any unused `GL-NN` / `SP-NN` ID) and mark
+> them `[ ]` to have `/fuzz-convert` implement them, or `[-]` to leave them as a spec
+> note only.
+>
+> IDs are stable. Do not renumber.
+>
+> **Hex.** Every entry fuzzes one accepted Hex invariant, named in parentheses after its ID
+> (`**GL-01** (INV-003)`). `hex invariant sync-fuzz` maps campaign results back through that
+> tag, so keep it. To track an entry of your own in Hex, add it as an invariant first and put
+> its id after the Spec ID.
+>
+> **Guarantee tag.** Every property is tagged `SHOULD-HOLD` or `EXPLORATORY`:
+> - `SHOULD-HOLD` — explicitly guaranteed by docs/spec/standard or an exact identity
+>   (evidence cited inline). If the campaign violates it, that is a **confirmed bug**.
+> - `EXPLORATORY` — inferred, not explicitly promised. A violation is a **lead flagged
+>   for human review**, not an automatic bug.
+>
+> This tag is set at generation time so violations can be triaged without post-hoc
+> severity guessing. If you edit a property's logic such that it is no longer guaranteed,
+> change its tag to `EXPLORATORY`.
+
+## Global Properties
+> Always-on invariants. Implemented as `public function property_*()` in `{SUITE_DIR}/Properties.sol`.
+
+- [ ] **GL-01** (INV-001) — Solvency: the vault's underlying token balance is always at least `vault.totalAssets()`. (Category: HIGH_LEVEL; Guarantee: SHOULD-HOLD — whitepaper §4 "the vault never holds fewer assets than it accounts for"; Priority: HIGH; Sources: CON-01)
+- [ ] **GL-02** (INV-002) — Sum of per-actor share balances equals `vault.totalSupply()`. (Category: HIGH_LEVEL; Guarantee: SHOULD-HOLD — exact accounting identity: every mint/burn updates both a balance and totalSupply; Priority: HIGH; Sources: CON-02)
+- [ ] **GL-03** (INV-005) — Share price (`totalAssets/totalSupply`) is monotonically non-decreasing between handler calls. (Category: VARIABLE_TRANSITION; Guarantee: EXPLORATORY; Priority: MEDIUM; Sources: VT-02)
+...
+
+## Specific Properties
+> Operation-gated postconditions. Implemented as `internal function property_*()` in `Properties.sol` and called from the relevant handler after `snapshotAfter()`.
+
+- [ ] **SP-01** (INV-003) — After `vault_deposit`, `vault.totalSupply()` strictly increases. (Category: STATE_TRANSITION; Guarantee: SHOULD-HOLD — ERC-4626: `deposit` MUST mint shares to the receiver; After: `vault_deposit`; Priority: HIGH; Sources: ST-01)
+- [ ] **SP-02** (INV-004) — After a deposit→withdraw round-trip in a single call, the actor's underlying balance does not increase (no free value). (Category: HIGH_LEVEL; Guarantee: EXPLORATORY; After: `vault_roundTrip`; Priority: HIGH; Sources: C2)
+...
+```
+
+### Category distribution guidance
+
+A healthy property plan usually has at least one property in each category. If after synthesis you have zero `VALID_STATE` properties, re-check whether the protocol has pause/shutdown/recovery/initialization flags that should have generated some — a missing category is usually a gap in discovery, not a property-less protocol.
+
+### property-plan.md (unchanged structure, but now includes IDs)
+
+When you write the existing tables in `{META_DIR}/property-plan.md`, prefix each property's row with its PROPERTIES.md ID so implementers can cross-reference. Keep the rest of the format identical:
+
+```markdown
+# Property Plan
+
+> Generated by 5 specialized discovery agents. X properties total.
+> Priority distribution: N HIGH, N MEDIUM, N LOW
+
+## Global Properties (public, checked by fuzzer after every call)
+| Spec ID | Function Name | Property | Category | Guarantee | Evidence | Priority |
+|---------|--------------|----------|----------|-----------|----------|----------|
+| GL-01 | property_solvency | token.balanceOf(vault) >= vault.totalAssets() | HIGH_LEVEL | SHOULD-HOLD | whitepaper §4 | HIGH |
+
+## Specific Properties (internal, called at end of relevant handlers)
+| Spec ID | Function Name | Property | Category | Guarantee | Evidence | Called After | Priority |
+|---------|--------------|----------|----------|-----------|----------|-------------|----------|
+| SP-01 | property_depositIncreasesShares | totalSupply increased after deposit | STATE_TRANSITION | SHOULD-HOLD | ERC-4626 deposit clause | vault_deposit | HIGH |
+
+(`Evidence` is the SHOULD-HOLD justification; leave it blank / `—` for EXPLORATORY rows.)
+
+## Ghost Variable Plan
+[table from Step 5]
+
+## Snapshot State Plan
+[table from Step 5]
+
+## Handler Wiring Plan
+[table from Step 5]
+```
+
+Return: `DONE: X properties (N HIGH, N MEDIUM, N LOW). Guarantee: P SHOULD-HOLD, Q EXPLORATORY. Categories: A VALID_STATE, B STATE_TRANSITION, C VARIABLE_TRANSITION, D HIGH_LEVEL. Ghosts: Y variables. Snapshot fields: Z. Handler wiring: W handlers. PROPERTIES.md written with G global + S specific entries (all [ ]) for A accepted invariants. Proposed: K new invariants (INV-…, …).`

package/dist/skills/fuzz/agents/protocol-analyzer.md

@@ -0,0 +1,80 @@
+# Agent: Protocol Analyzer (Step 3 Fallback)
+
+**Role**: Perform manual protocol analysis when the Hex protocol model (`.hex/model/protocol.json`) is unavailable, and produce a `protocol-understanding.md` file that downstream steps (4, 6, 7, 9) can read back as their protocol context.
+
+**Spawn config**: `general-purpose` agent, `model: "{AGENT_MODEL}"` (see SKILL.md "Subagent Model" section — defaults to `sonnet`, `opus` under `--max`). Spawned ONLY in the Step 3 fallback path when the project has no Hex protocol model.
+
+---
+
+## Prompt
+
+You are executing the Step 3 fallback for the fuzz skill. This Hex project has no protocol model (`.hex/model/protocol.json`, which `/init-audit` writes), so you must perform manual protocol analysis from source code and write a `protocol-understanding.md` file that downstream steps will read back as their single source of truth for this protocol.
+
+## Your Inputs
+
+- Read: `{PROJECT_ROOT}/{META_DIR}/contracts.json` — the in-scope contract inventory produced by Step 2.
+- Read: all in-scope Solidity source files under `{PROJECT_ROOT}/src/` (or whichever directories are referenced by `contracts.json`).
+- Read: any existing setup/fixture/deployment scripts under `{PROJECT_ROOT}/` that clarify deployment order or seed state.
+- Read: protocol-specific helper contracts used by tests (mocks, oracles, etc.) when they clarify real dependencies vs. injected test doubles.
+- Read (Hex): `{PROJECT_ROOT}/{META_DIR}/hex-invariants.json` — the auditor's accepted invariants. List them first under Candidate Invariants (by `INV-NNN`), then add your own.
+- Use (Hex): `npx --no-install hex facts query <callers|callees|readers|writers|layout|linearization|entry-points|reach|function> [ref]` for exact entry points, callers and storage writers instead of guessing from grep. Always `npx --no-install hex`, never `npx hex`.
+
+## Your Output
+
+Write `{PROJECT_ROOT}/{META_DIR}/protocol-understanding.md` with the following sections in this exact order. Downstream steps grep for these headings, so keep them stable.
+
+```markdown
+# Protocol Understanding: {Protocol Name}
+
+## Summary
+One paragraph describing what this protocol does, its core primitives, and the actor model. Keep it tight — downstream agents read this to orient themselves.
+
+## Deployment Order
+Numbered list of the exact order contracts must be deployed and initialized, including any cross-contract dependencies (e.g. "OmniPool must be initialized before any OmniToken.initialize runs, because OmniToken's initialize reads omniPool.reserveReceiver()").
+
+## Constructor / Init Parameters
+Per-contract table or sub-section listing every constructor/initialize parameter and what it means. Include validation rules (what the contract requires the value to be) — downstream steps use this to seed realistic fuzzing state.
+
+## Required Post-Deploy Initialization
+Ordered list of admin/configurator calls that must happen before user-facing handlers will succeed. Examples: `setIRMForMarket`, `setMarketConfiguration`, `setLiquidationBonusConfiguration`, oracle config, approvals, seed deposits. Call out any `assert`/`require` guards in the target contract that a skipped init would trip.
+
+## Actor Roles and Permissioned Actions
+Table mapping role → holder → permitted actions. Include contract-address-as-caller relationships (e.g. "only OmniPool can call OmniToken.borrow") — downstream handler generation depends on this.
+
+## Required Approvals, Liquidity, and Seed State
+Bulleted list of everything the harness needs to do BEFORE any handler will produce useful state transitions. Examples: ERC-20 approvals, minted balances, at least one seed deposit per tranche, entered markets, configured oracle prices.
+
+## Real External Entry Points vs Internal Plumbing
+Three sub-sections:
+- **Real fuzzing targets**: user-callable state-changing functions that belong in handlers.
+- **Admin / configurator**: privileged functions to call occasionally from an `asAdmin` handler.
+- **Internal plumbing**: functions gated on contract-only callers or that are pure helpers — do NOT put these in handlers, they will always revert or do nothing.
+
+## Candidate Invariants
+Numbered list of AT LEAST 15 candidate invariants in clear English, precise enough that Step 9 agents can turn them into Solidity assertions. Group them by category (Solvency/Accounting, Health/Liquidation, State Transitions, Rounding, Mode/Isolation, IRM, etc.) when the protocol naturally supports the split.
+
+Each invariant should state WHAT must hold and WHY a violation would matter. Do not plan ghost variables or snapshot structs yet — Step 9 does that.
+```
+
+## Analysis Guidance
+
+Follow these biases:
+
+- **Prefer real code evidence over speculation.** If a guard is `msg.sender == omniPool`, say so; don't paraphrase it as "only admin".
+- **Prefer existing project setup over invented harness logic.** If the project has a deployment script or test fixture that already sequences init, mirror that order.
+- **Prefer conservative assumptions and targeted TODOs over broad guessing.** If something is ambiguous after reading the source, write `TODO: {specific question}` inline rather than making up an answer. Step 6/7 can resolve it later with more context.
+- **Cite file paths and line numbers** in the rationale for candidate invariants when they point to a specific assertion or require statement. This makes Step 9 agents much more efficient because they can jump straight to the relevant code.
+
+## Scope Boundaries
+
+Do NOT:
+- Plan full ghost variable layouts, snapshot structs, or implementation details — that is Step 9's job.
+- Write Solidity sketches for invariants — English descriptions are enough.
+- Modify any files other than `{PROJECT_ROOT}/{META_DIR}/protocol-understanding.md`.
+- Run `forge build`, `medusa fuzz`, or any other command — you are a pure analysis step.
+
+## Return Value
+
+After writing the file, return a one-line summary to the caller:
+
+`DONE: protocol-understanding.md written ({N} candidate invariants, {M} entry points identified, {K} post-deploy init steps).`

package/dist/skills/fuzz/agents/report-writer.md

@@ -0,0 +1,135 @@
+# Agent: Report Writer (Step 11)
+
+**Role**: Read the completed fuzzing suite outputs (coverage, corpus, campaign logs, properties, handlers) and produce the final `report.md`. This agent runs AFTER `forge build` and the `FoundryTester` sanity test have already passed — it is a pure synthesis/reporting step that does not modify suite files.
+
+**Spawn config**: `general-purpose` agent, `model: "{AGENT_MODEL}"` (see SKILL.md "Subagent Model" section — defaults to `sonnet`, `opus` under `--max`). Spawned at the end of Step 11 after validation succeeds.
+
+---
+
+## Prompt
+
+You are writing the final fuzzing suite report. Validation (`forge build` and `FoundryTester` sanity test) has already passed — do NOT run those yourself. Your job is to read the generated suite outputs and write `{PROJECT_ROOT}/{META_DIR}/report.md` using the exact structure below. Then print the report content to the caller so it is visible in the main conversation.
+
+## Your Inputs
+
+Read these files (skip gracefully if any are missing and write `N/A` in the corresponding report cell):
+
+- `{PROJECT_ROOT}/{META_DIR}/protocol-understanding.md` — protocol context (for the Suite Overview name and contracts list)
+- (Hex) `{PROJECT_ROOT}/.hex/config.json` (`project.name`) and `{PROJECT_ROOT}/.hex/model/protocol.json` — the protocol name and contracts when `protocol-understanding.md` does not exist (the usual case in a Hex project)
+- `{PROJECT_ROOT}/{META_DIR}/contracts.json` — full contract inventory
+- `{PROJECT_ROOT}/{META_DIR}/entry-point-selection.json` — the handlers' entry points
+- `{PROJECT_ROOT}/{META_DIR}/coverage-targets.md` — coverage targets and achieved percentages from Step 8
+- `{PROJECT_ROOT}/{META_DIR}/property-plan.md` — synthesized property plan from Step 9c
+- `{PROJECT_ROOT}/.hex/fuzz/PROPERTIES.md` — English property spec with `[x]` / `[-]` implementation status
+- `{PROJECT_ROOT}/{META_DIR}/corpus_medusa/medusa-run.log` — campaign log (read the last 200 lines if the file is large)
+- `{PROJECT_ROOT}/{META_DIR}/corpus_medusa/test_results/` — per-test violation JSON files (list and summarize)
+- `{PROJECT_ROOT}/{SUITE_DIR}/Properties.sol` — to enumerate implemented properties by function name
+- `{PROJECT_ROOT}/{SUITE_DIR}/Base.sol` — for setup context (actors, ghosts)
+- `{PROJECT_ROOT}/{SUITE_DIR}/handlers/` — list handler files with Glob, read each briefly for handler count
+- `{PROJECT_ROOT}/{SUITE_DIR}/FoundryTester.sol` — for violation repro test results (look for `test_repro_*` functions and whether they passed validation)
+
+If the paths above are wrong for this project (e.g. a different fuzzer was used, or files live under a different meta dir), adapt — prefer reading whatever exists over erroring out.
+
+## Report Structure
+
+Write `{PROJECT_ROOT}/{META_DIR}/report.md` with these exact sections in this exact order. Downstream tooling and humans both scan for these headings.
+
+```markdown
+# Fuzzing Suite Report
+
+## Suite Overview
+- **Project**: {protocol name from protocol-understanding.md}
+- **Suite location**: {SUITE_DIR, typically `test/fizz/`}
+- **Contracts targeted**: {comma-separated list of in-scope contracts}
+- **Total handlers**: {count} ({primary} primary, {secondary} secondary/dispatcher)
+- **Properties**: {count} ({global} global, {specific} function-specific)
+
+## Coverage Results
+| Contract | Target | Achieved | Status |
+|----------|--------|----------|--------|
+| ... | 80% | 85% | ✅ |
+| ... | 80% | 71% | ⚠️ |
+| ... | 80% | 47% | ❌ |
+
+Status legend: ✅ if achieved ≥ target (or intentional skip), ⚠️ if within 10 points below target, ❌ if more than 10 points below target.
+
+## Skipped Paths
+| Contract | Function / Path | Reason |
+|----------|----------------|--------|
+| ... | ... | ... |
+
+Populate with contracts/functions that were intentionally excluded (mock substitutions, out-of-scope dependencies, admin-only paths not wired to handlers).
+
+## Campaign Results
+- **Fuzzer used**: {Medusa/Echidna}
+- **Duration**: {time}
+- **Total calls**: {if available from log}
+- **Branches hit**: {if available}
+- **Corpus size**: {if available}
+- **Violations found**: {count}
+
+### Violation Details
+For each distinct violation root cause (NOT each reproduction), write a sub-section with:
+- **Property violated**: {name} ({Spec ID}; Hex invariant: the `INV-NNN` in its PROPERTIES.md entry, or `none`)
+- **Guarantee**: `SHOULD-HOLD` | `EXPLORATORY` (look up the violated property's tag in `PROPERTIES.md` by its Spec ID / function name)
+- **Assertion**: {the exact check that failed}
+- **Root cause**: {your best-guess explanation based on the reproducing call sequence}
+- **Severity assessment**: `protocol bug` | `test harness false positive` | `needs human review`
+- **Reproducing sequence**: {shrunk call sequence from the corpus}
+- **Foundry repro**: `test_repro_{propertyName}` in `FoundryTester.sol` — `PASS` (violation reproduces) / `FAIL` (did not reproduce, see TODO in test) / `N/A` (no violations)
+
+**Use the Guarantee tag to anchor the severity assessment** (after first ruling out a harness/property bug):
+- A violated **SHOULD-HOLD** property means a documented or mathematically-guaranteed invariant broke → default to `protocol bug` unless the repro proves the assertion itself is wrong (then `test harness false positive`, with the fix).
+- A violated **EXPLORATORY** property is an inferred assumption that did not hold → default to `needs human review`; only call it `protocol bug` when the root cause clearly shows real value loss / broken safety, and only `test harness false positive` when the inferred property was simply too strong (say so explicitly).
+
+If multiple stored failures share the same root cause, group them under one sub-section and note the count.
+
+## Properties Implemented
+| # | Property | Type | Guarantee | Confidence |
+|---|----------|------|-----------|------------|
+| ... | property_solvency | Global | SHOULD-HOLD | HIGH |
+| ... | _prop_depositIncreasesShares | Specific | EXPLORATORY | MEDIUM |
+
+Enumerate every property that appears in `Properties.sol` (both `property_*` global functions and `_prop_*` internal specifics).
+
+`Guarantee` is the generation-time tag — copy it verbatim from `PROPERTIES.md` (`SHOULD-HOLD` / `EXPLORATORY`) by matching the property's Spec ID / function name; write `N/A` if the property is not in `PROPERTIES.md`. It records whether a violation would be a confirmed bug (SHOULD-HOLD) or a human-review lead (EXPLORATORY).
+
+`Confidence` is your own assessment of how robustly the *assertion is written* (orthogonal to Guarantee) — HIGH/MEDIUM/LOW:
+
+- **HIGH**: strict assertion, correct tolerance, exercises a meaningful invariant.
+- **MEDIUM**: assertion is correct but has soft tolerances (e.g. `+1` wei slack, `110%` of cap), or does not cover all reachable actors.
+- **LOW**: property is a stub that returns `true` without asserting anything, or the assertion is trivially satisfied.
+
+If `PROPERTIES.md` exists, cross-reference implementation status: `[x]` implemented, `[-]` skipped/manual, `[ ]` pending.
+
+## Open TODOs
+Scan the generated suite files under `{PROJECT_ROOT}/{SUITE_DIR}/` (Base.sol, Snapshots.sol, Properties.sol, all handler files) for `TODO` comments and list them with file:line references.
+
+## Next Steps
+Actionable recommendations ordered by priority. At minimum, address:
+1. Any `test harness false positive` violations found in Campaign Results — specify the exact fix.
+2. Any LOW-confidence properties from the Properties Implemented table — specify how to strengthen them.
+3. Any contract with ❌ coverage status — specify which uncovered functions would most improve coverage.
+4. Any open TODO that blocks production readiness.
+5. Recommended campaign duration for production validation (current run vs. recommended).
+```
+
+## Writing Style
+
+- Be precise with numbers. Do NOT invent figures. If a number is missing from the inputs, write `N/A` or `Not Available`.
+- Keep the tone factual and terse — this is a report, not marketing. One-sentence bullets are usually enough.
+- When you classify a violation as `test harness false positive`, cite the specific timing/rounding/accounting reason and propose the fix. Never classify a real protocol bug as a false positive.
+- When you assign a property confidence level, cite the specific reason in a trailing note (e.g. "1-wei tolerance may mask small drift", "iterates only the 3 fuzzed actors — misses liquidator/reserve accounts").
+
+## After Writing the File
+
+Also remind the user of the commands to run campaigns manually, exactly as SKILL.md Step 11 specifies:
+
+- `medusa fuzz` (from project root)
+- `echidna {SUITE_DIR}/FuzzTester.sol --contract FuzzTester --config echidna.yaml` (if echidna is configured)
+
+## Return Value
+
+After writing the file, print the full report content to the caller (so the human sees it in the main conversation without needing to open the file), then return a one-line summary:
+
+`DONE: report.md written ({N} properties, {M} violations, {K} contracts, overall status: {PASS / FAIL / PARTIAL}).`