hex-audit 0.4.4 → 0.5.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (102) hide show
  1. package/DEMO.md +14 -12
  2. package/README.md +66 -61
  3. package/dashboard/.next/BUILD_ID +1 -1
  4. package/dashboard/.next/app-build-manifest.json +18 -11
  5. package/dashboard/.next/app-path-routes-manifest.json +1 -1
  6. package/dashboard/.next/build-manifest.json +4 -4
  7. package/dashboard/.next/next-server.js.nft.json +1 -1
  8. package/dashboard/.next/prerender-manifest.js +1 -1
  9. package/dashboard/.next/prerender-manifest.json +1 -1
  10. package/dashboard/.next/required-server-files.json +1 -1
  11. package/dashboard/.next/routes-manifest.json +1 -1
  12. package/dashboard/.next/server/app/_not-found/page_client-reference-manifest.js +1 -1
  13. package/dashboard/.next/server/app/_not-found.html +1 -1
  14. package/dashboard/.next/server/app/_not-found.rsc +4 -4
  15. package/dashboard/.next/server/app/access/page_client-reference-manifest.js +1 -1
  16. package/dashboard/.next/server/app/api/flows/route.js +1 -1
  17. package/dashboard/.next/server/app/api/issues/[id]/move/route.js +1 -1
  18. package/dashboard/.next/server/app/api/issues/[id]/route.js +1 -1
  19. package/dashboard/.next/server/app/calls/page_client-reference-manifest.js +1 -1
  20. package/dashboard/.next/server/app/conformance/page_client-reference-manifest.js +1 -1
  21. package/dashboard/.next/server/app/diagram/page_client-reference-manifest.js +1 -1
  22. package/dashboard/.next/server/app/diagram.html +1 -1
  23. package/dashboard/.next/server/app/diagram.rsc +4 -4
  24. package/dashboard/.next/server/app/flows/page_client-reference-manifest.js +1 -1
  25. package/dashboard/.next/server/app/flows.html +1 -1
  26. package/dashboard/.next/server/app/flows.rsc +4 -4
  27. package/dashboard/.next/server/app/functions/page_client-reference-manifest.js +1 -1
  28. package/dashboard/.next/server/app/issues/page.js +12 -1
  29. package/dashboard/.next/server/app/issues/page_client-reference-manifest.js +1 -1
  30. package/dashboard/.next/server/app/overleaf/page.js +1 -0
  31. package/dashboard/.next/server/app/overleaf/page.js.nft.json +1 -0
  32. package/dashboard/.next/server/app/overleaf/page_client-reference-manifest.js +1 -0
  33. package/dashboard/.next/server/app/page_client-reference-manifest.js +1 -1
  34. package/dashboard/.next/server/app/progress/page_client-reference-manifest.js +1 -1
  35. package/dashboard/.next/server/app/stats/page_client-reference-manifest.js +1 -1
  36. package/dashboard/.next/server/app-paths-manifest.json +9 -8
  37. package/dashboard/.next/server/chunks/431.js +1 -1
  38. package/dashboard/.next/server/functions-config-manifest.json +1 -1
  39. package/dashboard/.next/server/middleware-build-manifest.js +1 -1
  40. package/dashboard/.next/server/pages/404.html +1 -1
  41. package/dashboard/.next/server/pages/500.html +1 -1
  42. package/dashboard/.next/server/server-reference-manifest.js +1 -1
  43. package/dashboard/.next/server/server-reference-manifest.json +1 -1
  44. package/dashboard/.next/static/chunks/app/issues/page-2bb52a36f20497fe.js +1 -0
  45. package/dashboard/.next/static/chunks/app/{layout-527d8aa86e483fbd.js → layout-9c3c84993dd895f6.js} +1 -1
  46. package/dashboard/.next/static/chunks/app/overleaf/page-bcea12a80c97b92f.js +1 -0
  47. package/dashboard/.next/static/chunks/{main-70c6d841ad572657.js → main-8f1e837090aef5cf.js} +1 -1
  48. package/dashboard/.next/static/css/9c84313d0484b74f.css +3 -0
  49. package/dashboard/app/api/flows/route.ts +4 -0
  50. package/dashboard/app/api/issues/[id]/move/route.ts +29 -58
  51. package/dashboard/app/api/issues/[id]/route.ts +11 -102
  52. package/dashboard/app/issues/IssuesBoardClient.tsx +155 -50
  53. package/dashboard/app/issues/page.tsx +40 -3
  54. package/dashboard/app/overleaf/OverleafClient.tsx +97 -0
  55. package/dashboard/app/overleaf/page.tsx +32 -0
  56. package/dashboard/components/DashboardLayout.tsx +8 -2
  57. package/dashboard/lib/finding-markdown.ts +110 -0
  58. package/dashboard/next.config.mjs +4 -0
  59. package/dist/analysis/external-calls.d.ts +8 -1
  60. package/dist/analysis/external-calls.d.ts.map +1 -1
  61. package/dist/analysis/external-calls.js +57 -13
  62. package/dist/analysis/external-calls.js.map +1 -1
  63. package/dist/commands/calls.d.ts.map +1 -1
  64. package/dist/commands/calls.js +15 -6
  65. package/dist/commands/calls.js.map +1 -1
  66. package/dist/commands/dashboard.d.ts.map +1 -1
  67. package/dist/commands/dashboard.js +12 -3
  68. package/dist/commands/dashboard.js.map +1 -1
  69. package/dist/commands/init.js +19 -19
  70. package/dist/commands/init.js.map +1 -1
  71. package/dist/commands/issue.d.ts +3 -0
  72. package/dist/commands/issue.d.ts.map +1 -0
  73. package/dist/commands/issue.js +195 -0
  74. package/dist/commands/issue.js.map +1 -0
  75. package/dist/core/config.d.ts +1 -0
  76. package/dist/core/config.d.ts.map +1 -1
  77. package/dist/core/config.js +10 -0
  78. package/dist/core/config.js.map +1 -1
  79. package/dist/core/issues.d.ts +116 -0
  80. package/dist/core/issues.d.ts.map +1 -0
  81. package/dist/core/issues.js +403 -0
  82. package/dist/core/issues.js.map +1 -0
  83. package/dist/core/schema.d.ts +24 -8
  84. package/dist/core/schema.d.ts.map +1 -1
  85. package/dist/core/schema.js +12 -1
  86. package/dist/core/schema.js.map +1 -1
  87. package/dist/index.js +3 -1
  88. package/dist/index.js.map +1 -1
  89. package/dist/skills/generate-overleaf.md +18 -10
  90. package/dist/skills/ingest-aa-report.md +15 -19
  91. package/dist/skills/init-audit.md +13 -18
  92. package/dist/skills/sync-issues.md +86 -195
  93. package/dist/skills/validate-all-findings.md +50 -0
  94. package/dist/skills/validate-issue.md +20 -10
  95. package/dist/skills/write-finding.md +23 -28
  96. package/package.json +1 -1
  97. package/dashboard/.next/server/app/api/flows.body +0 -1
  98. package/dashboard/.next/server/app/api/flows.meta +0 -1
  99. package/dashboard/.next/static/chunks/app/issues/page-dc110d4cc0a5c398.js +0 -1
  100. package/dashboard/.next/static/css/7a38e5062ba6d403.css +0 -3
  101. /package/dashboard/.next/static/{ePObaFrrwft0BlvlllUMo → NrFPHIFHWQ5jNF62Px_X8}/_buildManifest.js +0 -0
  102. /package/dashboard/.next/static/{ePObaFrrwft0BlvlllUMo → NrFPHIFHWQ5jNF62Px_X8}/_ssgManifest.js +0 -0
