hex-audit 0.6.2 → 0.7.0

package/dist/skills/ai-audit/references/report-formatting.md

@@ -0,0 +1,385 @@
+# Report Formatting
+
+## The one rule
+
+**A report must not overstate its own coverage.** Every other rule in this file serves that
+one. The report may print **less** than the scan found — a mistyped marker, a dead agent, a
+pass that never ran — and when it does it says so in words. It may never claim to print
+**more**. A report that shows 14 findings and reads as if it showed all of them is the defect
+this whole design exists to kill.
+
+## Who reads this file
+
+Nothing composes a report from this template any more. There are two readers:
+
+- **SKILL.md Turn 4 step 5a** — the pass writing its findings into `run-K.md`. It uses the
+  **finding block** shape below: title line, location line, `**Description**`, diff `**Fix**`
+  block. Those bytes are pasted straight through into the report, so they are written in the
+  report's own shape while the pass still has context to spare.
+- **`references/assemble.sh`** — the assembler. Everything below the finding block — the
+  banner, the Scope table, the ordering, the Findings List, the Leads section, "Known from
+  earlier scans", the disclaimer — is what the assembler emits.
+
+**This file settles the shape. `report-language.md` settles the words.** Every sentence a
+human reads in the report — the finding title, the Description, the Lead description, the
+Lead's code smells — is written in Simplified Technical English, and that file holds the rules.
+It is read by the same Turn 4 step 5a that writes the block, and it is in all twelve agent
+bundles. It never reaches the diff in a **Fix** block, the bug-class label inside a key, or an
+identifier on a location line: those three are data, and it says so.
+
+**The template is the contract the assembler emits, not a shape a model imitates.** A later
+editor must not re-teach the orchestrator to write it. The orchestrator under context pressure
+is the thing that failed; the step that must not lose a finding holds no model judgment.
+
+## Report Path
+
+**Every scan assembles `.hex/ai-audit/runs/{stamp}/full-report.md`** — the whole report,
+banner line down to the disclaimer — at any pass count, with or without flags. That file is
+the report. There is exactly one producer of it, and it is the assembler.
+
+`--file-output` makes a **copy** of that file into the current working directory as
+`{project-name}-hex-ai-audit-report-{stamp}.md`, where `{project-name}` is the repo root
+basename and `{stamp}` is `YYYYMMDD-HHMMSS` at scan time. A copy, not a second build —
+nothing regenerates, so the flag cannot collapse the report the way the terminal once did. The
+flag never causes a report to be produced; it only decides whether a copy lands where the
+runner can see it.
+
+The `run-K.md` files stay in `.hex/ai-audit/runs/{stamp}/` under the same stamp, so a
+report and the runs that produced it are tied together by eye. They are never copied into the
+working directory — they are memory, not reports.
+
+## Output Format
+
+This is what the assembler emits.
+
+````
+# 🔐 Security Review — <ContractName or repo name>
+
+---
+
+## Scope
+
+|  |  |
+| --- | --- |
+| **Mode** | ALL / default / filename                              |
+| **Files reviewed** | `File1.sol` · `File2.sol`<br>`File3.sol` · `File4.sol` | <!-- every file, 3 per line -->
+| **Confidence threshold (1-100)** | N                                    |
+| **Passes** | 3                                                      | <!-- only when passes > 1 -->
+| **Memory** | 12 records before this scan · 14 after · `a1b2c3d`     | <!-- only when memory is on -->
+| **Run files** | ⚠️ 2 findings marked, 1 readable. 1 could not be read. | <!-- only when the structure check disagrees -->
+
+---
+
+## Findings
+
+[95] **1. <Title>**
+
+`ContractName.functionName` · Confidence: 95 · seen in 2/3 runs · KNOWN (4 scans) <!-- runs segment only when passes > 1; memory segment only when memory is on -->
+
+**Description**
+<The vulnerable code pattern and why it is exploitable, in 1 short sentence>
+
+**Fix**
+
+```diff
+- vulnerable line(s)
++ fixed line(s)
+```
+
+---
+
+[82] **2. <Title>**
+
+`ContractName.functionName` · Confidence: 82
+
+**Description**
+<The vulnerable code pattern and why it is exploitable, in 1 short sentence>
+
+**Fix**
+
+```diff
+- vulnerable line(s)
++ fixed line(s)
+```
+
+---
+
+< ... all above-threshold findings >
+
+---
+
+[60] **3. <Title>**
+
+`ContractName.functionName` · Confidence: 60
+
+**Description**
+<The vulnerable code pattern and why it is exploitable, in 1 short sentence>
+
+---
+
+< ... all below-threshold findings (description only, no Fix block) >
+
+---
+
+Findings List
+
+| # | Confidence | Title |
+|---|---|---|
+| 1 | [95] | <title> |
+| 2 | [82] | <title> |
+| 3 | [75] | <title> |
+| | | **Below Confidence Threshold** |
+| 4 | [60] | <title> |
+
+---
+
+## Leads
+
+_Vulnerability trails with concrete code smells where the full exploit path could not be completed in one analysis pass. These are not false positives — they are high-signal leads for manual review. Not scored._
+
+- **<Title>** — `Contract.function` · NEW — Code smells: <missing guard, unsafe arithmetic, etc.> — <1-2 sentence description of the trail and what remains unverified> <!-- memory segment only when memory is on -->
+- **<Title>** — `Contract.function` · seen in 2/3 runs · KNOWN (2 scans) — Code smells: <...> — <1-2 sentence description> <!-- runs segment only when passes > 1 -->
+
+---
+
+## Known from earlier scans
+
+<!-- only when memory is on AND the ledger held at least one record — see Memory in the report -->
+
+_Recorded by earlier scans of this repo, not raised again by this one. Not re-checked — a record here may be fixed, or may still be live and missed. `.hex/ai-audit/memory.tsv`._
+
+| Scans | Kind | Location | Title |
+|---|---|---|---|
+| 4 | FINDING | `Router.swap` | Swap trusts a spot price as an oracle |
+| 2 | LEAD | `Vault.sweep` | Sweep lets the owner take user deposits |
+
+---
+
+> ⚠️ This review was performed by an AI assistant. AI analysis can never verify the complete absence of vulnerabilities and no guarantee of security is given. Team security reviews, bug bounty programs, and on-chain monitoring are strongly recommended.
+
+````
+
+**Rules describing the output**, all of them held by the assembler and none of them addressed
+to a model:
+
+- Findings are sorted by confidence, highest first.
+- A finding at or above the threshold carries a **Description** and a diff **Fix** block. One
+  below carries the **Description** only. Nothing in the run file marks which side of the line
+  a finding sits on — it is re-derived from the confidence, so there is one source of truth.
+- The **Below Confidence Threshold** separator row is printed whenever at least one finding
+  falls below the threshold, and left out when none does. Without it the table runs 1, 2, 3
+  with nothing to mark the boundary, so a reader of the table alone cannot tell which findings
+  carry no **Fix** block.
+- **Empty cases say so in words, never with an empty table**: `_None — this scan raised no
+  findings._` in place of the Findings List, `_None._` under Leads, `**Body missing** — pass K
+  raised this finding and wrote no description.` in place of a body.
+- **A `Run files` row appears only when the structure check disagrees.** The model types the
+  markers that bound each finding in a run file, so it can mistype one. The assembler counts
+  open markers against close markers against readable blocks, and prints the disagreement as a
+  Scope row naming how many findings could not be read. Everything readable is still printed
+  and the assembler never stops. That row is the one rule at the top made mechanical.
+- **The Scope table's column padding is not part of the shape.** Markdown renders
+  `| **Mode** | default |` and a space-padded form identically, and the padding above is for
+  reading this file. Content and order are the contract; character widths are not.
+
+**The threshold is 75**, set in `judging.md` and printed in the Scope row above. It is named
+in `judging.md` and nowhere else; this file reads it from there. A finding at 75 or above gets
+a description and a **Fix** block, one below 75 gets the description only. A promoted lead
+lands at exactly 75, so it clears — that is why the number is 75.
+
+## The size trigger
+
+**More than 20 findings.** At 20 the terminal prints the assembled file word for word; at 21
+it stops printing findings. Findings only — above and below the threshold together. **Leads
+are excluded from the trigger count**, so a scan with 18 findings and 40 leads prints in full.
+
+The trigger is on **size, not on flags**. A plain scan of a small contract is unchanged; a
+plain scan of a big one gets the new shape.
+
+**Above the trigger the terminal prints four things:** the banner, the Scope table unchanged,
+a **Findings List holding the top 3 findings**, and the path to the full report — then the
+disclaimer. About fifteen lines.
+
+The full report is unaffected. Above the trigger, as below it, `full-report.md` holds every
+finding in the shape above — only the terminal changes.
+
+**The slice is honest because it is counted.** The table's header reads
+`Findings List — top 3 of {F}`, and that `{F}` is the whole rule:
+
+- **A report may print less than the scan found. It may never look like it printed more.**
+  A bare list of three findings breaks that — a reader cannot tell a truncated list from a
+  complete one. `top 3 of 52` cannot be misread.
+- **The total goes in the header, not a footnote.** A reader who sees the table sees the
+  total in the same glance. This is not a style choice; a footnote can be scrolled past.
+- **Three rows, and nothing else is enumerated.** No Leads, no "Known from earlier scans",
+  no findings past the third.
+
+> **This replaces the older "nothing is enumerated above the trigger" rule**, which forbade
+> every top-N slice. That rule was right that bare truncation lies and wrong to conclude no
+> slice can be honest; a counted one is. A later editor must not restore the blanket ban by
+> citing the half of the argument that survived.
+
+**The rows are extracted by shell, never typed.** One `awk` over the assembled file — which is
+already sorted highest-confidence first, so no sort happens in the terminal step. The
+orchestrator has read dozens of findings by then and is the least reliable thing in the room;
+the extractor cannot mis-rank, mis-quote a function name or invent a confidence. The command
+is in `dedup-and-assembly.md` Turn 5 step 3b.
+
+**The `Seen` column appears only when the `Passes` row does** — that is, when the pass count is
+above 1. A plain scan's location line carries no `seen in k/N runs`, so the column is dropped
+from the header, the separator and the rows together. A five-column header over four-column
+rows draws as a broken table.
+
+**There is 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}` carries the only total the
+moment needs, and the bucket split stood between the reader and the path. The buckets are still
+**computed** as a self-check — `A + B + C` must equal `F`, in every mode, or the assembled file
+is malformed and the scan says so instead of printing a slice of it.
+
+The path line names `.hex/ai-audit/runs/{stamp}/full-report.md`, or — when `--file-output`
+was passed — the **copy** and only the copy. Never both: two paths to identical bytes answer a
+question the runner did not ask at the moment they want one filename. That line is the only
+part of the block a flag changes.
+
+The exact wording, spacing and order of the block are in `dedup-and-assembly.md` Turn 5 step
+3b, which is where the terminal is printed.
+
+## The freeze
+
+**A small scan with no flags prints what it printed before any of this existed.** Below the
+trigger the terminal prints `full-report.md` word for word — every byte, nothing added,
+nothing cut, no preface — so the freeze is a property of the assembled file.
+
+The freeze is a **diff against `golden/plain-full-report.md`**, the frozen plain-path report,
+and it covers the report's **content and order, not its column padding** and not what lands on
+disk. Byte-identity against "today" was tried and is unmeetable: no captured report exists
+anywhere, and today's bytes were composed by a model from a template that contradicted itself.
+The golden file is what replaced it.
+
+What the freeze does **not** cover: writing files. Every scan now writes a runs directory and
+assembles a report there, at any pass count. Writing a file is not printing, and the freeze is
+on printed output.
+
+## Memory in the report
+
+Everything in this section is printed **only when memory is on** (`--memory`, or a pass count
+above 1). With memory off the assembled file carries no extra rows, no extra segments, no
+extra sections and no dangling `·`, and below the trigger it still diffs clean against the
+golden file.
+
+**Segment order on the meta line.** One dot-separated chain, in a fixed order:
+
+```
+`ContractName.functionName` · Confidence: 95 · seen in 2/3 runs · KNOWN (4 scans)
+```
+
+location · confidence · runs · memory. **A segment appears only when it carries information** —
+`seen in k/N runs` needs more than one run, `KNOWN (n scans)` / `NEW` needs memory on. So:
+
+| Scan | Meta line |
+|---|---|
+| 1 pass, no flags | `` `Vault.withdraw` · Confidence: 95 `` |
+| 1 pass, `--memory` | `` … · Confidence: 95 · KNOWN (4 scans) `` |
+| 3 passes | `` … · Confidence: 95 · seen in 2/3 runs · KNOWN (4 scans) `` |
+
+`KNOWN (4 scans)` and `NEW` are the ledger's own two words, so the report and the file say the
+same thing. **`n` counts this scan.** The tag is derived by the assembler from
+`memory-before.tsv` — the pre-scan photocopy — and `n` is that row's `scans` **plus one**: the
+scan that is printing has just found it again, and the ledger already holds that same number.
+Printing the stored count instead would show a report one behind its own ledger. `NEW` carries
+no count. The tag is **not** carried in the run-file marker: one source, so the report and the
+ledger cannot disagree.
+
+The `Scans` column of "Known from earlier scans" is the opposite case and is printed **as
+stored**: this scan did not raise those records, so nothing about them counts up. The
+**Findings List** table is unchanged — it stays `# | Confidence | Title`.
+
+Leads carry the same segments as findings, on their own line, because a Lead is a full ledger
+record.
+
+**The `Memory` row in Scope.** `<records in the ledger before this scan> records before this
+scan · <records after the merge> after · `<sha>``. The SHA is the one every row of this scan
+wrote; `none` when the repo has no commits. The row states the whole ledger state in one line,
+so the two counts show at a glance what the scan added.
+
+**The "before" count is the count after the prune** — the row count of `memory-before.tsv` as
+the merge reads it, not the row count of the file the scan opened. On a scan where the prune
+drops records the two differ, and using the pre-prune number makes the row's own arithmetic
+wrong: a scan that opened 4 records, pruned 1 and added 12 would read `4 records before this
+scan · 15 after`, and a reader counting 4 + 12 gets 16. The prune is already reported on its
+own line (`Pruned N records …`), so the Scope row does not restate it and must not contradict
+it.
+
+**Building "Known from earlier scans".** These are the records the ledger already held that
+this scan did **not** raise again. It is **not** a filter on the `status` column — `status`
+stays `KNOWN` once set and never marks the not-found-again case.
+
+**The `comm` block that used to sit here is now in `assemble.sh`**, under
+`# Known from earlier scans`. It reads two inputs Turn 5 copies into the runs directory:
+`memory-before.tsv`, the pruned photocopy, and `source-names.tsv`. The keys this scan raised
+come from the assembler's own index of the run files, so no `run-keys.tsv` or `scan-rows.tsv`
+is carried in — the run files are the record. It is computed once per scan, scoped to the
+whole scan and not to the last run, so a bug found in run 1 but not in run 3 does not appear
+here.
+
+Each key `comm` returns is one row: `Scans`, `Kind` and `Title` come straight from its row in
+`memory-before.tsv`. `Location` is rebuilt from the key's first two segments, which are stored
+normalised (lower case, hyphenated) and cannot be printed as they are — each segment is looked
+up in `source-names.tsv` and printed as the source spells it, or printed as stored when it is
+not in the map, which happens on a named-file scan where the contract was never assembled into
+`source.md`.
+
+Three states, and no fourth:
+
+- The ledger held records this scan did not raise → the table above.
+- The ledger held records and this scan raised **every one** → `_None — every record in the
+  ledger was raised again by this scan._`
+- Memory is off, or the ledger is empty (first-ever scan) → **no section at all.** A plain
+  scan grows no empty headings.
+
+The italic line under the heading is load-bearing and is printed verbatim: these records are
+**not re-checked**. A reader must not take the section as "still open", and must not take it
+as "fixed".
+
+## Loop mode in the report
+
+Everything in this section is printed **only when the pass count is above 1**. One pass prints
+none of it.
+
+**One report per scan.** However many passes ran, the runner sees one combined list. The
+per-pass output is one summary line each (SKILL.md Turn 4 step 5b) and one `run-K.md` in
+`.hex/ai-audit/runs/{stamp}/` — neither is a report.
+
+**`seen in k/N runs`.** `k` is how many of this scan's runs raised that group key; `N` is how
+many passes produced a run file. A pass that collapsed produced none, so it is not in `N` — a
+report must not claim a run that never happened. The segment sits between confidence and the
+memory tag, and it is printed on Leads exactly as it is on findings, because a Lead is a full
+ledger record.
+
+**`seen in k/N runs` and `KNOWN (n scans)` count different things and must never be mixed.**
+`k/N` counts runs inside **this** scan and is never written to the ledger. `n` counts scans and
+comes from the ledger. A finding first raised by pass 1 of this scan is `NEW` in pass 3 — it is
+this scan's work, however many of its runs saw it.
+
+**Which write-up survives the merge.** One winner per key: strongest kind, then highest
+confidence, then the later pass — a later pass read the ledger every earlier pass wrote, so it
+is the better-informed write-up. **Confidence is untouched by the merge.** A finding three runs
+saw keeps the number the runs gave it; repetition is reported on the line, never scored, and
+`seen in 3/3 runs` is there for the reader to weigh.
+
+**The `Passes` row in Scope** is composed by the assembler from recorded facts, never written
+as prose. It carries degradation text whenever the scan did not run whole — a report claiming
+3 passes when one of them ran three-quarters of its agents overstates its own coverage:
+
+```
+| **Passes** | 3                                                    |
+| **Passes** | 3 (pass 2 ran 11/12 agents)                          |
+| **Passes** | 2 of 3 (pass 3 failed)                               |
+| **Passes** | 2 of 3 (pass 1 ran 11/12 agents, pass 3 failed)      |
+```
+
+The `R of P` prefix comes from counting run files. The dead agent's **name** never appears
+here — it stays in the run file, in the sentence under the `<!--RUN-->` marker.
+
+On a 1-pass scan this row is suppressed, so a pass 1 that produced nothing is reported by the
+`Run files` row instead: `⚠️ No pass produced a run file. This scan reviewed nothing.`

