hex-audit 0.6.1 → 0.6.3

package/dist/skills/validate-finding.md

@@ -120,7 +120,16 @@ Combine the two axes — correctness (Step 2) and security relevance (Step 2.5):
 
    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.
 
-   Any description you write must be **flat prose** (plus a fenced code block only when a snippet is genuinely needed) — no markdown headings or header-like section labels (`Summary`/`Details`/`Impact`/`Affected code`); weave impact into the prose. **Keep it concise** — a single tight paragraph covering what the issue is, why it exists, and its impact, plus a 1–2 sentence hedged recommendation; trim anything that doesn't drive the point home. This matches the finding template used by the dashboard copy and the GitHub issue body. If the affected files are missing or wrong, set them with `--file` (repeatable) rather than narrating them in the description: `npx hex issue patch <id> --file src/Foo.sol [--file src/Bar.sol]`.
+   Any description you write must be **structured, readable prose** (no markdown headings), not a single dense block. Split it into short paragraphs that separate how the code is supposed to work (expected behavior / the spec), what is wrong (the flaw), and the impact, and include a fenced ```` ```solidity ```` block of the offending code. Do not introduce paragraphs with bold section labels (`**Summary**:`/`**Impact**:`/`**Details**:`/`**Affected code**:`) — the separation is paragraph breaks, not headers. **Backtick every Solidity identifier**, writing functions as `` `functionName(...)` `` with literal `(...)` and contracts/variables/constants in plain backticks; never leave a bare identifier in the prose. Keep each paragraph tight (no padding), and add a 1–2 sentence hedged recommendation. This matches the finding template used by the dashboard copy and the GitHub issue body. If the affected files are missing or wrong, set them with `--file` (repeatable) rather than narrating them in the description: `npx hex issue patch <id> --file src/Foo.sol [--file src/Bar.sol]`.
+
+   **A conformance-sourced (or auditagent/github) finding must be rewritten to the exact same standard as a manual `/write-finding` finding** — do not pass the raw source text through. AuditAgent findings in particular arrive as one long unformatted paragraph; reshape them into the structured, backticked, snippet-bearing form above. Specifically, the prose you land must obey the report-facing content rules:
+   - **Structure + identifiers:** short expected/flaw/impact paragraphs, a ```solidity snippet, every identifier backticked and functions as `` `name(...)` `` (as above).
+   - **Recommendation tone:** hedged (`Consider...`, `One option is...`), never prescriptive (`Replace X with Y`, `You must...`). Follow the project writing style (no em dashes, no banned words / AI giveaways).
+   - **No line numbers — show the code.** Never cite specific source lines ("line 56"); line numbers drift. Use the ```solidity block instead, and refer to code by function/variable name. Do not transcribe line numbers from the conformance item's `code_location` into the prose (that field stays internal, for navigation only).
+   - **Stand alone — no cross-references** to other findings by Hex id (`H-NNN`) or number/title.
+   - **No PoC references** in the description or recommendation.
+
+   **Normalizing legacy findings:** if you are re-run on a finding whose stored description still contains line numbers, `H-NNN` cross-references, or PoC mentions (authored before these rules), rewrite it now: replace line references with a fenced ```` ```solidity ```` block, drop the id/PoC references, and re-land the cleaned prose via `--description-file`. This (followed by `/sync-issues`) is how an already-synced finding gets cleaned; the report never rewrites GitHub-canonical prose itself.
 
    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.
 

package/dist/skills/write-finding.md