package/DEMO.md CHANGED
@@ -58,7 +58,8 @@ Key pages:
58
58
  - `/functions` — Aggregated function view.
59
59
  - `/diagram` and `/flows` — Full-bleed Mermaid canvas with auto-fit zoom and legend overlay.
60
60
  - `/conformance` — Conformance check results, deviations first, clickable spec links.
61
- - `/issues` — **The board.** Four columns: Potential / Verified / Invalid / Duplicate. Cards with severity, source badge, GitHub sync chip, duplicate signals. Drag a card to change column. Click to open a modal that edits severity, description, recommendation, resolution, and client update.
61
+ - `/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).
62
+ - `/overleaf` — The four LaTeX report sections from `/generate-overleaf`, each with a copy button. Only populated after you run the skill.
62
63
 
63
64
  ### Phase 2 — Manual review + `/write-finding`
64
65
 
@@ -76,13 +77,15 @@ When you have something concrete, point Claude at it:
76
77
 
77
78
  #### `/validate-issue` for any potential issue
78
79
 
79
- `/validate-issue` is source-agnostic. Pass an id (`F003`, `SC-007`, `AA-N002`, `github-42`) or a free-text reference:
80
+ `/validate-issue` is source-agnostic. Pass a uniform id (`H-003`) or a free-text reference:
80
81
 
81
82
  ```
82
- /validate-issue F003
83
+ /validate-issue H-003
83
84
  /validate-issue for the rounding issue
84
85
  ```
85
86
 
87
+ To validate the whole Potential backlog in one interactive pass, run `/validate-all-findings`.
88
+
86
89
  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.
87
90
 
88
91
  #### `/ingest-aa-report` — Nethermind AuditAgent only
@@ -99,19 +102,18 @@ When complete, the skill fetches findings, materializes them as Potential cards
99
102
 
100
103
  #### `/sync-issues` — team mode via GitHub Issues
101
104
 
102
- If `settings.github.repo` is configured in `.hex/config.json` (e.g. `nethermind/audit-vaultx`) and `gh auth login` has been run:
105
+ If a repo is configured (`hex init --github-repo <owner/repo>`, or `settings.github.repo`) and `gh auth login` has been run:
103
106
 
104
107
  ```
