hex-audit 0.7.0 → 0.8.0

package/dist/skills/ai-audit/references/hex-board.md

@@ -12,7 +12,7 @@ The report Turn 5 printed is not touched. The board copy is a **rewrite** of eac
 Hex's report standard, because the board's text ends up verbatim in the client's report.
 
 **Never** hand-edit `.hex/tracking.json` or `.hex/findings.json` — cards go through
-`npx hex issue`, leads through `npx hex note lead`. **Never** move a card to Verified, and never
+`npx --no-install hex issue`, leads through `npx --no-install hex note lead`. **Never** move a card to Verified, and never
 run `/validate-finding` or `/sync-issues` from here: those are the auditor's calls.
 
 ---
@@ -46,42 +46,25 @@ Read, in one parallel message:
 
 ## Step 3 — Triage each FINDING
 
+Also read the triage rules once: `npx --no-install hex rules list`.
+
 Go through the digest's FINDINGs in order. For each one decide **exactly one** outcome:
 
 1. **already on board** — its key is in the set above. Skip it. Do not update that card: the
    auditor may have edited, validated or rejected it, and a re-scan does not overrule them.
-2. **known from the prior audit** — differential audit only. It matches a prior finding (match
-   rules below) that the prior audit left open: `review.json` status
-   `acknowledged_still_present`, or a prior `resolution` of `Acknowledged`, `Unresolved` or
-   `Not Fixed`. Skip it; the client already knows. A match to a prior finding that was **fixed**
-   is not "known" — that is a regression, and it is filed (outcome 4, or 3 if `/init-audit`
-   already carded the regression).
-3. **duplicate** — it matches an existing card from any other source, or an `ai-audit` card with
-   a different key. It is filed, then moved to the Duplicate column (Step 5).
-4. **new** — none of the above. It is filed.
-
-### Match rules (the same rules `/ingest-aa-report` uses)
-
-Compare the finding against each candidate on four signals:
-
-| 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. |
-| **attack_vector** | `same` / `overlapping` / `different` — judge what an attacker actually does. |
-
-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`.
-
-When several cards match, the canonical one is the earliest-created card that is not itself in
-the Duplicate column.
+2. **excluded by a triage rule** — the finding's whole impact depends on a rule (a trusted role,
+   an out-of-scope token type, a known issue). Skip it and list it in the summary with the rule
+   id. A finding a rule only partly covers is filed.
+3. **known from the prior audit** — differential audit only. It is the same issue as a prior
+   finding the prior audit left open: `review.json` status `acknowledged_still_present`, or a
+   prior `resolution` of `Acknowledged`, `Unresolved` or `Not Fixed`. Skip it; the client already
+   knows. A match to a prior finding that was **fixed** is a regression, and it is filed.
+4. **file it** — everything else. Whether it duplicates an existing card is decided after
+   filing, by the dedup engine (Step 5).
 
 ## Step 4 — Write the raw records
 
-For every finding that is **new** or a **duplicate**, read the code at its location
+For every finding you **file**, read the code at its location
 (`Contract.function` — find the contract's file in the scope, then read the function), and write
 one record. Ids continue from the highest `AI-NNN` already in the file (`AI-001` when empty).
 
@@ -110,7 +93,7 @@ Write the whole file once with the Write tool, keeping every earlier record:
 
 This file is the source record behind the cards (as `ai-results/auditagent/findings.json` is for
 AuditAgent); `hex issue new` materializes each card from it. Writing it directly is correct.
-Skipped findings (already on board, known from the prior audit) get **no** record.
+Skipped findings (already on board, excluded by a rule, known from the prior audit) get **no** record.
 
 ### Field rules
 
@@ -164,29 +147,26 @@ code-block rules as above). This is what fills the card's File(s) line and the r
 For each record, in id order:
 
 ```bash
-npx hex issue new --source ai-audit --source-ref AI-NNN --title "<title>" --severity <Severity>
+npx --no-install hex issue new --source ai-audit --source-ref AI-NNN --title "<title>" --severity <Severity>
 ```
 
 It prints the allocated `H-NNN`; capture it. The card lands in Potential as `unverified`, with
 description, recommendation and code materialized from the record.
 
-For each **duplicate**, move it and record why:
+Then run the dedup engine on each new card:
 
 ```bash
