hex-audit 0.4.4 → 0.5.0

package/dist/skills/sync-issues.md

@@ -1,266 +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
+## Context
 
-**0a. `gh` installed and authenticated?** Run `gh auth status`. If non-zero exit, print:
+- `<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).
 
-```
-gh CLI is not authenticated. Run `gh auth login` once on this machine, then re-run /sync-issues.
-```
-
-…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`.
+**1b. Parse each issue.** Title is `[Severity] Title`. Body is the five-field template:
 
-For each issue whose `updatedAt` is newer than the prior `last_synced_at`, fetch comments:
-
-```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.
-
-## Phase 3 — Push
-
-Skip if `push_enabled = false`.
-
-**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).
 
-Within candidates:
-- Has `github.issue_number` → update via `gh issue edit`.
-- No `github.issue_number` → create via `gh issue create`.
+Either way the card lands in the **Synced** column, locked. Reconcile strictly by `#N`; never scan the body for an identifier.
 
-**3b. Render the body** (write to a temp file, then `--body-file`):
+## Phase 1.5 — Dedup before push (GitHub is canonical)
 
-```markdown
-**Severity:** <Severity>
+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:
 
-<finding.description>
+| 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 |
 
-### Affected code
+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`.
 
-<for each finding.root_cause.locations[]>
-**`<location.file>`**
+On match — the synced (on-GitHub) finding is canonical, so the local verified copy becomes the duplicate. Do **not** push it:
 
-```solidity
-<location.snippet>
+```bash
+npx hex issue move <verified-H-id> --to duplicate --duplicate-of <synced-H-id>
 ```
-</for>
-
-### Recommendation
-
-<finding.recommendation>
-
----
 
-*Synced from Hex audit `<config.project.name>` at commit `<config.project.commit>`.*
+Then append to `<output_dir>/comparison.json` under `duplicates` (the board renders the chip + signals from this):
 
-<!-- hex-finding-id: <finding.id> -->
+```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>" }
 ```
 
-The footer is the round-trip identity key — never omit.
+If `comparison.json` doesn't exist, create it with `{ "duplicates": [], "novel": [], "rejected": [] }`.
 
-**3c. Labels.**
+## Phase 2 — Push (verified local findings → GitHub)
 
-```
-<default_labels...> severity:<lowercased> source:<finding.source or 'manual'> status:<tracking.status>
-```
+Skip if `push_enabled` is false.
 
-Apply via repeated `--label` flags.
+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.)
 
-**3d. Create or update.**
+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> \
-  --label "hex" --label "audit" --label "severity:..." --label "source:..." --label "status:..."
+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> \
-  --add-label "severity:..." --add-label "status:..."
+npx hex issue sync-set <H-id> --issue-number N --issue-url <url> --state open
 ```
 
-Do NOT `--remove-label` — teammates may have added labels we shouldn't strip.
-
-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.
+From now on the finding is identified by `#N`; the next pull matches it by number, so it never duplicates.
 
-**3e. Persist** `findings.json` once after all pushes, atomically.
+If a single `gh` call fails, log the error and continue with the next candidate — never abort the whole sync.
 
-## Phase 4 — Status report
-
-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 create labels (manual one-time setup; `gh issue create` errors if a label is missing).
-- 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

@@ -77,22 +77,32 @@ For conformance items, the "claim" is `spec_text` + the finding paragraph — i.
    >
    > Reply **1** or **2**.
 
-2. **If PoC chosen:** invoke the `generate-poc` skill flow (read the project test setup, write the PoC, run and iterate until it passes). Set `poc.status = "passing"`, `poc.file = "test/hex-pocs/<id>_<name>.t.sol"`.
+2. **If PoC chosen:** invoke the `generate-poc` skill flow (read the project test setup, write the PoC, run and iterate until it passes). Note the test path, e.g. `test/hex-pocs/<id>_<name>.t.sol`.
 
-3. **If memo-only chosen:** leave `poc.status = "not_started"`, `poc.file = null`.
+3. **If memo-only chosen:** no PoC file.
 