105
108
  /sync-issues
106
109
  ```
107
110
 
108
- One run does both directions:
111
+ GitHub is the source of truth; **identity is the issue number `#N`** (no hidden footer). One run does both directions:
109
112
 
110
- - **Pulls** every issue with the `hex` label. Issues with the round-trip footer `<!-- hex-finding-id: F<NNN> -->` link back to local findings; issues without the footer are teammate findings, materialized as new tracking entries (`source: "github"`).
111
- - **Inline dedup, GitHub-canonical.** If a pulled GitHub issue matches a local potential, **the local entry becomes the duplicate** (`status: "duplicate"`, `duplicate_of: "github-<num>"`). Reason: a teammate has already filed it — your in-progress card is redundant.
112
- - **Pushes** local findings whose tracking status is in `settings.github.publish_status` (default `["verified"]`). Updates existing issues by `github.issue_number`, never creates labels.
113
+ - **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).
114
+ - **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.
113
115
 
114
- GitHub-sync state shows as a chip on each card on the board.
116
+ 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.
115
117
 
116
118
  ### Phase 4 — Final deliverable (`/generate-overleaf`)
117
119
 
@@ -126,7 +128,7 @@ Writes four `.txt` LaTeX section files to `.hex/overleaf/`:
126
128
  3. `summary_of_findings.txt` — `\section{Summary of Issues}` table linking to per-finding subsections.
127
129
  4. `findings.txt` — `\section{Issues}` with one `\subsection{[Sev] title}\label{issue:N}` per verified finding (description, code blocks via minted, recommendation, status, client update).
128
130
 
129
- The skill prompts once for any missing report metadata (initial/final commit, dates, doc/test assessment) and persists them under `settings.report.*` so reruns don't re-prompt. Upload the four files into your Nethermind Overleaf template's matching slots.
131
+ The skill prompts once for any missing report metadata (initial/final commit, dates, doc/test assessment) and persists them under `settings.report.*` so reruns don't re-prompt. Read the four sections on the dashboard's `/overleaf` page and copy each into your Nethermind Overleaf template's matching slot (or grab the files directly from `.hex/overleaf/`).
130
132
 
131
133
  Only `verified` findings make the cut. Duplicates, rejected, and pending entries are skipped.
132
134
 
@@ -134,8 +136,8 @@ Only `verified` findings make the cut. Duplicates, rejected, and pending entries
134
136
 
135
137
  - `/init-audit` is now a single skill that runs everything pre-manual-review.
136
138
  - The board (`/issues`) is the only findings page. Cards are interactive: drag to change column, click to edit.
137
- - `/write-finding` records Potential issues — promote them via `/validate-issue` or by dragging on the board.
139
+ - `/write-finding` records Potential issues (uniform `H-NNN` ids, no in-code comments) — promote via `/validate-issue`, `/validate-all-findings`, or by dragging on the board.
138
140
  - `/ingest-aa-report` takes a scan ID, never starts a scan.
139
- - `/sync-issues` treats GitHub as the source of truth — your local entry is the duplicate on a match.
141
+ - `/sync-issues` treats GitHub as the source of truth — synced issues are read-only in Hex and identified by issue number; `/generate-overleaf` reports only from synced issues.
140
142
  - `/generate-overleaf` is the final handoff to the LaTeX report.
141
143
  - `hex update` upgrades the package and prompts to re-sync skills in one shot; `hex update-skills` re-syncs skills only.
package/README.md CHANGED
@@ -110,7 +110,7 @@ When you have something concrete, file it as a Potential issue:
110
110
  /write-finding for the rounding error in src/Vault.sol
111
111
  ```
112
112
 
113
- `/write-finding` writes the finding to `findings.json` with the next sequential `F<NNN>` ID. The corresponding tracking entry has `status: "pending_validation"` and `source: "manual"`, so the card lands in the **Potential** column on the dashboard board.
113
+ `/write-finding` allocates a uniform `H-NNN` id (all issues share one scheme regardless of origin; `source` is a separate field) and records the finding with `status: "pending_validation"` and `source: "manual"`, so the card lands in the **Potential** column. It does not write `@audit-issue` comments into the source — the board is the only place the issue lives.
114
114
 
115
115
  Phase 2 is where Hex gets out of your way. You think; the toolkit just gives you a place to record what you find.
116
116
 
@@ -126,19 +126,17 @@ Phase 2 is where Hex gets out of your way. You think; the toolkit just gives you
126
126
  - GitHub teammate entries materialized by `/sync-issues`.
127
127
 
128
128
  ```
129
- /validate-issue F003
130
- /validate-issue SC-007
131
- /validate-issue AA-N002
129
+ /validate-issue H-003
132
130
  /validate-issue for the rounding issue in Vault.sol