-npx hex issue move <new H-NNN> --to duplicate --duplicate-of <canonical H-NNN>
+npx --no-install hex issue dedup <new H-NNN>
 ```
 
-Then append to `.hex/comparison.json` → `duplicates` (create the file as
-`{ "duplicates": [], "novel": [], "rejected": [] }` if it does not exist):
+It lists existing cards on the same exact functions first and prints the match rules (the same
+rules every source uses). Judge each strong candidate against those rules. On a match (the
+canonical card is the earliest-created one that is not itself a duplicate):
 
-```json
-{
-  "ai_finding": "<new H-NNN>",
-  "matches": "<canonical H-NNN>",
-  "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-NNN> --of <canonical H-NNN> \
+  --root-cause <same|overlapping|different> --attack-vector <same|overlapping|different> \
+  [--same-contract] [--same-function] --reasoning "<one short sentence>"
 ```
 
 ## Step 6 — Leads to notes
@@ -195,7 +175,7 @@ For each LEAD in the digest, add it to the contract's note. `<Contract>` is the
 location before the first `.`:
 
 ```bash
-npx hex note lead "<Contract>" \
+npx --no-install hex note lead "<Contract>" \
   --text "<title> (\`Contract.function\`): <the lead's body, one line>" \
   --source ai-audit --source-ref "<key>"
 ```
@@ -204,7 +184,14 @@ The command is idempotent on the key: a lead already added by an earlier scan (o
 dismissed) is left as it is, and the command says so on stderr. Open leads keep the contract
 unreviewed on `/progress` until the auditor closes them — that is intended.
 
-## Step 7 — Summary
+## Step 7 — Pre-validate
+
+Run the **`/prevalidate`** skill on the cards this scan filed that are not duplicates. Background
+agents reproduce or refute each one; conclusive cases move on their own (reproduced with a passing
+PoC → Verified; refuted by two independent agents → Rejected), the rest stay in Potential with a
+verdict. Skip this step only when the auditor passed `--no-prevalidate`.
+
+## Step 8 — Summary
 
 Print, and nothing else:
 
@@ -213,6 +200,7 @@ Hex board — scan {stamp}
 - N new Potential card(s): H-0xx, H-0yy, ...
 - K marked Duplicate of existing cards
 - J already on the board from an earlier scan (not re-filed)
+- E excluded by triage rules (R-…)
 - P known from the prior audit (not filed)
 - L lead(s) added to contract notes (M already there)
 Report: .hex/ai-audit/runs/{stamp}/full-report.md

package/dist/skills/diane.md

@@ -4,9 +4,8 @@ description: "Diane — your audit recorder. Ingest voice narration into a livin
 
 # Skill: Diane
 
-**Recommended model:** Sonnet
 
-You are **Diane**, the auditor's **pair auditor** — the Twin Peaks framing: the auditor narrates their thought process aloud while reading a contract, and you are Diane, a sharp second set of eyes who organizes their reasoning into a living profile **and audits alongside them**. You don't just record — you read the code, check what they claim, and speak up. The auditor records narration from the dashboard **Notes** tab (Record button + contract dropdown); the recording is transcribed locally and lands as a *session*. This skill picks up that session and processes it.
+You are **Diane**, the auditor's **pair auditor** — the Twin Peaks framing: the auditor narrates their thought process aloud while reading a contract, and you are Diane, a sharp second set of eyes who organizes their reasoning into a living profile **and audits alongside them**. You don't just record — you read the code, check what they claim, and speak up. The auditor records narration from the dashboard's **Review** page (the *Record narration* button; the selected function's contract is the active contract); the recording is transcribed locally and lands as a *session*. This skill picks up that session and processes it.
 
 Persona: attentive, candid, direct. Be concise. Confirm briefly when the auditor is right; push back with `file:line` evidence when they're wrong or have missed something. Never flatter, never challenge without grounds, never narrate your own process at length. **Address the auditor directly and impersonally — never by name.**
 
@@ -21,22 +20,23 @@ Persona: attentive, candid, direct. Be concise. Confirm briefly when the auditor
 ## Step 1 — Pick up the latest narration
 
 ```bash
-npx hex note session latest
+npx --no-install hex note session latest
 ```
 
 This prints JSON: `{ file, contract, ts, processed, text }` for the most recent unprocessed session, or `null`. If `null`, tell the auditor there's nothing new to process and stop. Otherwise:
 
-- `contract` is the **active contract** the notes belong under (the dropdown selection). `general` means cross-cutting.
+- `contract` is the **active contract** the notes belong under (the contract selected on the Review page). `general` means cross-cutting.
 - `text` is the raw transcript — disfluent, with filler, repetition, and false starts. That's expected.
 
 ## Step 2 — Segment the transcript into thought-units
 
 Read `text` and split it into discrete thoughts. For each, classify it as a **trigger** or a **note**:
 
-- A **trigger** is an explicit instruction to you. Recognize these three (match intent, not exact words):
+- A **trigger** is an explicit instruction to you. Recognize these four (match intent, not exact words):
   - **create a finding** — "this is a bug", "write a finding", "flag this", "log an issue".
   - **answer a question** — "how is this encoded?", "is this reachable?", "where is X set?", "what calls this?".
   - **search online** — "look up EIP-x", "search for the spec", "find the reference for…".
+  - **review progress** — the auditor says where they are with a function or contract: "done with `withdraw`", "`deposit` is fine / clean / checked", "I've read through `setFee` but want to come back", "I'm not sure about `liquidate`, question there", "finished the Vault contract".
 - Everything else is a **note**: observations, hypotheses, things to revisit.
 
 When a unit is ambiguous, treat it as a note (the safe default — nothing is lost, and the auditor can re-narrate a real instruction).
@@ -62,6 +62,17 @@ All three edit the same structured record; Step 5 covers the read-merge-write me
 
 **search online** → use WebSearch, read the most relevant result, and fold it where it belongs — a question's `answer`, a `description` field, or a `leads` entry — with the source link.
 
+**review progress** → tick the review map (the dashboard's Review page) for exactly what the auditor said, never more:
+
+| The auditor says | State | Command |
+|---|---|---|
+| done / clean / checked / no issues with `fn` | `cleared` | `npx --no-install hex review mark <Contract.fn> --state cleared --by diane` |
+| read it but will come back / skimmed it | `read` | `… --state read --by diane` |
+| unsure / has a question / something smells | `questioned` | `… --state questioned --by diane --note "<the question, one line>"` |
+| finished the whole contract | every function | `npx --no-install hex review mark <Contract> --state cleared --by diane` |
+
+Resolve the function to its exact id first (`npx --no-install hex facts query function <name>`; with overloads, pick the one the narration is about, or mark all of them when it is clearly the whole name). **Never tick on inference.** A function the auditor merely discussed stays as it is; only an explicit statement of where they are moves it. When the Step-3 verification found a correction or a missed issue in a function the auditor called done, mark it `questioned` instead and say why in the verdict.
+
 ## Step 5 — Update the contract profile
 
 A contract's notes are a **structured record** you grow over time — not per-session blocks. Each run: read the current record, merge this session **and your Step 3 verification** into it, write it back. Clean up filler/repetition; keep the reasoning, not the disfluency.
@@ -79,6 +90,7 @@ The record (JSON):
     "roles": ["`onlyOwner` — gates setFee / setOwner"],
     "functions": [
       {
+        "fn_ref": "Vault.deposit(uint256,address)",
         "sig": "deposit(assets, receiver) — external",
         "purpose": "pull assets, mint shares",
         "access": "anyone",
@@ -97,32 +109,34 @@ The record (JSON):
 }
 ```
 
-- **description** = how the contract works (verified truth), top-to-bottom: `purpose`, `inheritance`, `storage`, `roles`, then `functions` in **source order** (each with Purpose / Access / Effects + `notes`). Step-3 corrections go in that function's `warnings`, with `file:line`.
+- **description** = how the contract works (verified truth), top-to-bottom: `purpose`, `inheritance`, `storage`, `roles`, then `functions` in **source order** (each with Purpose / Access / Effects + `notes`). Step-3 corrections go in that function's `warnings`, with `file:line`. Every function entry carries `fn_ref`, its exact facts id (`npx --no-install hex facts query function <name>`), so notes, review state and cards line up on the dashboard even for overloads.
 - **questions** = your Q&A; an entry with no `answer` is still open.
 - **leads** = things worth investigating (the Step-3 misses/angles). Only `status:"open"` leads show in the dashboard; `logged` (→ finding) and `dismissed` are kept but hidden.
 
 Merge mechanics — read the record, edit JSON, write it back:
 
-1. `npx hex note show "<contract>" > /tmp/diane_<ts>.json` — prints an empty skeleton on first run.
+1. `npx --no-install hex note show "<contract>" > /tmp/diane_<ts>.json` — prints an empty skeleton on first run. Also read the auditor's code comments on that contract's file (`npx --no-install hex note comments <file>`): they are written on specific lines in the dashboard and are part of what the auditor said. Fold them into the note where they belong; never delete or rewrite them.
 2. Edit `/tmp/diane_<ts>.json`: add or refine entries where they belong (fill a storage row, flesh out a function, set a question's `answer`, add a lead, attach a `warning`). **Preserve existing `id`s, don't duplicate** — sharpen what's there. Keep arrays concise.
-3. `npx hex note set "<contract>" --json-file /tmp/diane_<ts>.json` (this also recomputes the `/progress` review state).
+3. `npx --no-install hex note set "<contract>" --json-file /tmp/diane_<ts>.json` (this also recomputes the `/progress` review state).
 
-`<contract>` is the session's `contract` value verbatim (e.g. `Vault.sol`). Cross-cutting remarks still go to the free-form `general` markdown note: `npx hex note append general --body-file …` (`general` isn't structured). If the auditor says they're done with a contract, run `npx hex note done "<contract>"`.
+`<contract>` is the session's `contract` value verbatim (e.g. `Vault.sol`). Cross-cutting remarks still go to the free-form `general` markdown note: `npx --no-install hex note append general --body-file …` (`general` isn't structured). If the auditor says they're done with a contract, run `npx --no-install hex note done "<contract>"`.
 
 ## Step 6 — Close the loop & deliver the verdict
 
 Mark the session processed so it isn't ingested again:
 
 ```bash
-npx hex note session mark-processed "<file>"
+npx --no-install hex note session mark-processed "<file>"
 ```
 
 Then deliver a candid **pair-audit verdict** — lead with the substance (corrections, misses, what holds up), then the housekeeping. Cite `file:line`. Don't manufacture pushback when the narration is sound — confirming is a valid verdict. Address the auditor directly, never by name. Example:
 
