hex-audit 0.4.5 → 0.5.0

package/dist/skills/sync-issues.md

@@ -1,249 +1,157 @@
 ---
-description: 'Two-way sync between local Hex findings and GitHub Issues — pulls teammate issues into the board (canonical), pushes verified findings out, runs inline dedup'
+description: 'Two-way sync between local Hex findings and GitHub Issues — GitHub is the source of truth; identity is the issue number'
 ---
 
 # Skill: Sync Issues
 
 **Recommended model:** Sonnet
 
-This skill is Hex's GitHub Issues integration. Hex never authenticates with GitHub — you authenticate once via `gh auth login` and this skill drives the `gh` CLI via bash. A single invocation runs both directions plus inline dedup.
+Hex's GitHub Issues integration. Hex never authenticates with GitHub — you authenticate once via `gh auth login` and this skill drives the `gh` CLI. One invocation runs both directions.
 
-**Dedup direction note.** GitHub is the **source of truth**. When a teammate's pulled GitHub issue matches a local potential issue (same root cause, same contract/function), the **local** entry is marked Duplicate — not the GitHub one. The rationale is multi-auditor coordination: if a teammate already filed an issue, your in-progress local card is redundant. This is opposite of the auditagent dedup direction in `/ingest-aa-report`.
+## The model: GitHub is the source of truth, identity is the issue number
 
-## Context Assembly
+Once an issue is on GitHub it is **read-only in Hex** (status `synced`, locked on the board). Edits — severity, description, recommendation, status — happen on GitHub; this skill pulls them back into the local finding. `/generate-overleaf` reports **only** from synced issues.
 