133
131
  ```
134
132
 
135
- Claude reads the relevant source-of-truth (findings.json | ai-results/auditagent/findings.json | spec-conformance.json | external/github/findings.json), traces the attack path in the code, and writes a validation memo to `.hex/validations/<id>_memo.md`. Then it asks per issue:
133
+ Claude reads the relevant source record, traces the attack path in the code, and writes a validation memo to `.hex/validations/<id>_memo.md`. Then it asks per issue:
136
134
 
137
135
  > The issue appears valid. PoC or memo-only?
138
136
 
139
137
  If PoC: invokes `/generate-poc` to produce a runnable test and iterates until it passes. If memo-only: skips PoC, just records the validation reasoning.
140
138
 
141
- Valid → tracking entry promotes to `verified` (the card moves to Verified). Invalid → tracking entry becomes `rejected` (the card moves to Invalid). Severity adjustment is offered after promotion.
139
+ Valid → the card moves to Verified (`hex issue move`). Invalid → it moves to Invalid. Severity adjustment is offered after promotion. To clear a whole backlog, **`/validate-all-findings`** runs this same flow over every Potential card, one at a time.
142
140
 
143
141
  #### Ingest a Nethermind AuditAgent scan (`/ingest-aa-report`)
144
142
 
@@ -157,25 +155,24 @@ The skill:
157
155
 
158
156
  #### Team mode (`/sync-issues`)
159
157
 
160
- When two or three auditors share an engagement, sync findings through a shared GitHub repo. Set `settings.github.repo` in `.hex/config.json` (the firm's internal repo, e.g. `nethermind/audit-vaultx`) and authenticate the `gh` CLI once:
158
+ GitHub is the source of truth for an audit's findings. Set the repo at init time with `hex init --github-repo <owner/repo>` (or `settings.github.repo` in `.hex/config.json`) — the firm's internal repo, e.g. `nethermind/audit-vaultx` — and authenticate the `gh` CLI once:
161
159
 
162
160
  ```bash
163
161
  gh auth login
164
162
  ```
165
163
 
166
- Hex itself never stores GitHub credentials — `/sync-issues` drives the `gh` CLI directly. Then:
164
+ Hex never stores GitHub credentials — `/sync-issues` drives the `gh` CLI directly. Then:
167
165
 
168
166
  ```
169
167
  /sync-issues
170
168
  ```
171
169
 
172
- One invocation does both directions:
170
+ One invocation does both directions. **Identity is the GitHub issue number `#N`** — there is no hidden footer in the issue body (auditors create issues by hand), so reconciliation matches a local finding to the issue number it has stored.
173
171
 
174
- - **Pull** every issue with the configured labels. Issues with a hidden footer `<!-- hex-finding-id: F<NNN> -->` link back to local findings. Issues without the footer become teammate findings (`source: "github"`, status `pending_validation`).
175
- - **Inline dedup, GitHub-canonical.** When a pulled GitHub issue matches a local potential entry, **the local entry becomes the duplicate** (`status: "duplicate"`, `duplicate_of: "github-<num>"`). Rationale: a teammate already filed it, so your in-progress local card is redundant. This is the opposite of the auditagent dedup direction, which flips the auditagent entry to duplicate.
176
- - **Push** every local finding whose tracking status is in `settings.github.publish_status` (default `["verified"]`). Body rendered from the description, code locations, recommendation. Labels applied for severity, source, status. Existing issues are updated by their `github.issue_number`.
172
+ - **Pull every issue** in the repo (no label filter — audit repos contain only findings). Each issue's title (`[Severity] Title`) and five-field body are parsed back into the local finding. If a body is blatantly not in the Hex format it's skipped with a warning. Issues already linked by `#N` are refreshed from GitHub; new ones become local findings. All pulled issues land in the **Synced** column.
173
+ - **Push** every local finding whose tracking status is in `settings.github.publish_status` (default `["verified"]`) and that isn't already on GitHub. The body is exactly the five-field template (File(s), Description, Recommendation(s), Status, Update from the client) — no labels, no footer. The returned issue number is stored on the finding, which locks it into Synced.
177
174
 
178
- The dashboard's `/issues` page surfaces GitHub-sync state as a chip on each card (✓ open, ✕ closed).
175
+ **Once synced, an issue is read-only in Hex.** Edit it on GitHub (severity, description, recommendation, status), then re-run `/sync-issues` to pull the changes back. `/generate-overleaf` reports only from synced issues. The board's `/issues` page surfaces sync state as a chip: `GH unsynced` (verified, not pushed), `GH #N open` / `GH #N closed`, or `GH conflict`.
179
176
 
180
177
  Comments stay on GitHub — Hex never posts, edits, or deletes comments. Auditors discuss inside GitHub itself.
181
178
 
@@ -202,15 +199,16 @@ Upload these into the Nethermind Overleaf template's matching slots. Only `verif
202
199
 
203
200
  Each skill has a recommended model — switch your Claude Code model before invoking skills that recommend Opus.