package/dist/skills/ai-audit/references/report-language.md

@@ -0,0 +1,151 @@
+# Report language — Simplified Technical English
+
+Every sentence a human reads in the report obeys this file. The rules are ASD-STE100
+(Simplified Technical English), reduced to the part an audit finding needs.
+
+## Why
+
+A report is read by the developer who must fix the code, often at speed, often not in their
+first language. A sentence they must decode twice costs the fix, and the bug stays in the
+code. The scan is only as good as the sentence that delivers it.
+
+Short words do not make a finding less rigorous. The proof is the diff in the **Fix** block
+and the location on the meta line. The sentence exists to say what breaks and who breaks it.
+
+## What this covers
+
+Four pieces of text, and no others:
+
+- the finding **title**
+- the **Description** sentence
+- the **Lead** description
+- the **code smells** list on a Lead
+
+## What it must never touch
+
+These are data, not prose. Rewriting one of them for readability breaks the scan:
+
+- **Solidity identifiers** — contract, function, variable and event names. They are printed as
+  the source spells them. `withdrawToNativeChain` is never softened to `withdraw to chain`.
+- **The diff inside a Fix block.** It is code. It is pasted verbatim from the agent that wrote
+  it, and `judging.md` and `dedup-and-assembly.md` both forbid paraphrase there.
+- **The bug-class label** (`zero-abort-address`). It is the third segment of a memory key.
+  The same bug under a plainer word is a second ledger record, so memory remembers it twice
+  and recognises it never. Labels are chosen by the rules in `dedup-and-assembly.md` step 1,
+  never by this file.
+- **Fixed strings the assembler prints** — the banner, the Scope table headers, the italic
+  lines under Leads and "Known from earlier scans", the disclaimer. They are in
+  `assemble.sh` and they are already written.
+
+## The rules
+
+1. **One sentence, one idea.** A Description is one sentence. A Lead description is one or
+   two. Never three.
+2. **Twenty-five words is the ceiling.** Count them. Over the ceiling means two ideas in one
+   sentence — cut it or split it.
+3. **Active voice, and name the actor.** Who does this? Write that word first.
+   - No: `Funds can be drained due to a missing check.`
+   - Yes: `Any caller can take all the tokens, because the function checks no caller.`
+4. **Simple present tense.** The code does this today. Not `would be able to`, not
+   `could potentially`. If the path is uncertain it is a Lead, and the Lead says which step
+   is unproven.
+5. **No `-ing` clauses.** They hide the actor and the order of events. Use `that`, `so`, or a
+   second sentence.
+   - No: `Missing access control allowing anyone to drain the vault.`
+   - Yes: `The function has no access control, so any caller can take all the tokens.`
+6. **Keep the articles.** `the`, `a`, `an`. Telegraphic style — `Function reverts on zero
+   amount` — is not shorter to read, only shorter to type.
+7. **Three nouns in a row is the limit.** Break a longer stack with `of`, `for` or `in`.
+   - No: `cross-chain message replay protection gap`
+   - Yes: `the contract does not stop a replay of a cross-chain message`
+8. **One word for one thing, every time.** Pick `token`, or pick `asset`, and use that word
+   in the title, the Description and the fix. A synonym reads as a second thing.
+9. **No metaphor, no idiom, no slang.** See the table below. A metaphor is a word the reader
+   must translate before they can act.
+10. **Say what happens, not how bad it is.** `catastrophic`, `critical`, `severe` and
+    `trivially` carry no information — the confidence number and the Fix block carry it. Write
+    the effect: `the caller keeps the tokens and the pool keeps the debt`.
+11. **Positive statements. No double negatives.** `The check is absent` beats `the check is
+    not present`.
+12. **Event order is sentence order.** Cause, then effect. `The price comes from the pool
+    balance, so an attacker who moves the balance moves the price.`
+13. **A title is one clause, twelve words or fewer,** present tense, active, and it names the
+    defect or its effect. `Swap trusts a spot price as an oracle.`
+    Not `Oracle manipulation vulnerability in swap functionality`.
+
+## Words to replace
+
+Left column: the wording to keep out of the report. Right column: what the report prints.
+
+| Do not write | Write |
+| --- | --- |
+| burns the funds | sends the tokens to an address that cannot spend them |
+| bricks the contract | makes the function fail for every caller, forever |
+| rug / rugpull | the owner takes the user deposits |
+| griefing | an attacker makes the function fail for other users |
+| footgun | (delete the word and name the defect) |
+| silently swallows the error | ignores the error |
+| DoS / denial of service | blocks every caller |
+| attack surface / attack vector | path |
+| malicious actor / bad actor | an attacker |
+| leverages / utilizes | uses |
+| is able to | can |
+| in order to | to |
+| arbitrary value | any value the caller chooses |
+| stale price | old price |
+| sanity check | check |
+| happy path | the normal path |
+| atomically | in one transaction |
+| trustlessly / permissionlessly | (delete, or name who may call) |
+| non-zero | more than zero |
+| cascading failures | (name each failure) |
+| exponentially / trivially / catastrophically | (delete) |
+| edge case | (name the input or the state) |
+
+## Technical names stay
+
+STE-100 keeps technical names, and a security report cannot work without them:
+`reentrancy`, `slippage`, `oracle`, `revert`, `overflow`, `rounding`, `allowance`, `nonce`,
+`slot`, `delegatecall`. Use them. They are precise and the reader who fixes Solidity knows
+them.
+
+The rule is what goes **around** them: name the mechanism once with its technical name, then
+say in plain words what the attacker gets.
+
+- No: `Classic CEI violation enabling reentrant drainage of the vault.`
+- Yes: `The function sends ETH before it lowers the balance, so a reentrant call withdraws
+  the same deposit twice.`
+
+## Worked examples
+
+Before, and after. The code the sentence describes did not change.
+
+**One**
+
+- Before: `Improper validation of the abort address results in a catastrophic loss of user
+  funds via burning to the zero address.`
+- After: `The function accepts a zero abort address, so a failed transfer sends the tokens to
+  an address that nobody controls.`
+
+**Two**
+
+- Before: `Lack of slippage protection in the swap path exposes users to sandwich attacks,
+  potentially leading to significant value extraction by MEV searchers.`
+- After: `The swap sets the minimum output to zero, so an attacker who trades before and
+  after the victim keeps most of the output.`
+
+**Three — a Lead**
+
+- Before: `Potential accounting inconsistency stemming from asymmetric fee handling on
+  deposit/withdraw flows warranting further investigation.`
+- After: `The deposit takes the fee from the amount, and the withdrawal takes it from the
+  balance. We did not find the input that makes the two disagree.`
+
+## Self-check before you write the block
+
+Four questions. Any `no` means rewrite the sentence, not the code:
+
+- Does the sentence name **who** acts and **what** they get?
+- Is it one sentence, twenty-five words or fewer, with no `-ing` clause?
+- Is every word in it a word the reader does not have to translate?
+- Are the identifiers, the label and the diff exactly as the source and the agent wrote them?