-Read:
-- `<output_dir>/config.json` — needs `settings.github.repo` set.
-- `<output_dir>/findings.json` — local canonical findings.
-- `<output_dir>/tracking.json` — for status filtering on push (default: only `verified` is pushed).
-- `<output_dir>/external/github/findings.json` if it exists — last pulled state.
-- `<output_dir>/external/github/sync-status.json` for `last_synced_at`.
+**Identity is the GitHub issue number `#N`.** There is no hidden footer in the issue body (auditors create issues by hand, so a footer can't be relied on). Reconciliation matches a local finding to the issue number it has stored in `github.issue_number`. The body is exactly the five-field template, nothing hidden.
 
-Writes to:
-- `<output_dir>/findings.json` — updates `github.*` blocks on local findings.
-- `<output_dir>/external/github/findings.json` — teammate findings in `AiResultFile` shape.
-- `<output_dir>/external/github/sync-status.json` — counters + timestamp.
-- `<output_dir>/external/github/raw-issues.json` — debug cache of the gh JSON.
-- `<output_dir>/tracking.json` — teammate findings as new entries; local entries flipped to `duplicate` on match.
-- `<output_dir>/comparison.json` — appended with `match_signals` for each dedup hit.
+All board mutations go through `hex issue` — never hand-edit `tracking.json` / `findings.json`.
 
-## Phase 0 — Preflight
-
-**0a. `gh` installed and authenticated?** Run `gh auth status`. If non-zero exit, print:
+## Context
 
-```
-gh CLI is not authenticated. Run `gh auth login` once on this machine, then re-run /sync-issues.
-```
+- `<output_dir>/config.json` — needs `settings.github.repo`.
+- `<output_dir>/findings.json` — local findings (some already carry a `github.issue_number`).
+- `<output_dir>/tracking.json` — status (`verified` are push candidates).
 
-…and stop. Hex never stores GitHub credentials.
+## Phase 0 — Preflight
 
-If `gh` itself is missing: instruct install from `https://cli.github.com/` then `gh auth login`.
+**0a.** `gh auth status`. If non-zero, print "gh CLI is not authenticated. Run `gh auth login` once, then re-run /sync-issues." and stop. If `gh` is missing, point to `https://cli.github.com/`.
 
-**0b. Resolve `settings.github.repo`.** If missing, use **AskUserQuestion**: "Which GitHub repo should this audit sync to? (e.g. `nethermind/audit-vaultx`)". Validate it has an `owner/repo` shape. Persist back to `config.json`.
+**0b.** Resolve `settings.github.repo`. If missing, **AskUserQuestion** for `owner/repo`, validate the shape, persist to `config.json`.
 
-**0c. Permission check.** Run `gh repo view <repo> --json viewerPermission`. If `READ` or null, **AskUserQuestion**: "Read-only access to <repo>. Push will fail. Continue with pull-only? (yes/no)". Track `push_enabled`.
+**0c.** `gh repo view <repo> --json viewerPermission`. If `READ`/null, **AskUserQuestion**: "Read-only access — push will fail. Continue pull-only? (yes/no)". Track `push_enabled`.
 
-## Phase 1 — Pull
+## Phase 1 — Pull (all issues, GitHub → local)
 
-**1a. Fetch issues.**
+**1a. Fetch every issue — no label filter.** Audit repos contain only audit findings, so pull them all:
 
 ```bash
-gh issue list --repo <repo> --label "hex" --state all --limit 1000 \
-  --json number,title,body,labels,state,author,createdAt,updatedAt,url
+gh issue list --repo <repo> --state all --limit 1000 \
+  --json number,title,body,state,author,createdAt,updatedAt,url
 ```
 
-Save raw JSON to `external/github/raw-issues.json`.
-
-For each issue whose `updatedAt` is newer than the prior `last_synced_at`, fetch comments:
+**1b. Parse each issue.** Title is `[Severity] Title`. Body is the five-field template:
 
-```bash
-gh issue view <number> --repo <repo> --json comments
-```
+```markdown
+**File(s)**: [`<file>`](<url>)
 
-(First sync: fetch for everything.)
+**Description**: <text>
 
-**1b. Classify each issue.**
+**Recommendation(s)**: <text>
 
-Find the round-trip footer in the body: regex `<!--\s*hex-finding-id:\s*(F\d+|AA-\d+|SC-\d+)\s*-->`. Then:
+**Status**: <Fixed|Mitigated|Acknowledged|Not Fixed|Unresolved>
 
-- **Footer present, ID matches a local `findings.json` entry** → known local finding. Update its `github` block in place:
-  ```json
-  {
-    "issue_number": <num>,
-    "issue_url": "<url>",
-    "state": "open|closed",
-    "last_synced_at": "<now>",
-    "sync_status": "in_sync",
-    "comments": [{ "author": "<login>", "body": "<text>", "created_at": "<iso>", "url": "<url>" }]
-  }
-  ```
+**Update from the client**: <text>
+```
 
-- **Footer present, no matching local finding** → an issue we previously pushed that's since been deleted locally. Append a tracking entry restoring the link (status `pending_validation`, source `manual`, notes pointing at the URL). Do not touch `findings.json` — the body may have been edited remotely.
-
-- **No footer** → teammate finding. Two writes:
-  1. Add to the in-memory `external/github/findings.json` AiResultFile (`tool: "github"`, severity parsed from `severity:*` labels, default Medium):
-     ```json
-     {
-       "id": "github-<issue_number>",
-       "tool": "github",
-       "title": "<issue title>",
-       "severity": "Critical|High|Medium|Low|Info",
-       "description": "<body without footer>",
-       "affected_code": [<best-effort file refs extracted from body>],
-       "confidence": "medium",
-       "category": "<from label if present>",
-       "raw_category": "github-issue"
-     }
-     ```
-  2. Add to `tracking.json`:
-     ```json
-     {
-       "id": "github-<issue_number>",
-       "title": "<title>",
-       "severity": "<severity>",
-       "source": "github",
-       "status": "pending_validation",
-       "poc_status": "not_started",
-       "poc_file": null,
-       "duplicates": [],
-       "notes": "issue=<url> author=<author>"
-     }
-     ```
-
-Write `external/github/findings.json` atomically after the pass.
-
-## Phase 2 — Inline dedup (GitHub-canonical)
-
-For each **new github entry** added in Phase 1 step 1b's third branch, run a semantic comparison against every **existing** non-github tracking entry. Match signals:
+Extract severity from the title, and the four body fields. If a body is **blatantly malformed** (no `**Description**:` marker), warn (`Skipping #N: not in the Hex finding format`) and skip it — do not fail the whole sync. Otherwise treat it as a valid finding (most will be).
 
-| Signal | Compare |
-|---|---|
-| **contract** (boolean) | Affected contract name match? |
-| **function** (boolean) | Affected function name match? |
-| **root_cause** (`same` / `overlapping` / `different`) | Technical mechanism |
-| **attack_vector** (`same` / `overlapping` / `different`) | What an attacker actually does |
-
-A match requires at least one of:
-- `root_cause = same` AND `function = true`, or
-- `root_cause = same` AND `contract = true` AND `attack_vector = same`, or
-- `root_cause = overlapping` AND `function = true` AND `attack_vector = same`.
-
-**On match (GitHub is canonical):**
-
-- Flip the **local** matching entry to `status: "duplicate"`, set `duplicate_of: "github-<issue_number>"` on it.
-- The github entry stays `pending_validation` (it's the canonical the team is working from).
-- Append to `comparison.json` under `duplicates`:
-  ```json
-  {
-    "ai_finding": "<local-entry-id>",
-    "matches": "github-<issue_number>",
-    "confidence": "high|medium|low",
-    "match_signals": { "contract": true, "function": true, "root_cause": "same", "attack_vector": "same" },
-    "reasoning": "<one short sentence>"
-  }
+**1c. Reconcile by issue number `#N`:**
+- **A local finding already records `github.issue_number === N`** → it's the same issue; pull GitHub's content into it:
+  ```bash
+  npx hex issue sync-set <local-H-id> --issue-number N --issue-url <url> --state <open|closed> \
+    --title "<title-without-[Severity]>" --severity <Severity> \
+    --description-file /tmp/N_desc.md --recommendation-file /tmp/N_reco.md \
+    --resolution "<Status>" --update-from-client-file /tmp/N_update.md
+  ```
+- **No local finding has `#N`** (a teammate's hand-added issue, or one created outside Hex) → create a local finding for it, then sync-set:
+  ```bash
+  ID=$(npx hex issue new --source github --source-ref N --title "<title>" --severity <Severity>)
+  npx hex issue sync-set "$ID" --issue-number N --issue-url <url> --state <open|closed> \
+    --description-file /tmp/N_desc.md --recommendation-file /tmp/N_reco.md \
+    --resolution "<Status>" --update-from-client-file /tmp/N_update.md
   ```
-  (The schema field is named `ai_finding` for historical reasons but is repurposed here as "the local duplicate.")
 
-Persist updated `tracking.json` and `comparison.json` after the dedup pass.
+Either way the card lands in the **Synced** column, locked. Reconcile strictly by `#N`; never scan the body for an identifier.
 
-## Phase 3 — Push
+## Phase 1.5 — Dedup before push (GitHub is canonical)
 
-Skip if `push_enabled = false`.
+Before pushing, guard against filing a finding that is already on GitHub (e.g. a teammate created it by hand, and you pulled it into Synced in Phase 1). For each **verified** local finding that has no `github.issue_number` yet, semantically compare it against every **synced** finding on these axes:
 
-**3a. Candidates.** From `findings.json`, select each finding whose tracking entry has `status` in `settings.github.publish_status` (default `["verified"]`). Skip findings already marked `status: "duplicate"` (no point publishing a known duplicate).
+| Signal | Compare |
+|---|---|
+| **contract** (boolean) | affected contract name |
+| **function** (boolean) | affected function name |
+| **root_cause** (`same`/`overlapping`/`different`) | the technical mechanism |
+| **attack_vector** (`same`/`overlapping`/`different`) | what an attacker actually does |
 
-Within candidates:
-- Has `github.issue_number` → update via `gh issue edit`.
-- No `github.issue_number` → create via `gh issue create`.
+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`.
 
-**3b. Render the body** (write to a temp file, then `--body-file`). Use this exact template — nothing more, nothing less in the visible body. It mirrors `dashboard/lib/finding-markdown.ts::findingToGithubBody`, so the board's "Copy as HackMD" output and the pushed issue stay identical:
+On match — the synced (on-GitHub) finding is canonical, so the local verified copy becomes the duplicate. Do **not** push it:
 
-```markdown
-**File(s)**: [`<file>`](<github-blob-url-or-empty>)
+```bash
+npx hex issue move <verified-H-id> --to duplicate --duplicate-of <synced-H-id>
+```
 
-**Description**: <finding.description>
+Then append to `<output_dir>/comparison.json` under `duplicates` (the board renders the chip + signals from this):
 
-**Recommendation(s)**: <finding.recommendation>
+```json
+{ "ai_finding": "<verified-H-id>", "matches": "<synced-H-id>", "confidence": "high|medium|low",
+  "match_signals": { "contract": true, "function": true, "root_cause": "same", "attack_vector": "same" },
+  "reasoning": "<one sentence>" }
+```
 
-**Status**: <finding.resolution or "Unresolved">
+If `comparison.json` doesn't exist, create it with `{ "duplicates": [], "novel": [], "rejected": [] }`.
 
-**Update from the client**: <finding.update_from_client or empty>
+## Phase 2 — Push (verified local findings → GitHub)
 
-<!-- hex-finding-id: <finding.id> -->
-```
+Skip if `push_enabled` is false.
 
-Rules:
-- **File(s)** — one markdown link per affected file in `root_cause.locations[]`, comma-separated when there is more than one: `` [`src/Vault.sol`](url1), [`src/MockToken.sol`](url2) ``. Build each URL as `<settings.report.repository_url>/blob/<settings.report.initial_commit>/<file>`. If either `repository_url` or `initial_commit` is missing from `config.json`, use an empty link target: `` [`<file>`]() ``.
-- **Status** — the finding's `resolution` field if set, otherwise the literal `Unresolved`.
-- **Update from the client** — the finding's `update_from_client` field if set, otherwise leave it blank after the colon.
-- Do NOT add a `**Severity:**` line (severity is already in the title), an `### Affected code` section, code blocks, or a "Synced from Hex" attribution line.
-- The `<!-- hex-finding-id: <finding.id> -->` HTML comment at the very bottom is **mandatory and load-bearing** — it is the round-trip dedup key, invisible in GitHub's rendered view. Never omit it.
+Candidates: findings whose tracking status is in `settings.github.publish_status` (default `["verified"]`) **and** which have no `github.issue_number` yet, **and** which Phase 1.5 did not flag as duplicates. (Synced findings are already on GitHub; duplicates/rejected/unverified are never pushed.)
 
-**3c. Create or update — no labels.** Hex does not apply, add, or remove labels. The target repo's label set is the repo owner's concern; assuming labels exist (e.g. `severity:critical`) makes `gh issue create` fail when they don't.
+For each candidate, render the body with the exact five-field template (see Phase 1b — `dashboard/lib/finding-markdown.ts::findingToGithubBody` is the canonical renderer). Write it to a temp file. **No labels, no footer.**
 
-Create:
 ```bash
 gh issue create --repo <repo> --title "[<Severity>] <title>" --body-file <tmp>
 ```
 
-Parse the returned URL to extract the issue number; update the local finding's `github` block.
+Parse the returned URL for `#N`, then lock it into Synced and record the number:
 
-Update existing:
 ```bash
-gh issue edit <num> --repo <repo> --title "[<Severity>] <title>" --body-file <tmp>
+npx hex issue sync-set <H-id> --issue-number N --issue-url <url> --state open
 ```
 
-(`settings.github.default_labels` in config is retained for backwards compatibility but is no longer applied.)
-
-If push fails for any single finding: capture stderr, set its `github.sync_status` to `conflict`, append a one-line error, continue with the next finding. Never abort the whole sync on one failure.
-
-**3e. Persist** `findings.json` once after all pushes, atomically.
+From now on the finding is identified by `#N`; the next pull matches it by number, so it never duplicates.
 
-## Phase 4 — Status report
+If a single `gh` call fails, log the error and continue with the next candidate — never abort the whole sync.
 
-Write `external/github/sync-status.json`:
-
-```json
-{
-  "repo": "<repo>",
-  "last_synced_at": "<now>",
-  "pushed": <new-created>,
-  "updated": <existing-updated>,
-  "pulled": <total-issues-seen>,
-  "teammate_findings": <count-of-footer-less>,
-  "duplicates_detected": <local-entries-flipped-to-duplicate>,
-  "errors": [<one-line-per-error>]
-}
-```
+## Phase 3 — Status report
 
 Print:
 
 ```
 GitHub sync complete (<repo>)
-  ↑ Pushed N new, updated M
-  ↓ Pulled K issues — J teammate findings, L matched local
-  ⇄ Dedup flipped D local entries to Duplicate (GitHub is canonical)
-<if errors:>
-  Errors:
-    - <error 1>
+  ↓ Pulled K issues (S synced into the board, M skipped as malformed)
+  ↑ Pushed P verified findings as new issues
+  Errors: <n>
 ```
 
-## Conflict resolution defaults
+## Conflict resolution
 
-- **Body content** — local wins on push. Reviewer edits inside `### Affected code` will be overwritten on re-push. Reviewer comments are never touched.
-- **State (open/closed)** — remote wins. Updates the local finding's `github.state`. Surface in the dashboard so the auditor can decide whether to also reject the finding.
-- **Comments** — pull-only. Hex never posts.
+- **Field content** — GitHub wins for synced issues. Every pull overwrites the local finding's title/severity/description/recommendation/status/update from the issue.
+- **State (open/closed)** — from GitHub, stored on `github.state`.
+- **Comments** — Hex never reads or posts comments.
 
 ## Error handling
 
-- Per-issue errors are isolated — log to `errors[]`, continue.
-- Rate limit (403 with "rate limit" in output): print "Rate-limited — sync resumes after <ISO time>." Stop the current phase.
-- Network failures: print the gh error and stop the current phase. Already-completed phases stay persisted.
+- Per-issue errors are isolated — log and continue.
+- Rate limit (403 / "rate limit"): print "Rate-limited — try again later." and stop the current phase.
+- Network failures: print the `gh` error and stop the current phase; completed work stays persisted.
 
 ## What this skill does NOT do
 
-- Does not authenticate (use `gh auth login` once).
-- Does not post comments (auditors discuss inside GitHub).
-- Does not apply, create, or remove labels (the repo owner manages its own labels).
-- Does not delete remote issues.
-- Does not push `rejected`, `unverified`, or `duplicate` findings.
+- Authenticate (use `gh auth login`).
+- Post or read comments.
+- Apply, create, or remove labels (the repo owner manages labels).
+- Embed any hidden footer or marker in the issue body.
+- Delete remote issues.
+- Push `rejected`, `unverified`, `duplicate`, or already-`synced` findings.

package/dist/skills/validate-all-findings.md

@@ -0,0 +1,50 @@
+---
+description: "Walk every Potential issue on the board and validate them one by one (interactive)"
+---
+
+# Skill: Validate All Findings
+
+**Recommended model:** Opus
+
+Runs `/validate-issue` over every issue currently in the **Potential** column, one at a time, so the auditor can clear the backlog in a single pass without naming each id.
+
+## Step 1 — Build the work list
+
+Read `<output_dir>/tracking.json`. The Potential column is every entry whose `status` is `pending_validation` or `unverified`. Collect their ids in a stable order: severity (Critical → High → Medium → Low → Info), then id. Call this list `POTENTIAL` with size `N`.
+
+If `N` is 0, report "No Potential issues to validate." and stop.
+
+## Step 2 — Loop
+
+For each issue `i` of `N` (1-based), print a header:
+
+```
+── Validating i/N: <id> [<severity>] <title> ──
+```
+
+Then run the full **`/validate-issue`** flow for that `<id>` exactly as that skill defines it:
+1. Assemble context (the tracking entry + its source record + the affected source).
+2. Trace the claim in the code.
+3. Reach a verdict:
+   - **Valid** → ask PoC-vs-memo (AskUserQuestion), write the validation memo, optionally generate the PoC, then `hex issue patch <id> ...` + `hex issue move <id> --to verified`; offer the severity-adjustment prompt.
+   - **Invalid** → `hex issue move <id> --to invalid`, memo records why.
+   - **Uncertain** → leave in place, `hex issue patch <id> --notes "<open questions>"`.
+
+Do not batch or skip the interactive prompts — this skill is the same per-issue UX as `/validate-issue`, just iterated. The auditor stays in control of each verdict.
+
+## Step 3 — Resume safety
+
+Re-fetch the entry's current status before validating it (an earlier loop iteration, or a previous run, may have already moved it). Skip any id that is no longer in the Potential column and note it: `Skipping <id> (already <status>)`. This makes the skill safe to re-run after an interruption.
+
+## Step 4 — Summary
+
+After the loop, print a tally:
+
+```
+Validated N Potential issues:
+  → Verified: V
+  → Invalid:  X
+  → Left for review (uncertain): U
+```
+
+Remind the auditor of the next steps: `/sync-issues` to push the Verified findings to GitHub, then `/generate-overleaf` for the report.

package/dist/skills/validate-issue.md

@@ -95,14 +95,14 @@ For conformance items, the "claim" is `spec_text` + the finding paragraph — i.
 
    For a memo-only verdict, the same two commands apply (the PoC fields just stay unset). For `--description-file`, you may pass either the memo or a dedicated description file; prefer a clean description file if the memo is long.
 
-5. **Annotate source files** (this is the one mutation `hex issue` deliberately does NOT do, so it stays explicit). For each location in the finding's `root_cause.locations[]`, replace any `// @audit-issue <id> ...` comment with `// @audit-issue-verified <id> <short title>` (matching indentation), or insert it if absent.
+   Hex does not write `@audit-issue` comments into the client's source files — the board and finding record are the only place the issue lives.
 
-6. Use **AskUserQuestion** to ask:
+5. Use **AskUserQuestion** to ask:
    > Issue verified as **\<id\>** with severity **\<current severity\>**.
    >
    > Would you like to change the severity? Reply with the new severity (Critical / High / Medium / Low / Info), or **no** to keep it.
 
-7. If the user provides a new severity, run `npx hex issue patch <id> --severity <NewSeverity>`.
+6. If the user provides a new severity, run `npx hex issue patch <id> --severity <NewSeverity>`.
 
 **Invalid:**
 

package/dist/skills/write-finding.md

@@ -13,13 +13,13 @@ This skill records a manual issue that the auditor has spotted during review. Th
 Read:
 - The issue description provided by the auditor.
 - The relevant source code.
-- `<output_dir>/findings.json` and `<output_dir>/tracking.json` — to determine the next finding ID. Use the highest existing `F<NNN>` ID across both files and increment by 1. Rejected and invalid findings keep their IDs reserved.
+- `<output_dir>/findings.json` and `<output_dir>/tracking.json` — to check for duplicates (ids are allocated by `hex issue new`, never hand-assigned).
 
 ## Step 0: Duplicate gate
 
 Scan `findings.json` and `tracking.json` for any existing entry that covers the same vulnerability (same affected contract/function, same or overlapping root cause). If a match is found, warn the auditor:
 
-> "This appears to duplicate `F<NNN>`: \<title\>. Proceed anyway?"
+> "This appears to duplicate `<H-NNN>`: \<title\>. Proceed anyway?"
 
 Only continue if confirmed.
 
@@ -51,9 +51,11 @@ Cross-reference both before assigning a severity.
 
 Write the finding following this structure:
 
+The `id`, `poc`, and `created_at` fields are managed by `hex issue new` (see Actions) — you supply the rest via `hex issue patch`. The full record shape, for reference:
+
 ```json
 {
-  "id": "F<NNN>",
+  "id": "H-NNN (allocated by hex issue new)",
   "title": "<concise, descriptive title>",
   "severity": "Critical|High|Medium|Low|Info",
   "category": "<e.g., Math / Rounding, Access Control, Reentrancy, Oracle Manipulation>",
@@ -108,35 +110,28 @@ All inserted audit comments must be full sentences starting with a capital lette
 
 ## Actions
 
-1. **Append the finding** to the `findings` array inside `<output_dir>/findings.json`. File structure is `{ "findings": [...] }` — create with this wrapper if missing.
-2. **Add a tracking entry** to `<output_dir>/tracking.json`. The file MUST be wrapped as `{ "findings": [...] }` (the wrapper key is `findings`, not `issues`); see `init-audit.md` Phase 6 for the canonical schema. Append this entry:
-   ```json
-   {
-     "id": "F<NNN>",
-     "title": "<same as finding>",
-     "severity": "<same as finding>",
-     "source": "manual",
-     "status": "pending_validation",
-     "poc_status": "not_started",
-     "poc_file": null,
-     "duplicates": [],
-     "notes": ""
-   }
+Persist through the `hex issue` CLI — never hand-edit `findings.json` or `tracking.json`. The CLI allocates the uniform `H-NNN` id, writes the tracking entry (`status: pending_validation`, `source: manual`), and creates the findings.json skeleton.
+
+1. **Create the issue:**
+   ```bash
+   npx hex issue new --source manual --title "<concise title>" --severity <Severity>
+   ```
+   This prints the allocated id (e.g. `H-007`). Capture it.
+
+2. **Fill the fields** (write the description and recommendation to temp files first, to preserve newlines):
+   ```bash
+   npx hex issue patch <id> --description-file /tmp/<id>_desc.md --recommendation-file /tmp/<id>_reco.md
    ```
-3. **Annotate source files.** For each entry in `root_cause.locations[]`:
-   - Open the source file at `file`.
-   - Find the first significant line of the `snippet` (skip blank lines and `// ....`).
-   - If an existing `// @audit-issue ...` comment is directly above, replace it with `// @audit-issue F<NNN> <short title>`.
-   - Otherwise insert `// @audit-issue F<NNN> <short title>` directly above, matching indentation.
+   The description must be self-contained (what the issue is, why it exists, the impact). The recommendation is prose only, hedged (`Consider...`), no code.
 
-(The `@audit-issue-verified` annotation comes later, via `/validate-issue` once the issue is promoted to Verified.)
+There is **no source-file annotation** — Hex does not write `@audit-issue` comments into the client's `.sol` files. The board and the finding record are the single place the issue lives.
 
 ## After writing
 
-The finding now appears on the dashboard's `/issues` board as a Potential card. The auditor can:
+The finding appears on the dashboard's `/issues` board as a Potential card (`H-NNN`). The auditor can:
 
-- Run `/validate-issue F<NNN>` to write a validation memo and optionally generate a PoC; on success the card moves to Verified.
-- Drag the card directly from Potential → Verified on the board if they're confident no PoC is needed (e.g., trivial Info-level issues).
-- Run `/sync-issues` if `settings.github.repo` is configured, to push verified findings to the team's GitHub repo.
+- Run `/validate-issue <id>` to write a validation memo and optionally generate a PoC; on success the card moves to Verified.
+- Drag the card from Potential → Verified on the board if no PoC is needed (e.g., trivial Info-level issues).
+- Run `/sync-issues` (once findings are Verified and `settings.github.repo` is set) to push them to GitHub.
 
-Do NOT run `/validate-issue` or `/sync-issues` automatically — those are auditor-driven decisions.
+Do NOT run `/validate-issue` or `/sync-issues` automatically — those are auditor-driven.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "hex-audit",
-  "version": "0.4.5",
+  "version": "0.5.0",
   "type": "module",
   "description": "CLI toolkit for Solidity smart contract auditors",
   "bin": {

package/dashboard/.next/static/chunks/app/issues/page-30f7bcde0f4f6ddb.js

@@ -1 +0,0 @@
-(self.webpackChunk_N_E=self.webpackChunk_N_E||[]).push([[4521],{4260:function(e,t,a){Promise.resolve().then(a.bind(a,7063))},7063:function(e,t,a){"use strict";a.d(t,{IssuesBoardClient:function(){return x}});var r=a(7821),n=a(8078),o=a(3924);let i={Critical:"bg-[var(--critical)]/18 text-[var(--critical)]",High:"bg-[var(--high)]/18 text-[var(--high)]",Medium:"bg-[var(--medium)]/18 text-[var(--medium)]",Low:"bg-[var(--low)]/18 text-[var(--low)]",Info:"bg-[var(--info)]/18 text-[var(--info)]"};function s(e){var t;let{severity:a}=e,n=null!==(t=i[a])&&void 0!==t?t:i.Info;return(0,r.jsx)("span",{className:"inline-flex items-center rounded-md px-2 py-0.5 text-caption font-medium ".concat(n),children:a})}let l=[{id:"potential",label:"Potential",description:"Awaiting validation"},{id:"verified",label:"Verified",description:"Confirmed issues ready to report"},{id:"invalid",label:"Invalid",description:"Rejected after review"},{id:"duplicate",label:"Duplicate",description:"Covered by another entry"}],c={Critical:0,High:1,Medium:2,Low:3,Info:4},d=["Critical","High","Medium","Low","Info"],u=["Fixed","Mitigated","Acknowledged","Not Fixed","Unresolved"];function x(e){var t;let{issues:a,formatCtx:i={}}=e,[s,d]=(0,n.useState)(a),[u,x]=(0,n.useState)(null),[f,b]=(0,n.useState)("all");(0,n.useEffect)(()=>{d(a)},[a]);let h=(0,o.Dy)((0,o.VT)(o.we,{activationConstraint:{distance:4}})),g=(0,n.useMemo)(()=>"all"===f?s:s.filter(e=>e.source===f),[s,f]),y=(0,n.useMemo)(()=>{let e={potential:[],verified:[],invalid:[],duplicate:[]};for(let t of g)e[t.column].push(t);for(let t of Object.values(e))t.sort((e,t)=>{var a,r;return(null!==(a=c[e.severity])&&void 0!==a?a:5)-(null!==(r=c[t.severity])&&void 0!==r?r:5)||e.id.localeCompare(t.id)});return e},[g]),j=(0,n.useMemo)(()=>{let e={potential:0,verified:0,invalid:0,duplicate:0};for(let t of s)e[t.column]++;return e},[s]),N=(0,n.useCallback)(async(e,t)=>{d(a=>a.map(a=>a.id===e?{...a,column:t,status:function(e){switch(e){case"potential":return"pending_validation";case"verified":return"verified";case"invalid":return"rejected";case"duplicate":return"duplicate"}}(t),duplicate_of:"duplicate"===t?a.duplicate_of:null}:a));try{let a=await fetch("/api/issues/".concat(encodeURIComponent(e),"/move"),{method:"POST",headers:{"Content-Type":"application/json"},body:JSON.stringify({column:t})});if(!a.ok){var r;let e=await a.json().catch(()=>({}));throw Error(null!==(r=e.error)&&void 0!==r?r:"move failed")}}catch(t){console.error(t),d(t=>t.map(t=>{var r;return t.id===e&&null!==(r=a.find(t=>t.id===e))&&void 0!==r?r:t}))}},[a]),w=(0,n.useCallback)(async(e,t)=>{d(a=>a.map(a=>a.id===e?{...a,...t}:a));try{let r=await fetch("/api/issues/".concat(encodeURIComponent(e)),{method:"PATCH",headers:{"Content-Type":"application/json"},body:JSON.stringify(t)});if(!r.ok){var a;let e=await r.json().catch(()=>({}));throw Error(null!==(a=e.error)&&void 0!==a?a:"update failed")}}catch(e){console.error(e)}},[]),_=null!==(t=s.find(e=>e.id===u))&&void 0!==t?t:null;return(0,r.jsxs)("div",{children:[(0,r.jsxs)("header",{className:"mb-6 flex flex-wrap items-end justify-between gap-3",children:[(0,r.jsxs)("div",{children:[(0,r.jsx)("h1",{className:"text-title font-semibold text-text-primary",children:"Issues"}),(0,r.jsxs)("p",{className:"mt-1 text-body text-text-secondary",children:[s.length," total — ",j.potential," potential, ",j.verified," verified,"," ",j.invalid," invalid, ",j.duplicate," duplicate. Drag a card to change column; click to edit."]})]}),(0,r.jsx)(m,{value:f,onChange:b})]}),(0,r.jsx)(o.LB,{sensors:h,onDragEnd:e=>{let{active:t,over:a}=e;if(!a)return;let r=a.id,n=t.id,o=s.find(e=>e.id===n);o&&o.column!==r&&N(n,r)},children:(0,r.jsx)("div",{className:"grid grid-cols-1 gap-3 md:grid-cols-2 xl:grid-cols-4",children:l.map(e=>(0,r.jsx)(p,{column:e,issues:y[e.id],onOpen:x},e.id))})}),_&&(0,r.jsx)(v,{issue:_,formatCtx:i,onClose:()=>x(null),onSave:e=>w(_.id,e)})]})}function m(e){let{value:t,onChange:a}=e;return(0,r.jsx)("div",{className:"flex flex-wrap gap-1.5",children:[{id:"all",label:"All sources"},{id:"manual",label:"Manual"},{id:"auditagent",label:"AuditAgent"},{id:"conformance",label:"Conformance"},{id:"github",label:"GitHub"}].map(e=>{let n=t===e.id;return(0,r.jsx)("button",{type:"button",onClick:()=>a(e.id),className:"rounded-md px-2.5 py-1 text-caption font-medium ".concat(n?"bg-accent text-surface-0":"bg-surface-2 text-text-secondary hover:text-text-primary"),children:e.label},e.id)})})}function p(e){let{column:t,issues:a,onOpen:n}=e,{isOver:i,setNodeRef:s}=(0,o.Zj)({id:t.id});return(0,r.jsxs)("section",{ref:s,"aria-label":t.label,className:"flex flex-col gap-2 rounded-lg border bg-surface-1 p-3 transition-colors ".concat(i?"border-accent bg-surface-2":"border-border-subtle"),children:[(0,r.jsxs)("header",{className:"flex items-baseline justify-between",children:[(0,r.jsx)("h2",{className:"text-heading font-medium text-text-primary",children:t.label}),(0,r.jsx)("span",{className:"text-caption text-text-tertiary",children:a.length})]}),(0,r.jsx)("p",{className:"text-caption text-text-tertiary",children:t.description}),(0,r.jsxs)("div",{className:"mt-1 flex flex-col gap-2",children:[a.map(e=>(0,r.jsx)(f,{issue:e,onOpen:n},e.id)),0===a.length&&(0,r.jsx)("div",{className:"rounded-md border border-dashed border-border-subtle py-6 text-center text-caption text-text-tertiary",children:"Empty"})]})]})}function f(e){let{issue:t,onOpen:a}=e,{attributes:n,listeners:i,setNodeRef:l,isDragging:c,transform:d}=(0,o.O1)({id:t.id}),u=d?{transform:"translate3d(".concat(d.x,"px, ").concat(d.y,"px, 0)"),zIndex:30}:{};return(0,r.jsxs)("article",{ref:l,style:u,...n,...i,onClick:e=>{d||(e.stopPropagation(),a(t.id))},className:"group cursor-grab rounded-md border bg-surface-0 p-3 text-left active:cursor-grabbing ".concat(c?"border-accent shadow-lg":"border-border-subtle hover:border-border-default"),children:[(0,r.jsxs)("div",{className:"flex items-start justify-between gap-2",children:[(0,r.jsx)("span",{className:"font-mono text-caption text-text-tertiary",children:t.id}),(0,r.jsx)(s,{severity:t.severity})]}),(0,r.jsx)("h3",{className:"mt-1 text-body font-medium text-text-primary line-clamp-2",children:t.title}),(0,r.jsxs)("div",{className:"mt-2 flex flex-wrap items-center gap-1.5 text-caption",children:[(0,r.jsx)(b,{source:t.source}),(0,r.jsx)(h,{issue:t}),t.duplicate_of&&(0,r.jsxs)("span",{className:"rounded-md bg-surface-2 px-1.5 py-0.5 text-text-secondary",children:["dup of ",t.duplicate_of]}),"passing"===t.poc_status&&(0,r.jsx)("span",{className:"rounded-md bg-[var(--low)]/15 px-1.5 py-0.5 text-[var(--low)]",children:"PoC ✓"}),"failing"===t.poc_status&&(0,r.jsx)("span",{className:"rounded-md bg-[var(--critical)]/15 px-1.5 py-0.5 text-[var(--critical)]",children:"PoC ✕"}),t.resolution&&(0,r.jsx)("span",{className:"rounded-md bg-surface-2 px-1.5 py-0.5 text-text-secondary",children:t.resolution})]}),t.match_signals&&(0,r.jsx)("div",{className:"mt-2 text-caption text-text-tertiary",children:(0,r.jsx)("span",{className:"font-mono",children:[t.match_signals.contract?"contract":null,t.match_signals.function?"function":null,"different"!==t.match_signals.root_cause?"rc:".concat(t.match_signals.root_cause):null,"different"!==t.match_signals.attack_vector?"av:".concat(t.match_signals.attack_vector):null].filter(Boolean).join(" \xb7 ")})})]})}function b(e){var t;let{source:a}=e;return(0,r.jsx)("span",{className:"rounded-md bg-surface-2 px-1.5 py-0.5 text-text-tertiary",children:null!==(t=({manual:"Manual",auditagent:"AuditAgent",conformance:"Conformance",github:"GitHub"})[a])&&void 0!==t?t:a})}function h(e){var t,a;let{issue:n}=e,o=null!==(t=n.sync_state)&&void 0!==t?t:"none";if("none"===o)return null;if("unsynced"===o)return(0,r.jsx)("span",{title:"Run /sync-issues to push verified findings to GitHub.",className:"rounded-md border border-dashed border-border-default px-1.5 py-0.5 text-text-tertiary",children:"GH unsynced"});if("conflict"===o)return(0,r.jsx)("span",{title:"Local and remote diverged. Re-run /sync-issues to reconcile.",className:"rounded-md bg-[var(--critical)]/15 px-1.5 py-0.5 text-[var(--critical)]",children:"GH conflict"});let i="synced_closed"===o,s="GH #".concat(null!==(a=n.github_issue_number)&&void 0!==a?a:"?"," ").concat(i?"closed":"open"),l=i?"bg-surface-2 text-text-tertiary":"bg-[var(--low)]/15 text-[var(--low)]";return n.github_issue_url?(0,r.jsx)("a",{href:n.github_issue_url,target:"_blank",rel:"noopener noreferrer",onClick:e=>e.stopPropagation(),className:"rounded-md px-1.5 py-0.5 hover:underline ".concat(l),children:s}):(0,r.jsx)("span",{className:"rounded-md px-1.5 py-0.5 ".concat(l),children:s})}function v(e){var t,a,o;let{issue:i,formatCtx:s,onClose:l,onSave:c}=e,[x,m]=(0,n.useState)(i.title),[p,f]=(0,n.useState)(i.severity),[v,y]=(0,n.useState)(i.description),[j,N]=(0,n.useState)(i.recommendation),[w,_]=(0,n.useState)(null!==(t=i.resolution)&&void 0!==t?t:""),[C,k]=(0,n.useState)(null!==(a=i.update_from_client)&&void 0!==a?a:""),[S,M]=(0,n.useState)(!1),[H,E]=(0,n.useState)(!1),I=(0,n.useRef)(null);(0,n.useEffect)(()=>{var e;null===(e=I.current)||void 0===e||e.focus()},[]);let R=async()=>{let e=function(e){let t=arguments.length>1&&void 0!==arguments[1]?arguments[1]:{};return"## [".concat(e.severity,"] ").concat(e.title,"\n\n").concat(function(e,t){var a;let r=new Set,n=e.code_locations.map(e=>e.file).filter(e=>e&&!r.has(e)&&r.add(e)).map(e=>(function(e,t){if(t.repositoryUrl&&t.commit){let a=t.repositoryUrl.replace(/\/+$/,"");return"[`".concat(e,"`](").concat(a,"/blob/").concat(t.commit,"/").concat(e,")")}return"[`".concat(e,"`]()")})(e,t)).join(", "),o=e.resolution||"Unresolved",i=null!==(a=e.update_from_client)&&void 0!==a?a:"";return["**File(s)**: ".concat(n),"","**Description**: ".concat(e.description),"","**Recommendation(s)**: ".concat(e.recommendation),"","**Status**: ".concat(o),"","**Update from the client**: ".concat(i)].join("\n")}(e,t),"\n")}({...i,title:x,severity:p,description:v,recommendation:j,resolution:w||void 0,update_from_client:C||void 0},s);try{await navigator.clipboard.writeText(e),E(!0),setTimeout(()=>E(!1),1500)}catch(e){}},D=async()=>{M(!0),await c({title:x,severity:p,description:v,recommendation:j,resolution:w||void 0,update_from_client:C||void 0}),M(!1),l()};return(0,r.jsx)("div",{ref:I,tabIndex:-1,className:"fixed inset-0 z-50 flex items-center justify-center p-4 outline-none",style:{background:"var(--overlay-bg)"},onClick:l,onKeyDown:e=>{"Escape"===e.key&&l()},children:(0,r.jsxs)("div",{role:"dialog","aria-modal":"true","aria-label":"Edit issue ".concat(i.id),className:"relative flex max-h-[90vh] w-full max-w-2xl flex-col overflow-hidden border border-border-emphasis bg-surface-1 shadow-2xl",style:{borderRadius:"var(--radius-md)",boxShadow:"var(--shadow-accent)"},onClick:e=>e.stopPropagation(),children:[(0,r.jsxs)("div",{className:"flex items-center justify-between border-b border-border-default bg-surface-2 px-4 py-3",children:[(0,r.jsxs)("div",{className:"flex items-center gap-2 text-caption",children:[(0,r.jsx)("span",{className:"font-mono text-body text-text-tertiary",children:i.id}),(0,r.jsx)(b,{source:i.source}),(0,r.jsx)(h,{issue:i})]}),(0,r.jsx)("button",{type:"button",onClick:l,"aria-label":"Close",className:"rounded p-1 text-text-tertiary hover:bg-surface-3 hover:text-text-primary",children:(0,r.jsx)("svg",{className:"h-5 w-5","aria-hidden":"true",fill:"none",viewBox:"0 0 24 24",stroke:"currentColor",strokeWidth:2,children:(0,r.jsx)("path",{strokeLinecap:"round",strokeLinejoin:"round",d:"M6 18L18 6M6 6l12 12"})})})]}),(0,r.jsxs)("div",{className:"flex-1 overflow-y-auto p-4",children:[(0,r.jsx)(g,{label:"Title",children:(0,r.jsx)("input",{type:"text",value:x,onChange:e=>m(e.target.value),className:"w-full rounded-md border border-border-default bg-surface-0 px-3 py-2 text-body text-text-primary focus:border-accent focus:outline-none"})}),(0,r.jsxs)("div",{className:"mt-3 grid grid-cols-2 gap-3",children:[(0,r.jsx)(g,{label:"Severity",children:(0,r.jsx)("select",{value:p,onChange:e=>f(e.target.value),className:"w-full rounded-md border border-border-default bg-surface-0 px-3 py-2 text-body text-text-primary focus:border-accent focus:outline-none",children:d.map(e=>(0,r.jsx)("option",{value:e,children:e},e))})}),(0,r.jsx)(g,{label:"Resolution (verified only)",children:(0,r.jsxs)("select",{value:w,onChange:e=>_(e.target.value),className:"w-full rounded-md border border-border-default bg-surface-0 px-3 py-2 text-body text-text-primary focus:border-accent focus:outline-none",children:[(0,r.jsx)("option",{value:"",children:"— none —"}),u.map(e=>(0,r.jsx)("option",{value:e,children:e},e))]})})]}),(0,r.jsx)(g,{label:"Description",className:"mt-3",children:(0,r.jsx)("textarea",{value:v,onChange:e=>y(e.target.value),rows:8,className:"w-full rounded-md border border-border-default bg-surface-0 px-3 py-2 font-mono text-caption text-text-primary focus:border-accent focus:outline-none"})}),(0,r.jsx)(g,{label:"Recommendation",className:"mt-3",children:(0,r.jsx)("textarea",{value:j,onChange:e=>N(e.target.value),rows:4,className:"w-full rounded-md border border-border-default bg-surface-0 px-3 py-2 font-mono text-caption text-text-primary focus:border-accent focus:outline-none"})}),(0,r.jsx)(g,{label:"Update from the client",className:"mt-3",children:(0,r.jsx)("textarea",{value:C,onChange:e=>k(e.target.value),rows:4,placeholder:"How the client responded — used by /generate-overleaf.",className:"w-full rounded-md border border-border-default bg-surface-0 px-3 py-2 font-mono text-caption text-text-primary focus:border-accent focus:outline-none"})}),i.code_locations.length>0&&(0,r.jsxs)("div",{className:"mt-4",children:[(0,r.jsx)("div",{className:"mb-1 text-caption font-medium text-text-tertiary",children:"Code locations"}),(0,r.jsx)("ul",{className:"space-y-1 font-mono text-caption text-text-secondary",children:i.code_locations.map((e,t)=>(0,r.jsx)("li",{children:e.file},"".concat(e.file,"-").concat(t)))})]}),i.match_signals&&(0,r.jsxs)("div",{className:"mt-4",children:[(0,r.jsx)("div",{className:"mb-1 text-caption font-medium text-text-tertiary",children:"Duplicate signals"}),(0,r.jsx)("p",{className:"text-caption text-text-secondary",children:null!==(o=i.reasoning)&&void 0!==o?o:"Matched against another entry."}),(0,r.jsxs)("div",{className:"mt-1 flex flex-wrap gap-1.5 font-mono text-caption text-text-tertiary",children:[(0,r.jsxs)("span",{children:["contract: ",i.match_signals.contract?"✓":"—"]}),(0,r.jsxs)("span",{children:["function: ",i.match_signals.function?"✓":"—"]}),(0,r.jsxs)("span",{children:["root_cause: ",i.match_signals.root_cause]}),(0,r.jsxs)("span",{children:["attack_vector: ",i.match_signals.attack_vector]})]})]})]}),(0,r.jsxs)("div",{className:"flex items-center justify-between gap-2 border-t border-border-default bg-surface-2 px-4 py-3",children:[(0,r.jsx)("button",{type:"button",onClick:R,className:"rounded-md border border-border-default px-3 py-1.5 text-body text-text-secondary hover:bg-surface-3 hover:text-text-primary",children:H?"Copied!":"Copy as HackMD"}),(0,r.jsxs)("div",{className:"flex items-center gap-2",children:[(0,r.jsx)("button",{type:"button",onClick:l,className:"rounded-md px-3 py-1.5 text-body text-text-secondary hover:text-text-primary",children:"Cancel"}),(0,r.jsx)("button",{type:"button",onClick:D,disabled:S,className:"rounded-md bg-accent px-3 py-1.5 text-body font-medium text-surface-0 hover:bg-accent-secondary disabled:opacity-50",children:S?"Saving…":"Save"})]})]})]})})}function g(e){let{label:t,className:a,children:n}=e;return(0,r.jsxs)("label",{className:"block ".concat(null!=a?a:""),children:[(0,r.jsx)("span",{className:"mb-1 block text-caption font-medium text-text-tertiary",children:t}),n]})}}},function(e){e.O(0,[3924,7115,3205,1744],function(){return e(e.s=4260)}),_N_E=e.O()}]);