204
201
 
205
- | Skill | Phase | Recommended Model | What it does |
206
- | ------------------- | ----- | ----------------- | ------------------------------------------------------------------------------------------------------------------------------------------------ |
207
- | `init-audit` | 1 | Opus | Dependency-safety → `hex analyze` → overview → diagram → flows → spec conformance → materialize DEVIATES/PARTIAL items as Potential cards |
208
- | `write-finding` | 2 | Sonnet | Records a manual issue to `findings.json` as a Potential card (`status: pending_validation`, `source: manual`) |
209
- | `validate-issue` | 3 | Opus | Validates any Potential card (manual / auditagent / conformance / github); per-issue choice of PoC vs memo-only; promotes to Verified or Invalid |
210
- | `generate-poc` | 3 | Opus | Generates and runs a PoC test (invoked by `/validate-issue`) |
211
- | `ingest-aa-report` | 3 | Sonnet | Ingests a completed Nethermind AuditAgent scan by ID; materializes findings + inline dedup |
212
- | `sync-issues` | 3 | Sonnet | Two-way GitHub Issues sync with GitHub-canonical inline dedup |
213
- | `generate-overleaf` | 4 | Sonnet | Writes the four LaTeX section files for the final report |
202
+ | Skill | Phase | Recommended Model | What it does |
203
+ | ----------------------- | ----- | ----------------- | ------------------------------------------------------------------------------------------------------------------------------------------------ |
204
+ | `init-audit` | 1 | Opus | Dependency-safety → `hex analyze` → overview → diagram → flows → spec conformance → materialize DEVIATES/PARTIAL items as Potential cards |
205
+ | `write-finding` | 2 | Sonnet | Records a manual issue to `findings.json` as a Potential card (`status: pending_validation`, `source: manual`) |
206
+ | `validate-issue` | 3 | Opus | Validates any Potential card (manual / auditagent / conformance / github); per-issue choice of PoC vs memo-only; promotes to Verified or Invalid |
207
+ | `validate-all-findings` | 3 | Opus | Runs the `/validate-issue` flow over every Potential card, one at a time |
208
+ | `generate-poc` | 3 | Opus | Generates and runs a PoC test (invoked by `/validate-issue`) |
209
+ | `ingest-aa-report` | 3 | Sonnet | Ingests a completed Nethermind AuditAgent scan by ID; materializes findings + inline dedup |
210
+ | `sync-issues` | 3 | Sonnet | Two-way GitHub Issues sync; GitHub is the source of truth (issue number is identity, synced issues are read-only) |
211
+ | `generate-overleaf` | 4 | Sonnet | Writes the four LaTeX section files for the final report (from synced issues) |
214
212
 
215
213
  ### Where Skills Live
216
214
 
@@ -221,6 +219,7 @@ Skills use Claude Code's native skill format, stored in `.claude/skills/<name>/S
221
219
  ├── init-audit/SKILL.md
222
220
  ├── write-finding/SKILL.md
223
221
  ├── validate-issue/SKILL.md
222
+ ├── validate-all-findings/SKILL.md
224
223
  ├── generate-poc/SKILL.md
225
224
  ├── ingest-aa-report/SKILL.md
226
225
  ├── sync-issues/SKILL.md
@@ -248,19 +247,20 @@ hex update-skills --keep-custom # skip existing skill files to preserve per-pro
248
247
 
249
248
  The dashboard runs locally at `http://localhost:3000` and auto-refreshes when output files change. A live "Updated Ns ago" indicator in the sidebar footer tells you the watcher is connected.
250
249
 