package/dist/skills/ai-audit/references/senior-auditor-sop.md

@@ -0,0 +1,63 @@
+# Senior Auditor's Mindset
+
+This is how a senior auditor thinks. Pattern-matching catches the obvious bugs — your specialty file teaches that. The high-value bugs, the ones everyone else misses, come from HOW you reason about code, not from WHAT bugs you know.
+
+The senior auditor's edge is not "knowing more bug patterns" — it is having internalized mental tools they reach for instinctively when something feels off, when a path seems clean, or when a conclusion comes too quickly.
+
+This file gives you three tools. They are not steps. You reach for the right one the moment the trigger fires. They are how you think, not text you write: do not put them in your reply, which holds only your FINDING and LEAD blocks. Use them. Trust your discomfort.
+
+A finding is not real until you've traced the attack with concrete values. You are an attacker, not a defender — when you find a bug, deepen the attack; never argue yourself out of one.
+
+---
+
+## 1. The Feynman test (FIRST — use it before anything else)
+
+**This is the first tool. Apply it the moment you open any new function or contract — before you reason about anything else.** Code you have not Feynman'd is code you have not actually understood.
+
+When you read code, STOP and ask: "Can I explain what this function does to someone who doesn't know Solidity?"
+
+Try it. In plain words. The places where your explanation gets fuzzy — where you reach for Solidity jargon instead of plain meaning — are where you're papering over an assumption. That's where bugs hide.
+
+Example: you read `_handleFeeTransfer(zrc20, fee)` and your explanation comes out as "it transfers the fee." That's not Feynman. Feynman is: "it picks up the protocol's commission off the user's payment and moves it to the treasury wallet." Now keep going: what if the payment is in ETH and the function uses an ERC20 method? Your plain-English explanation breaks. Bug.
+
+A senior auditor doesn't trust their understanding until they can explain it without the safety net of technical vocabulary.
+
+---
+
+## 2. Socratic questioning
+
+For every line of code, ask: why is this here? What does it assume? What happens if the assumption breaks?
+
+Don't accept "because that's how it's written" as an answer. Don't accept "the function name says so" as an answer. Drill until you reach the implicit belief the code rests on. The first answer is usually a restatement. The actual assumption is two or three "whys" deeper.
+
+Example: `if (zrc20 != _ETH_ADDRESS_) IERC20(zrc20).transferFrom(msg.sender, address(this), amount);`
+- Why is `zrc20 != _ETH_ADDRESS_` checked? → because ETH isn't transferable via transferFrom.
+- Why is there no else branch? → because the developer assumed ETH arrives via `msg.value`.
+- Where is `msg.value` enforced to equal `amount` for the ETH path? → **nowhere**. Bug.
+
+A senior auditor accepts no "because" without examining it.
+
+---
+
+## 3. Inversion
+
+Every clean path gets a backward pass. After you understand what the code IS supposed to do, ask: how would I make it NOT do that?
+
+Same code, attacker's eye instead of developer's eye. The developer asks "does this work?" The attacker asks "how do I break this?" Read every check and ask "what value slips past it?" Read every state update and ask "what state am I in just before this?"
+
+A senior auditor never reads code only forward.
+
+---
+
+## When to reach for which tool
+
+You don't apply these in order — except Feynman, which is always first. You reach for what the moment calls for:
+
+- Opening any new function or contract → **Feynman** (always — before anything else)
+- Trying to understand a line you don't yet → **Socratic**
+- Something looks too clean → **Inversion**
+- You reached a "bug" conclusion → amplify the attack (chain it, find more victims, lower the precondition cost — do NOT refute it)
+
+The tools are how you keep yourself honest. Without them, you fall into the trap of every junior auditor: trusting your first read, accepting code that "looks right," moving on when something feels off.
+
+Trust your discomfort. Reach for the tool. Don't stop until the discomfort has a name.