-4. If the issue source is **conformance**, **auditagent**, or **github** (no manual finding record yet), invoke the `write-finding` skill flow to materialize a structured finding into `<output_dir>/findings.json` — reusing the existing tracking id. If `source = "manual"`, the finding already exists; update its `poc` block in place.
+4. **Persist via the CLI — do not hand-edit `findings.json` or `tracking.json`.** The `hex issue` command is the single source of truth for board mutations; it materializes a `findings.json` entry from the source record (conformance / auditagent / github) when one does not exist yet, and routes fields correctly. Write the validation memo and the recommendation to temp files, then:
 
-5. Update the tracking entry: `status = "verified"`, `poc_status` per choice above, `poc_file` per choice above.
+   ```bash
+   # Land the editable fields (materializes a finding for conformance/auditagent/github ids):
+   npx hex issue patch <id> \
+     --severity <Severity> \
+     --description-file <output_dir>/validations/<id>_memo.md \
+     --recommendation-file /tmp/<id>_reco.md
+   # Promote to Verified:
+   npx hex issue move <id> --to verified
+   ```
 
-6. For source files in `root_cause.locations[]`, replace any `// @audit-issue F<NNN>` annotation with `// @audit-issue-verified F<NNN> <short title>` (matching indentation).
+   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.
 
-7. Use **AskUserQuestion** to ask:
+   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.
+
+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.
 
-8. If the user provides a new severity, update both `findings.json` and `tracking.json`.
+6. If the user provides a new severity, run `npx hex issue patch <id> --severity <NewSeverity>`.
 
 **Invalid:**
 
@@ -100,14 +110,14 @@ For conformance items, the "claim" is `spec_text` + the finding paragraph — i.
    - Is the attack path blocked? By what specifically (modifier, require, state check)?
    - Are the preconditions impossible? Why?
    - Is the impact assessment wrong? What actually happens?
-2. Update tracking: `status = "rejected"`.
-3. Do NOT write a finding to `findings.json`. The memo alone records the reasoning.
+2. Move it to the Invalid column: `npx hex issue move <id> --to invalid`.
+3. Do NOT write a finding body. The memo alone records the reasoning.
 
 **Uncertain:**
 
 1. List specific questions that need manual investigation.
 2. State what would confirm or deny the issue.
