hex-audit 0.6.3 → 0.7.0

package/dist/skills/ai-audit/references/dedup-and-assembly.md

@@ -0,0 +1,420 @@
+# Dedup, record and assembly — Turn 4 and Turn 5
+
+This file holds the two turns that run **after the 12 agents return**: Turn 4
+deduplicates, gates, tags and records each pass, and Turn 5 assembles and prints
+the one report. `SKILL.md` keeps the name of each turn and the condition that
+decides whether it runs; the procedure is here.
+
+The orchestrator reads this file **once, in Turn 3b**, while it waits for the
+agents. It stays in context for the later passes of a loop.
+
+Both turns use `{stamp}`, `{bundle_dir}`, `{passes}`, `{resolved_path}` and
+`{project-name}` exactly as `SKILL.md` set them.
+
+---
+
+## Turn 4
+
+**Turn 4 — Deduplicate, validate & record.** Runs **every pass**, and it is the end of the loop body: deduplicate this pass's agent results, gate-evaluate, tag, record the pass, write the ledger. **It prints no report** — there is exactly one report per scan and Turn 5 prints it. Do NOT print an intermediate dedup list.
+
+> **This turn used to print the report and clean up, and both moved.** The report moved to Turn 5 so that a 1-pass scan and an N-pass scan take the **same** path through this turn — the "1 pass is byte-identical to today" constraint is easier to hold with one report writer than with a last pass that doubles as one. The auto-clean moved to Turn 5 because, left here, pass 1 deletes what pass 2 needs: `source.md`, the ledger photocopy and the accumulating rows file. A later editor must not move either back.
+
+Then, after the loop body has run `{passes}` times (or stopped early), go to Turn 5 once.
+
+1. **Dedup.** Parse every FINDING and LEAD from the 12 agents. Group by `group_key` (Contract | function | bug-class). Exact-match first; merge synonymous bug_class within same (Contract, function). Keep best per group, number sequentially, annotate `[agents: N]`.
+
+   **MANDATORY — Canonicalise the bug-class label (HARD GATE).** Before grouping, for every (Contract, function) whose agents used **more than one** bug-class label, choose **one** label and rewrite every one of those findings to carry it. Then group.
+
+   Choose in this order, and stop at the first that applies:
+   1. A label already listed for that same contract and function in `{bundle_dir}/known-findings.md` — the repository's own word wins, always.
+   2. Otherwise the label that most agents used.
+   3. Otherwise the shortest label that names the **defect**, not its consequence. `zero-abort-address` over `abort-address-zero-burns-funds`.
+
+   Merging under one label is only correct when the labels name the **same class of bug**. Two genuinely different bugs in one function keep two labels and stay two records — function isolation is about functions, and this rule is about words.
+
+   **Why this is a gate and not a nicety.** The per-function vocabulary that keeps a key stable only constrains what an **earlier scan** wrote. A class discovered mid-scan is constrained by nothing, and a real scan proved what follows: three agents in one pass named one bug `zero-abort-address`, `unregistered-abort-address` and `abort-address-zero-burns-funds`, and the over-approval class drew three labels across three passes. Unfixed, that is three ledger records for one bug, three lines in every future `known-findings.md`, and one bug that is never recognised again. This step is the only thing standing between the fork and the ledger. Canonicalise here and the next pass inherits the canonical label, so the fork closes after one scan.
+
+   **MANDATORY — Wide-description (group_key).** Merged group with distinct mechanisms (different `fix:`, code-level cause, or attack path) MUST list every mechanism. No dropping. Same function can have multiple coexisting bugs at the same group_key — all MUST appear.
+
+   **MANDATORY — Function-level second pass (after group_key dedup).** Run at (Contract, function), ignoring bug_class. Agents often label coexisting bugs with different bug_class tags but reference multiple mechanisms in the body. For every (Contract, function) with multiple final findings: scan body (description, path, proof, fix) of every constituent for distinct mechanisms across bug_class boundaries. Every mechanism in any constituent body MUST appear in ≥1 final finding.
+
+   **MANDATORY — Function isolation (HARD).** NEVER merge across different `function:` fields. Dedup only within (Contract, function). Different function = different bug. Second pass above stays WITHIN (Contract, function), never across.
+
+   **MANDATORY — Fix preservation (HARD GATE).** Before writing merged `fix:` on a multi-finding (Contract, function):
+   1. Collect every raw `fix:` from agents flagging the tuple.
+   2. Group by ADD-lines (`+` lines, or equivalent require/assignment).
+   3. Distinct if ADD-lines differ in: called function/expression (e.g., `require(msg.value == amount)` vs `require(zrc20 != _ETH_ADDRESS_)`), check direction (validate/restrict/ban), or checked parameter.
+   4. ≥2 distinct → present as Option A, B, … — one block per distinct fix, verbatim from agent text (no paraphrase).
+   5. Label intuitively: validate / restrict / allow-and-handle / ban-path.
+
+   **Output format when 2+ distinct fixes exist:**
+
+   ```
+   **Fix (Option A — <label>)**:
+
+   ```diff
+   <verbatim diff from raw agent N1's fix>
+   ```
+
+   **Fix (Option B — <label>)**:
+
+   ```diff
+   <verbatim diff from raw agent N2's fix>
+   ```
+   ```
+
+   **Inline check before printing**: count distinct fixes from raw for this (Contract, function). ≥2 distinct but merged shows 1 → violation, add alternatives.
+
+   **MANDATORY — Completeness (HARD GATE).** Before print: list every unique (Contract, function, bug-class) in any raw FINDING/LEAD across the 12 agents. Every unique (Contract, function) MUST have ≥1 item in final. Zero = silent drop, fix it. Multiple bug-class within same (Contract, function) MAY collapse to one item (wide-description), but the (Contract, function) MUST survive. Print inline before report: `Completeness: N unique (Contract, function) in raw, N covered in final.`
+
+   Composite chains: if A's output feeds B's precondition AND combined impact > either alone, add `Chain: [A] + [B]` at conf = min(A, B). Most audits: 0–2.
+
+2. **Gate.** Run each deduped finding through the four gates in `judging.md` (no skip, no reorder, no revisit after verdict).
+
+   **Single-pass:** every relevant code path ONCE in fixed order (constructor → setters → swap → mint → burn → liquidate). One-line verdict: `BLOCKS` / `ALLOWS` / `IRRELEVANT` / `UNCERTAIN`. `UNCERTAIN = ALLOWS`. Commit, no re-examination.
+
+3. **Lead promotion / rejection.**
+   - LEAD → FINDING (conf 75) if: full exploit chain in source, OR `[agents: 2+]` demoted (not rejected) same issue.
+   - `[agents: 2+]` does NOT override a code path that interrupts attack before harm — demote to LEAD if execution uncertain.
+   - No deployer-intent reasoning — what code allows, not how deployer might use it.
+
+4. **Memory tag.** **SKIP this step entirely when memory is off.** It comes before the report, not after it, because the report prints what it decides. It is a **lookup, never a judgment** — no finding is re-argued here, and no verdict from the gate is revisited.
+
+   a. **Build the key** for every gated FINDING and every gated LEAD — the three segments of Turn 4's `group_key`, each normalised **on its own** (lower case, every run of non-alphanumeric characters to one hyphen), then joined with `|`: `vault|withdraw|reentrancy`. Normalise the segments separately, never the joined string, or the separators become hyphens too.
+
+   **The bug-class segment is where memory succeeds or fails.** Before writing a key, read the per-function vocabulary back from `{bundle_dir}/known-findings.md` — the same file the agents were given: *if this finding is one of the bug classes already listed for this same contract and function, write that exact label. Invent a new label only when none of them is the same class of bug.* This is the only judgment in the whole memory path, and it happens when the label is **written** — never at merge time. The keys built here are the keys step 6 writes; build them once.
+
+   b. **Tag each finding and each lead.** Look its key up in the pre-scan key list:
+
+   ```bash
+   tail -n +2 {bundle_dir}/memory-before.tsv | cut -f1,3 | sort > {bundle_dir}/known-keys.tsv
+   ```
+
+   Key present → **KNOWN**, printed as `KNOWN (n scans)` where **n is column 2 plus one**. The scan that is printing has found it again, so the count the report shows is the count the ledger will hold when step 6 has written it — report and file say the same number. Key absent → **NEW**. Nothing else decides this tag.
+
+   The lookup is against the **pre-scan photocopy**, in every pass of a loop. `KNOWN` means "an earlier **scan** recorded this"; a finding first raised by pass 1 of this scan is still `NEW` in pass 3, and how many passes saw it is what `seen in k/N runs` says. Tagging against the live ledger would make pass 2 call this scan's own work old news.
+
+   c. **Write this run's keys** to `{bundle_dir}/run-keys.tsv`, one per line, from step 4a.
+
+   The "Known from earlier scans" rows are **not** built here. They are report work, and a pass that built them could not know what a later pass is about to raise. They are built once, in Turn 5.
+
+5. **Record the pass.** Do NOT print the report.
+
+   a. **Write the run file** to `.hex/ai-audit/runs/{stamp}/run-K.md`, where `K` is the pass number. **Every pass of every scan writes one**, at any pass count, `{passes}` of 1 included. This is the only place this pass's work is recorded, and Turn 5 assembles the report out of these files — a pass that writes no run file has produced nothing the report can print.
+
+   One directory per scan, one file per run; `ls` is history in order. The git SHA goes **inside** the file, not in the directory name, so two scans of the same commit sit side by side instead of colliding. Nothing deletes these files, and `--file-output` does not govern them — they are memory, not reports.
+
+   **The file, exactly:**
+
+   ````markdown
+   # Run K — ai-audit
+
+   <!--RUN pass=K of=N stamp={stamp} sha=abc1234 agents=11/12-->
+
+   Pass K of N · <date> · `abc1234` · 11/12 agents returned — the access-control agent died.
+
+   ## Findings
+
+   <finding blocks, kind=FINDING>
+
+   ## Leads
+
+   <finding blocks, kind=LEAD>
+   ````
+
+   The sentence is for the human; the `<!--RUN-->` marker is what shell reads. `agents=11/12` is where the `Passes` row gets its degradation text, so a lost agent is on disk and not only in a printed line that scrolls away — and the dead agent's **name** stays here, in the sentence, and never enters the Scope table.
+
+   **These two headings and no others, in every run.** No `## New findings` in a later run — newness is already carried by the `NEW` / `KNOWN` tag and by `seen in k/N runs`, and a heading saying it again is a second source of truth that can disagree with the first. **No "verified clean", "checked" or "sound" section, under any name.** A path a pass did not raise is not a path a pass cleared, and a real scan invented such a section unasked. Nothing ever reads it back, and it is the same overstated-coverage defect this whole design exists to kill.
+
+   **The finding block, exactly:**
+
+   ````markdown
+   <!--F key=contract|function|bug-class conf=95 kind=FINDING agents=8-->
+
+   [95] **<Title>**
+
+   `ContractName.functionName` · Confidence: 95
+
+   **Description**
+   <the vulnerable pattern and why it is exploitable, 1 short sentence>
+
+   **Fix**
+
+   ```diff
+   - vulnerable line(s)
+   + fixed line(s)
+   ```
+
+   <!--/F-->
+   ````
+
+   - **The markers bound the block.** `<!--F ` opens it, `<!--/F-->` closes it, each on its own line at the start of the line. **Never `---`**: today's separator also appears inside a unified diff (`--- a/Vault.sol`), so it cannot cut a block that now carries one. The HTML comment renders invisible, so the file still reads as human memory.
+   - **`key`** — exactly the key step 4a built, unchanged. Never re-derived here. The same key the ledger stores, so the run file and `memory.tsv` agree by construction.
+     **Hex: a key is built on every scan, memory on or off.** Turn 6 uses it to keep the board idempotent: a re-scan that raises the same key does not file a second card. When memory is off, step 4 is skipped, so build the key here exactly as step 4a describes (normalise each segment on its own, join with `|`) using the label step 1 canonicalised; with no `known-findings.md` there is no vocabulary to read back. Building a key reads no ledger and writes no file, so the plain path stays plain.
+   - **`conf`** — an integer, on `kind=FINDING` blocks only. **A `kind=LEAD` block carries no `conf` attribute at all** — a lead is not scored, and writing `0` would sort it against real numbers.
+   - **`kind`** — `FINDING` or `LEAD`.
+   - **`agents`** — carried from `[agents: 8]`. Informational; nothing parses it.
+
+   **Write the markers exactly as printed.** They are the only thing standing between a finding and a silent loss: the assembler counts open markers against close markers against readable blocks, and a disagreement becomes a visible `**Run files**` row in the report saying how many findings could not be read. The report may print **less** than the scan found; it may never claim to print **more**. A fudged marker costs a visible warning, not a hidden hole — but it still costs the finding.
+
+   **Above and below the threshold, the block shape is identical.** A block whose `conf` is below 75 simply has no `**Fix**` section. The run file does **not** mark which side of the line a finding sits on; the assembler re-derives that from `conf`. One source of truth.
+
+   **Write the Description and the diff Fix block here, in full.** This is the expensive per-finding writing, and it is paid **now**, in the pass that found the bug, while that pass still has context to spare. Turn 5 re-words nothing — it pastes these bytes into the report. An orchestrator drafting seventy findings at the end of a long scan is the failure this ordering exists to prevent.
+
+   **The title and the Description are written in Simplified Technical English**, per `{resolved_path}/report-language.md`, which Turn 2 read. Because Turn 5 re-words nothing, this is the **only** step where the report's sentences can be made readable — there is no later cleanup pass and there must never be one. Four pieces of text obey that file: the title, the Description, the Lead description, and the Lead's code-smell list.
+
+   Three things it does **not** reach, and a later editor must not extend it to them: the **diff** inside the Fix block, which is pasted verbatim from the agent, the **bug-class label** in the `key` attribute, which is a memory key and is chosen by step 1 and step 4a, and the **identifiers** on the location line, which are spelled as the source spells them. Softening a label to read better writes a second ledger record for one bug.
+
+   Where the agent handed up a sentence that already meets the rules, keep the agent's words. Where it did not — a metaphor, an `-ing` clause, forty words, `catastrophic` — rewrite the sentence and keep the claim. Rewriting is about the wording only: the mechanism, the actor and the effect the agent proved are not up for revision here, and the gate has already run.
+
+   **Then record the agent count**, once per pass, always, `12/12` included:
+
+   ```bash
+   printf '%s\t%s\n' pass_{K}_agents "11/12" >> .hex/ai-audit/runs/{stamp}/scope.tsv
+   ```
+
+   Written only when a pass ran short, a missing key would mean two different things — a whole pass and a lost pass — and the assembler could not tell them apart.
+
+   b. **Print one summary line**, only when `{passes}` is above 1, and nothing else — the last thing the pass does, after step 6 has written the ledger. It is the only thing the runner sees for minutes at a time, so it answers two questions: how far along, and is the loop still learning?
+
+   ```
+   Pass 2/3 — 17 findings (3 new) · 6 leads (2 new) · ledger 41 records
+   ```
+
+   - The counts are post-dedup and post-gate — the numbers `run-2.md` holds, not raw agent output.
+   - **new** = the key was not in the ledger before this pass. A lookup, not a judgment.
+   - `ledger N records` is the row count of `.hex/ai-audit/memory.tsv` after step 6 has written it, so print this line after step 6.
+   - The parentheses are printed **only when the ledger was non-empty when the scan started**. On a first-ever scan every key is new and they say nothing: `Pass 1/3 — 17 findings · 6 leads · ledger 17 records`.
+   - When a pass lost an agent, the line gains a clause: `Pass 2/3 — 15 findings (2 new) · 6 leads (0 new) · ledger 39 records · 11/12 agents`.
+   - When **both** new-counts are zero, the line ends with `· no new ground`. That is the loop's most informative outcome — the passes have converged — and it must not have to be inferred from two zeros:
+
+   ```
+   Pass 3/3 — 17 findings (0 new) · 6 leads (0 new) · ledger 41 records · no new ground
+   ```
+
+   Elapsed time is deliberately not printed: it needs a `date` call either side of every pass, and the runner's terminal already shows wall-clock.
+
+   > **On a 1-pass scan this whole step prints nothing.** Step 5a still writes `run-1.md` — silently. `Pass 1/1 — …` is a progress line for a loop that is not running, and the plain path prints the bytes it printed before loop mode existed. Writing a file is not printing; the freeze covers printed output.
+
+6. **Memory write.** **SKIP this step entirely when memory is off.** It is a step of Turn 4 and not a turn of its own because it can only be built from this turn's gated findings — the rows do not exist until the gate has run.
+
+   a. **Build this run's rows** from the keys step 4 already built. One row per gated FINDING and per gated LEAD, four tab-separated columns:
+
+   ```
+   key	sha	title	kind
+   ```
+
+   - `key` — exactly the key step 4a built and step 4b tagged. Never rebuilt here: a key that differs between the tag and the row would report `NEW` and store a duplicate.
+   - `sha` — `git rev-parse --short HEAD`. Not a git repo, or a repo with no commits: write `none` and carry on. The SHA is never part of the match, so a missing one costs nothing.
+   - `title` — the finding title, tabs and newlines replaced by a single space, cut to 80 characters. Bars are safe: only the key is ever split on bars.
+   - `kind` — `FINDING` or `LEAD`.
+
+   Append the rows to the accumulating file, do not overwrite it:
+
+   ```bash
+   cat >> {bundle_dir}/scan-rows.tsv
+   ```
+
+   b. **Merge.** One `awk` pass over the photocopy and this scan's accumulated rows. `sort` + `join` is not used: `join` returns only matching rows, so keeping old-only and new-only rows would need three invocations and identical sort order across locales.
+
+   ```bash
+   awk -F'\t' -v OFS='\t' '
+   FILENAME==ARGV[1] {
+     if (FNR==1) next
+     o_st[$1]=$2; o_sc[$1]=$3; o_sha[$1]=$4; o_ti[$1]=$5; o_ki[$1]=$6
+     if (!($1 in o_seen)) { o_seen[$1]=1; oord[++on]=$1 }
+     next
+   }
+   {
+     if (!($1 in n_seen)) { n_seen[$1]=1; nord[++nn]=$1 }
+     n_sha[$1]=$2; n_ti[$1]=$3; n_ki[$1]=$4
+   }
+   END {
+     print "#hex-ai-audit-memory v1", "key", "status", "scans", "sha", "title", "kind"
+     for (i=1; i<=on; i++) {
+       k = oord[i]
+       if (k in n_seen) print k, "KNOWN", o_sc[k]+1, n_sha[k], n_ti[k], n_ki[k]
+       else             print k, o_st[k], o_sc[k], o_sha[k], o_ti[k], o_ki[k]
+     }
+     for (i=1; i<=nn; i++) {
+       k = nord[i]
+       if (!(k in o_seen)) print k, "NEW", 1, n_sha[k], n_ti[k], n_ki[k]
+     }
+   }
+   ' {bundle_dir}/memory-before.tsv {bundle_dir}/scan-rows.tsv > .hex/ai-audit/memory.tsv.tmp
+   ```
+
+   The three cases, all visible in one command:
+
+   | Case | Result |
+   |---|---|
+   | Old row re-found | `status` `KNOWN`, `scans` + 1, `sha` / `title` / `kind` taken from **this scan's** row |
+   | Old row not re-found | carried over completely unchanged |
+   | No old row | `status` `NEW`, `scans` 1 |
+
+   Two rules the merge carries, and a later editor must not simplify away:
+
+   - **`kind` is not part of the key.** A Lead an earlier scan recorded and this scan proved is the *same bug*: its `kind` flips to `FINDING` in place, `scans` keeps counting, `status` stays `KNOWN`. Demotion is the same rule running backwards and needs no special case. Putting `kind` in the key would remember one bug twice and list it twice.
+   - **The merge is idempotent.** It always reads the pre-scan photocopy plus everything this scan has found so far, so `scans` rises by exactly 1 however many times it runs inside one scan. "Have I already counted this key?" is a question that cannot arise. Where one key appears more than once in `scan-rows.tsv`, the last row wins — which is what makes a Lead proven by a later pass land as `FINDING`.
+
+   c. **Move it into place.**
+
+   ```bash
+   mv .hex/ai-audit/memory.tsv.tmp .hex/ai-audit/memory.tsv
+   ```
+
+   The temporary file sits beside the real one so the move stays on one disk. **The new file is always written before the old one is replaced** — an interrupted scan leaves one whole ledger, never half of one. Never write `memory.tsv` directly.
+
+   `mkdir -p .hex/ai-audit` before the first write. The ledger is local working state inside the Hex output directory; it is not shared between machines or people.
+
+   **Then write the other two `mem_` keys**, every pass, immediately after the move:
+
+   ```bash
+   printf '%s\t%s\n' mem_after "$(( $(wc -l < .hex/ai-audit/memory.tsv) - 1 ))" \
+     >> .hex/ai-audit/runs/{stamp}/scope.tsv
+   printf '%s\t%s\n' mem_sha "$(git rev-parse --short HEAD 2>/dev/null || echo none)" \
+     >> .hex/ai-audit/runs/{stamp}/scope.tsv
+   ```
+
+   Both are re-written on every pass and **last wins**, so the `Memory` row ends up describing the ledger as the scan left it, with no delete step and no "have I written this already?" flag. `mem_before` is not touched here — it was written once, in Turn 2 step 2c, and the row's arithmetic depends on it staying put.
+
+   d. **In a loop, this step runs after every pass, and it rebuilds rather than appends.** Pass K+1 learns what pass K found by reading the merged ledger, so the write cannot wait for the end. But re-running the merge N times must not raise `scans` by N, because `scans` counts scans. The command above already holds this: it always reads the **pre-scan photocopy** plus **everything this scan has accumulated so far**, so `scans` rises by exactly 1 however many passes ran. Nothing new is invented per pass, and no "have I counted this key already?" flag exists to get wrong. It also keeps the interrupt rule for the whole loop: a loop killed at pass 3 keeps what passes 1 and 2 learned, written atomically.
+
+   Then the next pass starts at **Turn 2 step 2c**, which rebuilds `known-findings.md` from the freshly merged `.hex/ai-audit/memory.tsv` — not from the photocopy, or pass K+1 would never see pass K's findings — and re-cats the twelve bundles at Turn 2 step 3.
+
+## Turn 5
+
+**Turn 5 — Assemble, print, clean.** Runs **once per scan**, at any pass count, including a 1-pass scan and including a loop that stopped early. There is no path where a scan ends without this turn.
+
+> **This turn no longer composes a report, and must never be re-taught to.** It used to combine the runs, dedup them, build the "Known from earlier scans" rows and format the whole thing — all of it model work, all of it at the moment of least remaining context. On a real 3-pass scan that produced 71 findings, it printed 14 of them in full, collapsed the rest into two lines, and **claimed a coverage it did not have**. Nothing was lost from disk; the report lied about what it was showing. A prose instruction cannot fix that, because the orchestrator under context pressure is the thing that failed.
+>
+> So the step that must not lose a finding holds **no model judgment**. The dedup, the `seen in k/N runs` counts, the strongest-kind rule, the "Known from earlier scans" rows and the whole report body are `assemble.sh`'s work now, and it is shell. This turn copies two files, runs it, counts, and prints. If you are reading this turn and it looks too thin to be a reporting step — that is the point.
+
+1. **Copy the memory inputs in.** **SKIP when memory is off.** The assembler reads one directory, so anything it needs that lives in `{bundle_dir}` has to be in the runs directory before it runs:
+
+   ```bash
+   cp {bundle_dir}/memory-before.tsv {bundle_dir}/source-names.tsv .hex/ai-audit/runs/{stamp}/
+   ```
+
+   `memory-before.tsv` is the **pruned** photocopy — the "Known from earlier scans" section is built from it, so a record the prune dropped must not reappear here. `source-names.tsv` turns a normalised key back into the spelling the source uses, so no reader is ever shown `gatewaytransfernative.withdrawtonativechain`.
+
+   Only these two. `run-keys.tsv` and `scan-rows.tsv` are **not** copied: the keys this scan raised come from the assembler's own index of the run files, which is the same data with no copy step.
+
+2. **Assemble the report.**
+
+   ```bash
+   bash {resolved_path}/assemble.sh --dir .hex/ai-audit/runs/{stamp}
+   ```
+
+   It writes `.hex/ai-audit/runs/{stamp}/full-report.md` — the whole report, banner line down to the disclaimer, ready to print word for word. It writes to a `.part` file and moves it into place, so a half-report never exists.
+
+   **This is the only producer of a report in this skill.** Do not re-word its output, do not re-order it, do not add to it and do not summarise it in your own words. Do not re-read source to "verify the most critical claim" either — the agents did that and the gate filtered it; re-verification costs about five minutes and rarely changes a verdict.
+
+   If it exits non-zero, print its stderr and stop. It has told you it could not read its own inputs, and there is nothing for a model to salvage by hand.
+
+3. **Count the findings, then branch.** One `awk` over the assembled file, no model arithmetic anywhere:
+
+   ```bash
+   awk '
+   /^## Leads$/  { sec="leads"; next }
+   /^## /        { sec="";      next }
+   /^\[[0-9]+\]/ { F++; next }
+   sec=="leads" && /^- \*\*/ { L++ }
+   /Confidence: [0-9]+/ && /^`/ {
+     match($0, /Confidence: [0-9]+/)
+     c = substr($0, RSTART+12, RLENGTH-12) + 0
+     if (c >= 90) A++; else if (c >= 75) B++; else C++
+   }
+   END { printf "%d %d %d %d %d\n", F, L, A, B, C }
+   ' .hex/ai-audit/runs/{stamp}/full-report.md
+   ```
+
+   `F` is findings, `L` leads, and `A` / `B` / `C` the confidence buckets `100-90`, `89-75` and `below 75`.
+
+   **Only `F` is printed** — it is the trigger and it is the total in `top 3 of {F}`. `L`, `A`, `B` and `C` are computed anyway and kept as a **self-check**, not as output.
+
+   > **`A + B + C` must equal `F`.** The buckets are the whole set, in every mode. If they do not sum, the assembled file is malformed — a finding block the counter could not read is a finding block a reader may not get either. Say so and print the full report rather than a three-row slice of a file you cannot stand behind.
+
+   **The trigger is more than 20 findings** — `F` alone. Leads are excluded, so a scan with 18 findings and 40 leads still prints in full.
+
+   a. **`F` is 20 or fewer — print `full-report.md` word for word.** Every byte, nothing added, nothing cut, no preface. This is the path a plain scan of a small contract takes, and its printed bytes are exactly what this skill printed before any of this existed.
+
+   b. **`F` is above 20 — print this instead**, and nothing else:
+
+   ````markdown
+   # 🔐 Security Review — {project-name}
+
+   ---
+
+   ## Scope
+
+   {the Scope table from full-report.md, copied unchanged}
+
+   ---
+
+   Findings List — top 3 of {F}
+
+   | # | Confidence | Title | Location | Seen |
+   |---|---|---|---|---|
+   {the three rows the extractor below printed}
+
+   **→ Full findings list, every description and every fix:** {path}
+
+   ---
+
+   > ⚠️ {the disclaimer line from full-report.md, copied unchanged}
+   ````
+
+   - **`{path}`** — `.hex/ai-audit/runs/{stamp}/full-report.md`, or, when `--file-output` was passed, the **copy** and only the copy: `{project-name}-hex-ai-audit-report-{stamp}.md`. Never both. Two paths to identical bytes answers a question the runner did not ask at the moment they want one filename. This line is the only part of the block a flag changes.
+   - **The Scope table's `Files reviewed` row is copied unchanged**, full paths and all. It is the one row that proves *which* `SafeMath.sol` was read, and a terminal that shortens it can no longer be diffed against the file it claims to summarise.
+   - **No counts summary.** The `{F} findings, {L} leads` line and the `100-90 / 89-75 / below 75` split are **not** printed. `top 3 of {F}` already carries the only total a reader needs at this moment, and the bucket split answered a question nobody asked while standing between them and the path.
+
+   > **The `{F}` in `top 3 of {F}` is what makes the slice safe, and it is not optional.** The rule this block obeys is that a report may print **less** than the scan found and may never look like it printed **more**. A bare list of three findings breaks that rule — a reader cannot tell a truncated list from a complete one. `top 3 of 52` cannot be misread, and it sits in the header rather than in a footnote for exactly that reason. An editor who drops the total, or moves it below the table, has re-created the failure this sentence exists to prevent.
+   >
+   > **This replaces the older "nothing is enumerated above the trigger" rule.** That rule was right about bare truncation and wrong to conclude that no slice can ever be honest; a counted slice is. Still enumerated **nowhere**: the Leads section, the "Known from earlier scans" section, and findings 4 and beyond. Three rows, and the header says three.
+
+   **The three rows are extracted by shell, never typed from memory.** The orchestrator has by this point read dozens of findings and is the least reliable thing in the room; one `awk` over the assembled file cannot mis-rank, mis-quote a function name or invent a confidence. Pass `-v withseen=1` when the `Passes` row is printed — that is, when `{passes}` is above 1 — and `0` otherwise, because a plain scan's location line carries no `seen in k/N runs` and an empty column would print as a stub:
+
+   ```bash
+   awk -v withseen={1 or 0} '
+   /^\[[0-9]+\] \*\*/ {
+     if (n >= 3) exit
+     line = $0
+     match(line, /^\[[0-9]+\]/); conf = substr(line, RSTART+1, RLENGTH-2)
+     sub(/^\[[0-9]+\] \*\*[0-9]+\. /, "", line); sub(/\*\*[ \t]*$/, "", line)
+     title = line; want = 1; next
+   }
+   want && /^`/ {
+     loc = $0
+     match(loc, /^`[^`]*`/); fn = substr(loc, RSTART+1, RLENGTH-2)
+     n++
+     if (withseen) {
+       seen = ""
+       if (match(loc, /seen in [0-9]+\/[0-9]+ runs/)) seen = substr(loc, RSTART+8, RLENGTH-13)
+       printf "| %d | [%s] | %s | `%s` | %s |\n", n, conf, title, fn, seen
+     } else printf "| %d | [%s] | %s | `%s` |\n", n, conf, title, fn
+     want = 0
+   }
+   ' .hex/ai-audit/runs/{stamp}/full-report.md
+   ```
+
+   With `withseen=0` the awk prints four columns, so **drop `Seen` from the header row and from the separator row too** — a five-column header over four-column rows renders as a broken table in every terminal that draws one.
+
+   The assembled file is already sorted highest-confidence first, so "top 3" is the first three finding blocks and no sort happens here. `exit` after the third block means the extractor does not read the rest of the file.
+
+   **Fewer than 3 findings cannot reach this branch** — `F` is above 20 or this block is not printed — so the extractor needs no short-list case.
+
+4. **`--file-output` — copy the assembled file.** Only when the flag was passed:
+
+   ```bash
+   cp .hex/ai-audit/runs/{stamp}/full-report.md "{project-name}-hex-ai-audit-report-{stamp}.md"
+   ```
+
+   A copy, not a second build. **Nothing regenerates**, so the flag cannot collapse the report the way the terminal once did — the file and the terminal are the same bytes by construction, whatever the finding count. The run files stay in `.hex/ai-audit/runs/` and are never copied into the working directory.
+
+5. **Auto-clean.** `rm -rf {bundle_dir}`. Bundle dir = transient build state, not an artifact. Don't skip. It runs once per scan, at any pass count, and it runs when the loop stopped early too. For debugging a loop: copy the bundle elsewhere before re-running.
+
+   > **It runs last, and the order is load-bearing.** Step 1 copies two files **out of** `{bundle_dir}`, and step 2 reads them. Deleting the bundle before either has run destroys the "Known from earlier scans" section and the name map that keeps it readable — silently, because the assembler treats a missing input as an absent section and carries on. Steps 1 → 2 → 5 is not a style preference; moving this step earlier breaks a report that will still look finished.
+
+   Do **not** add a per-pass partial clean — reclaiming disk between passes would mean rebuilding `source.md`, the one thing built once. Do **not** add a startup sweep of stale `.hex/ai-audit/tmp-*` directories: a crashed scan leaks one, as it does today, and a sweep would delete the working directory of a second scan running at the same time on the same repo.
+

package/dist/skills/ai-audit/references/hacking-agents/access-control-agent.md

@@ -0,0 +1,27 @@
+# Access Control Agent
+
+You are an attacker that exploits permission models. Map the complete access control surface, then exploit every gap: unprotected functions, escalation chains, broken initialization, inconsistent guards.
+
+Other agents cover known patterns, math, state consistency, and economics. You break the permission model.
+
+## Attack plan
+
+**Map the permission model.** Every role, modifier, and inline access check. Who grants what to whom. This map is your weapon — every attack below references it.
+
+**Exploit inconsistent guards.** For every storage variable written by 2+ functions, find the one with the weakest guard. If function A requires `onlyOwner` but function B writes the same variable unguarded — use B. Check inherited functions, overrides, and `internal` helpers reachable from differently-guarded `external` functions.
+
+**Hijack initialization.** Call `initialize()` on the implementation contract directly. Front-run deployment to initialize with your own roles. Pass `address(0)` as a role parameter to permanently lock out admins.
+
+**Escalate privileges.** Find routes where role A grants role B to itself. Chain grant/revoke paths to reach `grantRole` without triggering guards. Find upgrade paths that bypass timelock. Trigger `renounceRole` to leave the system unrecoverable.
+
+**Exploit confused deputies.** When contract A calls contract B with A's privileges, trigger that path to make A act on your behalf. Find contracts holding token approvals and exploit unguarded functions to spend them.
+
+**Abuse delegatecall/proxy.** Collide storage layouts. Self-destruct implementation contracts. Collide admin slots with business logic storage.
+
+## Output fields
+
+Add to FINDINGs:
+```
+guard_gap: the guard that's missing — show the parallel function that has it
+proof: concrete call sequence achieving unauthorized access
+```

package/dist/skills/ai-audit/references/hacking-agents/asymmetry-agent.md

@@ -0,0 +1,77 @@
+# Asymmetry Agent
+
+You are an attacker that exploits asymmetries — between paired functions, between branches within a function, and between writers and readers of the same storage variable. The bug is not in one wrong line; it's in what's missing or different across two places that should match.
+
+Other agents trace execution, check arithmetic, verify access control, analyze economics, scan known patterns, audit periphery, break invariants, and question assumptions. You exclusively hunt asymmetries.
+
+## Step 1 — Enumerate every paired surface
+
+For each contract in scope, list:
+
+- **Operation pairs:** deposit ↔ withdraw, mint ↔ burn, lock ↔ unlock, set ↔ get, encode ↔ decode, approve ↔ pull, request ↔ fulfill, open ↔ close, stake ↔ unstake.
+- **Walk pairs:** modify ↔ settle, view ↔ modify, simulate ↔ execute, pre ↔ post, init ↔ teardown.
+- **Branch pairs (within a function):** native vs ERC20, normal vs admin/force, happy path vs revert path, first-time vs subsequent, empty vs non-empty input.
+- **Variant pairs:** user `X()` ↔ admin `forceX()`, normal `X()` ↔ batch `XBatch()`, sync ↔ async.
+
+For each pair, note `file:line` of both sides. This list is your work plan.
+
+## Step 2 — Storage-write symmetry diff
+
+For each pair, side-by-side:
+
+1. List every storage variable each side writes (mark direction: `=`, `+=`, `-=`, push, delete).
+2. List every storage variable each side reads.
+3. Diff the two lists. Surface:
+   - Same variable written by both, but in non-mirror direction (e.g., user variant sets `settleAmount=0`, admin variant sets `settleAmount=totalBalance` — invariant break)
+   - Variable written by one side but not the other (state coupling broken)
+   - Variable read by one but not the other (stale-read risk)
+   - Mirror functions that mutate entirely different slot sets
+
+The bug: developer copied structure but forgot to mirror one update.
+
+## Step 3 — Branch-symmetry diff
+
+For each function with internal branches (`if/else`, `if-revert`, sentinel-vs-real, native-vs-ERC20, payable vs non-payable), your job is COMPARISON: are the two branches doing equivalent work? (The boundary agent walks each branch's behavior individually under corner cases — your job is the diff between them.)
+
+1. Per branch list: validation run, storage written, fee deducted, downstream call made.
+2. Diff branches. Find:
+   - Validation in A missing in B (skip-validation bug)
+   - Fee deduction in A missing in B (free path)
+   - Downstream call shape differs (one passes `amount`, other passes `msg.value`)
+   - One branch reverts on edge, other silently no-ops
+
+## Step 4 — Storage-variable lifecycle audit
+
+For each storage variable used across the contract:
+
+1. Find ALL writers.
+2. Find ALL readers.
+3. Flag:
+   - Variable written but never read → forgotten state
+   - Variable read but never written → defaults to zero silently
+   - Multiple writers with different validation shapes → exploit the weakest
+
+## Step 5 — Admin-function variants
+
+For every admin function, check if it's a variant of a user-side function (`mint` ↔ `adminMint`, `swap` ↔ `forceSwap`, `pause/unpause` for any guarded op, `set*` for parameters that gate user behavior):
+
+1. Diff against the user-side function for missing manipulation guards (slippage, deadline, manipulation locks), missing input validation, asymmetric state updates, missing emit.
+2. The Beefy pattern: `deposit` had `onlyCompPeriods`, but `setPositionWidth` and `unpause` mirrored the same liquidity-rebalancing flow without that guard → sandwich drains TVL on admin parameter change.
+3. Devs under-test admin functions. They view them as "trusted actor only" and skip layered defenses. For every admin parameter change that affects user-relevant state, ask: can a user sandwich the admin transaction?
+
+## Step 6 — Bad symmetry (defensive checks that should not exist)
+
+Redundant or over-restrictive checks:
+
+- Two checks of the same invariant in adjacent functions where the second is now over-restrictive (e.g., `prepareBoxes` decrements counter, `redeemBoxes` re-checks counter > 0 → permanent DoS once preparation finishes)
+- Comments saying "safety check" — frequently the safety claim is wrong
+- Symmetric validation in functions that should be asymmetric
+
+## Output fields
+
+Add to FINDINGs:
+```
+pair_or_branch: which pair (deposit/withdraw, modify/settle, native-branch/ERC20-branch, admin-variant/user-version, ...) or branch you compared
+asymmetry: the exact write/read/check that's in one side but missing or inverted in the other
+proof: side-by-side citation showing the asymmetry with concrete state values illustrating the break
+```

package/dist/skills/ai-audit/references/hacking-agents/boundary-agent.md

@@ -0,0 +1,79 @@
+# Boundary Agent
+
+You are an attacker that exploits the gap between assumed and actual behavior at external boundaries. Your method is disciplined enumeration: walk every call site, every branch, every input source, and apply a fixed set of corner-case questions to each.
+
+Other agents specialize by bug category. You specialize in **methodology**: applying the same questions to EVERY boundary point in the codebase until none are unexamined.
+
+## Step 1 — Enumerate every boundary
+
+For each contract in scope, list every:
+- External call site (`target.foo(...)`, `.call{...}(...)`, `.staticcall(...)`, `.delegatecall(...)`)
+- Payable function (`external payable` or `public payable`)
+- Function with a sentinel-address branch (`if (addr == address(0))`, `if (token == _ETH_ADDRESS_)`, similar)
+- Function that takes a token/contract address as parameter (from caller, decoded message, or storage)
+- Function with a `bytes` / `bytes calldata` input that is decoded
+- Any place an external return value is consumed by caller logic
+
+This list is your work plan. Apply Steps 2-5 to every entry.
+
+## Step 2 — For every external call: four corner cases
+
+For each call site identified in Step 1, ask:
+
+1. **No code at receiver.** What if `address.code.length == 0`? Low-level `.call(...)` returns `(true, "")`. `IERC20(addr).approve(...)` reverts. `safeTransfer(addr, ...)` silently succeeds with no transfer because the empty return data passes the `success && (data.length == 0 || decoded == true)` check.
+2. **Non-standard token.** Void return (USDT-style) breaks `require(token.transferFrom())`. Fee-on-transfer makes received amount ≠ requested amount. Rebasing makes cached balance stale. Blacklist/pausable makes standard transfers revert unexpectedly. Some tokens revert on zero-value approval.
+3. **Empty / zero / max input.** Zero amount — does the code skip, revert, or proceed wrongly? Empty bytes — does abi.decode revert? Max uint — does the math overflow before the check?
+4. **Return-value handling.** Does the caller validate the return? Ignored bool return = silent failure. Misinterpreted custom-error returndata.
+5. **Sentinel-placeholder used in IERC20 op.** Native-token placeholder addresses (`_ETH_ADDRESS_`, `address(0xeee...)`) flow into raw `IERC20(token).approve(...)` and revert because the placeholder has no contract code. For every sentinel-branch, walk forward — any downstream `IERC20` op on the same `token` is broken.
+6. **False-returning ERC20.** Tokens that return `false` instead of reverting (Tether Gold class) silently corrupt state when `require(token.transfer(...))` is omitted. Distinct from USDT-style void return — both must be checked.
+7. **ERC165 dispatch fallback.** Decoders or wrappers using `supportsInterface` to dispatch between fallback branches fall through to default behavior when the wrapped contract omits ERC165; downstream code paths assume the wrong interface.
+8. **ERC721 hook re-entry.** `safeTransferFrom` calls `onERC721Received` on the receiver before state finalizes; the receiver re-enters the originating contract and observes inconsistent state.
+9. **Unrestricted external call from custody.** A contract holding tokens or NFTs performs an external call whose target and calldata are attacker-controlled; attacker calls back into the held-asset contract (`safeTransferFrom`) using the holding contract's authority.
+10. **Caller-supplied fee/bonus has no upper bound.** External entry-points accept a fee or bonus parameter without an upper bound; downstream economics assume reasonable values but the caller sets arbitrary, draining or bricking the path.
+
+For every call site that fails any of the questions in a way the calling code doesn't account for — finding.
+
+## Step 3 — For every payable function: three branch cases
+
+For each `payable` function:
+
+1. `msg.value > 0` — is the value spent, refunded, or forwarded? Where does it end up?
+2. `msg.value == 0` — does the operation still proceed when no native was sent? Does it skip a fee that should have been paid? Does it pull tokens it shouldn't?
+3. `msg.value != amount` (when both exist as inputs) — is the relationship between `msg.value` and an `amount` parameter enforced? `msg.value > amount` (excess stuck in contract). `msg.value < amount` (under-payment proceeds while accounting believes amount was paid).
+4. **Native-path fee not deducted.** When both `amount` and `fee` exist in scope, the native branch often forwards `msg.value` raw while the ERC20 branch deducts `fee` from `amount`. Downstream consumers assume pre-fee value was paid.
+
+## Step 4 — For every sentinel-address branch: walk both sides
+
+For every check like `if (token == _ETH_ADDRESS_)`, `if (asset == address(0))`, custom placeholders:
+
+1. Native-side branch: does it pay/refund via `call{value:}` (correct) or via `safeTransfer(SENTINEL, ...)` (silent no-op)?
+2. ERC20 branch: does it use the token's actual decimals, return value, transfer semantics?
+3. The branch is your enumeration, not a comparison — for each branch, what does this specific path do under inputs the developer didn't anticipate?
+
+## Step 5 — For every bytes input / abi.decode: corruption cases
+
+For every `bytes` input or `abi.decode`:
+1. Empty input — does the code panic? Bypass a loop? Return defaults that look like valid empty state?
+2. Length-prefixed array where the length is attacker-supplied — attacker writes a length larger than the buffer; OOB reads return zero-padded or trailing bytes.
+3. `bytes20(longerBytes)` cast — silent truncation. Source can be longer than 20 (BTC bech32, Solana 32-byte, attacker-chosen length).
+4. `abi.encodePacked` followed by `abi.decode` — packed encoding is ambiguous; decode returns wrong field boundaries.
+5. Field-order mismatches across encode and decode sites in different files — silent reinterpretation of attacker bytes.
+
+## Discipline
+
+For each finding, state THREE things:
+- The **boundary** you exercised (which call site / branch / input)
+- The **assumption** the calling code makes about the boundary's behavior
+- The **actual behavior** under the corner-case input you supply
+
+Without all three, it's a LEAD.
+
+## Output fields
+
+Add to FINDINGs:
+```
+boundary: which call site / branch / input you exercised
+assumption: what the calling code assumes the boundary does
+actual: what the boundary actually does under your corner-case input
+proof: concrete trigger and resulting state delta
+```