package/dist/skills/generate-report.md

@@ -56,8 +56,8 @@ Each section has a defined **input signature** — the exact set of data it deri
 
 | Section | Input signature (hash over) |
 |---|---|
-| `executive_summary` | severity + resolution histograms, `stats.totals.nsloc`, all `settings.report.*` fields, and the `overview.md` bytes (the synopsis derives from it) |
-| `audited_files` | the per-file LoC results for every `project.scope` file, `repository_url`, `initial_commit` |
+| `executive_summary` | severity + resolution histograms, `stats.totals.nsloc`, all `settings.report.*` fields, and the `overview.md` bytes (the synopsis derives from it); differential: also `diff.json` `base_commit` / `head_commit` / `summary` |
+| `audited_files` | the per-file LoC results for every `project.scope` file (differential: every changed file, with its +/- counts), `repository_url`, `initial_commit` |
 | `summary_of_findings` | the ordered synced-findings list: `(id, title, severity, resolution)` each |
 | `system_overview` | `overview.md`, `access-control.json`, `deps.json` bytes |
 | `findings` | the synced-findings full content: `(title, severity, description, code blocks, recommendation, resolution, update_from_client, root_cause.locations)` each |
@@ -85,7 +85,7 @@ Read `<output_dir>/config.json`. Look under `settings.report.*` for:
 - `final_commit` — commit hash after fixes (defaults to `initial_commit` if no remediation cycle).
 - `initial_report_date` — date the initial report was delivered (e.g. `May 22, 2026`).
 - `final_report_date` — date the final report was delivered (defaults to `initial_report_date`).
