hex-audit 0.6.3 → 0.8.0

package/dist/skills/generate-report.md

@@ -4,9 +4,8 @@ description: "Generate the LaTeX report sections for the final audit report (Ove
 
 # Skill: Generate Report
 
-**Recommended model:** Sonnet
 
-This skill produces the LaTeX section files an auditor assembles into the Nethermind Overleaf report template at the end of an engagement. It runs from the GitHub-synced issues (the report's source of truth), after findings have been pushed via /sync-issues, and reuses the analysis Hex already produced during /init-audit (`overview.md`, `stats.json`, `access-control.json`, `deps.json`).
+This skill produces the LaTeX section files an auditor assembles into the Nethermind Overleaf report template at the end of an engagement. It runs from the GitHub-synced issues (the report's source of truth), after findings have been pushed via /sync-issues, and reuses the analysis Hex already produced during /init-audit (`overview.md`, `stats.json`, the verified protocol model in `model/protocol.json`, and the diagrams the auditor marked for the report).
 
 ## What it writes
 
@@ -15,7 +14,7 @@ Seven report sections in `<output_dir>/report/`, each emitted in **two forms** (
 1. **Executive Summary** (§1) — project synopsis, severity histogram, status histogram, summary table of audit metadata.
 2. **Audited Files** (§2) — a LaTeX table of in-scope files (LoC, comments, ratio, blank, total).
 3. **Summary of Issues** (§3) — hyperlinked finding rows.
-4. **System Overview** (§4) — descriptive protocol architecture: components, actors & roles, per-module or per-flow subsections. Built from `overview.md` + access-control/deps analysis.
+4. **System Overview** (§4) — descriptive protocol architecture: components, actors & roles, per-module or per-flow subsections. Built from `overview.md` + the verified protocol model, with the diagrams marked "Use in report" as figures.
 5. **Issues** (§6) — one `\subsection{[Sev] title}\label{issue:N}` per synced finding, with description, code blocks, recommendation, status, client update.
 6. **Documentation Evaluation** (§7) — a `tcolorbox` remarks paragraph about the client's documentation.
 7. **Test Suite Evaluation** (§8) — the test-run result (passed/failed/skipped), coverage summary, and automated-tooling note, generated from a live test run plus `stats.json.test_coverage`.
@@ -56,10 +55,10 @@ Each section has a defined **input signature** — the exact set of data it deri
 
 | Section | Input signature (hash over) |
 |---|---|
-| `executive_summary` | severity + resolution histograms, `stats.totals.nsloc`, all `settings.report.*` fields, and the `overview.md` bytes (the synopsis derives from it) |
-| `audited_files` | the per-file LoC results for every `project.scope` file, `repository_url`, `initial_commit` |
+| `executive_summary` | severity + resolution histograms, `stats.totals.nsloc`, all `settings.report.*` fields, and the `overview.md` bytes (the synopsis derives from it); differential: also `diff.json` `base_commit` / `head_commit` / `summary` |
+| `audited_files` | the per-file LoC results for every `project.scope` file (differential: every changed file, with its +/- counts), `repository_url`, `initial_commit` |
 | `summary_of_findings` | the ordered synced-findings list: `(id, title, severity, resolution)` each |
-| `system_overview` | `overview.md`, `access-control.json`, `deps.json` bytes |
+| `system_overview` | `overview.md`, `model/protocol.json` and `model/diagrams/index.json` bytes, and the bytes of every `report/figures/*.png` marked `in_report` |
 | `findings` | the synced-findings full content: `(title, severity, description, code blocks, recommendation, resolution, update_from_client, root_cause.locations)` each |
 | `documentation_eval` | `settings.report.{doc_assessment,kickoff_call,client_availability}`, `project.docs_url`, and the NatSpec-presence signal (`stats.totals.comment_lines`) |
 | `test_suite` | the test-run summary (pass/fail/skip counts) and `stats.test_coverage`, `settings.report.test_assessment` |
@@ -85,7 +84,7 @@ Read `<output_dir>/config.json`. Look under `settings.report.*` for:
 - `final_commit` — commit hash after fixes (defaults to `initial_commit` if no remediation cycle).
 - `initial_report_date` — date the initial report was delivered (e.g. `May 22, 2026`).
 - `final_report_date` — date the final report was delivered (defaults to `initial_report_date`).
-- `audit_type` — defaults to `Security Review`.
+- `audit_type` — defaults to `Security Review`. A differential audit (`project.mode: "diff"`) is initialized with `Differential Review`.
 - `doc_assessment` — `High` / `Medium` / `Low`.
 - `test_assessment` — `High` / `Medium` / `Low`.
 - `kickoff_call` — optional focus note for the §7 kick-off sentence (e.g. "with a focus on the upgrade changes"). Empty means omit the kick-off sentence.
@@ -138,6 +137,8 @@ Style hints:
 
 Write to `executive_summary.txt` **and** `01-executive-summary.tex`.
 
+**Differential audit** (`config.json` → `project.mode` is `diff`): the review covers the changes between two commits, and the first paragraph must say so. Use `<SCOPE_DESCRIPTION>` = `changes to <scope description> between commit \href{<REPOSITORY_URL>/commit/<BASE_COMMIT>}{\texttt{<BASE_SHORT>}} and commit \href{<REPOSITORY_URL>/commit/<HEAD_COMMIT>}{\texttt{<HEAD_SHORT>}}` (commits from `.hex/diff.json`, short = first 7 characters). Replace the `<TOTAL_NSLOC>` sentence with the size of the change: `\textbf{The audit comprises} <ADDITIONS> added and <DELETIONS> removed lines of Solidity code across <FILES_CHANGED> files` (from `diff.json` `summary`). Everything else in the section is unchanged.
+
 ```latex
 \pagebreak \vspace*{0cm}
 \sectioncolor
@@ -222,6 +223,8 @@ Substitutions:
 
 Write to `audited_files.txt` **and** `02-audited-files.tex`.
 
+**Differential audit:** the rows are the files in `.hex/diff.json` `files` with status `added`, `modified` or `renamed` (not `deleted`), counted at the head commit, instead of every `project.scope` file. Keep the same columns; the table still describes the audited files at head. `<INITIAL_COMMIT>` in the links is the head commit.
+
 Compute per-file line counts from each scope file. For each in-scope file in `config.json.project.scope`:
 
 - Read the file. Count:
@@ -301,7 +304,20 @@ For each synced finding in severity-sorted order (Critical → Info), assign a s
 
 Write to `system_overview.txt` **and** `04-system-overview.tex`.
 
-Primary source: `<output_dir>/overview.md` (produced by /init-audit — it already carries an intro, a `## Key Contracts` table, `## External Dependencies`, and `## Architecture Notes`). Enrich the actors/roles material from `<output_dir>/access-control.json` (roles, modifiers, gated functions) and cross-contract relationships from `<output_dir>/deps.json`.
+Primary source: `<output_dir>/overview.md` (produced by /init-audit — it already carries an intro, a `## Key Contracts` table, `## External Dependencies`, and `## Architecture Notes`). Take actors, roles and privileges from the protocol model (`npx --no-install hex model show actors` / `privileges`), using **only claims with `status: "verified"`**; a contested claim is not a fact about the system. Exact relationships (inheritance, who calls what) come from `npx --no-install hex facts query linearization|callers|callees <ref>`.
+
+**Figures.** For every entry in `<output_dir>/model/diagrams/index.json` with `in_report: true` and a PNG at `<output_dir>/report/figures/<name>.png`, add a figure in the subsection it explains (custody near the components, privilege under Actors and Roles, sequences in their flow subsection), with the diagram's `takeaway` as the caption:
+
+```latex
+\begin{figure}[H]
+    \centering
+    \includegraphics[width=\textwidth]{figures/<name>.png}
+    \caption{<takeaway, LaTeX-escaped>}
+    \label{fig:<name>}
+\end{figure}
+```
+
+Tell the auditor to upload `report/figures/` next to the `.tex` files in Overleaf.
 
 **If `overview.md` is absent, abort**: "System Overview needs `<output_dir>/overview.md`. Run `/init-audit` first, then re-run `/generate-report`."
 

package/dist/skills/ingest-aa-report.md

@@ -4,7 +4,6 @@ description: "Ingest a completed Nethermind AuditAgent scan into the board and d
 
 # Skill: Ingest AuditAgent Report
 
-**Recommended model:** Sonnet
 
 This skill is the single point of integration with Nethermind's AuditAgent. It does **not** start scans — the auditor starts a scan separately (e.g. via the Nethermind portal or `aa scan ...` from the command line) and passes the resulting scan ID into this skill. The skill fetches the results, normalizes them into the board, and inline-dedupes against everything already there.
 
@@ -110,48 +109,30 @@ to `<output_dir>/ai-results/auditagent/findings.json`. Also write a small `metad
 The raw AuditAgent findings keep their own `AA-<NNN>` ids inside `ai-results/auditagent/findings.json` (that file is the source record). The **board** card gets a uniform `H-NNN` id. Create one per finding via the CLI — it allocates the id and materializes the full finding (title, severity, description, affected code) from the raw record by `source_ref`:
 
 ```bash
-npx hex issue new --source auditagent --source-ref <AA-NNN> --title "<title>" --severity <Severity>
+npx --no-install hex issue new --source auditagent --source-ref <AA-NNN> --title "<title>" --severity <Severity>
 ```
 
 Capture each printed `H-NNN`. Cards land in the Potential column with `status: unverified`. Never hand-edit `tracking.json`.
 
 ## Step 6 — Inline dedup
 
-Read all existing tracking entries (manual, conformance, github, and any previously ingested auditagent runs) — all uniform `H-NNN` ids. For each **new** auditagent card, run a semantic comparison against each existing entry on these axes:
-
-| Signal | How to compare |
-|---|---|
-| **contract** (boolean) | Does the affected contract name match? |
-| **function** (boolean) | Does the affected function name match? |
-| **root_cause** | `same` / `overlapping` / `different` — judge the technical mechanism (e.g. "reentrancy on external call before state update" is `same` as "missing CEI pattern around external call"). |
-| **attack_vector** | `same` / `overlapping` / `different` — judge what an attacker actually does to exploit it. |
-
-A match is **at least one of**:
-- `root_cause = same` AND `function = true`, or
-- `root_cause = same` AND `contract = true` AND `attack_vector = same`, or
-- `root_cause = overlapping` AND `function = true` AND `attack_vector = same`.
-
-On match, **move the new auditagent card to the Duplicate column** (the canonical is the existing entry — the auditor already filed or already has it from another source):
+For each new card, run the one Hex dedup engine:
 
 ```bash
-npx hex issue move <new-H-id> --to duplicate
+npx --no-install hex issue dedup <new-H-id>
 ```
 
-Then record the match in `<output_dir>/comparison.json` under `duplicates`. The board reads this to show the "dup of `<canonical-H-id>`" chip and the match signals (it derives `duplicate_of` from the `matches` field here):
+It maps the card to the exact functions it is about (from its code and the compiler facts), ranks existing cards that touch the same function or contract, and prints **the match rules** (four signals: contract, function, root cause, attack vector; three clauses) and the triage rules. Judge each strong candidate against those rules (root cause and attack vector are your call; the rules decide). On a match:
 
-```json
-{
-  "ai_finding": "<new-H-id>",
-  "matches": "<canonical-H-id>",
-  "confidence": "high | medium | low",
-  "match_signals": { "contract": true, "function": true, "root_cause": "same", "attack_vector": "same" },
-  "reasoning": "<one short sentence: which signals carried the call>"
-}
+```bash
+npx --no-install hex issue mark-duplicate <new-H-id> --of <canonical-H-id> \
+  --root-cause <same|overlapping|different> --attack-vector <same|overlapping|different> \
+  [--same-contract] [--same-function] --reasoning "<one sentence: which signals carried the call>"
 ```
 
-If `comparison.json` doesn't exist, create it with `{ "duplicates": [], "novel": [], "rejected": [] }`.
+It moves the card and records the signals in `comparison.json` in one step (the board shows the "dup of" chip). When a **triage rule** covers the finding's whole impact, exclude it instead: `npx --no-install hex issue exclude <new-H-id> --rule R-NNN`.
 
-For entries that don't match anything, leave them as `status: "unverified"` (the auditor will run `/validate-finding AA-<NNN>` on them).
+Cards that match nothing stay `unverified`. Then run **`/prevalidate`** on them: background agents reproduce or refute each one, conclusive cases move automatically, and the auditor triages the rest.
 
 ## Step 7 — Report
 
@@ -163,7 +144,7 @@ Ingested N AuditAgent findings (scan <scan_id>).
 - K flagged as Duplicate of existing entries
 - 0 errors
 
-Run /validate-finding <id> on any new finding to confirm and promote it to Verified.
+Pre-validation ran on the new cards; see its summary. Run /validate-finding <id> on anything left uncertain.
 ```
 
 ## Outputs (recap)

package/dist/skills/init-audit/SKILL.md

@@ -0,0 +1,155 @@
+---
+name: init-audit
+description: 'Initialize a Solidity audit with Hex: dependency safety, exact compiler facts, then a team of agents that builds and verifies the protocol model (actors, assets, privileges, accounting, state machines, invariants), spec conformance and explanatory diagrams. Full or differential (base → head) audits.'
+---
+
+# Skill: Initialize Audit
+
+You are the **orchestrator** of the pre-review. You gather inputs, run the safety gate and the deterministic layer yourself, then direct agents in four waves. By the end the dashboard shows a verified protocol model, proposed invariants, conformance cards and diagrams that explain the system.
+
+Use `npx --no-install hex …` for every Hex command (an unrelated npm package is called `hex`; `--no-install` makes sure only Hex runs). When the Hex MCP tools are available (`hex_facts_query`, `hex_model_get`, …) you may use them instead; they do the same thing.
+
+## How the agents work together
+
+The topology follows one rule: **silo where independence is the point, share where integration is the point.**
+
+- **Discovery is siloed.** Each contract reader sees only its own cluster plus the exact facts. Readers do not see each other's notes, so one reader's framing cannot anchor another's. The docs extractor reads documentation only and never code, so a gap between what the docs promise and what the code does shows up as a mismatch instead of being explained away.
+- **Synthesis is shared.** One synthesizer reads every draft and the facts and writes one consistent model.
+- **Verification is siloed again.** Skeptics get the claims and the code, but not the synthesizer's reasoning, so they check what the code does rather than whether the argument sounds right.
+- **Diagrams are shared.** Composers draw from the verified model.
+
+Agents never message each other. They communicate through files under `.hex/model/` (drafts, verdicts, specs), and they answer exact cross-contract questions ("who calls X?", "who writes Y?", "which entry points reach Z?") with `npx --no-install hex facts query …` instead of guessing or asking another agent.
+
+Agent prompts are in `references/agents/` next to this file. Claude Code prints this skill's base directory when it loads the skill ("Base directory for this skill: …"); the references live under it. If no base directory was printed, Glob exactly `.claude/skills/init-audit/references/agents/*.md`. Spawn agents with the Agent tool as **background** calls, in **one message per wave**, and wait for every completion notification before starting the next wave. Never poll or sleep.
+
+It runs in one of two modes, chosen in Phase 0:
+
+- **Full**: audit the whole scope at one commit (the default).
+- **Differential**: audit what changed between a previously audited **base** commit and the **head** commit, plus the flows those changes reach. Sections marked **(differential)** run only in this mode.
+
+---
+
+## Phase 0 — Inputs, safety gate, exact facts (orchestrator, sequential)
+
+### 0.1 Gather information
+
+Ask the auditor (one AskUserQuestion where possible):
+
+- **Audit type**: *Full* or *Differential*. Ask this first; the rest branches on it.
+- **Project directory** (default: current directory), **scope** globs (e.g. `src/**/*.sol`), **commit** (default `HEAD`), **chain** (default ethereum), **documentation URL** if any, and optionally the **GitHub repo** (`owner/repo`) findings sync to.
+- **(differential)** The **base commit** (required), the **head commit** (default `HEAD`, which must be checked out; `git fetch --unshallow` first on a shallow clone), and an optional **previous audit**: the earlier engagement's `.hex/` folder or its report (PDF or Markdown). When a previous `.hex/` is given, propose its `project.scope_globs` (or `project.scope`) as the scope and its `project.commit` as the base, and confirm both.
+
+### 0.2 Dependency safety (BEFORE anything compiles)
+
+Build scripts and install hooks are a supply-chain vector. Check, before any `forge build`, `npm install` or compile:
+
+1. `package.json` install hooks (`preinstall`, `postinstall`, `prepare`, `prebuild`, `pretest`) that shell out, download, or touch files outside the project.
+2. Foundry `lib/` submodules: each `lib/*/foundry.toml` for `ffi = true`, broad `fs_permissions`, or `script` entries.
+3. Root `foundry.toml`: `ffi = true` is **high risk**; `fs_permissions` broader than read-only on `./src`/`./out`; profile overrides that differ from the main profile.
+4. `remappings.txt`: every target exists in `lib/`; flag shadowed or hijacking remaps (`@openzeppelin/=lib/malicious-oz/`).
+5. Root-level `*.sh`, `*.py`, `Makefile` targets and `.github/` workflows.
+6. Plaintext secrets in `.env*` (do not print the values).
+7. `.vscode/extensions.json` recommending unknown publishers.
+
+**If anything looks risky, STOP and warn before compiling.** Then evaluate Solidity dependencies: known libraries and versions with advisories (OZ < 4.9.3, old Solmate `SafeTransferLib`), typosquats (`@openzepplin`), unused dependencies, and unknown packages with inline assembly, `selfdestruct` or `delegatecall` to fixed addresses.
+
+### 0.3 Initialize and build the deterministic layer
+
+```bash
+npx --no-install hex init --project "<path>" --scope "<globs>" --commit <hash> --chain <chain> --docs "<url>" [--github-repo <owner/repo>] \
+  [--mode diff --base <base-commit> [--previous-audit "<path>"]]
+npx --no-install hex analyze
+```
+
+`hex analyze` compiles into `.hex/.cache` (never the client's `out/`) and writes:
+
+- `.hex/facts.json`: exact compiler facts (call graph with `internal`/`super`/`library`/`external`/`virtual`/`modifier` edges, reads/writes per function, inheritance linearization, entry points, compiler storage layouts);
+- `.hex/stats.json`: nSLOC, ERC usage, coverage;
+- **(differential)** `.hex/diff.json` and `.hex/diff/changes.patch`: changed entities, slot-exact storage-layout changes, and impacted functions with reason chains.
+
+Read the first lines of `facts.json`. If `"source": "parser-fallback"`, the build failed: tell the auditor that facts are approximate (calls resolved by name, layout without packing) and how to fix the build, then continue.
+
+**(differential)** If `diff` failed (usually a commit missing from a shallow clone), stop: a differential audit without the diff is a full audit under the wrong label.
+
+### 0.4 Plan the waves
+
+From `facts.json` and `stats.json`, group the in-scope contracts into **clusters** of roughly 800–1500 nSLOC. Contracts that inherit from each other or call each other heavily belong together (use `linearization`, and `calls` edges between contracts). One reader per cluster; a small codebase may be a single cluster. Write the plan as a short list for the auditor (cluster → contracts → nSLOC) and continue without waiting.
+
+**(differential)** Readers cover only clusters that contain changed or impacted functions (`npx --no-install hex diff --scan-files` lists the files); each reader also gets `.hex/diff/changes.patch`.
+
+`mkdir -p .hex/model/drafts .hex/model/verdicts .hex/model/diagrams`
+
+---
+
+## Phase 1 — Discovery (siloed, parallel)
+
+Spawn in **one message**:
+
+| Agent | Prompt file | Count | Writes |
+|---|---|---|---|
+| Contract reader | `references/agents/contract-reader.md` | one per cluster | `.hex/model/drafts/reader-<n>.json` |
+| Docs extractor | `references/agents/docs-extractor.md` | one, only when there is documentation (URL, `docs/`, README with protocol text) | `.hex/model/drafts/docs-claims.json` |
+| Standards checker | `references/agents/standards-checker.md` | one, only when `stats.json` lists ERCs/EIPs or contracts implement known interfaces | `.hex/model/drafts/standards.json` |
+| **(differential)** Prior-audit importer | `references/agents/prior-audit.md` | one, only with a previous audit | `.hex/previous-audit/findings.json` |
+
+Substitute the placeholders each prompt file declares (cluster contracts and files, output path, docs URL, previous-audit path). Do not paste source code into prompts; agents read files themselves.
+
+## Phase 2 — Synthesis (shared)
+
+Spawn **one** synthesizer (`references/agents/synthesizer.md`). It reads every draft plus the facts and writes:
+
+- `.hex/model/protocol.json` (schema in its prompt; every claim has a `claim_id` and evidence),
+- `.hex/model/invariants.json` (all `status: "proposed"`),
+- `.hex/overview.md` (2–3 paragraphs + key contracts table; the report's System Overview is built from it),
+- **(differential)** `.hex/diff-overview.md`.
+
+When it finishes, run `npx --no-install hex model validate`. Every function id the model cites must exist in the facts. If validation fails, send the errors back to the synthesizer (SendMessage to the same agent) and re-validate. Do not hand-edit the model.
+
+## Phase 3 — Verification (siloed, parallel)
+
+On a re-run, first move the previous conformance results aside so the checker works fresh but can keep ids stable (cards cite them as `source_ref`): `mv .hex/spec-conformance.json .hex/model/drafts/spec-conformance.prev.json` (skip if absent).
+
+Spawn in **one message**:
+
+| Agent | Prompt file | Count | Writes |
+|---|---|---|---|
+| Skeptic | `references/agents/skeptic.md` | one per section group: (actors + privileges + trust), (assets + external dependencies), (accounting), (state machines + risky flows), (invariants) — skip empty groups | `.hex/model/verdicts/<group>.json` |
+| Conformance checker | `references/agents/conformance-checker.md` | one, when Phase 1 produced docs claims or standards checks | `.hex/spec-conformance.json` + `.md` |
+| **(differential)** Regression checker | `references/agents/regression-checker.md` | one, when prior findings were imported | `.hex/previous-audit/review.json` |
+
+Each skeptic gets **only** its claims (the JSON array for its sections, extracted from `protocol.json` without any prose) and the code. Then:
+
+```bash
+npx --no-install hex model apply-verdicts
+```
+
+It marks each claim `verified` or `contested` (any contesting skeptic wins), and records verdicts on invariant ids on the invariant itself (`verification`). Contested claims and invariants stay with the skeptic's note; the dashboard shows them, so the auditor sees where the system is not what it seems before accepting anything. Leads that skeptics raise go to the contract notes with `npx --no-install hex note lead <Contract> --text "<…>" --source init-audit --source-ref skeptic-<group>-<claim_id>`; skip leads that repeat one already in `npx --no-install hex note show <Contract>` (skeptics work in silos, so they often rediscover the same bug).
+
+## Phase 4 — Diagrams (shared, parallel)
+
+Spawn one diagram composer per view that has material in the verified model (`references/agents/diagram-composer.md`, with `{view}` set to `custody`, `privilege`, `accounting`, `state-machine` or `sequence`). In **one message**. Each writes `.hex/model/diagrams/<name>.spec.json`. Then:
+
+```bash
+npx --no-install hex diagram build
+```
+
+If a spec is invalid, send the error to its composer and rebuild. **(differential)** Composers draw the impacted flows and changed state; `hex diagram build` highlights changed functions automatically.
+
+## Phase 5 — Cards, summary, dashboard (orchestrator)
+
+1. **Conformance cards.** For every item in `spec-conformance.json` with status `DEVIATES` or `PARTIAL`, unless a tracking entry already has that `source_ref`:
+   ```bash
+   npx --no-install hex issue new --source conformance --source-ref "<SC-NNN>" --title "<first sentence of finding, ~80 chars, plain text without backticks>" --severity "<severity_hint or Info>"
+   ```
+   Then run `npx --no-install hex issue dedup <new id>` and apply its match rules. A conformance item often restates a finding the auditor already filed (a deviation from ERC-4626 is also a manual "first-depositor inflation" card); when it matches, `npx --no-install hex issue mark-duplicate <new id> --of <existing id> --root-cause <same|overlapping> --attack-vector <same|overlapping|different> [--same-contract] [--same-function] --reasoning "<one sentence>" --confidence <level>`, so the existing card (GitHub-synced cards first) stays canonical.
+2. **(differential) Regression cards.** For every `regressed` item in `previous-audit/review.json` (skip ids that already have a `prior-audit` tracking entry), create `npx --no-install hex issue new --source prior-audit --source-ref "<prior id>" --title "<title>" --severity <Severity>`, record the returned id as the item's `issue_id`, and rewrite the card's description for the head code with `npx --no-install hex issue patch <id> --description-file …`.
+3. **Summary.** Scope (files, contracts, nSLOC); facts source; model size and how many claims were contested (name the contested ones in one line each, since they are the most valuable output); proposed invariants (`npx --no-install hex invariant list`), with a reminder to accept the ones that hold (`npx --no-install hex invariant accept INV-…` or on the dashboard's Model page); conformance cards created; diagrams built; **(differential)** base → head, files changed, impacted entry points, storage-layout changes, and the prior-findings tally. Suggest next steps: `/ai-audit` (in a differential audit it scans only changed and impacted code), `/fuzz` once invariants are accepted, and the Review page's blind spots.
+4. **Dashboard.** Launch it in the background (`run_in_background: true`):
+   ```bash
+   npx --no-install hex dashboard --project "<absolute project dir>"
+   ```
+   and print one line: `Dashboard starting at http://localhost:3000`.
+
+## Writing standard (applies to every agent's prose)
+
+Everything written to `.hex/` may reach a client report. Plain, specific, technical prose. Backtick identifiers (`deposit(...)`, `totalAssets`). No em dashes, no filler, no speculation in the overview. Claims cite evidence as `file` + line range; the evidence is for navigation and never appears as "line N" in report prose.

package/dist/skills/init-audit/references/agents/conformance-checker.md

@@ -0,0 +1,36 @@
+# Conformance checker
+
+You compare what the protocol **promises** with what the code **does**: documentation claims (`.hex/model/drafts/docs-claims.json`, written by an agent that never saw the code), standards checks (`.hex/model/drafts/standards.json`), and NatSpec (`@notice`, `@dev`, `@param`, `@return`, especially conditional promises such as "reverts if…" and "only when…").
+
+Use the protocol model (`.hex/model/protocol.json`) for orientation only: skeptics verify it in parallel with you, so none of its claims is established yet. Every conformance status you write must rest on the code itself. Exact relationships: `npx --no-install hex facts query …`. **(differential)** Check only claims that touch changed or impacted functions (`.hex/diff.json`), plus any documentation of new behavior.
+
+**Ids are stable across re-runs.** If `.hex/model/drafts/spec-conformance.prev.json` exists, read it only after your own checks are done, then renumber: an item with the same root cause as a previous item keeps that item's id (board cards cite it as `source_ref`), new items continue after the highest previous id, and a retired id is never reused.
+
+Write `.hex/spec-conformance.json`:
+
+```json
+{
+  "checked_at": "<ISO>",
+  "sources_checked": { "external_docs": true, "natspec": true, "interfaces": true, "erc_eip": ["ERC-20", "ERC-4626"] },
+  "summary": { "total_checks": 0, "conforms": 0, "deviates": 0, "partial": 0, "unverifiable": 0, "undocumented": 0 },
+  "items": [
+    {
+      "id": "SC-001",
+      "source": "external_docs | natspec | interface | erc_eip",
+      "spec_text": "The promise, verbatim or closely paraphrased.",
+      "spec_location": { "type": "url | natspec | eip", "url": "", "section": "", "number": 4626 },
+      "status": "CONFORMS | DEVIATES | PARTIAL | UNVERIFIABLE | UNDOCUMENTED",
+      "finding": "What the code does vs the promise.",
+      "code_location": { "file": "src/Vault.sol", "line_start": 120, "line_end": 145 },
+      "severity_hint": "Info | Low | Medium | High | Critical",
+      "confidence": "high | medium | low"
+    }
+  ]
+}
+```
+
+Carry the standards checker's `DEVIATES`/`PARTIAL` results in as items (`source: "erc_eip"` or `"interface"`), re-verified against the code.
+
+The `finding` text becomes a board card's description and can reach the client's report. Write it to the report standard: flat prose, backticked identifiers, **no line numbers**, no cross-references to other items, no PoC mentions. When code helps, embed a minimal fenced `solidity` block and refer to it by name.
+
+Also write `.hex/spec-conformance.md`: the same items grouped by status, DEVIATES first.

package/dist/skills/init-audit/references/agents/contract-reader.md

@@ -0,0 +1,59 @@
+# Contract reader
+
+You are one of several **independent** readers building the model of a Solidity protocol. You cover one cluster of contracts. Other readers cover the rest; you will not see their notes, and that is deliberate: report what *your* code does, in your own framing.
+
+**Your cluster:** {contracts} (files: {files})
+**Write to:** `{output}` (JSON, schema below)
+{diff_block}
+
+## How to work
+
+1. Read your files in full. Read bases and libraries outside your cluster only as far as your code depends on them.
+2. For exact relationships use the compiler facts, never guesses:
+   - `npx --no-install hex facts query function <Contract.fn>`: signature, modifiers, calls, reads, writes, external calls
+   - `npx --no-install hex facts query callers|callees <ref> [--transitive]`
+   - `npx --no-install hex facts query call-sites <ref>`: every caller with the exact line of each call
+   - `npx --no-install hex facts query implementations <Interface.fn>`: where an interface or virtual function actually runs (overrides, and same-signature contracts such as a token behind `IERC20`)
+   - `npx --no-install hex facts query readers|writers <Contract.var>`
+   - `npx --no-install hex facts query reach <ref>`: entry points that can reach a function
+   - `npx --no-install hex facts query layout <Contract>` / `linearization <Contract>`
+3. Write down **claims**: one fact per claim, each with evidence (`file`, `line_start`, `line_end`) and the exact function ids it involves (ids look like `Vault.withdraw(uint256)`; get them from `hex facts query function`).
+
+You are read-only in the repository. Do not create, edit or delete files there except your output file.
+
+## What to claim (sections)
+
+- `actors`: who interacts (user roles, admins, keepers, guardians, external protocols) and **which functions only they can call** (from modifiers / `msg.sender` checks).
+- `assets`: what value the cluster holds (tokens, native ETH, shares, debt), where it sits, and **which functions move it** in or out.
+- `privileges`: each privileged function: who, effect, and the **worst case** if that actor is malicious or compromised; any timelock or cap.
+- `trust`: assumptions the code silently relies on (trusted admin, honest oracle, standard ERC-20 behavior, no reentrancy from token X).
+- `dependencies`: external contracts the code calls (oracles, DEXes, bridges, tokens): which functions call them and how each can fail.
+- `state_machines`: lifecycle entities (positions, requests, proposals, auctions): states, the functions that move between them, and the guards. Note transitions that look missing or unguarded.
+- `accounting`: the conservation laws the code maintains (`totalAssets == Σ balances + fees`, `totalSupply == Σ shares`), and which functions change each term in which direction.
+- `flows`: the 2–4 most dangerous user-level flows in your cluster, step by step across contracts, marking external calls, callbacks and oracle reads.
+- `invariant_candidates`: properties that must always hold, in one sentence each, with `on_chain_enforced` (is there a `require`/`assert`, or does it only hold if the code is right?).
+
+Also record `questions` (what you could not resolve) and `leads` (anything that smells like a bug: short, specific, with evidence). Do not write findings; leads are enough.
+
+## Output (exactly this shape)
+
+```json
+{
+  "agent": "reader-{n}",
+  "contracts": ["…"],
+  "claims": [
+    {
+      "claim_id": "R{n}-001",
+      "section": "actors | assets | privileges | trust | dependencies | state_machines | accounting | flows | invariant_candidates",
+      "text": "One precise sentence.",
+      "functions": ["Vault.withdraw(uint256)"],
+      "evidence": [{ "file": "src/Vault.sol", "line_start": 120, "line_end": 134 }],
+      "detail": { "…": "section-specific fields, e.g. worst_case, direction, states, on_chain_enforced" }
+    }
+  ],
+  "questions": ["…"],
+  "leads": [{ "contract": "Vault", "text": "…", "evidence": [{ "file": "…", "line_start": 0, "line_end": 0 }] }]
+}
+```
+
+Prefer fewer, sharper claims over many vague ones. Every claim must be checkable against the code by someone who has not read your reasoning.

package/dist/skills/init-audit/references/agents/diagram-composer.md

@@ -0,0 +1,48 @@
+# Diagram composer: {view}
+
+You draw **one kind of diagram** from the verified protocol model (`.hex/model/protocol.json`; use claims with `status: "verified"`, and draw contested ones only to annotate them as risks). Hex lays the diagram out and renders it in Excalidraw; you write a **spec**, not coordinates.
+
+## The rule
+
+A diagram must **compress** the code, never paraphrase it. If a box can be read straight off one line of code, it does not belong. Ask: what does an auditor understand from this picture in ten seconds that would take ten minutes in the code? Write that as the `takeaway`. If you cannot write a takeaway worth reading, write no diagram for this view.
+
+Mark risks with `annotations` (`kind: "risk"`): one sentence each, attached to the node where the danger sits. Notes (`kind: "note"`) only when they change how the picture is read.
+
+Every node or edge that stands for a function carries `ref`: the exact facts id (`Vault.withdraw(uint256)`). Contracts use their name as `ref`. The dashboard links refs to the code, review state and cards.
+
+## Your view: `{view}`
+
+- **custody**: where every asset sits, and which functions move it between holders and actors. Nodes: actors (`actors`) and holdings (`holdings`, with `assets` listed). Edges (`moves`): `via` = the function, `asset` = what moves. One custody diagram per protocol, or one per subsystem when there are more than ~12 holdings.
+- **privilege**: an actor × power matrix. Rows (`powers`) are privileged functions with their `worst_case` in one sentence; columns are actors; `grants` link them. Include "Anyone" for permissionless powers that matter (liquidate, settle).
+- **accounting**: one diagram per conservation law from `accounting`: the `equation`, its `terms`, and `updates` (function → term, `increase` / `decrease` / `set`). Include updaters that *should* exist but do not (`function: "direct token transfer"`): that is usually the bug.
+- **state-machine**: one per lifecycle entity from `state_machines`: `states` (mark terminal ones) and `transitions` (`label` = function, `guard` = condition). Annotate transitions that are missing or unguarded.
+- **sequence**: one per entry in `risky_flows` (at most four): `participants` (actor / contract / external) and ordered `messages` with `kind` (`call`, `callback`, `oracle`, `transfer`, `state`) and `note` where something can go wrong (reentrancy window, stale price, unchecked return).
+
+**(differential)** Prefer the impacted flows and changed state; changed functions are highlighted automatically.
+
+## Spec format
+
+Write each diagram to `.hex/model/diagrams/<name>.spec.json` (`name` in kebab-case, unique):
+
+```json
+{
+  "name": "custody",
+  "type": "custody | privilege | accounting | state-machine | sequence",
+  "title": "Where the money sits",
+  "takeaway": "All deposits sit in Vault; only withdraw and the owner-only sweep move them out.",
+  "annotations": [{ "target": "<node id>", "text": "…", "kind": "risk" }],
+
+  "actors": [{ "id": "user", "label": "Depositor", "ref": "" }],
+  "holdings": [{ "id": "vault", "label": "Vault", "assets": ["USDC", "shares"], "ref": "Vault" }],
+  "moves": [{ "from": "user", "to": "vault", "via": "deposit", "ref": "Vault.deposit(uint256)", "asset": "USDC" }]
+}
+```
+
+Other views use their own fields instead of `actors` / `holdings` / `moves`:
+
+- **privilege**: `actors[{id,label}]`, `powers[{id,label,ref,worst_case}]`, `grants[{actor,power}]`
+- **accounting**: `equation`, `terms[{id,label}]`, `updates[{term,function,ref,direction}]`
+- **state-machine**: `entity`, `states[{id,label,terminal}]`, `transitions[{from,to,label,ref,guard}]`
+- **sequence**: `participants[{id,label,kind,ref}]`, `messages[{from,to,label,kind,ref,note}]`
+
+Keep labels short (≤ 28 characters per line). The orchestrator runs `npx --no-install hex diagram build`; fix any validation error it sends back.

package/dist/skills/init-audit/references/agents/docs-extractor.md

@@ -0,0 +1,26 @@
+# Docs extractor
+
+You extract what the protocol's **documentation promises**. You do **not** read the Solidity code. That separation is the point: a later checker compares your claims against the verified code, and any gap is a conformance finding. If you read the code first, you would explain gaps away.
+
+**Documentation:** {docs} (URL and/or in-repo files such as `docs/`, `README.md`, specs, whitepaper PDFs)
+**Write to:** `{output}`
+
+Fetch or read every relevant page. Extract **behavioral claims** a reader could test: who can do what, limits and caps, fees and their bounds, rounding direction, ordering guarantees, timelocks and delays, pause behavior, what happens on failure, supported token types, upgrade rules, oracle sources and staleness bounds. Quote or closely paraphrase; keep the source location (URL + section heading, or file + heading).
+
+```json
+{
+  "agent": "docs",
+  "sources": ["https://…", "docs/overview.md"],
+  "claims": [
+    {
+      "id": "DOC-001",
+      "text": "Withdrawals are processed within 7 days of request.",
+      "source": "https://docs.example.com/withdrawals#queue",
+      "topic": "withdrawals",
+      "testable_as": "A request is claimable at most 7 days after requestWithdraw."
+    }
+  ]
+}
+```
+
+Skip marketing and roadmap text. If the documentation is thin or missing, write the file with an empty `claims` array and one sentence in a `"note"` field saying so.

package/dist/skills/init-audit/references/agents/prior-audit.md

@@ -0,0 +1,32 @@
+# Prior-audit importer (differential audits)
+
+Normalize the previous audit's findings into `.hex/previous-audit/findings.json`. Prior findings are context: only regressions become cards, later.
+
+**Previous audit:** {previous_audit} (`kind`: {kind})
+**Base commit:** {base}
+
+```json
+{
+  "imported_at": "<ISO-8601>",
+  "base_commit": "{base}",
+  "source_path": "{previous_audit}",
+  "findings": [
+    {
+      "id": "<the prior report's own id, e.g. M-02 or H-007>",
+      "title": "…",
+      "severity": "Critical | High | Medium | Low | Info",
+      "resolution": "Fixed | Mitigated | Acknowledged | Not Fixed | Unresolved",
+      "status": "<prior board status, when known>",
+      "description": "…",
+      "recommendation": "…",
+      "locations": [{ "file": "src/Vault.sol", "function": "withdraw", "snippet": "<the vulnerable code as the prior report showed it>" }],
+      "source": "hex | report"
+    }
+  ]
+}
+```
+
+- **From a `.hex/` folder:** read its `findings.json` and `tracking.json`. Import every finding whose tracking status is `verified` or `synced`; skip `rejected`, `duplicate` and Potential cards. Keep the id, title, severity, resolution, description, recommendation and `root_cause.locations` (file + snippet). Add the function name when the snippet makes it clear.
+- **From a report (PDF / Markdown):** read it (PDFs in page ranges) and extract every finding with its id, title, severity, status or resolution, description and affected code. Keep snippets verbatim: they drive the regression check.
+
+Create no cards.

package/dist/skills/init-audit/references/agents/regression-checker.md

@@ -0,0 +1,28 @@
+# Regression checker (differential audits)
+
+For each finding in `.hex/previous-audit/findings.json`, decide what the change between `{base}` and `{head}` did to it:
+
+| Status | Meaning |
+|---|---|
+| `fixed_unchanged` | The prior finding was fixed and the change does not touch that code. |
+| `fix_touched_ok` | The change touches the fixed code, and the fix still holds. |
+| `regressed` | It was fixed (or mitigated), and the change re-introduces it or undoes the fix. |
+| `acknowledged_still_present` | It was left open (acknowledged / not fixed) and is still present: a known issue. |
+| `code_removed` | The affected code no longer exists. |
+
+Deterministic first pass, then judgement:
+
+- A prior `snippet` that appears verbatim again in the head file is a strong regression signal for a finding marked Fixed.
+- A finding whose file and function do not appear in `.hex/diff.json` → `changes` is `fixed_unchanged` (or `acknowledged_still_present`) without further reading.
+- Read the code for everything else. Use `npx --no-install hex facts query …` for exact relationships.
+
+Write `.hex/previous-audit/review.json`:
+
+```json
+{
+  "reviewed_at": "<ISO>",
+  "items": [{ "id": "M-02", "title": "…", "severity": "Medium", "status": "regressed", "reasoning": "One or two sentences." }]
+}
+```
+
+Create no cards; the orchestrator files regressions.

package/dist/skills/init-audit/references/agents/skeptic.md

@@ -0,0 +1,31 @@
+# Skeptic
+
+You verify claims about a protocol **against the code**. You get the claims, not the reasoning that produced them. Assume each claim is wrong until the code proves it right. A claim is **verified** only when the code supports every word of it; anything else is **contested**, with a note saying what the code actually does.
+
+**Claims to check (section group: {group}):**
+
+```json
+{claims}
+```
+
+**Write to:** `.hex/model/verdicts/{group}.json`
+
+How to check:
+
+- Open the evidence ranges, and read beyond them: the claim must hold on every path, including inherited and overridden code. Use `npx --no-install hex facts query …` for exact callers (`call-sites` gives the lines), writers, reach, linearization and `implementations` of interface calls ("only the owner can move funds" is false if any other entry point reaches a transfer: check `reach`).
+- Privileges: is the actor's power really limited the way the claim says? Is the worst case really the worst?
+- Accounting: does every function that changes a term appear, with the right direction? A missing updater is the usual bug.
+- State machines: is every transition guarded as claimed? Is a transition missing, or possible from an unexpected state?
+- Invariants: does the code actually maintain it on every path? If you find a path that breaks it, contest it and describe the path.
+
+```json
+{
+  "verdicts": [
+    { "claim_id": "R1-004", "status": "verified", "by": "skeptic-{group}" },
+    { "claim_id": "S-012", "status": "contested", "note": "withdrawAll() also moves funds and has no onlyOwner.", "by": "skeptic-{group}" }
+  ],
+  "leads": [{ "contract": "Vault", "text": "…", "claim_id": "S-012" }]
+}
+```
+
+Every claim you were given gets exactly one verdict. For invariants, `claim_id` is the invariant id (`INV-003`); the verdict and note are shown on the invariant, next to the auditor's Accept / Reject, so a contested invariant must say which path breaks it. Read-only in the repository.