hex-audit 0.4.0

package/dist/skills/generate-overleaf.md

@@ -0,0 +1,326 @@
+---
+description: "Generate the four LaTeX section files for the final audit report (Overleaf-ready)"
+---
+
+# Skill: Generate Overleaf
+
+**Recommended model:** Sonnet
+
+This skill produces the four LaTeX section files an auditor uploads into the Nethermind Overleaf template at the end of an engagement. It runs after all findings have been verified or rejected on the dashboard's Issues board.
+
+## What it writes
+
+Four `.txt` files in `<output_dir>/overleaf/`:
+
+1. `executive_summary.txt` — `\section{Executive Summary}` body with project synopsis, severity histogram, status histogram, summary table of audit metadata.
+2. `audited_files.txt` — `\section{Audited Files}` body with a LaTeX table of in-scope files (LoC, comments, ratio, blank, total).
+3. `summary_of_findings.txt` — `\section{Summary of Issues}` body with hyperlinked finding rows.
+4. `findings.txt` — `\section{Issues}` body with one `\subsection{[Sev] title}\label{issue:N}` per verified finding, including description, code blocks, recommendation, status, client update.
+
+Output is plain `.txt` so the auditor pastes content into the matching Overleaf template slots. The skill does NOT compile LaTeX itself.
+
+## Phase 0 — Gather report metadata
+
+Read `<output_dir>/config.json`. Look under `settings.report.*` for:
+
+- `repository_url` — e.g. `https://github.com/mellow-finance/flexible-vaults`. Required for hyperref links in the audited files table and per-finding file links.
+- `initial_commit` — commit hash for the initial report scope.
+- `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`.
+- `doc_assessment` — `High` / `Medium` / `Low`.
+- `test_assessment` — `High` / `Medium` / `Low`.
+
+For each missing field, use **AskUserQuestion** to prompt the auditor. After collection, persist all values back to `config.json` under `settings.report.*` so re-runs don't re-prompt.
+
+If `repository_url` is not set, also offer to derive it from the project's git remote (`git -C <project_dir> remote get-url origin`).
+
+## Phase 1 — Compute the histograms and counts
+
+Read `<output_dir>/findings.json` and `<output_dir>/tracking.json`.
+
+**Verified findings** are findings whose tracking entry has `status: "verified"`. These are the ones that go in the report. Sort by severity (Critical → High → Medium → Low → Info), then by id within each severity.
+
+Severity histogram (count of verified findings per severity):
+```
+{ "Critical": N, "High": N, "Medium": N, "Low": N, "Undetermined": 0, "Info": N, "Best Practices": 0 }
+```
+(`Undetermined` and `Best Practices` are not currently in Hex's severity model — render them as 0 to match the Nethermind template.)
+
+Resolution histogram (count of verified findings per `resolution` field):
+```
+{ "Fixed": N, "Acknowledged": N, "Mitigated": N, "Not Fixed": 0, "Unresolved": N }
+```
+Findings without a `resolution` field count as `Unresolved`.
+
+## Phase 2 — Build the protocol synopsis paragraph
+
+Read `<output_dir>/overview.md`. Produce a roughly half-page (~120-180 words) plain-language summary of what the protocol does and the security-relevant mechanics. This becomes the second paragraph of `executive_summary.txt`. Match the tone of the Nethermind example:
+
+- Open with one sentence on the project's purpose and the in-scope contract(s).
+- Use a short `\begin{itemize}[leftmargin=*,itemsep=4pt] ... \end{itemize}` to list 2-3 of the security-relevant axes (e.g., access-control gates, asset-flow surfaces, upgradeability boundaries).
+- Close with one or two sentences on any notable edge cases the auditor wants to flag generally (an entry point that bypasses a typical gate, a non-obvious permission, etc.).
+
+Style hints:
+- Refer to contracts as `\texttt{ContractName}`, role constants as `\texttt{ROLE\_NAME}`, function names as `\texttt{name(...)}`.
+- Bold key terms with `\textbf{...}`.
+- No code blocks in this paragraph — those belong in the per-finding sections.
+
+## Phase 3 — Write `executive_summary.txt`
+
+```latex
+\pagebreak \vspace*{0cm}
+\sectioncolor
+\section{Executive Summary}
+\black
+This document presents the results of the security review conducted by \href{https://www.nethermind.io/smart-contract-audits}{Nethermind Security} for <PROJECT_NAME>'s <SCOPE_DESCRIPTION>.
+
+<AI-GENERATED PROTOCOL SYNOPSIS PARAGRAPH FROM PHASE 2>
+
+\textbf{The audit comprises <TOTAL_NSLOC>} lines of Solidity code. \textbf{The audit was performed using} (a)~manual analysis of the codebase, and (b)~automated analysis tools.
+
+\textbf{Along this document, we report} <ISSUE_COUNT_PHRASE>.
+%
+The issues are summarized in Fig.~1.
+
+\textbf{This document is organized as follows.}
+%
+{Section~2} presents the files in the scope.
+%
+{Section~3} presents the summary of issues.
+%
+{Section~4} presents the System Overview.
+%
+{Section~5} discusses the risk rating methodology.
+%
+{Section~6} details the issues.
+%
+{Section~7} discusses the documentation provided by the client for this audit.
+%
+{Section~8} presents the test suite evaluation and automated tools used.
+%
+{Section~9} concludes the document.
+\color{black}
+
+\begin{figure}[H]
+        \centering
+        \subfigure[]
+        {
+            \includegraphics[trim=0cm 0cm 0cm 0cm, clip=true, width=0.45\textwidth]{img/Severity.pdf}
+            \label{fig:severity}
+        }
+        \subfigure[]
+        {
+            \includegraphics[trim=0cm 0cm 0cm 0cm, clip=true, width=0.45\textwidth]{img/Status.pdf}
+            \label{fig:status}
+        }
+        \label{fig:trapezio}
+ \end{figure}
+\begin{center}
+    \begin{footnotesize}
+        \textbf{Fig.~1: Distribution of issues:} \textbf{Critical}~(<C>), \textbf{High}~(<H>), \textbf{Medium}~(<M>), \textbf{Low}~(<L>), \textbf{Undetermined}~(0), \textbf{Informational}~(<I>), \textbf{Best Practices}~(0).\\
+        \textbf{Distribution of status:} \textbf{Fixed}~(<F>), \textbf{Acknowledged}~(<A>), \textbf{Mitigated}~(<MI>), \textbf{Unresolved}~(<U>)
+    \end{footnotesize}
+\end{center}
+
+\color{black}
+
+\begin{longtable}[c]{ll}
+\caption*{\textbf{Summary of the Audit}} \\ \hline
+\textbf{Audit Type} & <AUDIT_TYPE> \\
+\textbf{Initial Report} & <INITIAL_REPORT_DATE> \\
+\textbf{Final Report} & <FINAL_REPORT_DATE> \\
+\textbf{Initial Commit}  & \href{<REPOSITORY_URL>/blob/<INITIAL_COMMIT>/<FIRST_SCOPE_FILE>}{<INITIAL_COMMIT_SHORT>} \\
+\textbf{Final Commit} & \href{<REPOSITORY_URL>/commit/<FINAL_COMMIT>}{<FINAL_COMMIT_SHORT>} \\
+\textbf{Documentation Assessment} & <DOC_ASSESSMENT> \\
+\textbf{Test Suite Assessment} & <TEST_ASSESSMENT> \\ \hline
+\end{longtable>
+\color{black}
+```
+
+Substitutions:
+- `<PROJECT_NAME>` ← `config.json.project.name`.
+- `<SCOPE_DESCRIPTION>` ← if a single in-scope file, `\texttt{<filename without extension>}` followed by a single-clause description from the overview; if many, `the contracts listed in Section~2`.
+- `<TOTAL_NSLOC>` ← `stats.json.totals.nsloc`.
+- `<ISSUE_COUNT_PHRASE>` ← something like "five points of attention, where one is classified as `\texttt{Low}`, and four are classified as `\texttt{Informational}` severity." Build dynamically from the severity histogram. If 0 verified findings: "no points of attention requiring remediation." If 1: "one point of attention, classified as `\texttt{<severity>}` severity." Pluralize properly.
+- `<C><H><M><L><I>` ← severity histogram counts.
+- `<F><A><MI><U>` ← resolution histogram counts.
+- `<INITIAL_COMMIT_SHORT>` ← first 7 chars of the commit hash.
+- `<FIRST_SCOPE_FILE>` ← relative path of the first file in `config.json.project.scope` (for the initial commit hyperref, which the template anchors to a specific file).
+
+## Phase 4 — Write `audited_files.txt`
+
+Compute per-file line counts from each scope file. For each in-scope file in `config.json.project.scope`:
+
+- Read the file. Count:
+  - `code` lines (non-blank, non-comment).
+  - `comments` (lines starting with `//` or `#`, or any line inside a `/* ... */` block).
+  - `blank` (empty after `.strip()`).
+  - `total` = sum of the three.
+- `ratio` = `round(comments * 100 / max(code, 1), 0)` followed by `\%`.
+
+Render the table:
+
+```latex
+\pagebreak \vspace*{0cm}
+%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
+%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
+\sectioncolor
+\section{Audited Files}
+\black
+%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
+%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
+
+\begin{table}[H]
+    \centering
+    \begin{footnotesize}
+    \begin{tabular}{|p{.5cm}|p{9cm}|p{1cm}|p{1.5cm}|p{1cm}|p{1cm}|p{1cm}|}
+        \hline
+        &\textbf{Contract} & \textbf{LoC} & \textbf{Comments} & \textbf{Ratio} & \textbf{Blank} & \textbf{Total} \\ \hline
+            <N> & \href{<REPOSITORY_URL>/blob/<INITIAL_COMMIT>/<FILE_PATH>}{ \texttt{<FILENAME>}} & <code> & <comments> & <ratio>\% & <blank> & <total> \\ \hline
+            ...
+&            \textbf{Total} &             \textbf{<sum-code>} &             \textbf{<sum-comments>} &             \textbf{<aggregate-ratio>\%} &             \textbf{<sum-blank>} &             \textbf{<sum-total>}            \\ \hline
+%%
+        \end{tabular}
+    \end{footnotesize}
+\end{table}
+```
+
+- `<FILENAME>` is the basename, LaTeX-escaped (no extension processing — show e.g., `ThreeFModule.sol`).
+- `<FILE_PATH>` is the path relative to the project root (`src/utils/ThreeFModule.sol`).
+- Number rows sequentially `1, 2, 3 ...`.
+- Aggregate ratio = `round(sum-comments * 100 / max(sum-code, 1), 0)`.
+
+## Phase 5 — Write `summary_of_findings.txt`
+
+For each verified finding in severity-sorted order (Critical → Info), assign a sequential `issue:N` label starting at `issue:0`. This same label is used in `findings.txt` for the `\hyperref`.
+
+```latex
+%\pagebreak \vspace*{0cm}
+
+%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
+%%%%%%%%%%%% H E A D E R 1 %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
+%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
+\sectioncolor
+\section{Summary of Issues}
+\black
+%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
+\begin{table}[H]
+    \centering
+    \begin{footnotesize}
+    \begin{tabular}{|p{1cm}|p{11cm}|p{2.1cm}|p{2.1cm}|}
+            \hline
+             & \textbf{Finding} & \textbf{Severity} & \textbf{Update} \\ \hline
+             <N>&\hyperref[issue:<I>]{<title-LaTeX-escaped>} &<Severity-display> & <Resolution-display>\\ \hline
+            %
+        \end{tabular}
+        \end{footnotesize}
+\end{table}
+```
+
+- `<N>` is the 1-based row counter.
+- `<I>` matches the `\label{issue:N}` index used in `findings.txt`.
+- `<Severity-display>` maps `Info` → `Info`, others use their name as-is.
+- `<Resolution-display>` maps the `resolution` field directly (`Fixed`, `Acknowledged`, `Mitigated`, `Not Fixed`); blank/`Unresolved` shows `Unresolved`.
+
+## Phase 6 — Write `findings.txt`
+
+For each verified finding in the same order (severity-sorted), render one subsection. Use the index `i` (0-based) matching `summary_of_findings.txt`.
+
+```latex
+\pagebreak \vspace*{0cm}
+
+\sectioncolor
+\section{Issues}
+\black
+%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
+
+<per-finding block>
+
+<per-finding block>
+
+...
+```
+
+Each per-finding block:
+
+```latex
+%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
+%%%%%%%%%%%% H E A D E R 3 %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
+%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
+\subsubsectioncolor
+\subsection{[<Severity-display>] <title-LaTeX-escaped>}\label{issue:<i>}
+\begin{footnotesize} \black
+
+ \textbf{File(s)}: \href{<REPOSITORY_URL>/blob/<INITIAL_COMMIT>/<FILE_PATH>}{ \texttt{<FILE_PATH>}}
+
+ \textbf{Description}: <description converted from markdown to LaTeX>
+
+<each code block from description rendered as \begin{minted}[linenos,firstnumber=1]{solidity} ... \end{minted}>
+
+ \textbf{Recommendation(s)}: <recommendation converted from markdown to LaTeX>
+
+ \textbf{Status}: <Resolution-display or "Unresolved">
+
+ \textbf{Update from the client}: <update_from_client, LaTeX-escaped>
+
+\end{footnotesize}
+
+```
+
+If the finding has multiple `root_cause.locations[]`, list them as `\href{...}{...}, \href{...}{...}` comma-separated.
+
+### Markdown → LaTeX conversion rules
+
+Apply to `description`, `recommendation`, and `update_from_client` (in that order, on non-code-block text only — first split out fenced code blocks, then convert the prose):
+
+| Markdown | LaTeX |
+|---|---|
+| `` `text` `` | ` \texttt{text}` (leading space intentional, matches Nethermind template) |
+| `**text**` | ` \textbf{text}` |
+| `[label](url)` | ` \href{url}{label}` — if `label` contains `#`, replace with `/#` (anchors break in LaTeX otherwise) |
+| `_` (literal underscore in prose) | `\_` |
+| `^` | `\^{}` |
+| `%` (only when no `](` was present on the line — to avoid mangling URLs) | `\%` |
+| Numbered list `1. text` | `\begin{enumerate}\n \def\labelenumi{\arabic{enumi}.} \tightlist\n\item text;\n...\end{enumerate}` |
+| Bulleted list `- text` | `\begin{itemize}\n\tightlist\n\item text;\n...\end{itemize}` |
+| Fenced code block ` ```solidity ` | `\begin{minted}[linenos,firstnumber=1]{solidity}` ... `\end{minted}` — also support `python`, `typescript`, `javascript`, `cairo` (use `python` lexer), `diff`, `shell`, `rust` |
+
+End list items with `;` (replace trailing `.` with `;`). Last item still ends with `;`.
+
+The markdown-to-LaTeX logic matches the spirit of the Python script `create-section-findings.py` referenced by the auditor — port that semantically into the skill's instructions rather than calling it.
+
+### Severity-display mapping
+- `Critical` → `Critical`
+- `High` → `High`
+- `Medium` → `Medium`
+- `Low` → `Low`
+- `Info` → `Info` (the Nethermind template uses `Info` in the subsection headers and `Informational` in the histogram caption)
+
+## Phase 7 — Final report
+
+After writing all four files, print:
+
+```
+Wrote 4 LaTeX section files to <output_dir>/overleaf/:
+  - executive_summary.txt     (<N> bytes)
+  - audited_files.txt          (<N> bytes)
+  - summary_of_findings.txt    (<N> bytes)
+  - findings.txt               (<N> bytes)
+
+Verified findings included: <count>
+  Critical=<C> High=<H> Medium=<M> Low=<L> Info=<I>
+
+Status distribution:
+  Fixed=<F> Acknowledged=<A> Mitigated=<MI> Unresolved=<U>
+
+Upload these into your Overleaf project's Section 1 / 2 / 3 / 6 slots respectively.
+```
+
+## What this skill does NOT do
+
+- Does not compile LaTeX (no `pdflatex` invocation).
+- Does not modify any file outside `<output_dir>/overleaf/` and (with permission) `config.json` under `settings.report.*`.
+- Does not push to Overleaf, GitHub, or any remote — output is local plain-text.
+- Does not include `rejected`, `duplicate`, `pending_validation`, or `unverified` findings. Only `verified` makes the cut.

package/dist/skills/generate-poc.md

@@ -0,0 +1,186 @@
+---
+description: "Validate an issue and generate a proof-of-concept test"
+---
+
+# Skill: Generate Proof of Concept
+
+**Recommended model:** Opus
+
+## Context Assembly
+
+Read:
+- The issue description provided by the auditor
+- Run: `npx hex context --target <relevant_contract>` for focused context
+- `<output_dir>/state-vars.json` — for relevant state variable info
+- `<output_dir>/access-control.json` — for access restrictions
+- `<output_dir>/external-calls.json` — for external call surface (if relevant)
+
+## Step 0: Understand the Project's Test Infrastructure
+
+**CRITICAL: You MUST complete Step 0 before writing any test code.** Do not proceed to Step 2 until you have identified the base test contract (if any), the deployment fixture/setup, and how tokens are dealt and accounts impersonated. Failure to reuse existing test infrastructure is the #1 cause of PoC failures.
+
+Before writing any test code, inspect the project's existing test setup:
+
+1. Look at the test directory structure (`test/`, `tests/`, etc.)
+2. Read 2-3 existing test files to understand:
+   - Which test framework is used (Foundry, Hardhat/Mocha, Brownie, etc.)
+   - How contracts are deployed in tests (direct deploy, factory, fork, etc.)
+   - Existing base test contracts or test helpers (e.g., `BaseTest.sol`, `TestSetup.sol`)
+   - How tokens are dealt, accounts are impersonated, etc.
+   - Fork configuration (RPC URL, block number) if applicable
+3. Read the project config (`foundry.toml`, `hardhat.config.ts`, etc.) for test settings
+
+**CRITICAL:** Reuse existing test infrastructure. If the project has a `BaseTest.sol` that deploys the full system, inherit from it. Do NOT recreate deployment logic that already exists.
+
+## Step 1: Validate by Reasoning
+
+Before writing any code, reason through:
+
+1. **Is this actually exploitable?** Trace the exact execution path step by step.
+2. **What are the preconditions?** What state must the system be in? What does the attacker need?
+3. **What would the impact be?** Quantify if possible (fund loss amount, DoS duration, etc.)
+4. **Are there existing protections?** Check for:
+   - Reentrancy guards
+   - Access control that prevents the attack path
+   - Input validation that blocks required preconditions
+   - Economic constraints that make the attack unprofitable
+
+If you conclude the issue is **NOT valid**, explain why clearly and stop. Still write the validation memo.
+
+## Step 2: Write PoC (only if Step 1 validates)
+
+### Foundry Project
+```solidity
+// SPDX-License-Identifier: MIT
+pragma solidity ^0.8.20;
+
+import {BaseTest} from "../BaseTest.sol";  // or whatever the project uses
+
+contract F001_Description_PoC is BaseTest {
+    function setUp() public override {
+        super.setUp();
+        // Only add PoC-specific setup here
+    }
+
+    function test_poc_description() public {
+        // Step 1: Set up initial state
+        // Step 2: Execute attack
+        // Step 3: Assert impact
+    }
+}
+```
+
+### Hardhat/TypeScript Project
+```typescript
+import { expect } from "chai";
+import { loadFixture } from "@nomicfoundation/hardhat-network-helpers";
+import { deployFixture } from "../helpers/deploy";
+
+describe("F001 - Description", function () {
+  it("should demonstrate the vulnerability", async function () {
+    // Reuse project fixtures
+    // Step-by-step attack
+    // Assert impact
+  });
+});
+```
+
+Requirements:
+- Match the project's coding style and conventions
+- Inherit from / reuse existing test base contracts or fixtures
+- Add descriptive comments for each step
+- End with clear assertions that demonstrate the impact
+- Name the file: `test/hex-pocs/<finding_id>_<short_name>.t.sol` (Foundry) or `test/hex-pocs/<finding_id>_<short_name>.test.ts` (Hardhat)
+- Create the `test/hex-pocs/` directory if it doesn't exist
+
+### Economic Impact Logging (REQUIRED)
+
+Every PoC MUST log economic impact with before/after balance snapshots:
+
+```solidity
+// Before exploit
+uint256 attackerBalanceBefore = token.balanceOf(attacker);
+uint256 victimBalanceBefore = token.balanceOf(address(vault));
+
+// ... execute exploit steps ...
+
+// After exploit
+uint256 attackerBalanceAfter = token.balanceOf(attacker);
+uint256 profit = attackerBalanceAfter - attackerBalanceBefore;
+uint256 victimLoss = victimBalanceBefore - token.balanceOf(address(vault));
+
+console.log("Attacker profit: %s tokens (%s decimals)", profit, token.decimals());
+console.log("Victim loss: %s tokens", victimLoss);
+// If price oracle available in tests:
+// uint256 priceUsd = oracle.latestAnswer();
+// console.log("Profit in USD: $%s", (profit * priceUsd) / (10 ** token.decimals()));
+```
+
+### Descriptive Assertions
+
+Use assertion messages that explain the exploit impact, not just pass/fail:
+
+```solidity
+assertGt(attackerBalanceAfter, attackerBalanceBefore, "Exploit should be profitable for attacker");
+assertLt(token.balanceOf(address(vault)), victimBalanceBefore, "Vault should have lost funds");
+assertEq(profit, victimLoss, "Attacker profit should equal vault loss (no external source)");
+```
+
+### Rounding Error PoCs
+
+For rounding/precision vulnerabilities, demonstrate BOTH per-transaction and cumulative impact:
+
+```solidity
+// Per-transaction loss
+uint256 before = token.balanceOf(address(vault));
+// ... single operation ...
+uint256 singleLoss = before - token.balanceOf(address(vault));
+console.log("Loss per transaction: %s wei", singleLoss);
+
+// Cumulative impact over realistic timeframe
+uint256 cumulativeLoss = 0;
+for (uint256 i = 0; i < 1000; i++) {
+    uint256 b = token.balanceOf(address(vault));
+    // ... repeat operation ...
+    cumulativeLoss += b - token.balanceOf(address(vault));
+}
+console.log("Cumulative loss over 1000 transactions: %s tokens", cumulativeLoss);
+console.log("Average loss per transaction: %s wei", cumulativeLoss / 1000);
+```
+
+This pattern is critical for rounding bugs where per-transaction loss seems negligible but compounds to significant value over time.
+
+## Step 3: Run and Verify
+
+Run the test:
+- Foundry: `forge test --match-test test_poc_description -vvv`
+- Hardhat: `npx hardhat test test/hex-pocs/<file> --grep "poc_description"`
+
+If it fails, debug and fix. Iterate until the PoC passes.
+
+## Output
+
+**Always produce a validation memo** at `<output_dir>/validations/<finding_id_or_short_name>_memo.md`:
+
+```markdown
+# Validation Memo: <Title>
+
+**Verdict:** Valid / Invalid / Uncertain
+**Date:** <YYYY-MM-DD>
+
+## Reasoning
+[Step-by-step reasoning from Step 1]
+
+## Execution Path
+[Traced call path: function1() -> function2() -> ...]
+
+## Protections Considered
+[Existing guards, checks, or mitigations evaluated and why they don't prevent the issue]
+
+## Conclusion
+[If valid: summary of exploit + pointer to PoC file]
+[If invalid: clear explanation of why not exploitable]
+[If uncertain: specific questions for manual investigation]
+```
+
+If valid, also write the test file to the project's test directory.

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

@@ -0,0 +1,172 @@
+---
+description: "Ingest a completed Nethermind AuditAgent scan into the board and dedup against existing issues"
+---
+
+# 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.
+
+## When to use
+
+After you have a scan ID for a completed (or running) AuditAgent scan and want its findings on the dashboard's Issues board. Typical sequence:
+
+1. Auditor starts a scan elsewhere: `aa scan --quality auditor <files>`, copies the scan ID printed by the CLI.
+2. Auditor invokes `/ingest-aa-report` with that ID.
+
+## Step 1 — Resolve the scan ID
+
+Try in order:
+
+1. The free-text argument passed with the invocation (e.g., `/ingest-aa-report abc123def`).
+2. `settings.ai.auditagent_scan_id` in `<output_dir>/config.json`.
+3. **Ask the auditor** via AskUserQuestion: "Paste the AuditAgent scan ID, or type `cancel` to stop."
+
+When a scan ID is resolved, persist it to `config.json` under `settings.ai.auditagent_scan_id` (so re-runs work without re-asking) and to `<output_dir>/ai-status.json` under `tools.auditagent.scan_id` (so `hex ai-status --watch` can poll it).
+
+## Step 2 — Check scan status
+
+Run:
+
+```bash
+aa scan --status <scan_id>
+```
+
+Interpret the output:
+
+- Status indicates **pending / running / in progress** → print `Scan <scan_id> is still <status>. Come back once it completes — you can run \`hex ai-status --watch\` in another terminal to be notified.` Update `ai-status.json` with `status: "pending_scan"`. **Exit cleanly** — do NOT block.
+- Status indicates **failed** or `aa` exits non-zero → print the error, update `ai-status.json` with `status: "failed"` and `error: <message>`. Exit non-zero.
+- Status indicates **completed** → continue to Step 3.
+
+Never invoke `aa scan` to start a new scan. If the auditor has no scan ID, instruct them to start one externally.
+
+## Step 3 — Fetch findings
+
+Run:
+
+```bash
+aa scan --report <scan_id>
+```
+
+(Or the equivalent results-fetch command exposed by the installed `aa` version — check `aa scan --help` if `--report` is not supported.)
+
+Capture the raw output to `<output_dir>/ai-results/auditagent/raw-output.md`.
+
+## Step 4 — Normalize into findings.json
+
+Parse the AuditAgent output (markdown with severity-tagged sections per finding) and convert each finding into the schema:
+
+```json
+{
+  "id": "AA-<NNN>",
+  "tool": "auditagent",
+  "title": "<finding title>",
+  "severity": "Critical | High | Medium | Low | Info",
+  "description": "<full description from the report>",
+  "affected_code": [
+    { "file": "<path>", "snippet": "<relevant code if present>" }
+  ],
+  "confidence": "high | medium | low",
+  "category": "<auditor-style category, e.g., Access Control, Math/Rounding>",
+  "raw_category": "<the raw category string from auditagent, preserved verbatim>"
+}
+```
+
+Write the full array under:
+
+```json
+{
+  "tool": "auditagent",
+  "ran_at": "<ISO timestamp of this ingest>",
+  "duration_seconds": null,
+  "total_findings": <count>,
+  "findings": [ ... ]
+}
+```
+
+to `<output_dir>/ai-results/auditagent/findings.json`. Also write a small `metadata.json` next to it:
+
+```json
+{
+  "scan_id": "<scan_id>",
+  "ingested_at": "<ISO>",
+  "report_status": "completed",
+  "total_findings": <count>
+}
+```
+
+## Step 5 — Materialize tracking entries
+
+For each AuditAgent finding, append (or update if id already exists) a tracking entry in `<output_dir>/tracking.json`:
+
+```json
+{
+  "id": "AA-<NNN>",
+  "title": "<title>",
+  "severity": "<severity>",
+  "source": "auditagent",
+  "status": "unverified",
+  "poc_status": "not_started",
+  "poc_file": null,
+  "duplicates": [],
+  "notes": "scan_id=<scan_id>"
+}
+```
+
+These appear on the board as Potential cards.
+
+## Step 6 — Inline dedup
+
+Read all existing tracking entries (manual, conformance, github, and any previously ingested auditagent runs). For each **new** auditagent entry, 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, **flip the new auditagent entry** to `status: "duplicate"` (the canonical is the existing entry — the auditor already filed or already has it from another source) and set `duplicate_of: "<existing-entry-id>"`. Append to `<output_dir>/comparison.json` under `duplicates`:
+
+```json
+{
+  "ai_finding": "AA-<NNN>",
+  "matches": "<existing-entry-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>"
+}
+```
+
+If `comparison.json` doesn't exist, create it with `{ "duplicates": [], "novel": [], "rejected": [] }`.
+
+For entries that don't match anything, leave them as `status: "unverified"` (the auditor will run `/validate-issue AA-<NNN>` on them).
+
+## Step 7 — Report
+
+Print a one-paragraph summary:
+
+```
+Ingested N AuditAgent findings (scan <scan_id>).
+- M new on the Potential column
+- K flagged as Duplicate of existing entries
+- 0 errors
+
+Run /validate-issue <id> on any new finding to confirm and promote it to Verified.
+```
+
+## Outputs (recap)
+
+- `<output_dir>/ai-results/auditagent/raw-output.md`
+- `<output_dir>/ai-results/auditagent/findings.json`
+- `<output_dir>/ai-results/auditagent/metadata.json`
+- `<output_dir>/ai-status.json` (updated)
+- `<output_dir>/tracking.json` (appended)
+- `<output_dir>/comparison.json` (appended)
+- `<output_dir>/config.json` — `settings.ai.auditagent_scan_id` persisted if new