-- `audit_type` — defaults to `Security Review`.
+- `audit_type` — defaults to `Security Review`. A differential audit (`project.mode: "diff"`) is initialized with `Differential Review`.
 - `doc_assessment` — `High` / `Medium` / `Low`.
 - `test_assessment` — `High` / `Medium` / `Low`.
 - `kickoff_call` — optional focus note for the §7 kick-off sentence (e.g. "with a focus on the upgrade changes"). Empty means omit the kick-off sentence.
@@ -138,6 +138,8 @@ Style hints:
 
 Write to `executive_summary.txt` **and** `01-executive-summary.tex`.
 
+**Differential audit** (`config.json` → `project.mode` is `diff`): the review covers the changes between two commits, and the first paragraph must say so. Use `<SCOPE_DESCRIPTION>` = `changes to <scope description> between commit \href{<REPOSITORY_URL>/commit/<BASE_COMMIT>}{\texttt{<BASE_SHORT>}} and commit \href{<REPOSITORY_URL>/commit/<HEAD_COMMIT>}{\texttt{<HEAD_SHORT>}}` (commits from `.hex/diff.json`, short = first 7 characters). Replace the `<TOTAL_NSLOC>` sentence with the size of the change: `\textbf{The audit comprises} <ADDITIONS> added and <DELETIONS> removed lines of Solidity code across <FILES_CHANGED> files` (from `diff.json` `summary`). Everything else in the section is unchanged.
+
 ```latex
 \pagebreak \vspace*{0cm}
 \sectioncolor
@@ -222,6 +224,8 @@ Substitutions:
 
 Write to `audited_files.txt` **and** `02-audited-files.tex`.
 
+**Differential audit:** the rows are the files in `.hex/diff.json` `files` with status `added`, `modified` or `renamed` (not `deleted`), counted at the head commit, instead of every `project.scope` file. Keep the same columns; the table still describes the audited files at head. `<INITIAL_COMMIT>` in the links is the head commit.
+
 Compute per-file line counts from each scope file. For each in-scope file in `config.json.project.scope`:
 
 - Read the file. Count:
@@ -392,6 +396,8 @@ If the finding has multiple `root_cause.locations[]`, list them in the **File(s)
 
 **A finding shows the relevant code as a fenced code block, not a line reference.** Authors embed a minimal ` ```solidity ` block in the description illustrating the issue; the report renders those (and any `root_cause.locations[].snippet` that a materialized finding happens to carry) as `minted` blocks.
 
+Finding descriptions are authored already backticked and structured (identifiers in backticks, functions as `` `name(...)` `` which the markdown→LaTeX rule turns into `\texttt{name(...)}`, and short expected/flaw/impact paragraphs). Preserve that: render the paragraph breaks as-is (blank lines between paragraphs), do not collapse a multi-paragraph description into one block.
+
 **Content the report must NOT contain** (enforced upstream at authoring time — the report renders synced GitHub content verbatim and does not rewrite it, so it must arrive clean):
 - No specific source line numbers ("line 56", "on lines 43, 55") in `description` / `recommendation` — code is shown via `snippet` instead.
 - No cross-references to other findings by hex id (`H-NNN`) or number/title — each finding stands alone; report readers have no hex ids.