-> "Two corrections: previewWithdraw rounds **up**, not down (Vault.sol:88); and `setFee` has no upper bound (Vault.sol:120), which you didn't flag — added as a lead. Your reentrancy read on `deposit` checks out. Profile updated, session marked processed."
+> "Two corrections: previewWithdraw rounds **up**, not down (Vault.sol:88); and `setFee` has no upper bound (Vault.sol:120), which you didn't flag — added as a lead. Your reentrancy read on `deposit` checks out. Ticked `deposit` as cleared; left `setFee` as questioned because of the missing bound. Profile updated, session marked processed."
+
+Always end the verdict with the review ticks you made (function → state), or "no review changes" when there were none.
 
 ## Notes
 
-- **Never hand-edit** `notes.json` or the `.md` files directly — always go through `npx hex note …`, exactly as the other skills route through `npx hex issue …`.
+- **Never hand-edit** `notes.json` or the `.md` files directly — always go through `npx --no-install hex note …`, exactly as the other skills route through `npx --no-install hex issue …`.
 - One session per invocation. If the auditor wants the next one, they run `/diane` again (or process them in a loop if they ask).
 - Do not create PoCs from narration — that stays an explicit, auditor-driven `/validate-finding` step.

package/dist/skills/fix-review.md

@@ -0,0 +1,58 @@
+---
+description: 'Fix review: map the client''s fix commits to findings, re-run each PoC at the fix commit, review unmapped changes, then update Status and "Update from the client" on GitHub after one confirmation'
+---
+
+# Skill: Fix Review
+
+After the client fixes the reported issues, decide for each one whether it is fixed, and review any code the fixes changed that no finding explains. Evidence first: a PoC that reproduced the issue at the audited commit and **fails** at the fix commit is the strongest proof of a fix.
+
+Use `npx --no-install hex …` for every Hex command.
+
+## Step 1 — Inputs
+
+Ask for the **fix commit** (default `HEAD`; it must exist locally, so `git fetch` first) and confirm the **audited commit** (default: `settings.report.initial_commit`, else `project.commit` in `.hex/config.json`). If the audit's cards are synced to GitHub, `settings.github.repo` must be set.
+
+## Step 2 — Deterministic pass
+
+```bash
+npx --no-install hex fix-review --from <audited> --to <fix>
+```
+
+It diffs the two commits on compiler facts (exact changed functions and storage layout) and maps changes and commit messages (`H-012`, `#12`) to every Verified or Synced card. It re-runs each card's PoC (`test/hex-pocs/…`) at the fix commit in a throwaway worktree, then writes `.hex/fix-review/<fix-sha>.json`, with per card `status` (`fixed` / `not_fixed` / `unknown` / `unaddressed`), evidence, PoC before/after, the changed functions and commits, plus `unmapped_changes`.
+
+## Step 3 — Judgement where the evidence is not conclusive
+
+For every card with status `unknown`, and every `fixed` card whose evidence is "code removed", spawn a background agent (one per card, up to 6 at a time) with:
+
+> Card **{id}** (`npx --no-install hex issue show {id}`) was reported at {audited}. Decide whether commit range {audited}..{fix} fixes it. Read the original finding and the diff of the functions it touches (`git diff {audited} {fix} -- <files>`). If a PoC exists but no longer compiles, adapt it minimally to the new API and run it at the fix commit in a scratch worktree, not in the auditor's checkout. Decide: `fixed`, `partially_fixed` (say what remains) or `not_fixed`. Draft the "Update from the client" text: what changed, in which commit, and why that resolves (or does not resolve) the issue, in two sentences at most, plain prose, no line numbers. Then run:
+> `npx --no-install hex fix-review propose {fix} {id} --status <status> --resolution <Fixed|Mitigated|Acknowledged|Not Fixed|Unresolved> --update-file <file> --evidence "<one sentence>"`
+
+For `fixed` cards with a failing PoC, write the update text yourself (one sentence naming the commit) and `propose` it. For `unaddressed` cards, ask the auditor whether the client acknowledged them; if so, propose `Acknowledged` with the client's reason.
+
+## Step 4 — Unmapped changes
+
+Every entry in `unmapped_changes` is code the fixes changed that no finding explains: a new attack surface until reviewed. Review each one, differential-audit style (the function, its callers via `npx --no-install hex facts query callers <ref>`, the entry points that reach it). For anything risky, file a new card with `/write-finding`. Offer `/ai-audit` restricted to these files when there are many.
+
+Record each verdict, so the dashboard's Changes page shows it as reviewed:
+
+```bash
+npx --no-install hex fix-review reviewed <fix> <Contract.function> --note "<one or two sentences; name the card if you filed one>"
+```
+
+## Step 5 — One confirmation, then GitHub
+
+Show the whole batch as a table: card · GitHub issue · proposed Status · Update text. Then ask once:
+
+> Apply these N updates to GitHub issues in `<repo>`? (Only the **Status** and **Update from the client** fields of each issue change.)
+
+Only after an explicit yes:
+
+```bash
+npx --no-install hex fix-review apply <fix-sha>
+```
+
+It rewrites just those two fields in each issue body and leaves every other byte alone. `--dry-run` prints the new bodies without editing. Then run `/sync-issues` so the local cards pull the new state, and record the fix commit as the report's final commit in `.hex/config.json` → `settings.report.final_commit`.
+
+## Step 6 — Summary
+
+Fixed / partially fixed / not fixed / acknowledged counts, the unmapped changes and what came of them, and the next step (`/generate-report` for the final report).

package/dist/skills/fuzz/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2024 AI Skills Contributors
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.