hex-audit 0.7.0 → 0.8.0

package/CLAUDE.md

@@ -6,100 +6,160 @@
 - Output directory: `.hex/`
 - Dashboard package: `hex-dashboard`
 
+## Principles: elegance through simplicity
+The dashboard is a calm review workspace that sits next to the auditor's Claude Code session. Every
+design decision follows from these:
+- **One question, one action.** Every screen answers one question and has one obvious next action
+  (Today: "what next?" → Continue; Review: "is this function safe?" → Clear; Model: "how does it
+  hold value and power?" → Use in report). Only that action uses the accent fill.
+- **Content first, chrome last.** No decoration, no nested cards, no badge clutter, no wide
+  multi-column tables by default.
+- **Progressive disclosure.** Lists show only what's needed to choose; everything else lives in the
+  right-hand inspector (Mail/Xcode three-pane: source list | content | inspector). Rarely needed
+  controls hide behind a toggle (e.g. the canvas Style panel).
+- **One accent.** Indigo marks selection and the primary action, nothing else. No accent text for
+  code, no accent chips, no accent banners.
+- **Quiet severity and status.** A small colored dot plus a word, never a filled badge.
+- **Typography and whitespace carry hierarchy** on an 8pt grid; hairline dividers instead of boxes.
+- **Motion** is 200ms ease-out fades and short slides only.
+- **Light and dark are equally polished** (dark is the default).
+- **Keyboard-first.** `j`/`k` move, `r`/`q`/`c` mark read/questioned/cleared (Review), F12 / ⌥F12 /
+  ⇧F12 go to definition / peek / callers, Alt+←/→ back and forward along the walked flow, `e` edit,
+  `/` search, `⌘K` go to anything, `⌘\` toggle the sidebar, `Esc` close; every mutation toasts with
+  Undo.
+- **Empty states** are one sentence plus the single command that fills them (`hex facts`,
+  `/init-audit`, `/generate-report`).
+
 ## Typography
 - **Display/body**: Manrope (Google Fonts), variable weight 200-800
-- **Code only**: JetBrains Mono (file paths, code snippets, code blocks)
+- **Code only**: JetBrains Mono (file paths, signatures, code snippets, code blocks)
 - **Fallback (sans)**: `system-ui, -apple-system, sans-serif`
 - **Fallback (mono)**: `ui-monospace, 'SF Mono', monospace`
 - **Scale**: display (28px/600), title (20px/600), heading (15px/500), body (14px/400), caption (12px/400)
-- **Section headers**: sentence case, medium weight (not uppercase)
+- **Section headers**: sentence case, medium weight, caption size and `text-tertiary` inside the
+  inspector (not uppercase)
 
 ## Color Palette
+OKLCH throughout for perceptual uniformity; surfaces are blue-tinted (hue 265), never pure black.
+Tokens live in `dashboard/app/globals.css` and are exposed as Tailwind colors (`bg-surface-1`,
+`text-text-secondary`, `border-border-subtle`, `bg-accent-subtle`, ...).
 
-### Dark Mode (primary)
-Surfaces are blue-tinted (hue 265), not pure black. Built with OKLCH for perceptual uniformity.
-
+### Dark mode (default)
 | Token | Value | Usage |
 |-------|-------|-------|
-| `--surface-0` | `oklch(0.13 0.005 265)` | Page background |
-| `--surface-1` | `oklch(0.17 0.006 265)` | Cards, sidebar |
-| `--surface-2` | `oklch(0.21 0.006 265)` | Elevated surfaces, inputs |
-| `--surface-3` | `oklch(0.26 0.006 265)` | Hover states |
+| `--surface-0` | `oklch(0.13 0.005 265)` | Page, lists, content panes |
+| `--surface-1` | `oklch(0.17 0.006 265)` | App sidebar, inspector, kanban cards |
+| `--surface-2` | `oklch(0.21 0.006 265)` | Hover, inputs, segmented track |
+| `--surface-3` | `oklch(0.26 0.006 265)` | Pressed / active toggle |
 | `--text-primary` | `oklch(0.93 0.005 265)` | Body text |
-| `--text-secondary` | `oklch(0.65 0.01 265)` | Secondary labels |
-| `--text-tertiary` | `oklch(0.48 0.008 265)` | Disabled, hints |
-| `--accent` | `oklch(0.58 0.19 265)` | Indigo (links, active states) |
-| `--accent-subtle` | `oklch(0.58 0.19 265 / 0.10)` | Hover tint |
-| `--accent-secondary` | `oklch(0.68 0.14 265)` | Lighter indigo |
-| `--border-subtle` | `oklch(0.25 0.005 265 / 0.5)` | Faint dividers |
-| `--border-default` | `oklch(0.30 0.006 265 / 0.6)` | Standard borders |
-| `--border-emphasis` | `oklch(0.40 0.01 265 / 0.7)` | Active borders |
-
-### Severity Colors (both modes)
-| Severity | Color | Value |
-|----------|-------|-------|
-| Critical | Red | `oklch(0.58 0.22 25)` |
-| High | Amber | `oklch(0.68 0.16 55)` |
-| Medium | Yellow | `oklch(0.72 0.14 85)` |
+| `--text-secondary` | `oklch(0.68 0.01 265)` | Secondary text |
+| `--text-tertiary` | `oklch(0.52 0.008 265)` | Captions, hints, counts |
+| `--accent` | `oklch(0.62 0.18 265)` | Selection, primary action |
+| `--accent-subtle` | `oklch(0.62 0.18 265 / 0.14)` | Selected row / nav item |
+| `--accent-secondary` | `oklch(0.72 0.13 265)` | Primary button hover |
+| `--border-subtle` | `oklch(0.30 0.006 265 / 0.45)` | Hairlines between panes and rows |
+| `--border-default` | `oklch(0.34 0.006 265 / 0.6)` | Inputs, secondary buttons |
+| `--border-emphasis` | `oklch(0.44 0.01 265 / 0.7)` | Focused inputs, pressed toggles |
+
+### Light mode
+Page and content are near-white (`--surface-0: oklch(0.995 0.001 265)`); the sidebar and inspector
+are a faint tint (`--surface-1: oklch(0.972 0.003 265)`), like a macOS source list. Accent shifts
+to a deeper indigo (`oklch(0.50 0.21 265)`) for contrast. Check every screen in both modes.
+
+### Severity and status colors (both modes)
+| Meaning | Color | Value |
+|---------|-------|-------|
+| Critical / regressed / failing | Red | `oklch(0.58 0.22 25)` |
+| High / modified / contested | Amber | `oklch(0.68 0.16 55)` |
+| Medium / questioned / stale | Yellow | `oklch(0.72 0.14 85)` |
 | Low | Blue | `oklch(0.58 0.14 250)` |
-| Info | Gray | `oklch(0.55 0.01 265)` |
-
-### Light Mode (secondary)
-Surfaces start at near-white. Accent shifts to deeper indigo for contrast. Lower priority; dark mode is the primary experience.
-
-## Layout Patterns
-
-### Page Structure
-1. **Page title**: title size, semibold
-2. **Summary metrics** (where applicable): grid of stat cards
-3. **Detail table**: FilterableTable or SortableTable with the full dataset
-
-### Sidebar Navigation
-- Fixed 220px width, `bg-surface-1`, right border `border-subtle`
-- Groups labeled in sentence case, caption size
-- Active item: `bg-accent-subtle text-accent` (no border-left stripe)
-- Footer: theme toggle + `⌘K` hint
-
-### Cards
-- Background: `bg-surface-1`
-- Border: `border border-border-subtle`
-- Border radius: `rounded-lg` (12px)
-- Hover: `border-border-default bg-surface-2`
-- Padding: `p-4` to `p-6`
+| Info / unverified / neutral | Gray | `oklch(0.55 0.01 265)` |
+| Cleared / verified / passing / fixed | Green | `oklch(0.62 0.13 160)` |
+
+Always rendered as an 8px dot plus a word (`SeverityDot`, `Dot`), never as a filled badge.
+
+## Layout
+
+### App shell
+- Sidebar: 220px by default, drag its edge to resize (180-360px); collapses to a 60px icon rail
+  with `⌘\`. `bg-surface-1`, hairline right border.
+  Exactly six destinations: Today `/`, Model `/model`, Review `/review`, Changes `/changes` (diff
+  mode, or once a fix review exists), Board `/issues`, Report `/report`. Active (including nested routes):
+  `bg-accent-subtle text-accent`, no stripe. Footer: live status, `⌘K` hint, appearance toggle.
+- Main area is exactly the viewport height; each pane scrolls on its own.
+
+### Workspace pages (Model, Review, Changes, Board, Report)
+`SplitView`: a slim `Toolbar` (title + one line of meta on the left, at most two actions on the
+right), then source list | content | inspector. Panes are separated by hairlines. The inspector
+appears only when something is selected; over a canvas it floats (`inspectorFloating`) so the
+canvas keeps its size. Every pane edge (sidebar, list, inspector) is a `ResizeHandle`: drag to
+resize, double-click to reset, arrow keys nudge; the hairline shows `border-emphasis` on hover.
+Widths are CSS variables (`--w-<page>-list`, `--w-<page>-inspector`, `--w-sidebar`) remembered
+per viewer and restored before first paint (`lib/pane-width.ts`).
+
+### Document pages (Today, Changes overview)
+One centered column, max 720-780px, generous top padding (56px), sections separated by whitespace
+and hairline-bordered lists.
+
+### Inspector
+Eyebrow (caption: kind · context) → title (heading, semibold) → subtitle (signature in mono) →
+actions (primary first) → sections, each a caption label over plain content, separated by a
+hairline. Footer: the one-time "Claude can see your selection" hint.
+
+## Components (`dashboard/components/ui/`)
+- **Sidebar**, **SplitView** / **Toolbar** / **ScrollArea**, **Inspector** / **InspectorSection** /
+  **InspectorField**
+- **ListRow** / **ListGroupLabel**: 30-36px rows, leading glyph, title, optional caption line,
+  trailing detail; selected = `bg-accent-subtle` + accent title; hover = `bg-surface-2`
+- **SegmentedControl**: recessed `bg-surface-2` track, raised `bg-surface-0` segment with
+  `shadow-sm` for the active one (not accent). At most one per view; filters are a search field plus
+  one segmented control.
+- **SearchField** (`/` focuses), **Button** (`primary` = accent fill, once per screen; `secondary`;
+  `ghost`), **Kbd**, **Chip** (quiet; at most one per row), **SeverityDot** / **Dot**,
+  **StateGlyph** (unread ○, read ◐, questioned ?, cleared ●), **RiskMeter**, **ProgressRing**,
+  **EmptyState**, **Toast** (`useToast`, with Undo)
+- **CodeViewer**: whole file, Solidity highlighting (`lib/solidity.ts`), selected range tinted
+  with `--code-highlight`, line selection reported to the focus bridge. With `comments`
+  (`useCodeComments`), a gutter `+` on hover and a "Comment on lines a-b" pill after a selection
+  open an inline composer; comments render as hairline-bordered `bg-surface-1` bands under their
+  code (sans text, one caption meta line, ghost actions: Edit, Write to source, Delete). **CodeReference**: clickable
+  mono `file:line` that opens a code peek.
+- **Code navigation** (Review code pane, backed by `.hex/xref.json` from `hex facts`): references
+  are segments (`applyRefs`); holding Ctrl/⌘ underlines them. Ctrl/⌘-click or F12 goes to the
+  definition (interface or virtual calls go where they run; several implementations open a small
+  menu captioned override / same signature); Alt-click or ⌥F12 opens an inline **peek band**
+  (`bg-surface-1`, `border-border-default`, header: name · file:line · via, then Open ↵ and Esc
+  next to it, never right-aligned, since bands are as wide as the longest code line); on a
+  declaration's own name, or ⇧F12, the **usages band** lists call sites or reads/writes, one row
+  per line. A quiet **hover card** (450ms, no chips) shows signature, where it runs and NatSpec.
+  Every jump is a browser history entry (`history.pushState` with our own state object, so Next
+  syncs `useSearchParams`); the code header shows ← → and the walked **trail** (mono caption,
+  chevrons, current step in `text-primary`). The landed line is tinted `--code-focus`.
+- Kanban cards are the only bordered boxes: `bg-surface-1`, `border-border-subtle`,
+  `rounded-lg`, title + one meta line (severity dot, id · source, at most one chip).
+- Lists of prose items (Diane's open leads and questions) are rows split by hairlines
+  (`divide-y`), each with a quiet dot, text clamped to three lines with Show more, and a caption
+  line (source, actions on hover). Never a run-on block of paragraphs.
+- Retired: FilterableTable, SortableTable, filled severity badges, KPI walls, Mermaid.
+
+## Focus bridge
+Selecting a function, card, diagram node, code range or invariant writes `.hex/focus.json`
+(`POST /api/focus`, debounced via `lib/focus.ts`); the Claude Code session reads it with the Hex
+MCP tool `hex_focus`. The watcher ignores `focus.json` so selection never triggers a refresh.
 
 ## Animations & Motion
-
-### Principles
-- Subtle, functional, not decorative
-- All transitions: 200ms ease on interactive elements only (not universal)
-- No persistent background effects
-
-### Utilities
-- `.stagger`: children fade-in with 30ms staggered delay
-- `.scale-in`: KPI number scale animation (0.92 to 1, 350ms)
-
-## Component Conventions
-
-### Tables
-- Header row: caption size, text-tertiary
-- Row hover: `bg-surface-3`
-- Row dividers: `border-border-subtle`
-- Filter pills: rounded-md, `bg-accent text-surface-0` when active
-
-### Badges
-- Severity badges use the severity color palette
-- All badges: `rounded-md`, `px-2.5 py-1 text-caption`
-
-### Code References
-- Clickable `file:line` format in monospace
-- Modal with clean surface, subtle shadow
-- Highlighted lines: `bg-accent/10`
+- 200ms `--ease-out` fades/slides on interactive elements only (not universal)
+- `.fade-in`, `.rise-in` (4px), `.slide-in` (8px, inspectors), `.stagger` (30ms steps)
+- No persistent or looping animation, no background effects; respect `prefers-reduced-motion`
 
 ## Do NOT
-- Use monospace fonts outside of code blocks
-- Use colored border-left/right stripes on cards (>1px)
+- Use monospace fonts outside of code, file paths and signatures
+- Use colored border-left/right stripes on cards or rows (>1px)
 - Add gradient text
-- Use bounce/elastic easing
+- Use bounce/elastic easing, pulsing or looping animation
 - Use green (#00cc33) or neon accent colors
 - Use glassmorphism/backdrop-blur decoratively
 - Default to all-uppercase labels
+- Nest cards, fill badges, or put more than one status chip on a row
+- Use the accent for anything but selection and the primary action
+- Add a second segmented control or a multi-column table to a primary view

package/DEMO.md

@@ -1,159 +1,82 @@
 # Hex Demo Guide
 
-Step-by-step demo of Hex's audit workflow using Claude Code.
+A walk through one engagement, start to finish, inside Claude Code with the dashboard open beside it.
 
 ## Setup
 
-1. Pick any Foundry project with Solidity contracts. If you don't have one handy:
-
-   ```bash
-   git clone https://github.com/transmissions11/solmate.git
-   cd solmate
-   ```
-
-2. Install skills (works before init — no config required):
-
-   ```bash
-   hex claude
-   ```
-
-3. Open Claude Code:
-   ```bash
-   claude
-   ```
-
-## Demo flow (all inside Claude Code)
-
-### Phase 1 — One-shot pre-review (`/init-audit`)
+```bash
+git clone https://github.com/transmissions11/solmate.git && cd solmate   # or any Foundry project
+npm install -g hex-audit
+hex claude     # skills + the Hex MCP server in .mcp.json
+claude         # approve the "hex" MCP server when asked
+```
 
-Switch your Claude Code model to **Opus** for this one — it does all of the reasoning-heavy pre-review work in a single skill.
+## 1. Pre-review: `/init-audit`
 
 ```
 /init-audit
 ```
 
-It asks for scope, commit, chain, and docs URL. For solmate something like `--scope "src/**/*.sol"` works. Then the skill runs end-to-end:
-
-1. **Dependency safety audit** — checks `package.json` install hooks, Foundry `lib/` submodules, `foundry.toml` (FFI, fs_permissions, remappings), plaintext secrets in `.env*`, suspicious VS Code extensions. Stops before compilation if anything looks risky.
-2. **`hex init` + `hex analyze`** — runs the seven deterministic analyses (stats, deps, access, state, calls, patterns, constraints) in parallel, plus surface last. Slither and forge flatten results are cached across commands.
-3. **Protocol overview** — writes a 2-3 paragraph `overview.md` (key contracts table, external deps, architecture notes).
-4. **System diagram** — `.hex/diagrams/diagram.mmd` Mermaid architecture with trust zones and semantic symbols. Split into multiple files if >15 nodes.
-5. **Flow charts** — `.hex/diagrams/flow-*.mmd` per archetype (deposit/withdraw, governance, liquidation, etc.) with distinct shapes per node role and explicit success+revert branches on every decision.
-6. **Spec conformance** — cross-references docs, NatSpec, interfaces, and ERC/EIPs (fetches canonical specs from `eips.ethereum.org`). Writes `spec-conformance.json`.
-7. **Materialize conformance items to the board** — every DEVIATES/PARTIAL spec item becomes a Potential card in `tracking.json` (source `conformance`).
-
-**Differential variant.** Answer *Differential* when asked for the audit type, and give a base commit (plus, optionally, the previous audit's `.hex/` folder or report). `hex analyze` then also runs `hex diff`, which writes `diff.json` with the changed entities, storage-layout changes and impacted flows. The overview, flows and conformance phases focus on the change, prior findings get a regression check, and the dashboard shows a **Changes** page. To demo it on a single repo, audit `HEAD~5` → `HEAD`: `hex init --mode diff --base HEAD~5 --scope "src/**/*.sol"`.
-
-If anything fails, `hex doctor` prints a labelled preflight table (node, forge, slither, solc, Claude Code, output dir, `.hex/config.json`) with one-line install hints.
-
-### Dashboard opens automatically
-
-The last step of `/init-audit` launches `hex dashboard` in the background, so `http://localhost:3000` opens in your browser when the pipeline finishes. Live-refreshes on every `.hex/` change. If you ever need to start it manually, run `hex dashboard` in a second terminal.
-
-Key pages:
-
-- `/progress` — Weighted progress bar (70% nSLOC reviewed, 20% audit steps, 10% findings triage), contract review checklist.
-- `/stats` — KPI cards, ERC badges, per-contract metrics, coverage, dependencies.
-- `/access` — Role → function matrix with "Show unprotected only" and "Show inferred / unknown modifiers" toggles.
-- `/state` — State variable inventory with reader/writer tracking and storage-collision warnings.
-- `/calls` — External call surface with filterable Trust column.
-- `/functions` — Aggregated function view.
-- `/diagram` and `/flows` — Full-bleed Mermaid canvas with auto-fit zoom and legend overlay.
-- `/conformance` — Conformance check results, deviations first, clickable spec links.
-- `/changes` — Differential audits only: base → head, changed entities, storage layout, impacted flows with reasons, prior-findings regression check.
-- `/issues` — **The board.** Five columns: Potential / Verified / Synced / Invalid / Duplicate. Uniform `H-NNN` ids with a source badge. Drag cards between the editable columns; click to edit, or copy as HackMD. The **Synced** column is reached only via `/sync-issues` and is read-only (edit on GitHub).
-- `/report` — The seven LaTeX report sections from `/generate-report`, each with a copy button. Only populated after you run the skill.
+It asks for the scope (`src/**/*.sol` works for solmate), the commit, the chain and the docs. Then:
 
-### Phase 2 — Manual review + `/write-finding`
-
-Read the code in your editor. Leave `// @audit-issue ...` comments above anything suspicious.
+1. **Safety gate.** Install hooks, `ffi`, remappings and secrets are checked before anything compiles.
+2. **Exact facts.** `hex analyze` compiles into `.hex/.cache` and writes `facts.json` from the compiler AST. Try it yourself:
+   ```bash
+   npx --no-install hex facts query callers ERC20.transferFrom
+   npx --no-install hex facts query layout ERC4626
+   ```
+3. **Agents in waves.** Readers model each cluster in parallel without seeing each other, and a docs reader extracts the promises without seeing the code. A synthesizer writes the protocol model and proposed invariants, then skeptics verify every claim against the code. Watch the claims turn **verified** or **contested** on the Model page.
+4. **Diagrams.** Custody, privilege, accounting, state-machine and sequence views, each with a takeaway, rendered in Excalidraw.
+5. **Conformance.** Documentation, NatSpec and ERC deviations become Potential cards.
 
-When you have something concrete, point Claude at it:
+The dashboard opens at `http://localhost:3000` on **Today**: progress, the riskiest unread functions, and cards to triage.
 
-```
-/write-finding for the rounding error in src/Vault.sol
-```
+**Differential variant.** Answer *Differential* and give a base commit (and optionally the previous audit's `.hex/` folder or report). To demo it on any repo: `hex init --mode diff --base HEAD~5 --scope "src/**/*.sol"`. The Changes page shows the compiler storage-layout diff slot by slot and every impacted flow.
 
-`/write-finding` records the finding to `findings.json` and adds a tracking entry with status `pending_validation` and source `manual` — it shows up on the **Potential** column of the board. (No more "born verified" findings — every issue is validated explicitly.)
+## 2. Model: accept invariants
 
-### Phase 3 — Validate, ingest AI, sync GitHub
+On **Model**, read the diagrams (edit them if you like; edits are kept across rebuilds) and accept the invariants that really hold. You can also do it from the CLI with `npx --no-install hex invariant accept INV-001 INV-003`. Click "Use in report" on the diagrams worth showing the client.
 
-#### `/validate-finding` for any potential issue
+## 3. Review
 
-`/validate-finding` is source-agnostic. Pass a uniform id (`H-003`) or a free-text reference:
+Open **Review**. Pick a function from *Blind spots*: the code sits in the middle, with facts, notes and cards in the inspector. Mark it with `r` / `q` / `c`. Back in the terminal, ask:
 
 ```
-/validate-finding H-003
-/validate-finding for the rounding issue
+why is this safe?
 ```
 
-To validate the whole Potential backlog in one interactive pass, run `/validate-all-findings`.
+Claude calls `hex_focus` and knows which function you have selected.
 
-Claude traces the attack path in the code, writes a validation memo (always), and asks per-issue whether you want a PoC or memo-only. On valid → tracking entry promotes to `verified` and the card moves to Verified on the board. On invalid → tracking entry becomes `rejected` and the card moves to Invalid.
+**Diane.** Hit Record on the Review page, narrate a function ("deposit looks fine, done with it; not sure about the rounding in previewWithdraw"), stop, then run `/diane`. Diane checks your claims against the code, notes corrections, ticks `deposit` cleared and `previewWithdraw` questioned, and tells you exactly what she ticked.
 
-#### `/ai-audit` — 12 parallel attacker agents
+## 4. Find
 
 ```
+/write-finding for the rounding issue in previewWithdraw
 /ai-audit
+/fuzz
 ```
 
-Asks which model the agents use and how many passes to run (1, 3 or 5), then spawns 12 specialised agents over the Hex scope. In a differential audit it scans only the changed and impacted files and briefs the agents on the change. It prints the assembled report, then publishes it: each finding becomes a Potential card (`source: "ai-audit"`) rewritten to Hex's finding standard and deduped against the board, and each lead becomes an open lead on the contract's Notes. Run it again later and it files only what is new. Based on pashov's `solidity-auditor` (MIT).
+- `/ai-audit` asks for the model and the number of passes, then 12 agents hunt with your accepted invariants and triage rules in their brief. Findings land on the **Board**, deduped; leads land in the notes. `/prevalidate` then runs automatically: watch cards move to Verified (PoC passed) or Rejected (two refuters agreed) with an *auto* chip you can revert.
+- `/fuzz` turns accepted invariants into an Echidna/Medusa/Foundry suite; a broken invariant becomes a card with its repro test.
 
-#### `/ingest-aa-report` — Nethermind AuditAgent only
-
-Hex only integrates with **AuditAgent** (Nethermind's cloud scanner). You start a scan separately (Nethermind portal or `aa scan ...`) and paste the scan ID into Hex:
-
-```
-/ingest-aa-report <scan-id>
-```
-
-The skill checks status via `aa scan --status`. If the scan is still running it prints a status line and exits — you come back later. Run `hex ai-status --watch` in another terminal to be notified when the scan finishes.
-
-When complete, the skill fetches findings, materializes them as Potential cards (`source: "auditagent"`), and runs **inline dedup** against existing entries. Auditagent findings that match a manual or conformance issue are flipped to `duplicate` and surface in the Duplicate column with `match_signals` (contract / function / root_cause / attack_vector).
-
-#### `/sync-issues` — team mode via GitHub Issues
-
-If a repo is configured (`hex init --github-repo <owner/repo>`, or `settings.github.repo`) and `gh auth login` has been run:
+## 5. Validate and sync
 
 ```
+/validate-finding H-004
+/validate-all-findings
 /sync-issues
 ```
 
-GitHub is the source of truth; **identity is the issue number `#N`** (no hidden footer). One run does both directions:
+Validation writes a PoC by default and records it on the card. Rejecting something as by design offers to add a triage rule, so the next AI run stops raising it. `/sync-issues` pushes verified cards to GitHub; from then on GitHub is the source of truth.
 
-- **Pulls every issue** in the repo (no label filter). Title + the five-field body are parsed back into the local finding; issues already linked by `#N` are refreshed, new ones become local findings. All land in the **Synced** column (read-only).
-- **Pushes** verified findings not yet on GitHub. Body is exactly the five fields (no labels, no footer). The returned `#N` is stored, locking the card into Synced.
+## 6. Fix review and report
 
-Once synced, edit on GitHub and re-run `/sync-issues` to pull changes back. GitHub-sync state shows as a chip on each verified/synced card.
-
-### Phase 4 — Final deliverable (`/generate-report`)
+When the client sends fixes:
 
 ```
+/fix-review
 /generate-report
 ```
 
-Writes seven report sections to `.hex/report/`, each as a `.txt` (dashboard viewer / copy-paste) and a numbered `.tex` (`\input{}` into the Overleaf `main.tex`):
-
-1. `executive_summary.txt` / `01-executive-summary.tex` — `\section{Executive Summary}` with project synopsis, severity histogram, status histogram, summary table.
-2. `audited_files.txt` / `02-audited-files.tex` — `\section{Audited Files}` table of in-scope files (LoC, comments, ratio, blank, total).
-3. `summary_of_findings.txt` / `03-summary-of-findings.tex` — `\section{Summary of Issues}` table linking to per-finding subsections.
-4. `system_overview.txt` / `04-system-overview.tex` — `\section{System Overview}` protocol architecture (components, actors & roles, per-module/flow subsections) from `overview.md`.
-5. `findings.txt` / `06-issues.tex` — `\section{Issues}` with one `\subsection{[Sev] title}\label{issue:N}` per synced finding (description, code blocks via minted, recommendation, status, client update).
-6. `documentation_eval.txt` / `07-documentation-eval.tex` — `\section{Documentation Evaluation}` `tcolorbox` remarks paragraph.
-7. `test_suite.txt` / `08-test-suite.tex` — `\section{Test Suite Evaluation}` coverage summary from `stats.json.test_coverage`, plus automated-tooling note.
-
-The skill prompts once for any missing report metadata (initial/final commit, dates, doc/test assessment, kick-off/availability notes) and persists them under `settings.report.*` so reruns don't re-prompt. Read the sections on the dashboard's `/report` page and copy each into your Nethermind Overleaf template's matching slot (or grab the files directly from `.hex/report/`). Sections 5 (risk methodology) and 9 (conclusion) are template-static.
-
-Only `synced` findings make the cut. Duplicates, rejected, and pending entries are skipped.
-
-## Key points
-
-- `/init-audit` is now a single skill that runs everything pre-manual-review.
-- The board (`/issues`) is the only findings page. Cards are interactive: drag to change column, click to edit.
-- `/write-finding` records Potential issues (uniform `H-NNN` ids, no in-code comments) — promote via `/validate-finding`, `/validate-all-findings`, or by dragging on the board.
-- `/init-audit` runs full or differential audits; a differential audit focuses every phase on the change and the flows it reaches.
-- `/ai-audit` puts AI findings on the board and leads in Notes, idempotently across re-scans.
-- `/ingest-aa-report` takes a scan ID, never starts a scan.
-- `/sync-issues` treats GitHub as the source of truth — synced issues are read-only in Hex and identified by issue number; `/generate-report` reports only from synced issues.
-- `/generate-report` is the final handoff to the LaTeX report.
-- `hex update` upgrades the package and prompts to re-sync skills in one shot; `hex update-skills` re-syncs skills only.
+`/fix-review` re-runs every PoC at the fix commit. A PoC that used to pass and now fails proves the fix. Agents judge the rest, and fix-commit code that no finding explains gets flagged for review. After one confirmation it updates the Status and Update-from-the-client fields on GitHub. `/generate-report` writes the LaTeX sections, with the chosen diagrams as figures in the System Overview.