251
- | Page | URL | What you see |
252
- | ---------------- | -------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
253
- | Home | `/` | Project info, AI overview, key stats |
254
- | Progress | `/progress` | Weighted progress bar (70% nSLOC reviewed, 20% audit steps, 10% findings triage), contract review checklist |
255
- | Statistics | `/stats` | Per-contract metrics, test coverage, dependencies, ERCs |
256
- | System Diagram | `/diagram` | Mermaid architecture diagram with zoom/pan |
257
- | Flows | `/flows` | Mermaid flow charts with zoom/pan |
258
- | Access Control | `/access` | Role → function matrix with "Show unprotected only" and "Show inferred / unknown modifiers" toggles |
259
- | State Variables | `/state` | Variable inventory with reader/writer tracking and storage-collision warnings |
260
- | External Calls | `/calls` | Call surface with filterable Trust column |
261
- | Functions | `/functions` | Aggregated function view |
262
- | Spec Conformance | `/conformance` | Code vs spec check results, deviations first, clickable spec links |
263
- | **Issues** | `/issues` | **The board.** Four columns (Potential / Verified / Invalid / Duplicate). Drag cards to change column, click to edit (severity, description, recommendation, resolution, client update). |
250
+ | Page | URL | What you see |
251
+ | ---------------- | -------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
252
+ | Home | `/` | Project info, AI overview, key stats |
253
+ | Progress | `/progress` | Weighted progress bar (70% nSLOC reviewed, 20% audit steps, 10% findings triage), contract review checklist |
254
+ | Statistics | `/stats` | Per-contract metrics, test coverage, dependencies, ERCs |
255
+ | System Diagram | `/diagram` | Mermaid architecture diagram with zoom/pan |
256
+ | Flows | `/flows` | Mermaid flow charts with zoom/pan |
257
+ | Access Control | `/access` | Role → function matrix with "Show unprotected only" and "Show inferred / unknown modifiers" toggles |
258
+ | State Variables | `/state` | Variable inventory with reader/writer tracking and storage-collision warnings |
259
+ | External Calls | `/calls` | Call surface with filterable Trust column |
260
+ | Functions | `/functions` | Aggregated function view |
261
+ | Spec Conformance | `/conformance` | Code vs spec check results, deviations first, clickable spec links |
262
+ | **Issues** | `/issues` | **The board.** Five columns (Potential / Verified / Synced / Invalid / Duplicate). Drag cards between the editable columns, click to edit (severity, description, recommendation, resolution, client update), or copy a finding as HackMD markdown. The **Synced** column is reached only via `/sync-issues` and is read-only (edit on GitHub). GitHub-sync chip per verified/synced card. |
263
+ | **Overleaf** | `/overleaf` | The four LaTeX report sections from `/generate-overleaf`, each with a copy-to-clipboard button — paste straight into the Nethermind Overleaf template. |
264
264
 
265
265
  ---
266
266
 
@@ -350,29 +350,34 @@ You usually don't call these directly — `/init-audit` and the other skills do.
350
350
 
351
351
  All commands run from within the project directory (or with `--project /path/to/project`).
352
352
 
353
- | Command | What it does |
354
- | --------------------------------- | -------------------------------------------------------------------------------------------------------------- |
355
- | `hex doctor` | Preflight check: node, forge, slither, solc, Claude Code, output-dir writability, project config |
356
- | `hex claude` | Copy skills to `.claude/skills/` for Claude Code discovery |
357
- | `hex init` | Initialise audit config — scope, commit, chain, docs URL (called by `/init-audit`) |
358
- | `hex analyze` | Run all analysis commands in parallel (stats, deps, access, state, calls, patterns, constraints), then surface |
359
- | `hex stats` | Generate codebase statistics and test coverage |
360
- | `hex deps` | Build contract dependency graph |
361
- | `hex access` | Extract access control mapping (roles → functions, including inherited) |
362
- | `hex state` | Generate state variable inventory + storage-collision detection |
363
- | `hex calls` | Map external call surface (AST-based, Slither optional) |
364
- | `hex patterns` | Detect security-relevant patterns (ORACLE, FLASH_LOAN, TEMPORAL, etc.) |
365
- | `hex constraints` | Extract setter validation status (AST-aware, follows helpers and modifiers) |
366
- | `hex surface` | Build attack surface summary cross-referencing all analysis |
367
- | `hex context` | Assemble optimised AI context from codebase |
368
- | `hex context --target Vault` | Context for a specific contract and its dependencies |
369
- | `hex context --estimate` | Show token count without generating context |
370
- | `hex dashboard` | Start local dashboard and open in browser |
371
- | `hex dashboard --port 8080` | Start dashboard on a custom port |
372
- | `hex update` | Update hex-audit to the latest version on npm, then prompt to re-sync skills into the current project |
373
- | `hex update --check` | Check for an available update without installing |
374
- | `hex update --yes` | Update and re-sync skills without the post-install prompt |
375
- | `hex update-skills` | Re-copy skill files from package, removing orphans (overwrites by default) |
376
- | `hex update-skills --keep-custom` | Skip existing skill files instead of overwriting |
377
- | `hex ai-status` | Show the latest status for AuditAgent scans |
378
- | `hex ai-status --watch` | Poll every 5 minutes until pending scans resolve (typical scan: 30-60 min) |
353
+ | Command | What it does |
354
+ | --------------------------------- | ------------------------------------------------------------------------------------------------------------------ |
355
+ | `hex doctor` | Preflight check: node, forge, slither, solc, Claude Code, output-dir writability, project config |
356
+ | `hex claude` | Copy skills to `.claude/skills/` for Claude Code discovery |
357
+ | `hex init` | Initialise audit config — scope, commit, chain, docs URL, `--github-repo` (called by `/init-audit`) |
358
+ | `hex analyze` | Run all analysis commands in parallel (stats, deps, access, state, calls, patterns, constraints), then surface |
359
+ | `hex stats` | Generate codebase statistics and test coverage |
360
+ | `hex deps` | Build contract dependency graph |
361
+ | `hex access` | Extract access control mapping (roles → functions, including inherited) |
362
+ | `hex state` | Generate state variable inventory + storage-collision detection |
363
+ | `hex calls` | Map external call surface (AST-based, Slither optional) |
364
+ | `hex patterns` | Detect security-relevant patterns (ORACLE, FLASH_LOAN, TEMPORAL, etc.) |
365
+ | `hex constraints` | Extract setter validation status (AST-aware, follows helpers and modifiers) |
366
+ | `hex surface` | Build attack surface summary cross-referencing all analysis |
367
+ | `hex context` | Assemble optimised AI context from codebase |
368
+ | `hex context --target Vault` | Context for a specific contract and its dependencies |
369
+ | `hex context --estimate` | Show token count without generating context |
370
+ | `hex dashboard` | Start local dashboard and open in browser |
371
+ | `hex dashboard --port 8080` | Start dashboard on a custom port |
372
+ | `hex update` | Update hex-audit to the latest version on npm, then prompt to re-sync skills into the current project |
373
+ | `hex update --check` | Check for an available update without installing |
374
+ | `hex update --yes` | Update and re-sync skills without the post-install prompt |
375
+ | `hex update-skills` | Re-copy skill files from package, removing orphans (overwrites by default) |
376
+ | `hex update-skills --keep-custom` | Skip existing skill files instead of overwriting |
377
+ | `hex ai-status` | Show the latest status for AuditAgent scans |
378
+ | `hex ai-status --watch` | Poll every 5 minutes until pending scans resolve (typical scan: 30-60 min) |
379
+ | `hex issue new --source <s> ...` | Allocate a uniform `H-NNN` id and create a board card (used by the skills) |
380
+ | `hex issue move <id> --to <col>` | Move an issue between board columns (potential / verified / invalid / duplicate); materializes a finding on verify |
381
+ | `hex issue patch <id> [...]` | Edit an issue's severity / resolution / description-file / recommendation-file / update-from-client / notes |
382
+ | `hex issue sync-set <id> ...` | Mark an issue synced to a GitHub issue number (used by `/sync-issues`) |
383
+ | `hex issue show <id>` | Print the merged finding + tracking record for an issue |
@@ -1 +1 @@
1
- ePObaFrrwft0BlvlllUMo
1
+ NrFPHIFHWQ5jNF62Px_X8
@@ -12,23 +12,23 @@
12
12
  "static/chunks/618f8807-547c5614e1318888.js",
