hex-audit 0.6.3 → 0.8.0

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.