-3. Leave tracking `status` as-is. Append findings to the `notes` field describing the open questions.
+3. Leave the column as-is (no `hex issue move`). Record the open questions on the card: `npx hex issue patch <id> --notes "<open questions>"`.
 
 ## Output: validation memo
 

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` with:
-   ```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.4",
+  "version": "0.5.0",
   "type": "module",
   "description": "CLI toolkit for Solidity smart contract auditors",
   "bin": {

package/dashboard/.next/server/app/api/flows.body

@@ -1 +0,0 @@
-{"flows":[]}

package/dashboard/.next/server/app/api/flows.meta

@@ -1 +0,0 @@
-{"status":200,"headers":{"content-type":"application/json","x-next-cache-tags":"_N_T_/layout,_N_T_/api/layout,_N_T_/api/flows/layout,_N_T_/api/flows/route,_N_T_/api/flows"}}

package/dashboard/.next/static/chunks/app/issues/page-dc110d4cc0a5c398.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,6310))},6310:function(e,t,a){"use strict";a.d(t,{IssuesBoardClient:function(){return x}});var r=a(7821),n=a(8078),s=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 o(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}=e,[i,o]=(0,n.useState)(a),[d,u]=(0,n.useState)(null),[x,f]=(0,n.useState)("all");(0,n.useEffect)(()=>{o(a)},[a]);let b=(0,s.Dy)((0,s.VT)(s.we,{activationConstraint:{distance:4}})),v=(0,n.useMemo)(()=>"all"===x?i:i.filter(e=>e.source===x),[i,x]),g=(0,n.useMemo)(()=>{let e={potential:[],verified:[],invalid:[],duplicate:[]};for(let t of v)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},[v]),y=(0,n.useMemo)(()=>{let e={potential:0,verified:0,invalid:0,duplicate:0};for(let t of i)e[t.column]++;return e},[i]),j=(0,n.useCallback)(async(e,t)=>{o(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),o(t=>t.map(t=>{var r;return t.id===e&&null!==(r=a.find(t=>t.id===e))&&void 0!==r?r:t}))}},[a]),N=(0,n.useCallback)(async(e,t)=>{o(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)}},[]),w=null!==(t=i.find(e=>e.id===d))&&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:[i.length," total — ",y.potential," potential, ",y.verified," verified,"," ",y.invalid," invalid, ",y.duplicate," duplicate. Drag a card to change column; click to edit."]})]}),(0,r.jsx)(m,{value:x,onChange:f})]}),(0,r.jsx)(s.LB,{sensors:b,onDragEnd:e=>{let{active:t,over:a}=e;if(!a)return;let r=a.id,n=t.id,s=i.find(e=>e.id===n);s&&s.column!==r&&j(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:g[e.id],onOpen:u},e.id))})}),w&&(0,r.jsx)(h,{issue:w,onClose:()=>u(null),onSave:e=>N(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:o}=(0,s.Zj)({id:t.id});return(0,r.jsxs)("section",{ref:o,"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,s.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)(o,{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}),t.github_synced&&(0,r.jsxs)("a",{href:t.github_issue_url,target:"_blank",rel:"noopener noreferrer",onClick:e=>e.stopPropagation(),className:"rounded-md bg-surface-2 px-1.5 py-0.5 text-text-secondary hover:bg-surface-3 hover:text-text-primary",children:["GH ","closed"===t.github_state?"✕":"✓"]}),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,s;let{issue:i,onClose:o,onSave:l}=e,[c,x]=(0,n.useState)(i.title),[m,p]=(0,n.useState)(i.severity),[f,h]=(0,n.useState)(i.description),[g,y]=(0,n.useState)(i.recommendation),[j,N]=(0,n.useState)(null!==(t=i.resolution)&&void 0!==t?t:""),[w,_]=(0,n.useState)(null!==(a=i.update_from_client)&&void 0!==a?a:""),[C,k]=(0,n.useState)(!1),S=(0,n.useRef)(null);(0,n.useEffect)(()=>{var e;null===(e=S.current)||void 0===e||e.focus()},[]);let M=async()=>{k(!0),await l({title:c,severity:m,description:f,recommendation:g,resolution:j||void 0,update_from_client:w||void 0}),k(!1),o()};return(0,r.jsx)("div",{ref:S,tabIndex:-1,className:"fixed inset-0 z-50 flex items-center justify-center p-4 outline-none",style:{background:"var(--overlay-bg)"},onClick:o,onKeyDown:e=>{"Escape"===e.key&&o()},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",children:[(0,r.jsx)("span",{className:"font-mono text-body text-text-tertiary",children:i.id}),(0,r.jsx)(b,{source:i.source}),i.github_synced&&i.github_issue_url&&(0,r.jsx)("a",{href:i.github_issue_url,target:"_blank",rel:"noopener noreferrer",className:"rounded-md bg-surface-3 px-1.5 py-0.5 text-caption text-text-secondary hover:text-text-primary",children:"GitHub issue"})]}),(0,r.jsx)("button",{type:"button",onClick:o,"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)(v,{label:"Title",children:(0,r.jsx)("input",{type:"text",value:c,onChange:e=>x(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)(v,{label:"Severity",children:(0,r.jsx)("select",{value:m,onChange:e=>p(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)(v,{label:"Resolution (verified only)",children:(0,r.jsxs)("select",{value:j,onChange:e=>N(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)(v,{label:"Description",className:"mt-3",children:(0,r.jsx)("textarea",{value:f,onChange:e=>h(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)(v,{label:"Recommendation",className:"mt-3",children:(0,r.jsx)("textarea",{value:g,onChange:e=>y(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)(v,{label:"Update from the client",className:"mt-3",children:(0,r.jsx)("textarea",{value:w,onChange:e=>_(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!==(s=i.reasoning)&&void 0!==s?s:"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-end gap-2 border-t border-border-default bg-surface-2 px-4 py-3",children:[(0,r.jsx)("button",{type:"button",onClick:o,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:M,disabled:C,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:C?"Saving…":"Save"})]})]})})}function v(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()}]);