13
13
  "static/chunks/3205-728c260fbb4f89c6.js",
14
14
  "static/chunks/main-app-9d2f6b8a47133e9b.js",
15
- "static/css/7a38e5062ba6d403.css",
15
+ "static/css/9c84313d0484b74f.css",
16
16
  "static/chunks/7498-ea83cb9e30ec5491.js",
17
- "static/chunks/app/layout-527d8aa86e483fbd.js"
17
+ "static/chunks/app/layout-9c3c84993dd895f6.js"
18
18
  ],
19
- "/flows/page": [
19
+ "/diagram/page": [
20
20
  "static/chunks/webpack-08869f2b18792e51.js",
21
21
  "static/chunks/618f8807-547c5614e1318888.js",
22
22
  "static/chunks/3205-728c260fbb4f89c6.js",
23
23
  "static/chunks/main-app-9d2f6b8a47133e9b.js",
24
- "static/chunks/app/flows/page-fa67783d8cd79cab.js"
24
+ "static/chunks/app/diagram/page-b228444265546495.js"
25
25
  ],
26
- "/diagram/page": [
26
+ "/flows/page": [
27
27
  "static/chunks/webpack-08869f2b18792e51.js",
28
28
  "static/chunks/618f8807-547c5614e1318888.js",
29
29
  "static/chunks/3205-728c260fbb4f89c6.js",
30
30
  "static/chunks/main-app-9d2f6b8a47133e9b.js",
31
- "static/chunks/app/diagram/page-b228444265546495.js"
31
+ "static/chunks/app/flows/page-fa67783d8cd79cab.js"
32
32
  ],
33
33
  "/access/page": [
34
34
  "static/chunks/webpack-08869f2b18792e51.js",
@@ -47,6 +47,13 @@
47
47
  "static/chunks/8452-e616b5f43bceb95f.js",
48
48
  "static/chunks/app/calls/page-d07f5b8664cc8303.js"
49
49
  ],
50
+ "/overleaf/page": [
51
+ "static/chunks/webpack-08869f2b18792e51.js",
52
+ "static/chunks/618f8807-547c5614e1318888.js",
53
+ "static/chunks/3205-728c260fbb4f89c6.js",
54
+ "static/chunks/main-app-9d2f6b8a47133e9b.js",
55
+ "static/chunks/app/overleaf/page-bcea12a80c97b92f.js"
56
+ ],
50
57
  "/functions/page": [
51
58
  "static/chunks/webpack-08869f2b18792e51.js",
52
59
  "static/chunks/618f8807-547c5614e1318888.js",
@@ -56,13 +63,12 @@
56
63
  "static/chunks/8928-60c623ee89d2e6ad.js",
57
64
  "static/chunks/app/functions/page-686f0296639133a3.js"
58
65
  ],
59
- "/issues/page": [
66
+ "/conformance/page": [
60
67
  "static/chunks/webpack-08869f2b18792e51.js",
61
68
  "static/chunks/618f8807-547c5614e1318888.js",
62
69
  "static/chunks/3205-728c260fbb4f89c6.js",
63
70
  "static/chunks/main-app-9d2f6b8a47133e9b.js",
64
- "static/chunks/3924-4a05057b5450abe1.js",
65
- "static/chunks/app/issues/page-dc110d4cc0a5c398.js"
71
+ "static/chunks/app/conformance/page-2fede1d7b5f9265d.js"
66
72
  ],
67
73
  "/stats/page": [
68
74
  "static/chunks/webpack-08869f2b18792e51.js",
@@ -79,12 +85,13 @@
79
85
  "static/chunks/main-app-9d2f6b8a47133e9b.js",
80
86
  "static/chunks/app/progress/page-f07ac39d1d27b480.js"
81
87
  ],
82
- "/conformance/page": [
88
+ "/issues/page": [
83
89
  "static/chunks/webpack-08869f2b18792e51.js",
84
90
  "static/chunks/618f8807-547c5614e1318888.js",
85
91
  "static/chunks/3205-728c260fbb4f89c6.js",
86
92
  "static/chunks/main-app-9d2f6b8a47133e9b.js",
87
- "static/chunks/app/conformance/page-2fede1d7b5f9265d.js"
93
+ "static/chunks/3924-4a05057b5450abe1.js",
94
+ "static/chunks/app/issues/page-2bb52a36f20497fe.js"
88
95
  ],
89
96
  "/page": [
90
97
  "static/chunks/webpack-08869f2b18792e51.js",
@@ -1 +1 @@
1
- {"/_not-found/page":"/_not-found","/api/code/route":"/api/code","/api/issues/[id]/move/route":"/api/issues/[id]/move","/api/issues/[id]/route":"/api/issues/[id]","/api/flows/route":"/api/flows","/api/progress/route":"/api/progress","/api/mermaid/route":"/api/mermaid","/flows/page":"/flows","/diagram/page":"/diagram","/icon.svg/route":"/icon.svg","/api/github-status/route":"/api/github-status","/access/page":"/access","/calls/page":"/calls","/functions/page":"/functions","/api/watch/route":"/api/watch","/issues/page":"/issues","/stats/page":"/stats","/progress/page":"/progress","/conformance/page":"/conformance","/page":"/"}
1
+ {"/_not-found/page":"/_not-found","/api/mermaid/route":"/api/mermaid","/api/code/route":"/api/code","/api/progress/route":"/api/progress","/diagram/page":"/diagram","/flows/page":"/flows","/icon.svg/route":"/icon.svg","/api/github-status/route":"/api/github-status","/api/issues/[id]/route":"/api/issues/[id]","/api/flows/route":"/api/flows","/api/issues/[id]/move/route":"/api/issues/[id]/move","/api/watch/route":"/api/watch","/access/page":"/access","/calls/page":"/calls","/overleaf/page":"/overleaf","/functions/page":"/functions","/conformance/page":"/conformance","/stats/page":"/stats","/progress/page":"/progress","/issues/page":"/issues","/page":"/"}
@@ -5,8 +5,8 @@
5
5
  "devFiles": [],
6
6
  "ampDevFiles": [],
7
7
  "lowPriorityFiles": [
8
- "static/ePObaFrrwft0BlvlllUMo/_buildManifest.js",
9
- "static/ePObaFrrwft0BlvlllUMo/_ssgManifest.js"
8
+ "static/NrFPHIFHWQ5jNF62Px_X8/_buildManifest.js",
9
+ "static/NrFPHIFHWQ5jNF62Px_X8/_ssgManifest.js"
10
10
  ],
11
11
  "rootMainFiles": [
12
12
  "static/chunks/webpack-08869f2b18792e51.js",
@@ -18,13 +18,13 @@
18
18
  "/_app": [
19
19
  "static/chunks/webpack-08869f2b18792e51.js",
20
20
  "static/chunks/framework-cf6f5bdca6ba0184.js",
21
- "static/chunks/main-70c6d841ad572657.js",
21
+ "static/chunks/main-8f1e837090aef5cf.js",
22
22
  "static/chunks/pages/_app-6ad2b50514c24ab4.js"
23
23
  ],
24
24
  "/_error": [
25
25
  "static/chunks/webpack-08869f2b18792e51.js",
26
26
  "static/chunks/framework-cf6f5bdca6ba0184.js",
27
- "static/chunks/main-70c6d841ad572657.js",
27
+ "static/chunks/main-8f1e837090aef5cf.js",
28
28
  "static/chunks/pages/_error-d5eb11c5c4626811.js"
29
29
  ]
30
30
  },