@@ -59,7 +59,7 @@ The `id`, `poc`, and `created_at` fields are managed by `hex issue new` (see Act
   "title": "<concise, descriptive title>",
   "severity": "Critical|High|Medium|Low|Info",
   "category": "<e.g., Math / Rounding, Access Control, Reentrancy, Oracle Manipulation>",
-  "description": "<flat prose covering what the vulnerability is, why it exists, and its impact — no markdown headings; see Description format below>",
+  "description": "<short structured paragraphs (expected behavior, the flaw, the impact) with a fenced solidity snippet and every identifier backticked as `name(...)`; no headings or bold section labels — see Description format below>",
   "root_cause": {
     "locations": [
       { "file": "<path>", "snippet": "<relevant code>" }
@@ -90,12 +90,22 @@ Phrase recommendations as suggestions, not commands. The auditor proposes direct
 
 ### Description format (STRICT)
 
-The finding is rendered as a flat template (`## [Severity] Title`, then `**Description**:`, `**Recommendation(s)**:` …). The description goes inline after `**Description**:`, so it must read as **flat prose**:
+The finding is rendered inline after `**Description**:` in the report, so it must be prose (no markdown headings), but it must be **structured and readable**, not a wall of text:
 
-- **No markdown headings and nothing that looks like one** — no `#`/`##`/`###`, and no section labels such as `Summary`, `Details`, `Impact`, `Affected code`, whether as a heading or a bold line on its own. Weave the impact into the prose instead of giving it its own section.
-- **Code blocks are allowed when a snippet is genuinely needed** — a fenced ```` ```solidity ```` block illustrating the bug is fine. Keep it to what's relevant; follow the Code Block Formatting Rules below.
-- Affected file paths belong in `--file` (the File(s) line), not in an "Affected code" section in the description.
-- **Be concise.** Prefer a single tight paragraph: what the issue is, why it exists, and its impact — just enough to drive the point home. Don't restate the title, don't pad with background the reader doesn't need, and don't repeat the recommendation. There's no hard word count; brevity is the goal.
+- **Split into short paragraphs that separate the parts of the finding.** Cover, in order, how the code is supposed to work (the expected behavior or spec), what is wrong (the flaw), and the impact. Give each its own short paragraph rather than one dense block. Look at how a clean finding reads: a paragraph of context/expected behavior, the offending code, then a paragraph on what breaks and why it matters.
+- **No markdown headings and no bold section labels.** The separation is paragraph breaks, not headers. Do not write `#`/`##`, and do not introduce paragraphs with `**Summary**:`, `**Impact**:`, `**Details**:`, `**Affected code**:` or similar labels — those read as machine-generated. Let the prose carry the structure.
+- **Backtick every Solidity identifier** so the report renders it in monospace. Functions are written as `` `functionName(...)` `` with the literal `(...)`, e.g. `` `deposit(...)` ``, `` `sweepTreasury(...)` ``. Contracts, interfaces, variables, constants, and hex/number literals get plain backticks: `` `CardinalExchange` ``, `` `undeployedLpCapital` ``, `` `feeBps` ``. Standard names (ERC-4626, UUPS, ERC-20) stay as plain text. Never leave a bare identifier in the prose.
+- **Show the offending code.** Include a fenced ```` ```solidity ```` block of the relevant lines (with `@audit-issue` comments per the Code Block Formatting Rules below) rather than describing the code only in words. Keep it minimal — just what's needed to see the issue.
+- Affected file paths belong in `--file` (the File(s) line), not narrated in the description.
+- **Be concise within the structure.** Short paragraphs, no padding, don't restate the title or repeat the recommendation. Readable and specific beats long.
+
+### Report-facing content (STRICT)
+
+The description, recommendation, and title end up verbatim in the client's published report. Keep them free of anything that only makes sense inside Hex or that rots when the code moves:
+
+- **Stand alone — no cross-references to other findings.** Never point at another issue by its Hex id (`H-NNN`) or by its number/title ("see H-005", "as in the previous finding"). Report readers have no Hex ids and sections get reordered. If two issues share a mechanism, describe that mechanism inline in each.
+- **No line numbers — show the code.** Do not cite specific source lines ("line 56", "on lines 43, 55"). Line numbers drift the moment code or comments change. Instead embed a minimal fenced ```` ```solidity ```` block in the description showing the relevant code, and refer to it by function or variable name in the prose. (The report renders those blocks; it also renders `root_cause.locations[].snippet` when a materialized finding carries one.)
+- **No PoC references.** Do not name or link the proof-of-concept test or its path. The PoC belongs in the validation memo (`poc.validation_memo`), which the report never renders.
 
 ## Code Block Formatting Rules (STRICT)
 

package/package.json

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